PI to PI TCP/IP
Interface Documentation
Version 2.4.0
How to Contact Us
(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web / http://www.osisoft.com
Mail / OSI Software, Inc.
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
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.
ptpxtcp.doc
Ó 2001 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
5/17/2001 5:42 PM 9
Table of Contents
Introduction 1
Deployment Scenarios 1
Interface Requirements 1
Interface Features 2
Principles of Operation 4
Interface Point List 4
Scanning Principles 4
History Retrieval 4
Time Stamp 5
PI Point Configuration 7
Tag Attributes For PIToPI 7
Tag 7
InstrumentTag 7
Exdesc 7
PointSource 8
PointType 8
Location1 8
Location2 8
Location3 9
Location4 9
Location5 10
Shutdown 10
ExcMin, ExcMax, ExcDev and ExcDevPercent 10
Compressing 11
CompDev, CompMin, CompMax, CompDevPercent 11
Zero, Span 12
DigitalSet 12
DigStartCode and DigNumber 12
Scan 12
Dataaccess, Ptaccess 12
Additional Tag Attributes 12
Tag and Node Security 13
PI 3 Security 13
PI 2 Security 13
Receiving and Source System Manager Responsibilities 15
PI 2 Source System Point Limitations 17
Performance Point Configuration 18
Interface Startup Files 19
Interface Startup .bat File - NT 19
Interface Startup .sh File - UNIX Platforms 20
Interface Startup .ini File Used on NT and UNIX 22
Interface Command Line Parameters 24
Interface Installation 26
Windows NT for Intel and Alpha 26
Upgrades 26
Installing the files 26
Modifying the Interface start scripts 27
Modifying the API start and stop scripts 27
Configuring iorate counters 27
UNIX Installation 27
Installing the files 27
Modifying the Interface start scripts 28
Modifying the API start and stop scripts 28
Configuring iorate counters 28
Interface Operation 30
Windows NT Platforms 30
Starting PIToPI interactively 30
Configuring PIToPI to run as a service 30
Shutdown 30
Information and Error Messages 31
UNIX Platforms 31
Starting the PIToPI interface as a foreground process 31
Starting the PIToPI interface as a background process 31
Information and Error Messages 32
Interface Startup Messages 32
Scan Startup Summary 33
Troubleshooting 34
Revision History 36
October, 04 3
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 that it is associated with. 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.
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 would be able to sustain expensive queries from client tools regardless of the response time while the first PI system would be able to 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 overview of operations.
Remote access speed
A PI server may be accessible only through a limited bandwidth connection. In this cas,e 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, 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 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.
Interface Features
The PIToPI interface consists of a single executable program, a startup script that contains the interface identification number and startup information, and an initialization file specifying additional startup information. Data from multiple PI source nodes may be transferred by using additional copies of the interface executable and startup script file for each source/receiving PI node combination or by using additional scan classes in a single PIToPI executable, but each copy of the interface can have only one receiving PI node. If an additional scan class is used for each source node, all but one scan class retrieves archived values (i.e., values that have passed the compression test), rather than obtaining exceptions (new snapshot events). If several copies of the interface are used, each copy of the interface and startup script file should be identified by a unique interface number or point source character.
There is no limit to the number of points for which the PIToPI interface can collect data; however, there are limitations on the number of tags for which the interface can obtain exception reports on a PI 2 source node. See the section “PI 2 Source System Point Limitations” for details.
The PIToPI interface monitors point addition, deletion and editing on the receiving PI node and signs up for exceptions on the source PI node. Thus, if PIToPI is located on the receiving PI node, point updates will be monitored on the local PI node and exceptions will be monitored on the remote PI node. If PIToPI is on the source PI node, point updates will be monitored on the receiving PI node remotely and the exceptions will be monitored on the local PI node.
Inputs from the source systems may be scanned on an exception basis as new exceptions are received on the source system or by retrieving archive history. Since only one scan class in any interface copy can sign up for exceptions, the others can obtain only archived data.
The interface also retrieves archived historical data automatically for all points under three other circumstances. The starting point for retrieval under these circumstances is the time of the last event in the receiving server. These three circumstances are
· at startup
· when points are added
· when a connection is restored after a breach of communication between the source and receiving nodes.
One can disable history recovery in these situations for all tags with a command-line switch. See the section “Interface Startup Files” for details.
PI receiving nodes must allow the PIToPI interface read and write access. PI source nodes must grant read access. PIToPI supports point security as well as node security. PI 3 point security is configured using the tag attributes for data access (dataaccess) and point access (ptaccess). PI 2 point security is configured using a security file located in the PISYSDAT directory. The interface checks every 10 minutes to see if the security status has changed for points in error and it begins data collection for cleared errors. See “Tag and Node Security” for details.
Another feature is the suppression of interface generated digital states. This is useful when communication is lost or the interface is stopped. The data in the source system is copied to the new system without inserting additional digital states (I/O timeout and Access Denied). This is discussed in the section “PI Point Configuration.”
Supported Features /Platforms / Windows NT (intel and alpha), IBM AIX, Compaq Tru64 (OSF1), HP-UX, SUN Solaris (SunOS)
PI Point Types / Integer (16 and 32 bit), Real (16, 32 and 64 bit), Digital, String, Blob
Sub-second Timestamps / Yes
Automatically Incorporates PI Point Attribute Changes / Yes
Exception reporting / Yes
PI software required / PI-API
Outputs from PI / No (a second interface copy will accomplish this task)
Vendor software required / No
History recovery / Yes
Security / Yes
Interface generated digital state suppression / Yes
Maximum Point Count / Unlimited
UniInt-based / Yes
Automatic point attribute synchronization / No [1]
Principles of Operation
Interface Point List
At startup, the interface scans the PI point database for all points with a pointsource and location1 point attribute that match the specifications in the startup file pitopi.bat or pitopi.sh. During runtime, the interface continues to check the receiving system PI Point Database for point updates (additions, deletions and modifications) and modifies its point list accordingly. If a point has a status of ACCESS DENIED, the interface will keep the point in the list and check periodically for access change.
Scanning Principles
Typically, exception reporting is done on the source system. The receiving system then checks for those exceptions with the frequency specified by the scan class. The use of the /sn flag on the command line is therefore recommended, since this directs the interface to put the exception reports from the source server directly into the PI Snapshot of the receiving server. If this flag is not used, the data obtained from the source server will again be subjected to the exception test before it is logged in the PI Snapshot of the receiving server.
Scan classes that have /hronly or HistOnly=1 enabled will not sign up for exceptions on the source system, but will retrieve archived data when the scan class is scheduled. Only one scan class for each copy of the interface can retrieve snapshot data. By default, this is the first scan class listed on the command line. To change the scan class that retrieves snapshot data to another one listed on the command line, the HistOnly=1 parameter must be specified in the scan-class subsections of the pitopi.ini file for all other scan classes.
If data retrieval fails due to an extended communication failure, the digital state I/O Timeout is written to the PI Snapshot for the affected tags, unless this digital state has been suppressed. It is recommended that I/O Timeout be suppressed since the interface has the ability to retrieve history. The interface attempts to reconnect to the source system at two-minute intervals. As long as history recovery is enabled (the default case), the missing data is recovered when communication has been re-established.
History Retrieval
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. When the interface starts, it will recover 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 belonging to the interface, will be the starting time for history recovery. Then, 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 number hours of data, even if the timestamps are before the Point Created status. The amount of history should not, however, contain timestamps before the starting date of the current archive.[2] Any data before the start date of the current archive is discarded by the receiving PI Data 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.
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.