PI to PI TCP/IP
(NT / Unix)
Interface
Version 3.4.0.2
Revision A
2/18/2005 3:07:00 PM iii
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
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 OSIsoft, 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.
PI_pitopi.doc
Ó 1997 - 2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
2/18/2005 3:07:00 PM iii
Table of Contents
Introduction 1
Deployment Scenarios 1
Interface Requirements 2
Reference Manuals 2
Supported Features 2
Principles of Operation 7
Installation Checklist 11
Interface Installation on NT 13
Naming Conventions and Requirements 13
Interface Directories 13
The PIHOME Directory Tree 13
Interface Installation Directory 14
Interface Installation Procedure 14
Installing the Interface as an NT Service 14
Installing the Interface Service with PI-Interface Configuration Utility 15
Installing the Interface Service Manually 17
Interface Installation on UNIX 19
Naming Conventions and Requirements 19
Interface Directories 19
The PIHOME Directory 19
Interface Installation Directory 20
Interface Installation Procedure 20
Digital States 23
PointSource 25
Point Configuration on the Receiving PI System 27
Point Attributes 27
Tag 27
PointSource 27
PointType 27
Location1 27
Location2 28
Location3 28
Location4 29
Location5 29
InstrumentTag 30
ExDesc 30
Scan 31
Shutdown 31
ExcMin, ExcMax, ExcDev and ExcDevPercent 31
Compressing 32
CompDev, CompMin, CompMax, CompDevPercent 32
DataAccess, PtAccess 33
Zero, Span 33
Additional Tag Attributes 33
Failover 35
Principles of Operation 35
Failover Conditions and Configurations 36
Loss of Connectivity 36
Detection of Stale Data 37
Monitoring Interface and Failover Status 38
Failover Interface Startup Switches 41
Performance Point Configuration 43
Configuring Performance Points with PI-ICU (NT-Intel) 43
Configuring Performance Points Manually 44
I/O Rate Tag Configuration 45
Monitoring I/O Rates on the Receiving Node 45
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 45
Configuring I/O Rate Tags Manually 46
Configuring the PI Point on the Receiving Node 46
Configuration on the Interface Node 47
Tag and Node Security 49
PI 3 Security 49
PI 2 Security 49
Sample Security Files 52
System Manager Responsibilities 52
Receiving System Manager 52
Source System Manager 53
PI 2 Source System Point Limitations 53
Startup Command File 55
Configuring the Interface with PI-ICU 55
pitopi Interface Tab 60
Command-line Parameters 69
Sample PItoPI.bat File - NT 77
Sample pitopi.sh File - UNIX 79
Sample pitopi.ini File - NT and UNIX 82
Starting / Stopping the Interface on NT 85
Starting Interface as a Service 85
Stopping Interface Running as a Service 85
Starting / Stopping the Interface on UNIX 87
Command-line Syntax for Background Processes 87
Terminating Background Processes 88
Anomalous Background Job Termination 88
Buffering 89
Configuring Buffering with PI-ICU (NT-Intel) 89
Configuring Buffering Manually 93
Example piclient.ini File 94
Appendix A: Error and Informational Messages 97
Message Logs 97
System Errors and PI Errors 97
Interface Startup Messages 97
Scan Summary 98
Appendix B: Troubleshooting 99
Revision History 103
PI to PI TCP/IP Interface 105
Introduction
The PIToPI TCP/IP interface transfers data from one PI server (the source server) to another PI server (the receiving server) via TCP/IP. For each copy of the interface used, several source servers (one for each scan class) may be configured to send data to a single receiving server. The receiving and source servers may be either PI 2 (OpenVMS) or PI 3 (UNIX or Windows NT), but the interface program must run on a UNIX or Windows NT node. The interface program may be located on the receiving PI node, source PI node or a PI-API node separate from both PI servers. Thus, it can be moved to the most convenient or secure location.
Data is transferred for a list of points defined in the receiving PI server point database, each of which has a source PI server tag name with which it is associated. A source server tag may be used only once in each scan class.
The data transfer occurs in two steps. First, historical data is retrieved for the points belonging to the interface. The amount of time for which this history is obtained is configurable. When history recovery is completed, continuous scanning for new data is initiated. Tags in one scan class obtain real-time updates. Tags in the remaining scan classes retrieve new data from the source server archive at configurable intervals. The data on the source server will match that on the receiving server best for tags in scan classes that retrieve archived data. Those that receive exceptions from the source server may archive different events than the source tags at the point of transition from the history retrieval step to the real-time data retrieval.
Starting with PIToPI interface version 3.3.4.1, the interface supports a failover mechanism that enables the retrieval of data from either of two redundant source servers. This is explained in detail in the section entitled “Failover Configuration.”
Deployment Scenarios
The PIToPI interface is designed to facilitate the use of PI data in scenarios where the source PI system needs to be isolated from users. Some examples are provided here. In any situation listed below, the original PI server may be protected by a firewall if desired.
Database Load Distribution
If PI data collection must be unhindered by CPU-intensive user queries, the PIToPI interface replicates the original PI data to a second PI system. The second PI system can thus sustain expensive queries from client tools regardless of the response time while the first PI system can promptly respond to process changes.
Database Centralization
Essential data may be sent to a single central PI server from many PI systems. The central server may contain only those points needed for an overview of operations.
Remote Access Speed
A PI server may be accessible only through a limited bandwidth connection. In this case, the limited bandwidth access to the source PI server would make retrieving data for use in clients unreasonably slow. PIToPI enables faster client queries via the receiving PI server.
Interface Requirements
PIToPI requires the following software versions:
· The minimum operating system versions for the PIToPI interface are Windows NT 4.0, HP-UX 10.10, AIX 4.1, OSF1 3.2, or SunOS 5.4.
· PI-API version 1.3.3 or greater is needed. On Windows NT, the interface installation program automatically installs and/or updates the PI-API library. The PI-API must be manually installed first for UNIX nodes.
· TCP/IP connections are needed to both receiving and source PI servers. This interface also operates using RAS to connect over dial-up or ISDN connections. Dial-up connections of 9600 baud have been used successfully.
· Version requirements for PI-ICU: PI Host Server (PI Home Node) requires PI 3.3.361.43 or greater and PI-ICU/Interface node requires PI-SDK 1.1.0.142 or greater (installed by the PI-ICU setup)
Reference Manuals
OSIsoft
· UniInt End User Document
· PI Data Archive Manual
· PI-API Installation Instructions
· PI Interface Status
Supported Features
Feature / Support /Part Number / PI-IN-OS-PI-AIX
PI-IN-OS-PI-DUX
PI-IN-OS-PI-HP
PI-IN-OS-PI-NTA
PI-IN-OS-PI-NTI
PI-IN-OS-PI-SOL
Platforms / AIX / DUX / HP-UX / NTA / NTI / SunOS
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / Integer (16 and 32-bit), Real (16, 32 and 64-bit), Digital, String, Blob
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / PIToPI does either inputs (receives data) or outputs (sends data), but not both in the same instance of the interface.
Inputs to PI: Scan-Based / Unsolicited / Event Tags / Scan-based
Maximum Point Count / Unlimited
Uses PI-SDK / No
PINet to PI 3 String Support / N/A
* Source of Timestamps / See below
* History Recovery / Yes
* Failover / Yes
* UniInt-based / Yes
Vendor Software Required on PI-API / PINet Node / N/A
Vendor Software Required on Foreign Device / N/A
Vendor Hardware Required / N/A
* Additional PI Software Included with Interface / APS Connector
Device Point Types / N/A
* See paragraphs below for further explanation.
Source of Timestamps
The PIToPI interface writes values to the receiving PI system with three possible timestamps. A timestamp may be adjusted for time zone (Location2 = 0), unadjusted (Location2 = 1), or adjusted with time zone and clock differences (Location2 = 2). In the last case, the time differences are checked every two minutes. The mode of adjustment is configurable for each tag.
An unadjusted time stamp means that the local PI time stamp from the source system is used. A time stamp adjusted for time zone is equal to the source time minus the time difference between the source system and the receiving system in integer multiples of 1800 seconds. The time difference between the servers should be less than 900 seconds for an accurate time stamp. Adjusted time stamps should be used when the source system and the receiving system are in different time zones.
When the source and receiving servers are both PI 3 servers, Location2 = 0 produces the same behavior as Location2 = 1; that is, in both cases, the UTC (Universal Coordinated) time is used. The data is therefore archived with identical UTC times in both servers.
If Location2 = 0 or 1 and the client tool, PI-DataLink is used to view this data, the values and time stamps will be the same with PI 3 source and receiving servers. (With a PI 2 source server, if Location2 = 0, timestamps will be offset by the time zone difference.) If PI-ProcessBook is used to trend the same data on the two servers, the times will be offset by the time difference between the two servers. If Location2 = 2, PI-ProcessBook will display the same times and PIDataLink will show the times offset by the time difference between the two PI servers. (With a PI 2 source server, time stamps will be offset by the time zone difference plus the clock difference.)
History Recovery
The PIToPI interface allows specification of the number of hours of history to recover using the /rh=<number> command-line switch or the HistRecovery key in the pitopi.ini file. After the interface starts, as each scan class is serviced, the interface recovers number hours of data from the source PI data archive. If, however, snapshot data exists for a time more recent than this, the time of the oldest snapshot, among all points in the scan class, will be the starting time for history recovery. Archived data will be retrieved for each point starting at the last snapshot time for the receiving point, unless the snapshot value is Point Created. If the receiving system snapshot value of a point is Point Created and the receiving data archive is a PI 3 system, the interface will recover data from the time of the oldest snapshot, even if the timestamps are before the Point Created status. History cannot, however, be recovered before the starting date of the current archive. The receiving PI Data Archive discards any data before the start date of the current archive.
The interface will also automatically retrieve history after a loss of communication between the receiving and source systems. In addition, when new points are added to the interface, history recovery will be done for these points starting from the current receiving data archive time.
There is no limit to the history recovery time. However, recovering large amounts of data may be slow. The /rh_inc parameter specifies the number of hours spanning each archive call. For example, if /rh=48 and /rh_inc=12, four archive calls will be required for the time ranges *-48h to *-36h, *-36h to *-24h, *-24h to *-12h and *-12h to current time (* indicates the current time). This parameter is provided to protect against filling the archive unevenly on the receiving system by retrieving all the data for some points, and having no space left for the last few points. Since each archive call is CPU-intensive, the interval should not, however, be too small.
The historical data that has been retrieved will go through compression on the receiving node if compression is turned on and the receiving server version is less than PI 3.2 SR1 (build 357). This may cause some additional archive values to be eliminated from the data. For this reason, users are advised to run in /hronly mode with compressing off for all PIToPI tags with a receiving server version less than PI 3.2 SR1 (build 357) for exact data matching. (See the section “Principles of Operation” for more information.)
History recovery may also be disabled for all points by setting /rh=0 in the interface startup script.
Note: In some cases, times before the current archive may be desired, but this is only possible if a dated archive is created after the points to be recovered. This allows a primary record to be created in the dated archive in which the data will be stored. Otherwise, the data before the current archive will be discarded. Adding data to old archives with no primary record for a given point could cause severe performance degradation to PI servers.
Failover
PIToPI supports failover in the sense that two identical source servers may be configured for sending data to one receiving server. If one source server fails to send data, due to a disruption somewhere between the control system and the interface node, the interface will try to collect data from the other source server. This is explained further in the section entitled “Failover Configuration.”