OSI Software, Inc.
Universal Data Adapter
COM Connector for Honeywell PHD
Beta version 1.0.0.10
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web /
Bulletin Board / (510) 895-9423
Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)
8 data bits, 1 stop bit, no parity, up to 14400 bps download
protocols: Xmodem, Ymodem, Zmodem, Kermit
Mail / OSI Software, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland /
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
1999-2000 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
January 12, 20191
OSI Software, Inc.
Table of Contents
Introduction
Required Software
Required Hardware
PI-UDS Point Attributes
Data Access Concepts
Data Retrieval
Virtual Tags
Reductions
Putting Data into PHD
Exception Processing
PHD COM Connector Point Configuration
Point Types
Principle of Operation
Installation
Honeywell Total Plant Information (TPI)
PHD PROXY
PHD COM Connector
Point Building
Udaphdbuild
Point Creation
Point Maintenance
Digital Points
Command-Line Options for udaphdbuild
Troubleshooting
Installation Problems
PI-UDS Redirector
PHD COM Connector
Operational Problems
Starting PI-UDS while Redirector is not Registered
Starting PI-UDS While PHD is Not Running
Stopping PHD While PI-UDS is Running
Setting the password for the PIDEMO account
Introduction
The Universal Data Adapter is a Windows NT-based software product that allows OSI Software client applications to interact with data in data-storage systems other than the PI System Data Archive. This document outlines the features of the OSI Software Universal Data Adapter (UDA) to the Honeywell Uniformance PHD server. The PHD COM Connector retrieves snapshot and archive data from the Honeywell Uniformance PHD server on request by the PI-UDS. The PHD COM Connector also sends PI snapshot and historical data to the PHD server. The PHD COM Connector makes Honeywell PHD CAPI calls to retrieve data from the PHD server.
Client applications need not be changed in any way. Products such as ProcessBook, DataLink and PI-ODBC are able to retrieve data from a PHD server. This is also true for any custom applications coded with either the PI-SDK or PI-API.
Supported FeaturesPlatforms / NT-Intel
PI Point Types / Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String
Subsecond Timestamps / No
Subsecond Scan Classes / NA
Automatically Incorporates PI Point Attribute Changes / Yes
Exception Reporting / NA
Outputs from PI / Yes
History Recovery / NA
Failover / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / NA
Uniint-based / No
Maximum Point Count / Unllimited
SDK / Yes
Vendor Software Required / Yes
Vendor Software Required on DCS System / No
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
Required Software
PI Universal Data Server version 3.3 or higher from OSI Software, Inc.
UDA COM Connector for Honeywell PHD installation kit from OSI Software, Inc.
PI-SDK installation kit from OSI Software, Inc.
Honeywell PHD Server version 130 or higher.
If the PI-UDS is to be installed on a different computer than the Honeywell PHD Server, the Honeywell Total Plant Information (TPI) client tools installation kit will be necessary. The UDA COM Connector requires that the PHD file netapishr.dll be in the path. Note that this DLL may be dependent on other Honeywell-provided DLLs. These are installed by the Honeywell client tools kit.
Required Hardware
Windows NT PC (Intel) for the PHD server and PI-UDS.
The Honeywell PHD Server and PI-UDS may be on different PCs.
PI-UDS 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-UDS. During PI-UDS operation, requests for data will be made by clients using PI-UDS point information. The PI-UDS will then obtain data from the foreign system point to which the PI-UDS point is mapped.
The PI-UDS does not use point source to identify points. Instead, the system manager must define a point class with the following attributes:
Attribute Name / Descriptionuda_progid / COM Program ID, as stored in the Windows NT registry. This name is used to instantiate the COM Connector object.
uda_lmap / Longword mapping parameter.
uda_strmap / String mapping parameter.
The mapping parameters uda_lmap and uda_strmap are passed to the COM Connector so that it can locate the appropriate foreign system point. The usage of these two attributes is always specified in the manual for the COM Connector.
A point is identified as a UDA mapped point if it includes these three attributes.
The PI-UDS has a script file called classicuda.dif that can be used to define a point class called classicuda. This file can be used directly, or as a template for custom point class definitions.
Data Access Concepts
The UDA COM Connector for Honeywell PHD makes PHD CAPI calls to get data from the PHD server. These calls are made in the COM Connector when data are requested from client applications.
Data Retrieval
The phd_getdata routine is called for all data requests. The type of data returned depends on what type of data is requested. Snapshot and compressed data are retrieved as “Raw” data from the PHD server. If interpolated data (sample data) are requested, the PHD Point attribute “Linear Flag” must be set. If the “Linear Flag” is not set, Raw (compressed) data are returned. Setting the “Linear Flag” does not affect retrieval of compressed data from PHD.
Virtual Tags
The Honeywell PHD system supports virtual tags, which are tags that have a mathematical expression specified. When data values are retrieved from a virtual point, the PHD COM Connector does the calculation on demand. The time interval between the returned values is taken from the PHD point “scan seconds” attribute. Virtual tag data retrieval is also done with the phd_getdata call.
Reductions
The PHD CAPI supports the retrieval of reductions as well as raw values from its archive. Reductions are summarized values such as average, delta, minimum, maximum, standard deviation and reg slope. The phd_getdata routine is also called to get the reduction data.
Putting Data into PHD
The phd_putdata routine is called for all put value requests. The PHD tag must have the “Manual Input” flag enabled for the phd_putdata call to succeed. A PHD tag cannot have the “Collection” flag enabled for the phd_putdata call to work. Changes to the PHD data will be propagated to the DCS by the PHD.
Exception Processing
The PI-UDS supports its clients requesting new data values by exception. This means that a client expects to be notified of new values received by the PI-UDS for all points for which it is signed up. COM Connectors are expected to support this mechanism as well. However, data from the PHD Server cannot be obtained by exceptions. The COM Connector for Honeywell PHD emulates exception processing by polling for new values in the PHD snapshot. The frequency of polling is the value of the PHD point’s “scan time” attribute divided by 2. If this value is 0, then a polling interval of 10 seconds will be used.
PHD COM Connector Point Configuration
The following describes how to configure the PI-UDS specific point attributes for the PHD COM Connector.
Uda_Progid:This attribute specifies the COM Program ID of the COM Connector.
For the PHD COM Connector it is “PIPHDUDA.PIPHDConnector”.
All points for the PHD COM Connector must have “PIPHDUDA.PIPHDConnector” as the value of the uda_progid attribute.
Uda_lmap:This attribute is used to interpret the PHD confidence factor.
Each PHD value includes a “confidence level” between 0 and 100. A useable value is always available if the confidence number is between 0 and 100. One hundred indicates high quality, 0 represents an uncertain result. If no value is available at all, the confidence level becomes -1.
The uda_lmap point attribute will be used to specify the minimum confidence. The default setting for this parameter will be zero, that is, the value is returned if the confidence is zero or greater. This is consistent with Honeywell’s TPI clients’ default confidence level. If the PHD confidence is below the uda_lmap value, the PHD COM Connector returns “Bad Input.”
Uda_strmap: This attribute is used to specify the PHD tag from which to read data.
The field starts with the PHD Server name/socket number (usually 3000) followed by a single quote. The PHD server name/socket number is optional if there is only one PHD Server to access.
Although the default socket number is 3000, this number cannot be omitted. If the PHD server name/socket number is not entered, the PHD_HOST environment variable will be used.
The second element in the field is the PHD tag name.
There are three different categories of data that can be retrieved: snapshot and compressed or interpolated historical data, virtual tag data and reduction data. Example: The PHD COM Connector will get the data for fic100.pv on the PHD server Turboberry.
Turboberry/3000’fic100.pv
When retrieving historical values from a virtual point, the time interval between the returned values is taken from the PHD point “scan seconds” attribute.
A reduction calculation on a PHD tag is supported. After the tagname enter a space and then one of the following numbers then a space and a calculation period in seconds:
Index / Description1 / Average
2 / Delta
3 / Minimum
4 / Maximum
5 / Standard Deviation
6 / Regslope
Example: Turboberry/3000’fic100.pv 1 600
Data returned from this PI-UDS point will consist of a series of 10-minute averages.
If you do not enter a time period, the scan seconds attribute of the PHD point is used. If the scan time is 0, a value of 60 seconds will be used.
Point Types
All PHD point types are supported: Integer, Floating Point, Character String and Binary.
All PI point types are supported: Real, Integer, Digital and String. It is not required to match PI Point types to the PHD point type, but it is recommended to do so. For digital tags, you must configure PI Digital Sets for the digital tags to use.
The data event returned by the PHD COM Connector will be coerced into the defined data type of the PI-UDS point. If coercion is not possible, loss of data may occur. For example, if the COM Connector returns a string value from PHD, it is usually not possible to coerce the value of the data type of the PI-UDS point is a floating point value.
The following table is how the PI-UDS will perform the less obvious translations:
String / Digital / Looks up the string in its Digital Set. If no match, “Inp OutRange” will be returned (Input out of range).
Integer / Digital / Offset into the states in its Digital Set. If the value is outside of the point’s range, “Inp OutRange” will be returned. Positive numbers above the number of Digital States, and Negative numbers will return “Inp OutRange”
Float / Digital / Coerce to an Integer number and will work as above.
Binary / Blob / This is the only legal mapping for this PHD data type. The only way to read this value type is with the extended PI-API. See the PI-API manual for details.
Principle of Operation
The UDA COM Connector for Honeywell PHD is implemented as an in-process COM object in a DLL called piphduda.dll. The COM object is registered during installation of the COM Connector.
The PHD COM Connector will never appear in the Windows NT Task Manager process list as an independent process. It is loaded instead by a PI-UDS process called the Redirector, which appears in the process list as piudardr.exe. The Redirector loads the PHD COM Connector automatically when the PI Base Subsystem loads the first PI-UDS mapped point that references the PHD COM Connector in its uda_progid point attribute.
The PHD COM Connector will process new PI-UDS points, point edits and point deletes.
After startup, the first time a PHD UDS point is accessed, a UDAPHD server name is created if it is not already there in the PI-SDK list of servers. The PIDEMO account is used to access the server. The PI-SDK is used to check if the UDA point is Digital and its Digital number translation to strings. The PIDEMO account needs to be blank for Digital tags to work correctly. If the PIDEMO account is not blank, the value returned for Digital UDA tags will be BAD.
Installation
Honeywell Total Plant Information (TPI)
The Honeywell Total Plant Information (TPI) client tools must be installed.
Confirm that the Honeywell DLL netapishr.dll is in the Windows NT path before installing the COM Connector. Note that other dependent Honeywell DLLs must also be in the path.
PHD PROXY
A default PHD proxy may be needed for the PHD COM Connector to make a network connection to the PHD.
PHDMAN> PROXY os_domain os_username phd_username
Specifies a proxy login user for the specified operating system domain and user. When the specified user performs a proxy login (a login without specifying a username/password), he will be logged into the PHD system as the specified phd_username. If phd_username is not specified, then any previous proxy for the user is removed. PHD_SECURITY authorization is required to perform this command.
PHDMAN> proxy PHD-SERVER SYSTEM PHD_READONLY
Default proxies are attempted automatically when a network connection is established with PHD. The client PC software queries the owner of the process and the OS domain (see below) from the operating system and passes this to PHD. PHD then checks to see if there is a user defined which matches the owner. If a match is found, the proxy domain configured for the user is checked versus the one which was passed from the client PC. If this matches, PHD applies the security configured for this user to the session. The default proxy is also applied whenever a login is performed from the client.
The proxy domain for a user is set in the User Profile form (see the TotalPlant Information Fixed Plant Databook User Guide) by defining a DOMAIN attribute for the user.
PHD COM Connector
Locate the installation kit for the COM Connector for Honeywell PHD. The setup program name is piphduda.exe. Start this program from a command line or the Windows NT Explorer.
You will be prompted for the directory location into which to install the COM Connector. The default is:
C:\Program Files\OSI Software\Honeywell PHD
The COM Connector does not need to be located in the same directory as the PI-UDS.
The following files will placed into the target directory:
File / Descriptionpiphduda.dll / COM Connector for Honeywell PHD
hwphd_uda.doc / COM Connector for Honeywell PHD Manual (this document)
udaphdbuild.exe / Utility to build a PI-UDS piconfig input file from the PHD point database
udaphdload.dif / piconfig file describing the input data format when building PI-UDS points to map PHD points. This file is used in conjunction with the udaphdbuild utility
Point Building
PI-UDS points can be built using a number of different tools. Refer to the PI Data Archive Manual for details.
Udaphdbuild
This section will outline a utility that facilitates the building of PI-UDS points that map existing PHD points.
The udaphdbuild utility must be run from a command window prompt. It generates output that can be read by the PI-UDSpiconfig utility to build points. Normally, you would invoke the utility and redirect its output to a file.
Point Creation
To build PI-UDS points, the output from the udaphdbuild utility can be used as input to the piconfig utility. For example, to build a piconfig input file from all of the points in the PHD Server acorn, you would enter:
udaphdbuild –n acorn/3000 > acornphdpts.dat
The file udaphdload.dif defines the fields in the resulting data file to piconfig. To build PI-UDS points, you would enter:
piconfig
* (Ls - ) PIconfig> @input udaphdload.dif
* (Cr - PIPOINT) PIconfig> @input acornphdpts.dat