OSIsoft, Inc.
PI Server COM Connector
for
OPC HDA Servers
Version 1.0.0.39
Rev H
PI Server COM Connector for OPC HDA Servers 35
Installation
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA 94577 USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
§ Brazil
§ Middle East/North Africa
§ Republic of South Africa
§ Russia/Central Asia / § South America/Caribbean
§ Southeast Asia
§ South Korea
§ Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished -- rights reserved under the copyright laws of the United States.
© 2006 OSIsoft, Inc. PI_OPCHDACtr.Doc
PI Server COM Connector for OPC HDA Servers 35
Installation
Table of Contents
Introduction 1
Supported Features 1
Required Software 2
Required Hardware 2
Hardware Diagram 3
Principles of Operation 5
Installation 7
Installation Checklist 7
OPC HDA COM Connector Installation 7
PI Point Attributes 9
Data Access Concepts 11
Snapshot Data 11
Archive Data Retrieval 11
Quality Attributes 11
Summary Values 11
Exception Data 11
Writing Data 11
OPC HDA COM Connector PI Point Configuration 13
Tag 13
Ctr_progid 13
Ctr_lmap 13
Ctr_strmap 13
PointType 14
Mapping Data Types 14
PI Point Configuration Tool -- HDATagBuilder 15
Command-line Parameters 16
Output File – OPCHDACtr.csv 16
Troubleshooting 17
Installation Problems 17
PI Server Redirector 17
Point Class Classicctr is not Available 18
OPC HDA COM Connector 18
Operational Problems 18
Starting PI Server while Redirector is not Registered 18
Starting PI Server while OPC HDA Server is Not Available 18
Stopping OPC HDA Server while PI Server is Running 19
Using the DUMP Function 19
Configuring the Redirector for Interactive Use 19
DCOM Configuration 21
OPCEnum Tool 21
General Steps for DCOM Configuration 21
Windows XP 22
Windows NT/2000 28
Notes and Recommendations on DCOM Configuration 33
DCOM Configuration Instructions from OPC HDA Server Vendor 33
DCOM without an NT Primary Domain Controller 33
DCOM Configuration on Two Machines 34
DCOM Configuration on Single Machine 34
OPC HDA Server Registration 34
Revision History 37
PI Server COM Connector for OPC HDA Servers 35
Introduction
The PI Server is a Windows-based software product that allows OSIsoft client applications to interact with data in data-storage systems other than the PI Data Archive. The module loaded by the PI Server to make the connection to the foreign data storage system is a COM object called a COM Connector.
This document outlines the features of the PI Server COM Connector for OPC Historical Data Access (HDA) servers. The OPC HDA COM Connector will be referred to as PI OPCHDACtr. PI OPCHDACtr retrieves snapshot and archive data from OPC HDA servers on request by the PI Server. PI OPCHDACtr uses OPC calls to retrieve data from the OPC HDA server.
Client applications need not be changed in any way. Products such as ProcessBook, DataLink and PI-ODBC are able to retrieve data from an OPC HDA server via PI OPCHDACtr. This is also true for any custom applications coded with either the PI-SDK or PI-API.
Supported Features
Feature / Support /Platforms / Windows NTI 4.0 / 2000 / XP / 2003 Server /
APS Connector / No /
Point Builder Utility / Yes /
PI Point Types / Int16, Int32, Float16, Float32, Float64, String, Digital /
* OPC HDA Server Data Types / See Below /
Automatically Incorporates PI Point Attribute Changes / Yes /
Exception Reporting / No /
* Access to History / Yes /
Failover / No /
Access to Multiple System Nodes / No /
Inputs to PI / Yes /
Outputs from PI / No /
Maximum Point Count / Unlimited /
Vendor Software Required / No /
Vendor Software Required on DCS System / Yes /
Vendor Hardware Required / No /
* See Below for more information.
OPC HDA Server Data Types
These OPC HDA Server data types are supported by PI OPCHDACtr.
Data Type / DescriptionVT_I1 / 1-byte Integer
VT_UI1 / 1-byte Integer Unsigned
VT_I2 / 2-byte Integer
VT_UI2 / 2-byte Integer Unsigned
VT_I4 / 4-byte Integer
VT_UI4 / 4-byte Integer Unsigned
VT_R4 / 4-byte Float
VT_R8 / 8-byte Float
VT_BSTR / String
VT_BOOL / Boolean
VT_DATE / Date
VT_CY / Currency
Access to History
Access to history requires that the DCS system have an OPC HDA server.
Required Software
PI Server version 3.3 or higher from OSIsoft, Inc.
PI Server COM Connector for OPC HDA installation kit from OSIsoft, Inc.
Any OPC server compliant with the OPC HDA standard 1.2.
If the PI Server is to be installed on a different computer than the OPC Server, the OPC proxy DLLs will be installed with the PI OPCHDACtr Connector.
Required Hardware
The PI OPCHDACtr is designed to run on a Windows NT, Windows 200x, Windows 2000x Servers, and Windows XP-based computer (Intel or compatible) nodes.
The OPC servers and PI Server may be on different PCs.
Hardware Diagram
PI Server COM Connector for OPC HDA Servers 35
Principles of Operation
The PI Server COM Connector for OPC HDA is implemented as an “out-of-process COM object” in an executable called piopchdactr.exe. The object is registered when the COM Connector is installed. PI OPCHDACtr is able to connect with only one OPC HDA (Historical Data Access) Server, which may be on the same or a different machine.
PI OPCHDACtr uses the timestamps from the OPC Server.
The COM object is registered during installation of PI OPCHDACtr. OSIsoft recommends the installation of PI OPCHDACtr onto the system where the HDA server resides, whenever possible, to minimize the resources needed. However, the COM Connector may be installed on the same system as the PI Server or on another system entirely, if necessary. It is best to install PI OPCHDACtr alongside the OPC HDA server. PI OPCHDACtr is not installed as a service and is not started manually. It is loaded instead by a PI Server process called the Redirector, which appears in the Task Manager Process list on the PI Server system as piudsrdr.exe. The Redirector loads
PI OPCHDACtr automatically when the PI Base Subsystem loads the first PI Server mapped point that references PI OPCHDACtr in its ctr_progid point attribute.
PI OPCHDACtr will process new PI Server points, point edits and point deletes. PI points can be edited using PIConfig or the PI SMT Excel add-in.
PI Server COM Connector for OPC HDA Servers 35
Installation
Installation Checklist
To access values from the OPC HDA server follow this basic procedure:
- Verify that OPC HDA Server and the PI Server are installed.
- Install PI OPCHDACtr.
PI OPCHDACtr tags belong to the classicctr point class. These tags must have these attributes: ctr_progid, ctr_strmap, and ctr_lmap. The setup kit will create this class during the install.
3. Configure PI points. Run HDATagBuilder.exe.
- Start PI. As long as the archive, snapshot, and base services are running,
PI OPCHDACtr tags can be accessed from the OPC HDA server through PI. If PI was running during the installation of this COM connector, then it may need to stop and be restarted again.
Note: If there are problems defining points or having data updated correctly see Troubleshooting Tips section.
OPC HDA COM Connector Installation
Locate the installation kit for the COM Connector for OPC. The setup program name is PI_OPCHDActr_x.x.x.x.exe. Start this program from a command line or the Windows Explorer.
The default directory for installation is:
PIHOME\Interfaces\OPCHDACtr
If there are already client applications from OSIsoft installed on the computer, the default path shown above will be the path for the current PIPC directory.
The following files will placed into the target directory:
File / Description /PIOPCHDACtr.exe / COM Connector for OPC
PI_OPCHDA_Ctr.doc / COM Connector for OPC Manual (this document)
HDATagBuilder.exe / Tag configuration utility
PI_OPCHDA_Ctr_ReleaseNotes.txt / Description of latest changes
PI Server COM Connector for OPC HDA Servers 35
PI Point Attributes
The term map will be used throughout this document to mean making a relationship between a point on the foreign system and a point on the PI Server. During PI Server operation, requests for data will be made by clients using PI Server point information. The PI Server will then obtain data from the foreign system point to which the PI Server point is mapped.
The PI Server does not use point source to identify points. Instead, the system manager must define a point class with the following attributes:
Attribute Name / Description /ctr_progid / COM Program ID, as stored in the Windows NT registry. This name is used to instantiate the COM Connector object.
ctr_lmap / Longword mapping parameter.
ctr_strmap / String mapping parameter.
The ctr_progid is used by the PI Server to load the COM Connector. The mapping parameters ctr_lmap and ctr_strmap are passed to the COM Connector through a COM method call so that it can locate the appropriate foreign system point. The usage of these two attributes with PI OPCHDACtr is discussed later in this manual.
A point is identified as a PI Server mapped point if it includes these three attributes.
The PI Server has a script file called classicctr.dif that can be used to define a point class called classicctr. This file can be used directly, or as a template for custom point class definitions.
PI Server COM Connector for OPC HDA Servers 35
Data Access Concepts
The PI Server COM Connector for OPC makes DA or HDA calls to get data from and write data to the OPC HDA servers. These calls are made in the COM Connector when data updates are requested from client applications. All calls are made synchronously except when exception data have been requested; exception data requires an asynchronous connection to the OPC HDA server so that the COM Connector can receive updates from the OPC server and buffer them up until the PI Server requests the data.
Snapshot Data
Reading snapshot data is accomplished through the OPC HDA synchronous ReadRaw method, with a timestamp of NOW and a count of one.
Archive Data Retrieval
For archive value requests, the data may be retrieved using either ReadRaw or ReadProcessed, depending on the request.
Quality Attributes
Quality values are not stored in this release.
Summary Values
For those OPC servers which support them, summary values are available. These are similar to the standard PI summary values, such as minimum, mean, maximum, and range. Depending on the OPC server, the summary values retrieved may not be derived from the same equation as a similar PI summary value, therefore it will need to be known what the OPC server supports, and what calculations it makes, in order to understand what values are being retrieving
Exception Data
PI OPCHDACtr does not support the Advise methods to collect new values as they occur. PI OPCHDACtr will poll using ReadRaw/ReadProcessed to gather new values and report them back to the client through the PI Server.
Writing Data
Writing data to the OPC HDA Server is not supported in this release of PI OPCHDACtr.
PI Server COM Connector for OPC HDA Servers 35
OPC HDA COM Connector PI Point Configuration
The following describes how to configure the PI Server specific point attributes for the PI OPCHDACtr Connector.
Tag
A tag is a label or name for a point. Any tag name can be used in accordance with the normal PI point naming conventions.
Ctr_progid
This attribute specifies the COM Program ID of the COM Connector.
For PI OPCHDACtr, it is “PIOPCHDA.PIOPCConnector”.
All points for PI-OPCHACtr must have “PIOPCHDA.PIOPCConnector” as the value of the ctr_progid attribute.
Ctr_lmap
Not Used
Ctr_strmap
This attribute is used to specify the node name of the OPC server, the server's ProgID, and the ItemID from which to read and write data.
The field starts with the node name or IP address of the system where the OPC server is installed. Verify that the piadmin user, the account under which
PI OPCHDACtr will run, is configured in dcomcnfg to have permission to access, and if necessary, launch the OPC HDA server. After the node name or IP address, two colons are used to delimit the next field. If the server is on the same node as PI OPCHDACtr, this parameter and the two colons may be omitted.
The second element in the field is the progID of the OPC HDA server. This is the OPC HDA server name that shows up in most client software, including the PI_HDATool, which is installed by this setup kit. The progID will usually be a string such as OSI.HDA.1 or OPC.HDA. The progID of the OPC HDA server must always be specified.
Finally, the OPC ItemID is the final part of the attribute. This is separated from the progID by a single quotation mark. For example, to get the value for SINUSOID from the OPC HDA server OSI.HDA.1 which is running on the machine Turboberry, the following would be used
Turboberry::OSI.HDA.1'\\Turboberry\sinusoid
PointType
These OPC point types are supported: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_I4, VT_UI4, VT_R4, VT_R8, VT_BOOL, VT_INT, VT_UINT, VT_BSTR, VT_DATE, and VT_CY.
Note: OPC array types are not supported for this release.