PI to PI TCP/IPcdn.osisoft.com/interfaces/1971/PI_PItoPI_3.4.0.2.doc · Web view-- Name of failover status tag configured on receiving server. This must be specified as: /ist=tagname,

PI to PI TCP/IP (NT / Unix)

Interface

Version 3.4.0.2Revision A

How to Contact Us

Phone (510) 297-5800 (main number)(510) 297-5828 (technical support)

Fax (510) 357-8136

E-mail [email protected]

World Wide Web

http://www.osisoft.com

Mail OSIsoftP.O. Box 727San Leandro, CA 94577-0427USA

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, LtdP. O. Box 8256Level One, 6-8 Nugent StreetAuckland 3, New Zealand

OSI Software, Asia Pte Ltd152 Beach Road#09-06 Gateway EastSingapore, 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. HP-UX

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_document.doc

1997 - 2005 OSIsoft, Inc. All rights reserved777 Davis Street, Suite 250, San Leandro, CA 94577

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

Introduction......................................................................................................................1Deployment Scenarios...................................................................................................1

Interface Requirements..................................................................................................2

Reference Manuals........................................................................................................2

Supported Features........................................................................................................2

Principles of Operation...................................................................................................7

Installation Checklist.....................................................................................................11

Interface Installation on NT...........................................................................................13Naming 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.......................................................................................19Naming 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.......................................................27Point Attributes.............................................................................................................27

PI to PI TCP/IP Interface iii

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...........................................................................................................................35Principles 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................................................................................43Configuring Performance Points with PI-ICU (NT-Intel)...............................................43

Configuring Performance Points Manually...................................................................44

I/O Rate Tag Configuration...........................................................................................45Monitoring 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

iv

Tag and Node Security..................................................................................................49PI 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...................................................................................................55Configuring 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.......................................................................85Starting Interface as a Service.....................................................................................85

Stopping Interface Running as a Service.....................................................................85

Starting / Stopping the Interface on UNIX...................................................................87Command-line Syntax for Background Processes.......................................................87

Terminating Background Processes............................................................................88

Anomalous Background Job Termination....................................................................88

Buffering.........................................................................................................................89Configuring Buffering with PI-ICU (NT-Intel)................................................................89

Configuring Buffering Manually....................................................................................93

Example piclient.ini File................................................................................................94

Appendix A: Error and Informational Messages.........................................................97Message Logs..............................................................................................................97

System Errors and PI Errors........................................................................................97

Interface Startup Messages.........................................................................................97

Scan Summary.........................................................................................................98

Appendix B: Troubleshooting......................................................................................99

PI to PI TCP/IP Interface v

Revision History...........................................................................................................103

vi

IntroductionThe 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 ScenariosThe 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 DistributionIf 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 CentralizationEssential 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.

PI to PI TCP/IP Interface 1

Introduction

Remote Access SpeedA 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 RequirementsPIToPI 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 FeaturesFeature Support

Part Number PI-IN-OS-PI-AIXPI-IN-OS-PI-DUXPI-IN-OS-PI-HPPI-IN-OS-PI-NTAPI-IN-OS-PI-NTIPI-IN-OS-PI-SOL

Platforms AIX / DUX / HP-UX / NTA / NTI / SunOS

APS Connector No

Point Builder Utility No

ICU Control Yes

2

Feature Support

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 PI Point 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 TimestampsThe 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


Introduction

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 PI-DataLink 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 RecoveryThe 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

4

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.

FailoverPIToPI 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.”

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PIToPI interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt End User Document is a supplement to this manual.

Automatic Point SynchronizationThe PItoPI APS Connector (PItoPIAPS) is a specific module that communicates with the Receiving and Source Host PI Systems, gets tag attribute updates from the Source Host PI System, and locates new points on the Source Host PI System. The PItoPI APS Connector and its attendant routines are called up with each synchronization scan.

The PItoPI APS Connector runs on Windows NT or Windows 2000 with the PI-APS Sync Engine and PI-APS Configuration Utility. The NT/2000 node may be a PI server node or a PI-API node. However, OSIsoft recommends that PI-APS be run on a separate PI-API node and not the PI Server home node. The PI server version that PI-APS talks to must be 3.2.354.0 (SR1 beta release 2) or greater. This version of PI ensures compatibility with the PI-SDK version 1.1.


Principles of OperationThe PIToPI interface consists of a single executable program, a startup script that includes 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 (or for the same 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 that have passed the exception test). 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.

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’s 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.

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. In addition, if PIToPI is to be used for sending large amounts of data in real time (by obtaining exceptions), splitting up the tags into multiple copies of the interface can avoid problems with update list overflows. (See the “Troubleshooting” section.)

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 to the source systems may be scanned on an exception basis as new exceptions are received on the source server, or they may be retrieved from the source archive. Since only one scan class in any interface copy can sign up for exceptions, the others can obtain only archived data. By default, the scan class that signs up for exceptions is the first scan class listed on the command line. To change the scan class that retrieves the snapshot data to another one listed on the command line, the HistOnly parameter must be set to 1 in the scan-class subsections of the pitopi.ini file for all other scan classes and to 0 for the scan class that is to receive exception data. In this case, the HistOnly parameter should not be used in the main section of the pitopi.ini file for the particular copy of the interface. This would be equivalent to using /hronly on the command line, and none of the scan classes would sign up for


Principles of Operation

exceptions on the source system in this case; all would retrieve archived data when the scan class is scheduled.

If the user requires an exact match of data between the source and receiving servers, the interface must be run in /hronly mode. If the receiving server is a PI 2 server, compressing must be set to off for all the PIToPI tags. If some tags are to be used for real-time data collection and others are to receive regular updates from the source server archive, OSI recommends that different copies of the interface be used for these different purposes. Running the interface in the mode in which exceptions are obtained from the update manager will result in a small amount of data mismatch for PI 3 receiving servers and a larger amount for PI 2 receiving servers. The only way to avoid data mismatch in this mode of operation is to turn off compressing for both source tags and PIToPI tags.

The interface also retrieves archived historical data automatically for all points in 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 break in communication between the source and receiving nodes.

One can disable history recovery in these situations for all tags by setting the command-line switch /rh=0. See the section “Startup Command File” for details.

The interface many also be used to obtain history for tags only for a specified period of time, after which it exits. This feature is useful for filling in gaps in data archived on a second server. This process is slow, however, if out-of-order data is archived (i.e., if newer data exists in the receiving server after the time period for which data is to be transferred with PIToPI). If there is any data already in the receiving server for this time period, the new events that are retrieved will be appended to the old. Thus one may obtain duplicate events in the receiving archive. In order to fill gaps with this process, one must use the command-line switch, /hronly=t1,t2, where t1 and t2 are the start time and end time, respectively, and are based on the receiving server clocks. The correct format for the timestamps is essential. The interface should be run interactively for a time-range recovery.

Regardless of how the interface is used, PI receiving nodes must allow the PIToPI interface read and write access. PI source nodes must grant read access. In addition to node security, PIToPI supports point security. Node and point security requirements differ for PI 2 and PI 3 servers. 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 the section “Tag and Node Security” for details.

PIToPI is capable of suppressing interface-generated digital states. This is useful when communication is temporarily lost or the interface is stopped. Normally, the digital state I/O Timeout would be written to the PI Snapshot for the affected tags;

8

however, if this digital state has been suppressed, the data in the source system is copied to the receiving system without inserting the additional digital states. The digital state, AccessDenied, may also be suppressed. This state would be written to tags for which the interface did not have read permission. However, since the interface is capable of recovering history once the security permissions are changed, it is recommended that this digital state be suppressed, too. This is discussed in the section “PI Point Configuration.”

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.


Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this checklist helps you get the PItoPI interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.

The steps below should be followed in the order presented.

1. On NT, install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)

2. On UNIX platforms, install the PI-API. See the PI-API Installation Instructions for more information. (The PI-API is part of the installation kit for NT.)

3. Install the PItoPI interface. For UNIX, this means copying the files to the correct directories. For NT, this means using the install kit.

4. Define digital states on receiving node.

5. Choose a point source. If PI 2 home node, create the point source.

6. Configure PI points.

7. Configure performance points.

8. Configure I/O rate tag.

9. Set up tag and node security.

10. Edit startup command file.

11. Start the interface.

12. Verify data.

Note: Buffering is not recommended for this interface.


Interface Installation on NTOSIsoft generally recommends that interfaces be installed on PI Interface nodes instead of directly on the PI Server node. A PI Interface node is any node other than the PI Server node where the PI Application Programming Interface (PI-API) has been installed (see the PI-API Installation Instructions manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. However, since pitopi is used solely for transferring data between PI servers, it may be installed on either server node or on a PI Interface node.

In most cases, if the interface is installed on a PI Interface node, it should be installed as an automatic service. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files.

Note: The buffer server is installed and configured as well. For the PIToPI interface, it is not recommended to enable buffering. Buffering may be enabled later through the control panel\Services applet, if needed.

Naming Conventions and RequirementsIn the installation procedure, it is assumed that the name of the interface executable is pitopi.exe and that the startup command file is called pitopi.bat.

It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use pitopi1.exe and pitopi1.bat for interface number 1, pitopi2.exe and pitopi2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a file that has the same root name.

Interface Directories

The PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the WinNT directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\pipc

The above lines define the \pipc directory as the root of the PIHOME directory tree


Interface Installation on NT

on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryIt is recommended to place all copies of the interface into a single directory. The suggested directory is:PIHOME\interfaces\pitopi\

Replace PIHOME with the corresponding entry in the pipc.ini file.

Note: All PIToPI interface files are installed into PIHOME\interfaces\pitopi. If multiple copies of the interface are already installed with names other than pitopi, they will not be upgraded. Upgrade of multiple interfaces should be done by manually copying the executable files and startup files.

Interface Installation ProcedureThe PItoPI interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the PItoPI setup program will install the Windows Installer itself if necessary. To install, run the PItoPI_x.x.x.x.exe installation kit.

Installing the Interface as an NT ServiceThe PItoPI interface service can be created, preferably, with the PI-Interface Configuration Utility, or can be created manually.

14

Installing the Interface Service with PI-Interface Configuration UtilityThe PI-Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service. For instance:

Service Configuration

Service NameThe Service to Add box shows the name of the current interface service. This service name is obtained from the interface executable.

Display NameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSI suite of products.

Service TypeThe Service Type indicates whether the interface service will start automatically or need to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.


Interface Installation on NT

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependant should be moved into the

Dependencies list using the button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the

left. To remove a service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI-ICU dialog.

16

Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Installing the Interface Service ManuallyOne can get help for installing the interface as a service at any time with the command:pitopi.exe –help

Change to the directory where the pitopi1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

NT Service Installation Commands on a PI Interface Node or a PI Server Node

without Bufserv Implemented

Manual service pitopi.exe –install –depend tcpip

Automatic service pitopi.exe –install –auto –depend tcpip

When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.

Note: Interfaces are not typically installed as automatic services when the interface is installed on the PI Server node.

Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.


Interface Installation on UNIXOne of the first issues that must be resolved is where the interface should be installed. Should the interface be installed on the PI Server node or on a remote PI-API node? For most interfaces, OSIsoft recommends installation on a remote PI-API node since the primary function of the server node is to archive data and to service the clients that request that data. However, since pitopi is used solely for transferring data between PI servers, it may be installed on either server node or on an API node.

The PI-API must be installed prior to installing the interface. The shared library path environment variable must be defined; and, if I/O Rates tags will be used, the default PI home node must be set to the receiving server node in the piclient.ini file. It is not recommended to enable buffering since the interface recovers data after connections are restored. Refer to the PI-API Installation Instructions manual for more information on installing the PI-API. PI-API version 1.3.8 is required, which was only built against ANSI compilers on Solaris and HP-UX.

Once the PI-API is installed, the interface can be configured to start and stop with the PI-API using site-specific scripts, as described in the installation procedure below.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that one copy of the interface is used, and that the name of the interface executable is pitopi and the startup command file is called pitopi.sh.

To run multiple copies of the interface, create a soft link from the pitopi executable to the name used for the new interface instance, e.g., pitopi2. Make these links by issuing the command, ln –s pitopi pitopi2 (for interface number 2). Then the startup script file, pitopi.sh, must be modified to add the information for the additional copies of the interfaces. See the section “Startup Command File” for more information.

pitopi.ini and pitopi.shAll copies of the interface (executable and batch file) may reside in the same directory. In this case, only one pitopi.ini and one pitopi.sh file are required. These files have separate sections for each copy of the interface. If other copies of the interface are placed in separate directories, each directory must have one pitopi.ini and one pitopi.sh file, but in either case, the filename of the .ini should always be pitopi.ini, without any numbers.

Interface Directories

The PIHOME DirectoryPIHOME is an environment variable that points to the base directory where the PI-API is installed. This variable must be set prior to installing the interface. A commonly


Interface Installation on Unix

used directory for PIHOME is /opt/piapi. More information on setting the environment variables is available in the PI-API Installation Instructions manual.

Interface Installation DirectoryThere are two conventions for the installation directory. The recommended convention is to place all copies of the interface into a single directory. If this convention is followed, the files should be placed in the directory:$PIHOME\interfaces\pitopi\

The second convention is to create a separate interface directory for each copy of the interface. If this convention is followed, it is recommended to place pitopi, pitopi2, pitopi3, etc., in the directories:$PIHOME\interfaces\pitopi\$PIHOME\interfaces\pitopi2\$PIHOME\interfaces\pitopi3\

and so on.

Interface Installation ProcedureIn the installation procedure below, it is assumed that one copy of the interface is being installed.

The interface installation kit includes the executable file, pitopi, startup files pitopi.sh and pitopi.ini, automation scripts addtostart and addtostop, the release notes, and the manual. The kit comes in the form of a compressed tar file.

1. Back up the current pitopi directory, if you have one.

2. Change to the $PIHOME directory to extract the interface distribution files. Use the command zcat path/filename | tar -xvf - . Here, path is the directory location of the tar file and filename is the name of the file, for example ptpxtcp307_OSF1_tar.Z. If the file is on a CD-ROM, mount the CD-ROM drive and use the appropriate path name for the CD-ROM drive. If you are unable to find the correct device name for mounting the CD-ROM, contact your system administrator. When the files are extracted, they are placed in the directory ./interfaces/pitopi, which is created, if necessary.

3. Change to the directory ./interfaces/pitopi. Copy the file pitopi.sh.new to pitopi.sh if the latter does not already exist. Alter the command-line arguments in the pitopi.sh file as discussed in the section “Startup Command File.”

4. Concatenate the automation scripts, addtostart and addtostop, to the site-specific startup files, sitestart and sitestop (in $PIHOME/bin), by issuing these two commands: cat $PIHOME/interfaces/pitopi/add2start >>

$PIHOME/bin/sitestart cat $PIHOME/interfaces/pitopi/add2stop >>

$PIHOME/bin/sitestop.

20

Edit the sitestart and sitestop files to add additional pitopi startup lines if more than one interface copy will be used.


Digital StatesDigital states are defined differently in PI 2 and PI 3. In order to have matching digital states written to tags on the source and receiving servers, the digital state code numbers and strings must match on the two servers.

PI 2 Receiving NodeDigital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 - 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.

For more information, see the PI System Manual I (the DA manual).

PI 3 Receiving Node

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all tags, regardless of point type, to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state Bad Input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.

For more information about PI digital tags and editing digital state sets, see the PI Data Archive Manual for Windows NT and Unix manual.

Digital State CachingPI digital states in the sets used by tags in the interface scan list are cached on startup. During history recovery and each history-only scan, these cached states are checked when archived events are obtained for digital pitopi tags with string source server tags. If the string from the source server tag matches a string in the digital state set for the tag, the event is converted to a digital event for the pitopi tag. If the string is not recognized, no data is sent to PI for this event. A message is printed in the pipc.log once if this occurs.


PointSourceThe PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, one may choose the letter P to identify points that belong to the PIToPI interface. To implement this, one would set the PointSource attribute to P for every PI Point that is configured for the PIToPI interface. Then, if one uses /ps=P on the startup-command line of the PIToPI interface, the interface will search the PI Point Database upon startup for every PI point that is configured with PointSource P. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the sections “PI Point Configuration” and “Startup Command File.”

Case-sensitivity for PointSource AttributesIn all cases, the point source character that is supplied with the /ps command-line argument is not case-sensitive. That is, /ps=P and /ps=p are equivalent. One only needs to be careful with the case of the PointSource during point definition, and only if the interface will be running on a PINet node communicating to a PI 3 Server.

PI 2 Server NodesThe following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. If one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.

Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source P is not defined in the PI 2 point source table, a point with a point source of P cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.

Defining a Point Source Character in the PI 2 Point Source Table

1. Enter PI by typing the following command from a VMS command prompt: @pisysexe:pi

2. Select the PointSrc option from the menu.

3. Select New from the menu.

4. Assign a point source next to the “Code:” field. Assign minimum and maximum values for the Location1 to Location5 attributes.

Location1 Location2 Location3 Location4 Location5

Minimum -20000000 -20000000 -20000000 -20000000 -20000000

Maximum 20000000 20000000 20000000 20000000 20000000

5. Select “Save” from the menu.


PointSource

PI 3 Server NodesNo point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. If one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. PointSource L is typically used for lab (manual entry) tags. Therefore, it would be confusing to use L as the point source character for an interface.

26

Point Configuration on the Receiving PI SystemThe following tag attributes are necessary for defining a PI point on the receiving PI system for the PIToPI interface. If the receiving PI system is a PI 3 server, the point class should be classic. No change in configuration is required for the points on the source system. However, the interface must have access permissions to read the data.

Point Attributes

TagThis is the receiving PI tag name. It is a required field and is limited to 80 characters. The PI 2 tag name attribute longname is used if it exists. This attribute does not need to be the same as the source tag name. However, if the receiving tag attributes instrumenttag or exdesc do not specify the source tag name, the receiving tag name is assumed to be the same as the source tag name.

PointSourceThe pointsource character and the interface identification number specify the points belonging to the interface. See the description of the Location1 parameter below for details on the interface identification number. The point source character specified for the tag in this field must match the point source specified for the interface in the startup command file. Otherwise, the points will not be scanned by the PIToPI interface. See the section “Startup Command File” for more information on the startup command file.

The point source is a single character (for example P) and is case insensitive. For PI 2 systems, you must define the point source in the point source library before starting the interface.

PointTypeThe interface supports all PI point types. For PI 2 systems, the types are R (float16 and float32), D (digital) and I (int16). For PI 3 systems, the types are float16, float32, float64, int16, int32, digital, timestamp, string and blobs.

If the point type is not the same on the source and receiving systems, the PIToPI interface uses the source system point type when sending data to the receiving PI system. For a PI 3 server, the server performs any needed conversions. For a PI 2 server, the PI-API attempts to convert a string into a valid PI 2 point type by first, attempting to interpret it as a float, second, interpreting it as an integer, third interpreting it as a digital state. This mechanism may be used to translate string tags on the source system to digital, float or integer tags on the receiving system.

Location1The first location code contains the interface identification number. The pointsource and location1 combination identifies the points for which this copy


Point Configuration on the Receiving PI System

of the interface collects data. Both point attributes must match the interface command-line parameters. See the section “Interface Startup Files” for information on specifying the interface identification number on the command line.

Location2The location2 attribute determines the method for setting the timestamp for values transferred from the source to receiving PI servers. Three choices are available:

The timestamp may be adjusted for the time zone difference between the source and receiving PI servers by setting location2=0. A time stamp adjusted for time zone difference is equal to the source time minus the time difference between the source system and the receiving system in integer multiples of 1800 seconds. Adjusted time stamps should be used when the source system and the receiving system are in different time zones.

The timestamp may be left unadjusted from the source server time by setting location2=1. An unadjusted time stamp means that the local PI time stamp from the source server is used. The local PI time stamp includes time zone offsets from UTC time on the source PI server. Thus, if the source and receiving servers are in different time zones, the data will be in the future or past, which may result in rejected data.

The timestamp may be adjusted for the time zone and clock differences between the source and receiving PI servers by setting location2=2. This would compensate for any relative drift between the clocks of the source and receiving PI servers. The effect would be to make the receiving PI server the master timekeeper. However, the relative drift is not tracked in time (i.e., there is no way to know whether the time offset changes).

With two PI 3 servers, setting Location2=0 confers the same behavior as setting Location2=1, since UTC time is used in this case.

Location3The third location parameter is used to control whether interface-generated digital state codes are written to the point, as well as to specify whether the current snapshot on the source will be written to the receiving server when retrieving archived data. The paragraphs and the table below detail the use of this parameter.

Write “I/O Timeout”I/O Timeout digital state will be sent to the receiving node for this point when the interface can’t communicate with the source node and location3 equals 0, 2, 4, or 6.

Write “Access Denied”ACCESS DENIED digital state will be sent to the receiving node for this point when the source node or the receiving node has read access denied and location3 equals 0, 1, 4, or 5.

Include SnapshotBy default archived data is retrieved from the source server for history-only scan classes up until, but not including, the latest snapshot. By setting Location3 to 4, 5,

28

6, or 7 one can also obtain this latest snapshot. This could, however, result in the archiving of data that would normally be filtered by the compression test. It is therefore not a recommended setting for tags with compression on, but would be of interest in only a few cases, such as for manual inputs.

Location3 Write ”I/O Timeout”

Write”Access Denied”

Include Snapshot

0 Yes Yes --

1 -- Yes --

2 Yes -- --

3 -- -- --

4 Yes Yes Yes

5 -- Yes Yes

6 Yes -- Yes

7 -- -- Yes

Recommended SettingThe recommended setting is Location3=3 to suppress interface-generated digital states.

Other Examples If both suppression of the digital states and use of the latest snapshot are desired, set Location3=7.

To suppress Access Denied, but not I/O Timeout, and to use the latest snapshot set Location3=6.

Location4The fourth location parameter is used to specify the Scan Class Number to which this point is assigned. The scan class number refers to the ordered frequency specification (/f) in the interface startup file. The frequency and offset (described in the section “Startup Command File”) determine when processing of points in the scan class occurs. If location4=0, scan class 1 is assumed. Tags with negative values and values greater than the number of scan classes defined on the command line are rejected.

Location5The fifth location parameter is used for points that require manual editing (e.g., lab tags.) The default value is 0, and this is the recommended setting for all tags for which manual data editing is not desired. The following table summarizes the possible settings.

PI Server Version Location 5 Edit Snapshot Value Edit Archived Value

3.2.357.17 or higher

0 Appends new value Leaves old value



2 Replaces value Replaces value

3 Replaces value ** Replaces value **

2.3 0 Replaces value Leaves old value

1 Leaves old value Leaves old value



2.4 0 Appends value Leaves old value

1 Leaves old value Leaves old value



**Note: Location5=2 replaces the old value without reporting the change. Location5=3 replaces the old value and reports the change (with old and new values) in the log file.

Setting Location5 to 2 or 3 enables new values to be sent to the receiving server after they have been changed on the source server. Setting Location5 to 3 also prints a message to the log file stating that the value of the tag was changed along with the old value and new value. No point type conversions are allowed when replacing lab values. For PI 2 receiving nodes, if the user does not expect to edit data for a tag, OSI strongly recommends setting Location 5 to 0.

InstrumentTagThe instrument tag defines the tag name to be retrieved from the source PI system. Names entered into the instrument tag attribute are searched first. If the instrument tag is empty, the extended descriptor is searched for STAG= and that tag name is used. If neither instrument tag nor extended descriptor has a tag name, the receiving tag name is used for the source tag name. Consequently, if the tag name on the receiving PI system is different from the tag name on the source PI system, the source tag name should be entered into the instrument tag or the extended descriptor field

The instrument tag field is used for tag names of 32 characters or less. The extended descriptor is used for longer tag names and for tag names that contain commas.

ExDescThe extended descriptor may be used as an alternative source tag specification by using the keyword STAG=<tag name>. The extended descriptor field can hold up to 79 characters; therefore a tag name specified here is limited to 74 characters. If additional information is included after the STAG specification, the tag name should be terminated with a comma.

If the source tag name contains a comma within it, it should be enclosed in quotes. For example, STAG=”batchreactor1,temp” is a legitimate way to define a source tag name.

The extended descriptor is also checked for the string PERFORMANCE_POINT. If this character string is found, this point is treated as a performance point (see the section called “Performance Points” below). No source PI system data will be retrieved for this point.

30

ScanIf the Scan attribute is set to false (0), it will not be added to the interface. If the Scan attribute is changed from true to false (1 to 0), the digital state Scan Off will be written to the point and it will be removed from the interface point list.

ShutdownNote: It is recommended that this feature be suppressed for all PIToPI points since the PIToPI interface has the ability to recover history, which may contain valid data from another PI node, during the shutdown time.

PI 2 Server NodesThe Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.

PI 3 Server NodesThe shutdown attribute is used only if the server node is a PI 3 system.

The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line argument is specified.

One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.

ExcMin, ExcMax, ExcDev and ExcDevPercentThese are the exception reporting attributes. They are used to define the parameters used to filter out data that does not change enough to be significant. Note that there is no ExcDevPercent attribute for PI 2 servers. Instead, the units of ExcDev are determined by the DeviationUnits attribute.

The data entering the source system snapshot may have previously undergone exception processing. The PIToPI interface allows additional exception processing. Exception values that PIToPI retrieves from the source system queue will undergo additional exception processing if /sn is not specified in the startup file. During history recovery, this additional exception processing is not performed.



ExcMin is the exception minimum time, ExcMax is the exception maximum time, and ExcDev is the exception deviation or dead band. For PI 2, ExcDev is defined in terms of engineering units or in terms of percent of the Span attribute, depending on how the DeviationUnits attribute is set. For PI 3, ExcDev is always defined in terms of engineering units.

For PI 3, ExcDev is related to ExcDevPercent byExcDev = ExcDevPercent * Span / 100

where Span is defined by the Span PI point attribute. If either ExcDev or ExcDevPercent is changed, the other is automatically updated to be compatible. If both are changed at once, ExcDevPercent takes precedence.

Raw values are said to “pass exception” if:

1) The difference between the new value and the last value that passed exception is greater than ExcDevandthe difference between the times of the new value and the last value that passed exception is greater than ExcMin.

or

2) The difference between the times of the new value and the last value that passed exception is greater than ExcMax.

The last value that passed exception is called the “old value.” The next value that passes exception is called the “new value.” The last value that was received by the interface before the new value is called the “previous value.” There will not be a “previous value” if the interface did not receive a value between the “old value” and the “new value.” When a new value passes exception, the previous value and the new value will be sent to the snapshot. The new value will then become the old value, and the cycle continues.

The time between exceptions can be greater than the ExcMax if no new values are received by the interface for a point.

Note that the “previous value” will be sent to PI even if it was received before ExcMin seconds had expired. ExcMin applies only to the “new value.”

CompressingIf the compressing attribute is set to 1 (ON), then the compression specifications below are used to filter the data that is passed from the snapshot to the archive.

The compression algorithm is executed in the snapshot subsystem, not in the interface.

CompDev, CompMin, CompMax, CompDevPercentThese are the compression specifications. The interface does not use these attributes. However, they must be identical between the two PI servers to produce the same archive data. CompDev is the compression deviation, CompMin is the compression minimum time, and CompMax is the compression maximum time. CompDevPercent and CompDev are related by:CompDev = CompDevPercent * Span / 100

32

where Span is defined by the Span PI point attribute.

The swinging-door algorithm is used to filter the data. For PI 3 servers, the algorithm is described in the PI Data Manual. For PI 2 servers, the algorithm is described in the Data Archive (DA) section of PI System Manual I.

PIToPI adds data to the receiving system archive for PI 3.2 build 357 and greater PI systems. For all other systems, data is added to the snapshot. Addition to the snapshot may cause additional compression during history recovery.

For all PI servers during scanning for new exceptions, the data added to the receiving snapshot is compressed according to the receiving system specifications. If the compression specifications are identical on the source and receiving systems, the compressed data will be identical.

DataAccess, PtAccessPI 3 nodes use these attributes to control client read/write access to the data and point attributes. Access may be specified for owner, group and world. The user and groups used must be created before assignment. Example: dataaccess=o:rw g:rw w:r, ptaccess=o:rw g:r w:r.

Zero, SpanThese attributes should match for the source and receiving points.

PI 2 Server NodesFor a PI 2 server, the Zero and Span attributes are required for scaled integers and scaled floating points because the value of the Zero and Span attributes affects the data representation in the archive for these point types. The Zero and Span attributes do not affect the data representation of full-precision floating points. See the Data Archive (DA) section of PI System Manual I for more information.

PI 3 Server NodesFor PI 3 servers, the Zero and Span attributes are required for PI point types of Int16 and Float16 because the value of the Zero and Span attributes affects the data representation in the archive for these point types. The Zero and Span attribute does not affect the data representation of points of any other type. See the PI Data Archive Manual for NT and UNIX for more information.

For digital PI points, one must not define the Zero and Span attributes because they are set internally by PI when a digital point is created. Zero will be set to 0 and the Span will be set to the number of digital states in the set.

Additional Tag AttributesThe following tag attributes are not unique to the PIToPI interface but are required for proper operation. These parameters are listed below:

Note: To duplicate the archived source data, the filter code should be 0, and the resolution code (PointType on PI 3) and compression specifications should match those on the source system.



Descriptor Typical Value Engineering Units Filter Code Archiving Flag Resolution Code

Point Attributes not used by the interface are:

Square Root Code Totalization Code Conversion Factor Step

34

Failover

Principles of Operation

Figure1: PI Failover Configuration Diagram

The PIToPI interface failover configuration requires the receiving PI server to be connected to two source PI servers with identical data. The data stored in the source PI servers must be kept in sync via redundant data streams from the instrument system. In order to preserve data consistency on the receiving PI server it is essential that the source PI servers have identical data. In addition it’s required that all participating PI servers are PI3. The build will be checked at startup. If the any of the participating PI servers are PI2, the interface will exit.

On startup the interface connects to both source servers to obtain tag lists and initialization information. It then begins replicating data from the primary PI source server thus making it the active node. On startup the secondary PI source server takes the standby role. Users are required to specify a primary and secondary PI source server in the interface startup file.

There are two conditions that will cause the interface to initiate failover. If the interface looses connectivity to the active PI source server it will attempt to failover to the standby PI source server. The second failover condition happens when the interface detects the active PI source server is no longer receiving current data from the instrument system. This information is obtained via the Interface Status Utility. In order for failover to be successful the interface must be able to connect to the standby


Standby

Receiving PI3 ServerPI-to-PI Interface

Source PI3 ServerInterface Status Utility

Source PI3 ServerInterface Status Utility

Active

Instrument System

Failover Configuration

source PI server and its Interface Status Utility tag must indicate it is actively receiving updates from the instrument system.

The Interface Status Utility is a separate application that monitors the update rate between a PI server and data source to detect when data goes stale. It writes the current interface status to a digital tag that resides on the source PI server. For example if the data is being actively updated on the source server the utility may write a value of ‘Receiving Data’ to the status tag. If the updates stop, thus causing the data to go stale it may write a value of ‘Not Receiving Data’. By monitoring the current value of this digital status tag on both source servers the PIToPI interface is able to maximize data availability for the receiving PI server.

Note: It is the user’s responsibility to ensure the Interface Status Utility is setup on each source PI server prior to implementing PIToPI failover. The Interface Status Utility is not included as part of the PIToPI interface installation. Please call our techsupport number (510-297-5828) to obtain a copy of this program. Complete documentation for the Interface Status Utility is distributed during installation or can be obtained from our support site (support.osisoft.com).

The user has the option of specifying two PIToPI interface failover status tags in the startup file to track interface performance. In this configuration the interface will log status information regarding failover and internal state status to separate PI digital tags that exist on the receiving PI server. These tags are mutually exclusive meaning a user can choose to specify one or both status tags.

Failover Conditions and Configurations

Loss of Connectivity The primary failover condition is if the PIToPI interface looses connectivity to the active source PI server. There are many points of failure for loss of communication; temporary network upsets, shutdown of the active source PI server, hardware failure, etc. The interface has no way of identifying the actual cause of the communication failure. The symptom the interface will encounter is it sent a request to the active source PI server but did not receive a response within the configured timeout period. When this happens the interface will initiate a short wait period then attempt to reconnect to the active source server. The number of reconnection attempts and wait period are configurable interface parameters. If subsequent connection requests fail it will attempt to failover to the standby source PI server. Upon successful failover the interface will perform history recovery then begin normal data replication. If it also unable to connect to the standby server it will enter a connection loop until it successfully connects to the first available source PI server.

Related Interface Startup SwitchesThe following table contains a list of interface switches that allow a user to tune loss of connectivity interface behavior.

36

Startup File INI Description

/nt=

Default: /nt=1

-- Number of connection attempts after initial loss of connectivity to source PI server. Use this switch to tune interface sensitivity to network disruptions. The more connection attempts the less sensitive the interface will be to temporary network upsets thus preventing failover ‘flip flop’. Less connection attempts increases the interface response to disruptions in data replication.

/delayr=

Default: /delayr=120000 (2 minutes)

-- Set time delay between reconnection attempts to receiving PI server after a disruption.

Number specified as milliseconds. Valid values are 1000 - 28800000 (1 second to 8 hours).

Adjusting the API Timeout PeriodIn addition the following procedure describes how to modify the PI-API timeout period. This timeout period determines how long the interface waits for a response from a given PI server before assuming the connection is lost:

Open the pilogin.ini file located in \pipc\dat directory

Locate the [NETWORK] heading within this file. If one does not exist, add it to the end of the file

Look for the TIMEOUT parameter. If this parameter exists modify the existing value which has units of seconds. The default timeout is 60 seconds. If this parameter does not exist add it using the format:

[NETWORK]

TIMEOUT= <seconds>

Close and save the file.

A restart of each PI client is required in order for the new setting to take effect. This includes the PIToPI interface.

Detection of Stale DataA secondary cause for failover is if the interface detects a disruption in data flow from the instrument system to the source PI server. This information is acquired via the Interface Status Utility. The Interface Status Utility monitors the update frequency of a watchdog tag. If the watchdog tag does not receive a new value within an expected time period the Interface Status Utility updates its status tag to indicate the data has gone stale. The PIToPI interface monitors the value the status tag to determine if there has been a disruption in data flow to a given source server. Whenever possible the PIToPI interface will be connected a source PI server that is actively receiving data.

When configuring the Interface Status Utility users will want to select a watchdog tag that under normal conditions receives consistent high frequency updates. For example some instrument systems expose their system time for client access. In this scenario a user would setup an interface tag to read this value then configure the Interface Status Utility to use this as the watchdog tag. On the interface side the watchdog tag would



be configured to either receive unsolicited updates (if this update method is supported by the instrument system) or assign it to a high frequency scan rate (for example a one second scan class). It is also recommended the watchdog tag have exception reporting disabled (tag attributes excdev=0 and excdevpercent=0) to prevent any updates from being filtered by compression. In this setup the Interface Status Utility might be configured to write a stale data value to its status tag if it detects that the system time watchdog tag has not updated within 5 seconds. The underlying assumption being that the system time watchdog tag updates every second therefore if it has not received an update with 5 seconds all data from the instrument system has also gone stale. The 5 second wait period is a configurable Interface Status Utility parameter.

When the PIToPI interface detects the active source PI server has stale data it will attempt to failover to the standby source PI server. Upon successful connection to the standby source PI server it checks the current value of its Interface Status Utility status tag. If the value indicates it is currently receiving data the standby source PI server becomes the active server and the interface resumes data replication.

Related Interface Startup SwitchesThe following table contains a list of interface switches required for the interface to monitor the status of data updates on the source PI servers:


/ssu1= -- Name of PI Interface Status utility tag configured on source server defined in src_host. This must be specified as: /ssu1=tagname, where tagname is the PI point attribute Tagname.

/ssu2= -- Name of PI Interface Status utility tag configured on source server defined in sec_src. This must be specified as: /ssu2=tagname, where tagname is the PI point attribute Tagname.

Monitoring Interface and Failover Status The PIToPI interface has the optional functionality of outputting data to two separate interface status tags. The Failover Status tag is a digital tag that will reside on the receiving PI server. When configured to do so the interface will update this tag to indicate the current failover status of the interface. This information indicates whether the interface is currently collecting data from the primary source PI server, the secondary source PI server, in the processes of failing over or attempting to gain connection to a source PI server. The Internal State tag is also a digital tag that will reside on the receiving PI server. When configured to do so the interface will update this tag to indicate if the interface is currently in startup, recovering history, scanning for data, unable to gain permission to read/write data, unable to communicate to the receiving PI server, unable to communicate to the source PI server or in the process of shutting down.

These status tags are optional and mutually exclusive. This means the user can opt not to use them, use only one or configure the interface to use both. The status

38

information is useful for monitoring interface performance and assisting with troubleshooting investigations.

Status Tag ConfigurationsIn order to take advantage of this functionality the user will need to create a digital PI tag on the receiving PI server for each status. An associated PI digital state set must also be defined for each interface status tag.

The digital state set for the Failover Status tag must have the following states:

0. RETRYINGCONNECTION

1. DATAFROMPRIMARYSRC

2. FAILOVER

3. DATAFROMSECONDARYSRC

It’s not required that the verbiage of the digital states be the same as above. However it is required that the same information be described for each position in the digital state set (the 0 state must indicate the interface is retrying a PI server connection, the 1 state must indicate data is being collected from the primary source server, etc).

The digital state set for the Internal State status tag requires the following digital states:

0. INTFSTARTUP

1. RECOVERINGHISTORY

2. INTFSCANNING

3. INTFSHUTTINGDOWN

4. ACCESSDENIED

5. SRCSRVCNXTBAD

6. RCVSRVCNXTBAD

Again it’s not required that the verbiage be as described above but the same information must be represented in each corresponding digital state (the 0 state must indicate interface startup, the 1 state must indicate it is performing history recovery, etc).

These digital state sets can be created in one of two ways. The preferred method is to user the PI-PointBuilder application to create a new digital state set:



The PI-PointBuilder application is part of the PI-SMT v2.x distribution kit and can be run from any client machine. A copy of this program can be obtained by contacting our technical support team.

Alternatively the PI server command line utility piconfig can be used to create the required digital state sets:

40

The following table contains the required tag attributes for the digital PI tags to be created on the receiving PI server:

Attribute Value

PointSource L

PointType Digital

Compressing 0

ExcDev 0

DigitalStateSet As defined in the receiving PI3 server digital state database.

Related Interface Startup SwitchesThe following table contains the interface switch used to specify the optional interface status tags:


/fst= -- Name of failover status tag configured on receiving server. This must be specified as: /fst=tagname, where tagname is the PI point attribute.

/ist= -- Name of failover status tag configured on receiving server. This must be specified as: /ist=tagname, where tagname is the PI point attribute.

Failover Interface Startup Switches

The following table contains a list of interface startup switches used to configure PIToPI failover behavior:


/host=

Required

ReceivingHost Name of receiving PI node. The node name may be specified as /host= node_name:tcpip_port where the port number will be either 545 or 5450.

Unlike other parameters found in the INI file, ReceivingHost cannot be overridden on a scan class per scan class basis.




/src_host=

Required

SourceHost Name of primary source node to retrieve data from. This must be specified as: /src_host=node_name:tcpip_port where the port number will be either 545 or 5450.

/sec_src=

Required

-- Name of secondary source node to retrieve data from. This must be specified as: /sec_src=node_name:5450 where 5450 is the tcpip port number.

/ssu1=

Required

-- Name of PI Interface Status utility tag configured on source server defined in src_host. This must be specified as: /ssu1=tagname, where tagname is the PI point attribute Tagname.

/ssu2=

Required

-- Name of PI Interface Status utility tag configured on source server defined in sec_src. This must be specified as: /ssu2=tagname, where tagname is the PI point attribute Tagname.

/nt=

Default: /nt=1

-- Number of connection attempts after initial loss of connectivity to source PI server. Use this switch to tune interface sensitivity to network disruptions. The more connection attempts the less sensitive the interface will be to temporary network upsets thus preventing failover ‘flip flop’. Less connection attempts increases the interface response to disruptions in data replication.

/delayr=

Default: /delayr= 120000 (2 minutes)

-- Set time delay between reconnection attempts to receiving PI server after a disruption.

Number specified as milliseconds. Valid values are 1000 - 28800000 (1 second to 8 hours).

/fst=

Optional

-- Name of failover status tag configured on receiving server. This must be specified as: /fst=tagname, where tagname is the PI point attribute.

/ist=

Optional

-- Name of interface status tag configured on receiving server. This must be specified as: /ist=tagname, where tagname is the PI point attribute.

42

Performance Point ConfigurationThe PIToPI interface may be configured with performance points, however, the meaning of the performance data must be interpreted as the length of time to accomplish the given task. These tasks may be either to retrieve exceptions or retrieve history. Additionally, several tasks may cause some scans to take substantially longer than normal. These are the initial scan in which history is retrieved or whenever a disconnection occurs, whenever new points are added for which history is required, or PI 2 source server tag security checks. Unlike traditional interfaces, this does not mean that data is lost, even if many scans are skipped.

One can configure performance points to monitor the amount of time in seconds that an interface takes to complete a scan for a particular scan class. The closer the scan completion time is to 0 seconds, the better the performance. The scan completion time is recorded to millisecond resolution.

Configuring Performance Points with PI-ICU (NT-Intel)The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing Performance Points.

To create or delete a Performance Point, right mouse click the line belonging to the tag to be created, and click Create or Delete. If a tag already exists, the status is marked “Created”, the Delete option will be enabled. If a tag does not exist, the status is marked “Not Created” or “Deleted”, and the Create option is enabled.

The Performance Points are created with the following PI attribute values:

Attribute Details

Tag Tag name that appears in the list box

Point Source Point Source for tags for this interface, as specified on the first tab


Performance Point Configuration

Compressing Off

Excmax 0

Descriptor Interface name + " Scan Class # Performance Point"

Status

The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2. If a Performance Point does exist, a status of “Created” is displayed. If the Performance Point does not exist, a status of “Not Created” is displayed. If a Performance Point exists, and is deleted, a status of “Deleted” is displayed.

Scan Class

The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the Uniint Parameters tab.

Tagname

The Tagname column holds the Performance Point tag name.

Configuring Performance Points ManuallyPerformance point configuration is the same on all operating system platforms. Performance points are configured as follows.

1. Set the extended descriptor to:PERFORMANCE_POINTor to:PERFORMANCE_POINT=interface_idwhere interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.

2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of scan classes.

3. Set the PointSource attribute to correspond to the /ps flag on the startup command line of the interface.

4. Set the PointType attribute to float32.

44

I/O Rate Tag ConfigurationAn I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.

The rate at which events are added by PIToPI may vary greatly during history recovery, thus a point type of float32 is recommended.

Monitoring I/O Rates on the Receiving NodeFor NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.

Configuring I/O Rate Tags with PI-ICU (NT-Intel)The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing I/O Rates Tags.

PI-ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rates tags.

Enable IORates for this InterfaceThe Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O Rates for the selected interface, check this box.

Tag StatusThe Tag Status column indicates whether the I/O Rates tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the ICU is not able to access the PI Server


I/O Rate Tag Configuration

In FileThe In File column indicates whether the I/O Rates tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

Event CounterThe Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

TagnameThe tag name listed under the Tagname column is the name of the I/O Rates tag.

Right Mouse Button Menu OptionsCreateCreate the suggested I/O Rates tag with the tag name indicated in the Tagname column.

DeleteDelete the I/O Rates tag listed in the Tagname column.

RenameAllow the user to specify a new name for the I/O Rates tag listed in the Tagname column.

Add to FileAdd the tag to the IORates.dat file with the event counter listed in the Event Counter Column.

SearchAllow the user to search the PI Server for a previously defined I/O Rates tag.

Configuring I/O Rate Tags ManuallyThere are two configuration steps.

Configuring the PI Point on the Receiving Node

PI 2 Receiving NodesA listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:

46

@PISysDat:IOMonitor.com

Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.

PI 3 Receiving NodesCreate an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

CompDev 0

Configuration on the Interface NodeFor the following examples, assume that the name of the PI tag is pitopi001, and that the name of the I/O Rate on the home node is pitopi001.

NT Nodes

1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the system root (usually, \WinNT) directory. If both are specified, the PIPCSHARE entry takes precedence.

Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.

Add a line in the iorates.dat file of the form:

pitopi001, x

where pitopi001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.

3. The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.


I/O Rate Tag Configuration

UNIX Nodes

1. Edit/Create a file called iorates.dat in the $PIHOME\dat directory. PIHOME is an environment variable that is set equal to the PI home directory name as discussed in the PI-API Installation Instructions manual. Add a line in the iorates.dat file of the form:pitopi001, xwhere pitopi001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x flag in the startup command file. x can be any number between 1 and 34 or between 51 and 200, inclusive. However, it is best to use an event counter, x, that is not equal to 1 because 1 is the default event counter for UniInt-based interfaces.

To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.

2. Set the /ec=x flag on the startup command file of the interface to match the event counter in the iorates.dat file.

3. Set the default PI home node to the receiving PI server node in the piclient.ini file (in $PIHOME/dat).

4. The I/O Rate shared memory server and the I/O Rate monitor program must be stopped and started for the changes to take effect. The easiest way to do this is to run the pistop and pistart command scripts with the following commands:sh $PIHOME/bin/pistop

nohup sh $PIHOME/bin/pistart

5. One can determine that the shared memory server and the I/O Rate monitor are running with the commands:ps –ef | grep ioshmsrv

ps –ef | grep iorates

48

Tag and Node Security

PI 3 SecuritySecurity on a PI 3 system can cause PIToPI to be refused a connection, or may result in points not found on the source system. (For dataaccess and ptaccess attribute on PI 3 systems, see the PI Data Archive manual.) If a PIToPI node is refused access to a point, the error is listed in the log file. The number of points in error is summarized in the log file and the interface checks every 10 minutes for a change in access permissions. For writing to a PI 3.2 home node, a proxy account must be designated for the PIToPI client node. An example of creating a proxy entry using piconfig is shown below:

c:\pi\adm> piconfig* (Ls - ) PIconfig> @tabl pigen,piproxy* (Ls - PI_GEN) PIconfig> @mode create* (Cr - PI_GEN) PIconfig> @istr host,proxyaccount* (Cr - PI_GEN) PIconfig> raisin.osisoft.com,piadmin* (Cr - PI_GEN) PIconfig> @exit

The domain name should be entered with the machine’s name. Read access for points on a PI 3 node default to world readable. If access is changed, the same data access group should be assigned to the point and the PIToPI node’s proxy user.

For a PI 3.3 home node, a trust table entry must be created for the PIToPI client node. For instructions on creating this table, see the PI Trust Database section of Chapter 12 of the PI Data Archive manual.

PI 2 SecurityThere are two levels of security for the source node database, node security and tag security. Node security is provided by the PI 2 PIserver software. Tag security requires that a PI 2 source node contain a security file called PISysDat:PIToPI<name>.sec where <name> is the name string specified in the PIToPI startup script file. The security file contains tag security information.

PI 2 Node SecuritySupport for PI 2 node access security first began with PI 2 version 2.0.8. The full documentation for PIServer is available in the

PIBUILD:piserver.txt file and

PI System Installation and Upgrade Handbook section on PI Server.



The PI system manager configures security access in the PISYSDAT:piserver.dat file. A PI 2 node used as a data source must allow at least read-login access for the node on which PIToPI runs. It uses an entry in the piserver.dat file under the [CLIENTACCESS] section of

DEFAULT=RL (upper case), or <PIToPI_node>=RL

However, the level of access required also depends on the server version.

The normal access for PIToPI to read data from a PI 2.1.1 server (or lower version) should be read or read-login.

The normal access for PIToPI to read data from a PI 2.1.2 server (or higher version) should be read/write-login or read-login/write-login.

A PI 2 receiving node must allow read and write access for the PIToPI node with an entry under the [CLIENTACCESS] section of

DEFAULT=RW or

<PIToPI_node>=RW.

If a name server is unavailable for the PI 2 node, enter the IP address of the PIToPI node in the TCP/IP host table for the PI Server to resolve the piserver.dat entry.

PI 2 Tag SecurityA security file is used to specify access to the source tags. The file provides the ability to include tags for read access or exclude indicated tags so that the interface cannot read data for those tags. The source system manager has the responsibility for maintaining this file.

All PIToPI interfaces that will access data from a PI 2 source system check that the security file exists on the source server. If no security file exists on the PI 2 server, ACCESS DENIED status will be written to the tags that allow it; and the following message will be printed in the log file:PIToPI-1> Security file <name> not found on node <node>

where node <node> is the name of the source node. Then the interface will wait until it finds a security file. The interface will also check for new versions of the security file every 30 minutes if no points have security errors or every 10 minutes if some points have ACCESS DENIED status. If a new version of the file is detected, the interface will recheck the security status of all points. The following message is also printed.PIToPI-1> New security file specifications <name> retrieved

Two methods for retrieving the security file are used by the interface. First, the PI-API attempts to transmit the security-file contents, however, this requires write-login or write access by the interface. (This was first implemented with PI server 2.1.2.) If this fails, the interface uses an FTP script. This requires read or read-login access and a VMS login account.

The name of the security file must be specified in the pitopi.ini file. The suggested filename convention is PISysDat:PIToPI<name>.sec, where <name> is the name of the receiving node.

50

The structure of the security file will now be described. In the file, tags are included or excluded from being accessed by specifying a mode: I! is used to INCLUDE tags; and X! is used to EXCLUDE tags. Tags are referenced by a type specification. T! indicates that tags will be referred to by name; S! indicates that they will be referred to by point source.

The following specifications may be used to include or exclude tags:

Explicit tag name Tag mask with * and ? wildcards. Point source Point source plus location 1 parameter

The structure of the security file is as follows:

A leading exclamation point (!) is used to denote a comment.

Either an I! or an X! must be specified to set the mode before tag or point source specifications are made with T! and S!. Any specifications made without a mode will be ignored. It is possible to switch mode so that a set of tags can be included and another set of tags can be excluded.

A T! indicates that the following specifications are tags and tag masks.

Only one tag mask specification may be used per line and no comments may be used after the tag mask.

Asterisks (*) match any tag sub-string and the question mark (?) matches any single character.

An S! indicates that the following specifications are point sources and point sources plus location 1 parameters.

Only one point source specification is permitted per line.

An E! indicates the end of the file.

The letters I, X, E, T, and S as well as tag names and tag masks are case insensitive.

During interface initialization, each tag belonging to the interface is checked to ensure that the interface has permission to read the tag. If the interface does not have permission to read the tag, the following message is printed.PIToPI-1> Read access denied. source point X for rcv_tag Y,

error -210 The digital state AccessDenied will also be sent to the snapshot for that tag.

If a receiving point is edited and its source tag is changed, the edit will not be allowed. If the source point is the same, but the tag name of the point is changed, the new name will be used and the security access will be evaluated according to the current list of tag masks.

If the security file on the source node has been edited so that the interface now has permission to read a tag that previously had access denied, the interface will begin data collection. History will be recovered for the number of hours specified with the /rh=# parameter or starting from the current receiving system snapshot time, whichever is later.



Sample Security Files

Sample 1I! Mode is set to include.T! Specification type set to tag masks.! Default to including all points in system.*X! Reset mode to exclude.T!! All tags ending in ‘.al’ are excluded.*.alunit?flow.*S! Point source specifications.? ! All fractal tags are excluded.E!

Sample 2 X! Mode is set to exclude.T! Tag specifications.! Default to exluding all tags not explicitly matched.*I!T!! Some tag masks with wildcards.! multiple wildcards may be used.cd**unit1*! Match two of any characters.reactor1.??! Some tag names.sinusoidle420S! Point source specifications.! All PE tags included.C! Only point source ‘P’ with location1 = 2 included.P2E!

System Manager ResponsibilitiesSecuring the source archive data requires that both the source and receiving system managers perform the following tasks.

Receiving System Manager1. Give the source system manager a copy of the PIToPI interface manual.

52

2. Edit the pitopi.ini file and add the keys SecurityFile, SourceLogin, SourcePassword under the section [PITOPI-#] where “#” is the interface identification number. The three security keys may be listed under a particular scan class if the scan is retrieving data from a PI 2 server different from the default source server (use section name [PITOPI-#.*] where “*” is the scan class number).

3. If the ftp-script is to be used, a VMS user account must be entered in the appropriate location.

a) On Windows NT, edit the interface ftp script (interfaces\pitopi\ftp-script.bat) and specify the login name and password of the account to be used for reading the security file (e.g. anonymous and piadmin@pi). For multiple interfaces, the script file should be in a separate PIToPI directory for each interface copy with the appropriate login name and password for the source node to be accessed. The PSWD and USER lines should be edited in ftp-script.bat and replaced with a valid PI user:set PSWD=piadmin@piset USER=anonymousb) On UNIX, in the home directory of the user to run the PIToPI process (usually piadmin), create a file vi ~/.netrc with the permissions of rw for user and none for all others (chmod 600 .netrc). Use the following line containing site information for the keywords machine, login, and password: machine pivmsnode login anonymous password piadmin@piand a similar line for each source node accessed by additional PIToPI interfaces

Source System Manager1. The file PISysDat:PIServer.dat will be used to provide overall security for

the PI database. In this file, the receiving node must be given at least read-login access.

2. Create and maintain a security file for each PIToPI interface that will read data from the source system. This file is PISYSDAT:PITOPITEST.SEC, where TEST is the file name specified on the receiving node PIToPI command line.

3. A PI username and password must be provided which the interface will use as its PI login.

4. If the ftp-script is to be used, the protection of the security file should be set so that the VMS user name used for ftp access has the privilege to read the file. A user name and password must be provided for ftp access from the PIToPI node.

Note: Revisions to the security file are checked every 30 minutes.

PI 2 Source System Point LimitationsOn a PI 2 system, the maximum number of source points for which an interface can collect exception reports (i.e., retrieve data that has passed the exception test but has not been further processed by the compression test) is one-fourth the total number of



tags on the source system. This number is referred to as PTDIM in the file PIBUILD:PIPARAMS.FOR.

Data may be obtained from more tags in two ways. One way is by creating several instances of the PIToPI interface. The other is by collecting data for some tags with the HistOnly option. With this option enabled, archived data (i.e., data that has passed both the exception and compression tests) is collected. The number of tags for which archived data can be collected is unlimited.

Another limitation on the number of tags that can collect exception reports (also referred to as “signing up for exceptions”) is the overall limit for all processes on the source system of one-half the total number of tags on the system. Such processes include PI-DataLink and PI-ProcessBook. The only way to resolve this problem is to contact OSISoft and request a new PI tape with a larger total point count. There is no additional cost for the increased point count, but the change will require more memory on the PI 2 system. An OSI representative will be able to tell you how much more memory will be required.

If either the point limit on the interface or the point limit on all processes is reached, the interface will exit and print out an error message.

54

Startup Command FilePItoPI supports both interface-specific parameters (e.g. point source), as well as scan class-specific parameters (e.g. whether a scan class will sign up for exceptions on the source server or not). For these scan class attributes, PItoPI enables you to set a default then override this default on a scan-class-by-scan-class basis. Interface-specific parameters as well as default scan class attributes can be set in the interface startup file (pitopi.bat on Windows, and pitopi.sh on UNIX). The INI file can store default scan class attributes, as well as scan class-specific ones.

When a parameter is set in both the startup file and the INI file, the scan class-specific parameter overrides both the startup parameter (pitopi.bat or pitopi.sh) as well as the default scan class parameter. If a scan class-specific parameter is not set, then the startup parameter overrides the default scan class parameter.

In order of precedence:

Scan Class-Specific parameter in the INI file.

Default Scan Class parameter in the startup file

Default Scan Class parameter in the INI file

The command-line parameters required for interface startup are the same for both the NT and UNIX platforms; however, there are differences in the script files. Examples are shown below. An example of the pitopi.ini file is shown after the script files.

Notes for NTFor NT, command file names have a .bat extension. The NT continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.

Configuring the Interface with PI-ICU

Note: PI-ICU requires PI 3.3 or greater.

The PI-Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI-ICU, the batch file of the interface (pitopi.bat) will be maintained by the PI-ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI-ICU to configure the PI-PItoPI Interface.

From the PI-ICU menu, select Interface, New, and then Browse to the pitopi.exe executable file. Then, enter values for Point Source and Interface ID#. A window such as the following results:


Startup Command File

“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.

Click on Add.

You should then see a display such as the following:

Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, if you want the interface to communicate with a remote PI Server, you can do this by selecting ‘Connections…’ item from PI-ICU menu and make it your default server. If you do not see the remote node in the list of servers, you can add that in.

Once you add the interface to PI-ICU, near the top of the main PI-ICU screen, the Interface Type should be pitopi. If not, use the drop-down box to change the Interface Type to be pitopi.

Click on Apply to enable the PI-ICU to manage this copy of the PI-PItoPI Interface.

56

The next step is to make selections in the interface-specific tab (i.e. “pitopi”) that allow you to enter values for the startup parameters that are particular to the PI-PItoPI Interface.

The PItoPI ICU control has 3 tabs for each scan class, plus the default settings. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.

The next screenshot shows the Default Settings



The following screenshot is for scan class 2. Notice the yellow box for the event counter. This indicates that a value is required and has not yet been entered.

58

The Settings for drop down list will always have one entry titled “Default Settings”, and will have one entry for each scan class defined for this interface. The settings defined on the “Default Setting” tab are the settings that are used by the interface if one or more settings for any of the scan classes is not provided.

Since the PI-PItoPI Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI-ICU and to make changes to the behavior of the interface.

If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface interactively from the PI-ICU. To do that go to menu, select the Interface item and then Start Interactive.

For more detailed information on how to use the above-mentioned and other PI-ICU tabs and selections, please refer to the PI-Interface Configuration Utility User Manual. In the next section we will describe the selections that are available from the pitopi tab. After you have made your selections on the PI-ICU GUI, you will need to press the Apply button in order for PI-ICU to make these changes to the interface’s startup file.



pitopi Interface TabSince the startup file of the PI-PItoPI Interface is maintained automatically by PI-ICU, you should use the pitopi tab to configure the startup parameters and not make changes in the file manually. The following is the description of interface configuration parameters used in the PI-ICU Control and corresponding manual parameters.

Required/General Tab

When Default Settings is selected in the Settings for drop down, the first tab will be titled Required. This is because the information provided in this first tab is required only for the Default Settings, and not for each scan class.

1. Source hostThe Source host is the name of the source PI server from which this PItoPI interface is to get its data. (/SRC_HOST=hostname)

60

1 23

4567

8

2. PIx ServerThe type of server needs to be selected in the combo box next to the Source host text box. The options are PI3 Server or PI2 Server.

3. Event counterThe Event counter can only be configured for a particular scan class, so the Event counter field will remain disabled unless a scan class is selected in the Settings for combo box. (/EC=x)

4. PI2 Security FileThe PI2 Security File section is used only if the source host is a PI2 server. If a security file is to be used, check the Use PI2 security file check box.

5. Unique PartThe Unique part is the name suffix of tag security file on a PI 2 system. The full name on the PI 2 system is PITOPI<name>.SEC, where <name> is the portion specified in the Unique part text box. (/SF=uniquename)

6. UserThe User is the login user name of a PI user on PI 2 node that the interface is to use. This is used for PI 2 source systems. (/LN=username)

7. PasswordThe Password is the login password of the PI user specified in the User text box on PI 2 node. This is used for PI 2 source systems. (/PW=password)

8. Additional ParametersIn the space provided the user can enter any additional parameters that are not available through PI-ICU.



History Recovery Tab

1. Maximum hours of history to recoverNumber of hours to recover history for all points. Setting the value to 0 disables history recovery for all points. See “History Retrieval,” in the Principles of Operation section for more information on history recovery. (/RH=hours)

Use Default

Use the default setting of 8 maximum hours of history to recover.

2. Hours of history to recover per cycleThis is the number of hours of history to recover in each cycle through the point list. If the number of hours specified by Hours of history to recover per cycle is greater than or equal to the hours of history recovery requested in Maximum hours of history to recover, history will be recovered in one archive call from *- Hours of history to recover per cycle hours to *. If Maximum hours of history to recover is greater than Hours of history to recover per cycle, the archive calls to retrieve history will be

62

12

3

45

6

7

divided into N calls, where N = Maximum hours of history to recover / Hours of history to recover per cycle + 1. The calls, which start from (*-Maximum hours of history to recover), will each span Hours of history to recover per cycle hours. Each history increment is collected for all tags in the given scan class before the next time increment is begun. If this field is set to zero, the default 24 hours will be used. (/RH_INC=hours)

Use Default

Use the default setting of 24 hours for the maximum number of hours of history to recover per cycle.

3. Millisecond pause between history callsThe number of milliseconds to pause between history recovery calls. (/HRPAUSE=millisecond)

Use Default

Use the default setting of 10 milliseconds to pause between history recovery calls.

4. History recovery only (no snapshot data collection)If this check box is checked, tags do not sign up for exceptions. Each scheduled scan time (each scan class), history recovery is done from the last snapshot value to the current time. This box must be checked if the user wants to enter a History Time Range. (/HRONLY)

5. History time range (dd-mmm-yy:hh:mm,dd-mmm-yy:hh:mm)Alternately, specifies a range of history to recover before exiting. The times must be specified using PI time string formats with a colon separating the date and the time. For example:10-dec-98:10:00,10-dec-98:12:00

This will recover two hours of data from the source to receiving system, put it into the receiving PI system snapshot for all points and then exit. This switch will override the normal checking for the most recent snapshot time in the retrieving database, thus out of order data may result. (/HRONLY= dd-mmm-yy:hh:mm,dd-mmm-yy:hh:mm)

6. Retrieve history for a point starting from whichever is later, the initial hronly time, or last snapshot time.This will retrieve history for all the points starting from either the initial hronly time or the last snapshot time which ever is later. This can only be checked if the History recovery only check box has been checked.




Debug Tab

1. Debug ParametersThe Debug Levels flag is used to set a debug level for debug messaging per scan class. Check all types of debug messages that you would like to see logged. Any combination of debug levels can be applied.

2. Receiving Server Interface Status Utility Tag:This is the name of a failover status tag configured on receiving server. By clicking the small box at the end of the text box with the three … allows a user to browse the point database for this failover status tag using the Tag Search utility. (/IST=tagname)


64

1

2

3

Location Codes Tab

The override location codes tab allows users to configure the interface to ignore individual tag location codes and to apply specific settings for each of the location code

1. Override Location 1Ignore location 1 for each tag and set id for all tags for the specified point source to this (whole) number. (/C1=x)

2. Override Location 2Ignore location 2 for each tag and set location 2 value to be this number for all interface tags. (/C2=x)

3. Override Location 3Ignore location 3 for each tag and set location 3 value to be this number for all interface tags. (/C3=x)


6

5

43

12


4. Override Location 4Ignore location 4 for each tag. The value used here should be 1, to have all points for the interface sign up for exceptions, or 2, to have all points retrieve history only. (/C4=x)

5. Override Location 5Ignore location 5 for each tag and set all points for the interface to the same value of this parameter (i.e., 0, 1, 2, or 3). (/C5=x)


Optional Tab

66

12

3

45

6

7

1. Apply tag’s compression specification to data retrieved during history recovery.Use compression specifications in tag configurations to send data retrieved during history recovery with compression. (Usually data is retrieved from source server and sent to receiving server without compression during history recovery.) (/DC)

2. Source tag definition attribute.Use TagName on both servers (Ignoring Exdesc and InstrumentTag point attributes). Do not check the InstrumentTag or Exdesc attributes for source tag definitions. Use TagName to identify the point on both source and receiving PI Servers. (/TN)

Use Exdesc (Ignoring TagName and InstrumentTag point attributes). The source tag definition will be found in the Exdesc attribute. Ignore the TagName and InstrumetTag attributes. This parameter is useful for PI2 to PI3 migrations. (/TNEX)

3. Specify maximum events to retrieve for a single point in each call to get history.This parameter is available for PI 3.3 or higher receiving servers. It sets the maximum number of events to retrieve for a single point in each call to get history. With each call to retrieve history, one call is made to put it into the receiving server. At least one of these calls will be over the network, so using a small number could result in performance problems. (/MH=x)

4. Source Host reconnection delay.This parameter sets the time delay for attempting to reconnect to source PI server after a disruption. The number is entered in seconds and converted to milliseconds before being saved in the batch file. This number must be between 1 second and 8 hours. The default is 2 minutes. (/DELAYS=x)

5. Receiving Host reconnection delay.This parameter set the time delay for attempting to reconnect to receiving PI server after a disruption. The number is entered in seconds and converted to milliseconds before being saved in the batch file. This number must be between 1 second and 8 hours. The default is 2 minutes. (/DELAYR=x)

6. Suppress I/O TimeoutWhen setting location 3 to 0, 2, 4, or 6 for any tags, this parameter should be used to suppress the I/O Timeout state written to these tags upon reestablishment of a lost connection to the source PI server. If this parameter is not set, the state written at reconnection will prevent history from being recovered for the period of the disconnection. (/TS)




Failover Tab

1. Enable PItoPI FailoverThis check box is used to allow the configuration of the failover. Until this box is check none of the items on this tab are enabled. You will notice that having this check makes items 2, 3, and 4 required since they are in yellow.

2. Source Server Interface Status Utility TagThis the name of a PI Interface Status utility tag configured on the source server defined in /SRC_HOST=hostname. The small box with three … in it is used to invoke the Tag Search utility to browse for this tag. (/SSU1=tagname)

3. Secondary Source Server Node NameThis is the name of the second source node to retrieve data from. This must be a PI 3.x PI server node as such the port number of 5450 will be appended to the end of this name when it is saved in the batch file. (/SEC_SRC=nodename:5450)

68

1234

5

6

7

4. Secondary Source Int Status Utility TagThis the name of a PI Interface Status utility tag configured on the source server defined in /SEC_SRC=hostname. The small box with three … in it is used to invoke the Tag Search utility to browse for this tag. (/SSU2=tagname)

5. Number of connection attempts to source serverThis parameter is used to specify the number of time to try connecting to source server if connection fails the first time. It can be used to restrict failover from occurring until after a certain number of attempts have been made to connect to the primary server have failed. The default number of attempts is 1. (/NT=x)

6. Enable failover status logging.This check box is used to enable failover status logging. By checking this box the user is allowed to enter a receiving server status tag. This tagname entered in this text box is the failover status tag configured on receiving server. The small box with three … in it is used to invoke the Tag Search utility to browse for this tag. (/FST=tagname)


Notes for UNIXFor UNIX, command file names typically have a .sh extension, but UNIX does not enforce file-naming conventions. The backslash (\) continuation character allows one to use multiple lines for the startup command. There is no limit to the command-line length and there is no limit to the number or length of the command line parameters.

Command-line Parameters

Notes: Startup File refers to the parameter set in the pitopi.bat on Windows, and pitopi.sh on UNIX. INI refers to the parameter set in the pitopi.ini file.

While it is possible to configure every scan class to read from a different source server, this is not recommended. One should consider using multiple instances of the interface instead.

If a parameter is specified in both the startup file and the INI file, the Scan Class-specific parameter will override the default Scan Class parameter. If the default Scan Class parameter is specified in both the startup file and the INI file, the setting in the startup file takes precedence.



Interface Number: Required Default: 1


/id=/in=

-- Interface number. This switch must be set to the interface number. Each interface maintains a list of only those points with the PointSource and location1 point attributes which match the point source and interface number defined by /ps and /id. /in also defines the interface number and overrides the /id parameter.

Point Source: Required Default: None


/ps= -- Point source. The user must specify a unique point source such as P that is currently not in use by another process. Only single character point sources are supported.

Scan Class: Required Default: None


/f= -- The interface checks the source server for new data at this frequency. If only history is requested, archive data will be retrieved from the last snapshot value to the current time. Otherwise, all exceptions queued on the source server will be retrieved at the scheduled time. If more than one scan class is used, points in the first one will obtain snapshot values; points in the others obtain history (archive values). The scan class that obtains snapshots can be changed to another one in the list by specifying HistOnly=1 for the other scan classes in the scan-class subsections of the pitopi.ini file. If few points are configured, the scan frequency could be increased to eliminate excess requests for data. Specifying a scan of 10 seconds is recommended. The standard format may include two digits for each of hours:minutes:seconds, though only seconds is now needed (/f=10). If multiple scans are specified, offsets in scheduling may be specified with a comma /f=10,0 /f=60,5..

70

Receiving Server:Required Default: localhost


/host= ReceivingHost Name of receiving PI node. The node name may be specified as /host= node_name:tcpip_port where the port number will be either 545 or 5450.

Unlike other parameters found in the INI file, ReceivingHost cannot be overridden on a scan class per scan class basis.

Source Server:Required Default: None


/src_host= SourceHost Name of source node to retrieve data from. This must be specified as: /src_host=node_name:tcpip_port where the port number will be either 545 or 5450.

While it is possible to configure every scan class to read from a difference source server, this is not recommended.

Security File: Required for PI2 Default: None


/sf= SecurityFile Name-suffix of tag security file on a PI 2 system. The full name on the PI 2 system is PITOPI<name>.SEC, where <name> is the portion specified on the command line. The switch is used for PI 2 source nodes and is ignored if specified for PI 3 source nodes.

Snapshot: Optional Default: N/A


/sn -- Use pisn_putsnapshotqx for adding data to the receiving PI server. If this flag is removed, pisn_sendexceptionqx is used. The interface obtains exception values from the source PI server, so /sn should normally be used. However, if excess network traffic is a problem and the two PI databases do not need to be identical, the pisn_sendexceptionqx call may be used to reduce the amount of data sent to the receiving server by removing the /sn switch.



Queueing: Optional Default: N/A


/q -- The values sent to the receiving server will be sent in arrays approximately 4 kilobytes in size. The queued data will be sent to the server whenever the size nears 4 kb or at the end of each scan.

Event Counter:Optional Default: 1


/ec= EventCounter Range allowed is 1-34 and 51-200. Multiple counters may be specified on the command line. The first event counter is updated for every value sent to the server. Subsequent counters will be updated by individual scan classes if the scan class section specifies that counter in pitopi.ini.

Debug Flags: Optional Default: 0


/db= DebugFlags Turns on additional debug messages. Possible values (use as many as desired, each separated by commas):

5: history retrieval for each tag

6: print out pitopi.ini entries

7: print out security file name, source server login information

8: history retrieval summary for each interval

9: addition of tags to interface (including on startup)

10: results of point-level security check

13: results of attempt to get security file

14: print out tag masks from security file

15: print out when security file is read, problems reading it

16: results of check on security settings allowing access to source tags

Example: /db=5,6,9

Login Name: Optional for PI2 Default: None


/ln= SourceLogin Login name of PI user on PI 2 node. This is used for PI 2 source systems.

72

Source Password: Optional for PI2 Default: None


/pw= SourcePassword Login password of PI user on PI 2 node. This is used for PI 2 source systems.

Timeout Suppression: Optional Default: None


/ts -- When setting location 3 to 0, 2, 4 or 6 for any tags, this switch should be used to suppress the I/O Timeout state written to these tags upon reestablishment of a lost connection to the source PI server. If this switch is not set, the state written at reconnection will prevent history from being recovered for the period of the disconnection.

History Recovery Increment:Optional Default: 24


/rh_inc= MaxArcTimespan Number of hours of history to recover in each cycle through the point list. If the number of hours specified by /rh_inc=<Increment> is greater than or equal to the hours of history recovery requested in /rh=<Total>, history will be recovered in one archive call from *-<Increment> hours to *. If <Total> is greater than <Increment>, the archive calls to retrieve history will be divided into N calls, where N = <Total>/<Increment> + 1. The calls, which start from (*-<Total>), will each span <Increment> hours. Each history increment is collected for all tags in the given scan class before the next time increment is begun.

History Recovery Length: Optional Default: 8


/rh= HistRecovery Number of hours to recover history for all points. /rh=0 disables history recovery for all points. See “History Retrieval,” in the Principles of Operation section for more information on history recovery.



History Recovery Only:Optional Default: N/A


/hronly HistOnly If this parameter is set, tags do not sign up for exceptions. Each scheduled scan time (specified by /f), history recovery is done from the last snapshot value to the current time.

Alternately, specifies a range of history to recover before exiting. The times must be specified using PI time string formats with a colon separating the date and the time. For example, /hronly=10-dec-98:10:00,10-dec-98:12:00 will recover two hours of data from the source to receiving system, put it into the receiving PI system snapshot for all points and then exit. This switch will override the normal checking for the most recent snapshot time in the retrieving database, thus out of order data may result.

History Pause: Optional Default: 0


/hrpause= HistPause Milliseconds to pause between history recovery calls.

Adjusted Time-Range recovery: Optional Default: N/A


/ns -- Used with a time-range history recovery (see /hronly=time1,time2 above in the description of the /hronly parameter) to retrieve history starting from the initial time (time1) or the last snapshot time for the particular point, whichever is later.

Streamlining PItoPI Tag Configuration: Optional Default: N/A


/c1= -- Ignore location 1 for each tag and set id for all tags for the specified point source to this (whole) number. Valid values are greater than 0.

/c2= -- Ignore location 2 for each tag and set location 2 value to be this number for all interface tags. Valid values are 0-2.

74


/c3= -- Ignore location 3 for each tag and set location 3 value to be this number for all interface tags. Valid values are 0-7.

/c4= -- Ignore location 4 for each tag. Valid values are 1 (sign up for tag exceptions) or 2 (get archive data).

/c5= -- Ignore location 5 for each tag and set all points for the interface to the same value of this parameter. Valid values are 0 -3.

/tn -- Do not check InstrumentTag or Exdesc attributes for source tag definitions. Use TagName to identifying the point on both source and receiving PI servers.

/tnex -- Source tag definition in Exdesc attribute. Ignore TagName and InstrumentTag attributes. This switch is useful for PI2 to PI3 migrations.

Archive Retrieval Chunk: Optional Default: 100


/mh= -- This parameter is available for PI 3.3 or higher receiving servers. It sets the maximum number of events to retrieve for a single point in each call to get history. With each call to retrieve history, one call is made to put it into the receiving server. At lease one of these call will be over the network, so using a small number could result in performance problems.

Extra Compression: Optional Default: N/A


/dc -- Use compression specifications in tag configurations to send data retrieved during history recovery with compression. (Usually data is retrieved from source server and sent to receiving server without compression during history recovery.)

Server Connection Delay: Optional Default: 120000


/delays= -- Set time delay for attempting to reconnect to source PI server after a disruption. Number is in milliseconds. It must be between 1 second and 8 hours. Default = 2 minutes.




/delayr= -- Set time delay for attempting to reconnect to receiving PI server after a disruption. Number is in milliseconds. It must be between 1 second and 8 hours. Default = 2 minutes.

Failover: Optional for PI3 Default: N/A


/sec_src= -- Name of second source node to retrieve data from. This must be specified as: /sec_src=node_name:5450 where 5450 is the tcpip port number.

Source server connection tries:Optional Default: 1


/nt= -- Number of times to try connecting to source server if connection fails the first time. Can be used to restrict failover from occurring until after a certain number of attempts have been made to connect to the primary server have failed. Example: /nt=4 will try connection 4 times.

PI Interface Status Utility Tag: Optional for PI3 Default: N/A


/ssu1= -- Name of PI Interface Status utility tag configured on source server defined in src_host. This must be specified as: /ssu1=tagname, where tagname is the PI point attribute Tagname.

/ssu2= -- Name of PI Interface Status utility tag configured on source server defined in sec_src. This must be specified as: /ssu2=tagname, where tagname is the PI point attribute Tagname.

Failover Status Tag: Optional for PI3 Recvg Node Default: N/A


/fst= -- Name of failover status tag configured on receiving server. This must be specified as: /fst=tagname, where tagname is the PI point attribute.

76

Interface State Tag: Optional for PI3 Recvg Node Default: N/A


/ist= -- Name of failover status tag configured on receiving server. This must be specified as: /ist=tagname, where tagname is the PI point attribute.

Sample PItoPI.bat File - NTThe startup files for the interface reside in the directory PIHOME\interfaces\pitopi where PIHOME is defined in %WINDIR%\pipc.ini by the installation program. Typically, PIHOME is c:\pipc. The startup files consist of pitopi.bat and pitopi.ini. Examples are shown below.

REM Sample pitopi.batREMREM----------------------------------------------------------------------------REM Purpose:REM This command procedure passes parameters to the pitopi interface.REM REM If multiple copies of the interface are to be run, copy this file toREM pitopi#.bat where # is the same number passed by /id=# in the commandREM string.REM----------------------------------------------------------------------------REM Revisions: REM 29-sep-96 jfz>REM With pitopi version 2.1, /host refers to name of receiving node.REM Previously this was /local_host. Additionally /src_host now refersREM to the name of the source node. Previously this was the name of theREM receiving node.REM 21-Apr-97 rab> Removed noservice option - no longer neededREM 13-May-97 cah> Changed /in -> /id REM 16-Jul-97 cah> /ln, /pw added for PI2 security files.REM /comm may be excluded now: set to tcpip.REM /sf not needed when PI3 source nodes used.REM 25-Sep-97 cah> Reordered parameter listing/ changed PI2 tag securityREM parameters to optional.REM 19-Jan-98 cah> Added /rh_inc parameter.REM 04-Jun-98 cah> edited /sf parameter descriptionREM 25-Jan-99 cah> Added /perf parameter descriptionREM 03-Dec-99 cah> Changed to reflect pitopi.ini usage.REM 07-Dec-99 cah> Added /hronly, /hrpause, and added equivalent REM ini file options.REM---------------------------------------------------------------------------REM REM Required Command-line parametersREMREM /ps= point source REM /f= scan frequency REM /host= name of receiving node



REM (ReceivingHost in pitopi.ini file)REM /src_host= name of source node REM (SourceHost in pitopi.ini file)REMREM Optional Command-line parametersREMREM /id= (or /in= ) number to associate with particular interf. REM /sn use putsnapshot instead of sendexceptions REM /q use queueing for snapshots REM /ec= rate counter number(s) REM (EventCounter in pitopi.ini file)REM /perf= Interval between scan performance summaries. REM /db= turns on additional debug messagesREM (DebugFlags in pitopi.ini file)REM /sf= unique part of PI2 security file name on source node REM (SecurityFile in pitopi.ini file)REM /ln= name of PI2 PI user name REM (SourceLogin in pitopi.ini file)REM /pw= name of PI2 PI user password REM (SourcePassword in pitopi.ini file)REM /rh= max number of hours of history to recover, REM default=8 hours.REM (HistRecovery in pitopi.ini file)REM /rh_inc=hours of history in each archive call. REM default=24 hours.REM (MaxArcTimespan in pitopi.ini file)REM /hronly get history only, not exceptions REM (HistOnly in pitopi.ini file)REM /hrpause= milliseconds to pause between history calls. REM (HistPause in pitopi.ini file)REM /ts I/O timeout suppression (on reconnection to server)REM /ns can be used with time-range history recovery REM (i.e., /hronly=time1,time2) to start from last eventREM for each tag.REM /cx= where x is 1, 2, 3, 4, or 5. Ignore locationx setting REM and use whatever number is on right side of =REM /tn ignore what is in instrument tag attribute and use REM tagname for name of tag on source server.REM /tnex Use source tag definition in Exdesc ignoring Tagname and REM InstrumentTagREM /mh= set number of events to get in each call to get history REM /dc allow compression of events sent to destination server REM during history recovery.REM /delays= time to wait before attempting to reconnect to source REM server after disruption. REM /delayr= time to wait before attempting to reconnect to receiving REM server after disruption.REM /sec_src= Secondary source hostname and port numberREM /ssu1= Name of PI Interface status utility tag configured on theREM source server defined in /src_host.REM /ssu2= Name of the PI Interface status utility tag configured onREM the secondary source server defined in /sec_srcREM /fst= Name of failover status tag configured on receiving server.REM This is a failover status tag.

78

REM /ist= Name of failover status tag configured on receiving server.REM This is an interface state tag.REMREM Command-line parameters need a space between them, but no spacesREM within.REMREM Note: following configuration requires entries in pitopi.iniREM.\pitopi.exe ^/ps=p ^/ec=2 ^/id=1 ^/src_host=localhost:5450 ^/host=cd05252004:5450 ^/f=1 ^/rh=0 ^/rh_inc=0 ^/maxstoptime=2 ^/q ^/tsREMREM end of sample pitopi.bat

Sample pitopi.sh File - UNIXThe startup files for the interface reside in the directory $PIHOME/interfaces/pitopi and are called pitopi.sh and pitopi.ini.

An example pitopi.sh file is shown below.

#!/bin/sh# @(#)pitopi.sh 1.4 12/10/99## Purpose: # This command procedure passes required parameters to the pitopi interface.# # If multiple copies of the interface are to be run, pitopi.sh may# be started with the interface number as an argument. In that case,# all possible command line options should be moved to pitopi.ini.# Any parameters which must be different on the command line should# be passed as arguments to the script ($1 is used as interface number,# $2 maybe used as event counter).## Revisions: # 29-sep-96 jfz># With pitopi version 2.1, /host refers to name of receiving node.# Previously this was /local_host. Additionally /src_host now refers# to the name of the source node. Previously this was the name of the# receiving node.# 21-Apr-97 rab> Removed noservice option - no longer needed# 13-May-97 cah> Changed /in -> /id



# 16-Jul-97 cah> /ln, /pw added for PI2 security files.# /comm may be excluded now: set to tcpip.# /sf not needed when PI3 source nodes used.# 25-Sep-97 cah> Reordered parameter listing/ changed PI2 tag security# parameters to optional. Used continuation lines.# 19-Jan-98 cah> Added /rh_inc parameter.# 04-Jun-98 cah> edited /sf parameter description# 25-Jan-99 cah> Added /perf parameter description# 03-Dec-99 cah> Changed to reflect pitopi.ini usage.# 07-Dec-99 cah> Changed to detect running interfaces.# Added /hronly, /hrpause, and added equivalent # ini file options.# 10-Dec-99 cah> Added case switch for multiple exe's# # Command line arguments:# -ps= point source (required)# -f= scan frequencies (required)# -id= (or -in= ) number to associate with particular interf. (required)# -sn use putsnapshot instead of sendexceptions (optional)# -q use queueing for snapshots (optional)# -host= name of receiving node (required)# (ReceivingHost in pitopi.ini file)# -src_host= name of source node (required)# (SourceHost in pitopi.ini file)# -ec= rate counter number(s) (optional)# (EventCounter in pitopi.ini file)# -db= turns on additional debug messages (optional)# (DebugFlags in pitopi.ini file)# -perf= Interval between scan performance summaries. (optional)# -sf= unique part of PI2 security file name on source node (optional)# (SecurityFile in pitopi.ini file)# -ln= name of PI2 PI user name (optional)# (SourceLogin in pitopi.ini file)# -pw= name of PI2 PI user password (optional)# (SourcePassword in pitopi.ini file)# -rh= max number of hours of history to recover, (optional)# default=8 hours.# (HistRecovery in pitopi.ini file)# -rh_inc=hours of history in each archive call. (optional)# default=24 hours. Cannot be zero.# (MaxArcTimespan in pitopi.ini file)# -hronly get history only, not exceptions (optional)# (HistOnly in pitopi.ini file)# -hrpause= milliseconds to pause between history calls. (optional)# (HistPause in pitopi.ini file)## Command line arguments need a space between arguments, but no spaces# within argument.#

80

if [ "${1:-undef}" = "undef" ]; then INTF_NUM=1else INTF_NUM=$1fiPROG_NAME=pitopi$INTF_NUM# if PIHOME not in environment, then set for this procedureif [ "${PIHOME:-undef}" = "undef" ]; then echo "PIHOME not defined" PIHOME=$PWD/../..fiISRUNNING=̀ ps -e | grep "$PROG_NAME" | grep -v grep | grep -v pitopi.sh̀if [ "$ISRUNNING" = "" ]; then # stdout and stderr will be redirected to pitopi.log case "$IFNUM" in 1) echo "Starting interface $PROG_NAME" ./$PROG_NAME -ps=P -id=$INTF_NUM -sn -q -perf=0 \ -ec=11 -ec=12 -f=10,0 -f=300,5 \ -host=localhost:5450 > $PIHOME/dat/$PROG_NAME.log 2>&1 & ;;# 2)# echo "Starting interface $PROG_NAME"# ./$PROG_NAME -ps=P -id=$INTF_NUM -sn -q -perf=0 \# -ec=21 -ec=22 -f=10,0 -f=300,5 \# -host=pi:5450 > $PIHOME/dat/$PROG_NAME.log 2>&1 & # ;; *) echo "Interface $PROG_NAME not configured in pitopi.sh" $PIHOME/bin/shootq "Interface $PROG_NAME not configured in pitopi.sh" ;; esacelse echo "PIToPI Interface $PROG_NAME is already running" $PIHOME/bin/shootq "PIToPI Interface $PROG_NAME is already running"fi#

Sample pitopi.ini File - NT and UNIXThe startup pitopi.ini file for the interface will reside in the directory PIHOME\interfaces\pitopi. Each section name contains the interface number. The scan class number for the interface follows the interface number separated by a period. If an entry is missing in a scan class subsection, and there is an entry in the main section, the entry in the main section for that interface will be used.

This file may be used to specify different source servers for each scan class. For example, if one SourceHost is entered in [PIToPI-1.1] and a different SourceHost is entered in [PIToPI-1.2], tags in the first scan class (for interface copy number 1) will be retrieved from the server entered as SourceHost in



[PIToPI-1.1], and tags in the second scan class will be retrieved from the server entered as SourceHost in [PIToPI-1.2] (for interface copy number 1). However, if the SourceHost is entered in [PIToPI-1], and not in the scan class subsections, all scan classes will use the SourceHost from the main section. The other keys work in a similar manner. If a key for a given parameter is not entered, the interface defaults are used.

The PIToPI executables will always access the file pitopi.ini in the current directory. Do not make numbered pitopi#.ini files. The section names in pitopi.ini differentiate startup information for each interface number. For example, [pitopi-1] and [pitopi-2] specify startup information for two different interface instances.; Sample pitopi.ini file;; Default values are supplied for clarification.;-------------------------------------------------------------; This section applies to the copy of the interface with; /id=1 or /in=1 in the .bat file. The parameters in this ; section apply to all scan classes for this instance of the; interface..; This section is followed by sections which appply to ; individual scan classes. The scan class parameters take; precedence over parameters specified in this section or; the defaults.[PIToPI-1]EventCounter=10SourceHost=piHistRecovery=48.0 ; defaultMaxArcTimespan=24.0 ; default;;-------------------------------------------------------------; This section applies to scan class 1 of interface instance 1.[PIToPI-1.1]EventCounter=11;;-------------------------------------------------------------; This section applies to scan class 2 of interface instance 1.[PIToPI-1.2]EventCounter=12SourceHost=grapeHistOnly=1;;-------------------------------------------------------------; This section applies to the copy of the interface with; /id=2 or /in=2 in the .bat file. The parameters in this ; section apply to all scan classes for this instance of the

82

; interface..; This section may be followed by sections which appply to ; individual scan classes. The scan class parameters take; precedence over parameters specified in this section or; the defaults.[PIToPI-2]EventCounter=20SourceHost=piHistRecovery=48.0 ; defaultMaxArcTimespan=24.0 ; default;;-------------------------------------------------------------; --- List of possible keys ---;HistRecovery=;HistPause=;MaxArcTimespan= (same as rh_inc command-line parameter) ; It cannot be set to zero.;EventCounter=;DebugFlags= comma separated list (5,6,7,13,14,15 ; currently available);ReceivingHost=;SourceHost=;SourceLogin=;SourcePassword=;SecurityFile= Required for PI 2;HistOnly=;


Starting / Stopping the Interface on NTThis section describes starting and stopping the interface once it has been installed as a service. See the UniInt End User Document to run the interface interactively.

Starting Interface as a ServiceIf the interface is installed a service, it can be started from the services control panel or with the command:pitopi.exe –start

A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line arguments in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Stopping Interface Running as a ServiceIf the interface is installed a service, it can be stopped at any time from the services control panel or with the command:pitopi.exe –stopThe service can be removed by:pitopi.exe –remove


Starting / Stopping the Interface on UNIX This section describes starting and stopping the interface as a background process. See the UniInt End User Document to run the interface as a foreground process.

On API nodes, the interface is started automatically with the command pistart (from the $PIHOME/bin directory).

To start the interface separately, type the command sitestart from the $PIHOME/bin directory or, from the directory, $PIHOME/interfaces/pitopi, type ./pitopi.sh.

The interface is stopped automatically when the PI Home or API node is stopped. It may also be stopped by issuing the command sitestop from the $PIHOME/bin directory.

The following section provides details on the processes involved in these scripts.

Command-line Syntax for Background ProcessesJobs that are run in the background remain in existence even after the user that has started the process has logged off of the system. The command line in the pitopi.sh startup command file should begin with nohup and end with &. For example:nohup pitopi1.exe program_arguments > pitopi1.log 2>&1 &The & at the end of the command line causes the job to be launched in the background. The nohup at the beginning of the command line causes hang-ups and quits to be ignored. Always execute a background job with nohup, either by incorporating it into the startup command file of the interface or by typing nohup pitopi.sh or nohup sh pitopi.sh from the terminal. Unless the job is executed with nohup, the hang-up signal will cause the job to be terminated even if it is run in the background.

A job that is started with nohup will have its standard output redirected to the file nohup.out, unless the standard output is redirected to a different file name. On the command line above, the standard output is redirected with the > director to the file pitopi1.log.

The optional sequence 2>&1 causes the standard error to be redirected to standard output so that the standard error will also appear in pitopi1.log. System commands typically send error messages to the standard error. For example, the command:cat nonexistentfilefails with the error message “cat: cannot open nonexistent file: No such file or directory.” This error message is redirected to the standard error, which is normally seen on the screen.

Typically, messages that interfaces write to the standard output are also written to the $PIHOME/dat/pimesslogfile. To avoid this duplication, the user can redirect the standard output to the null device, which discards the messages. For example:nohup pitopi1.exe program_arguments > /dev/null &


Starting / Stopping the Interface on Unix

redirects the standard output to the null device. Initially, it is recommended to use the first command-line example, where the output is redirected to the pitopi1.log file.

Terminating Background ProcessesThe termination of background processes requires that one first obtain the process id (pid) of the background job. This is done as follows. First execute the command:ps –ef | grep pitopiwhich produces output similar to:matzen 12788 12707 2 09:55:27 ttys1 0:00 pitopi1.exe /ps=B …The second column is the PID of the process. That is, 12788 is the PID of the pitopi1.exe interface in the example above.

The process is then stopped by:kill 12788The kill command sends the SIGTERM signal to the interface, causing the exit handler to be invoked.

Unless it cannot be avoided, do NOT stop the interface with kill –9 pid. The option -9 causes the SIGKILL signal to be sent to the interface. The exit handler cannot catch this signal. SIGKILL will immediately terminate the process.

Anomalous Background Job TerminationOn some platforms, processes that are started in the background will be terminated if one types “control-c” in the same window that the job was started in. If one closes the window in which the interface was started or if one logs off and logs back on, the user will not be able to accidentally terminate the job in this manner.

88

BufferingNote: While the use of buffering is not the norm for the PItoPI interface, information is included here for those users who decide to implement it.

For complete information on buffering, please refer to the PI to PI TCP/IP .

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI-API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Note: Change the Local Security Policy on Windows XP. 1. Open "Administrative Tools" from the control panel. 2. Open "Local Security Policy" from administrative tools. 3. Browse to "Security Options" under "Local Policies." 4. Double click on "System Objects: Default owner for objects created by members of the Administrators group." 5. Change the dropdown from "Object Creator" to "Administrators group."

The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.

Configuring Buffering with PI-ICU (NT-Intel)Buffering is enabled through the PI-Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI-API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:


Buffering

Service TabThe Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.

Service NameThe Service name displays the name of the API Buffering Service.

Display NameThe Display name displays the full name associated with the API Buffering service.

Log On AsLog on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as:above.

Confirm passwordYou must reenter the password again to verify you have typed it correctly both times.

DependenciesThe Dependencies lists the Windows services on which the API Buffering service is dependent.

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.

Start / Stop ServiceThe Start / Stop buttons allow for the API Buffering service to be started and stopped. If the service is not created this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

90

Service Startup TypeThe Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the API Buffering service is set to start automatically.

Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

Settings TabThe Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.

Enable BufferingEnables the API Buffering feature.


Buffering

Maximum File SizeMaximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send RateSend rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.


Primary Memory Buffer SizePrimary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer SizeSecondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer ObjectsMax transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause RateWhen buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry RateWhen the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.


92

Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and can not be changed.

There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.

Configuring Buffering ManuallyBuffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI-API will not buffer data, sending data directly to the home node.

There are no additional steps needed to install buffering after installing the PI-API. The delivered PI-API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI-API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows NT. On UNIX systems, the file is found in the dat subdirectory of the PIHOME directory (e.g., /opt/piapi/dat). This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows, vi on UNIX) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0,1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 – 2,000,000

2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 – 2,000,000

120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 – 2,000,000

100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS 1 – 2,000,000

500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 – 32768 Primary memory buffer size. (bytes)


Buffering

2,000,000

BUF2SIZE 64 – 2,000,000

32768 Secondary memory buffer size. (bytes)

SENDRATE 0 – 2,000,000

100 The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.

Keywords Values Default Description

PIHOMENODE string none Default server for UNIX. Windows default server is in pilogin.ini

DSTMISMATCH 0 – 2,000,000

0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)

Example piclient.ini File

NTOn Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying.

On NT a piclient.ini file might look like:[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI-API connection routines have a 1 minute default

timeout.RETRYRATE=600

94

UnixThe BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying. The [PISERVER] and [TCP/IP] sections are used to define the default connection. Comment lines begin with a semicolon.

On UNIX a piclient.ini file might look like:[PISERVER]PIHOMENODE=MYNTSERVER; DSTMISMATCH=0[TCP/IP]PORT=5450[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI-API connection routines have a 1 minute default

timeout.RETRYRATE=600


Appendix A:Error and Informational Messages

A string PIToPI-ID is pre-pended to error messages written to the message log. PIToPI- is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id flag on the startup command line.

Message LogsThe location of the message log depends upon the platform on which the interface is running. See the UniInt End User Document for more information.

Messages are written to PIHOME\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.

If the /db is used on the command line, then various informational messages are written to the log file.

System Errors and PI ErrorsSystem errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions on NT and UnixOn NT, descriptions of system and PI errors can be obtained with the pidiag utility:\PI\adm\pidiag –e error_numberAll interface informational and error messages will be sent to the pimesslogfile located in $PIHOME/dat. This is the log file associated with the PI-API.

Interface Startup MessagesWhen the interface is started, the log file will contain informational messages that describe the settings that will be used from the startup script and the pitopi.ini file. The interface will then print a message stating the receiving PI server and a message for each source PI server. The message for each source PI server also states the time offset between source and receiving PI server along with time zone differences. Note that the pitopi.ini can be used to configure a different source server for each scan class. In addition each source server (and therefore scan class) can have different history recovery parameters. Finally the pitopi.ini can be used to specify which scan class signs up for exceptions (default is scan class 1 gets


Appendix A: Error and Informational Messages

exception data unless /hronly is specified in pitopi.bat ). After printing a message specifying the receiving and source PI servers it prints a message for each scan class stating if it will collect archive or exception data, the source PI server for that scan class and the history recovery parameters.

Scan SummaryAfter a scan has finished history recovery, the interface logs messages indicating the number of tags in error for the scan class.PIToPI- 1> Scan class 1: 26 src points established on source node BERRY:5450PIToPI- 1> Scan class 1: Beginning scans. 0 errors for 26 tags

The messages above indicate the number of points successfully registered with the update manager on the source node and the number of errors encountered in the given scan class.

98

Appendix B:Troubleshooting

1. Problem: The archive subsystem on the receiving node is using 99% of the CPU. Checking the archive subsystem statistics (e.g. with piartool –as) shows that many out-of-order events are being generated.Reason 1: This usually happens when servers have different time settings (either time zone or times are offset). History retrieval on startup or after a disconnection may cause out of order timestamps if the times are not translated to the receiving PI system time.

Solution 1: Check to make sure that location2=0 for all tags. If there are still problems, the debug flag can be set to /db=5. This will print out the start and end time of every archive call to the source PI system. Caution: You may want to do this with only a subset of the tags configured for the interface.

Reason 2: With PI 3.2. 357.17 and earlier PI 3 versions, when large amounts of data are sent by the snapshot subsystem to the archive subsystem in small packets, the order of the data is sometimes jumbled.

Solution 2: Change the size of the packets of data sent by the snapshot subsystem to the archive subsystem using piconfig. Use the following commands in piconfig:@table pi_gen, pitimeout@mode create@istr name, valuemaxeventqueue, 2048

The new value for maxeventqueue will be printed by piconfig on the next line, verifying that the change was made. Then simply exit piconfig with the command @exit.

If you have changed the value of maxeventqueue previously, you must use @mode edit instead of @mode create.

2. Problem: Point not found or access denied (error -5).Solution: PI 3 servers do not give any information for points with read access denied. It is as if they do not exist. Check the point attributes dataaccess and ptaccess. Check the proxy granted to the PIToPI interface from the server for adequate permissions.

3. Problem: Interface is running but no data is collected.Reason: Check for Error –999 in the pipc.log file. This means that data cannot be accessed from a PI 2 node.

Solution: Set up a security file on the source node and put the name of the security file in the interface startup file (either the .ini file or the .bat/.sh file). See the section “Interface Startup Files” for more information.


Appendix B: Troubleshooting

4. Problem: Times for history recovery are not displayed.Solution: Start and end times for every history call and the number of values put into the receiving server will be printed if the debug flag 5 is used. Flag 8 will print less verbose summary for the scan, but not for every tag.

5. Problem: Configuration not read in correctly.Solution: Use debug flags 6 (scan class configuration) and 7 (server configuration). These will print out every startup parameter for either scan class or server.

6. Problem: security file not correctly read or not updated.Solution: Use debug flags 13 (retrieving specifications), 14 (masks printed out), 15 (reading the specifications).

7. Problem: Numerical point types are converted to digitals.Solution: Check the zero and span settings. They should match for the source tags and the receiving tags.

8. Problem: Data does not match exactly from source to receiving server archives.For tags in the scan class that signs up for exceptions, sometimes there are a few different events in the transition from history recovery to normal scanning. The events are all real events, but some events that do not pass the exception and compression tests on the source server may pass on the receiving server. You may see one extra event after history recovery (the snapshot), which then resets the starting point for the compression algorithm causing further differences. This can also happen at the end of a history-recovery period after a network interruption or after backing up the source server archive. This is a necessary consequence of the compression algorithm and can only be avoided by using history-only scan classes.

9. Problem: Many events are missing on the receiving server for tags in scan class 1.Tags in the scan class that signs up for exceptions (by default, scan class 1) rely on prompt retrieval of data from a list that the Update Manager of the PI server maintains. If the events in the list are not retrieved in a timely fashion, the buffer may overflow. This can be seen in the source PI server log as “update list overflow” or sometimes, “global overflow.” In this case, events are lost.

This is most likely to occur towards the end of history recovery, during an archive backup, or during a network interruption. However, if it occurs during a network interruption and the source PI server is 3.3.361.43 or higher and the PI-API is version 1.3.5 or higher, the PI server should return an error which is received by the PIToPI interface. This causes the interface to start another history recovery period.

Solution:

1) If an update overflow occurs during history recovery, the /rh and /rh_inc command-line parameters should be adjusted so that fewer events are retrieved in a single increment. (The points sign up for exceptions just before the last history recovery increment. If it takes too long to retrieve the data in the last increment, the update buffer can overflow.)

100

2) Increase the size of the parameter maxupdatequeue, which is the number of pending updates the Update Manager maintains in its queue, as follows:

@table pi_gen, pitimeout@mode create@istr name, valuemaxupdatequeue, 6000

The value of this parameter should be sufficiently large to hold all the events that the source node is expected to produce in one scan period.

3) Increase the scan rate of the scan class that signs up for exceptions.

4) Put fewer tags in this scan class. More than one copy of the interface may be used if one prefers that the tags sign up for exceptions.

5) Throttle buffered data arriving at the source node. A uniform stream of data into the source node is more easily dealt with by the interface than rapidly varying data rates.

10. Problem: Some security settings do not work in the batch file.Solution: Put these parameters in the .ini file. This problem will be resolved in a future version of the interface.

11. Problem: Digital events manually entered for lab tags on the source PI 2 server are not translated to the equivalent states on the receiving server.Solution: Digitals entered using the string (e.g., “Manual”) on a source PI 2 server may not be translated properly on a PI 3 server. They should be entered using their digital state codes (e.g., 230).


Revision HistoryDate Author Comments

20-Jan-98 CAH Added v2.2.1 to VSS.

23-Apr-98 CAH Variable scan class, extended descriptor (STAG) documented.

03-Jun-98 CAH Fixed extension on PI2 security file in section on source system manager. Changed to version 2.2.2, June, 98. Changed description of /sf parameter.

05-Apr-99 CAH Added location2,location3 recommended values.

10-Dec-99 CAH v2.3.2. Changes for extended API and elaborated on setup, configuration, operation.

12-Jan-00 CAH Fixed Point type description and PI2 PIserver required settings.

21-Jul-00 CAH Minor installation changes.

12-Oct-00 CAH Update document format to match standard interface doc. Added ftp-script usage that was removed with v2.3.2.

27-Nov-00 CAH Added debug flag 8 to troubleshooting. Added /q flag to command line descriptions.

20-Nov-00 DM New version v2.3.8. Added support for commas in source tag name. Edited manual.

19-Feb-01 DM Added piconfig (maxeventqueue) fix to troubleshooting section. Edited sections on timestamps.

14-May-01 DM Added Location 5 information to PI Point Configuration section and security file (-999 error) to Troubleshooting section. Edited Interface Startup Files section. New version 2.3.9

17-May-01 DM Changed archive mode back to ARCAPPENDX and incremented version to 2.4.0

18-May-01 CG Skeleton 1.09

1-Aug-01 CG Further format revisions; added buffering, performance point, io rate tag

3-Aug-01 DM Further editing, corrections for pitopi specifics.

8-Aug-01 DM Corrections to installation, startup, I/O rate tag section, especially in Unix sections.

19-Jan-02 DM Editing, additions to troubleshooting section.

6-Feb-02 DM Added recommendations for data match and avoidance of update list overflow to beginning sections. Edited Loc 5 info.


Revision History

Date Author Comments

12-Feb-02 CG Added PI-ICU, renamed files to standard PI_pitopi

13-Feb-02 HAB Added section on PItoPI ICU Control. (2.7.7)

18-Jul-02 DM, SMS, CG

Clarified sections describing Locations 3 and 5; formatting

23-Jul-02 SMS, CG Added recommendation to not use the interface to read from different sources.

2-Nov-02 DM Fixed errors in description and table for Location 3. calling this manual revision B now.

31-Jan-03 DM Updated for new features in 3.0.7 release and added information to troubleshooting section. Added info on API v. 1.3.8 to UNIX install section.

26-Feb-03 DM Added default value to delays, delayr descriptions.

10-Mar-03 DM Added command-line switch /ts.

28-May-03 DM Digital state caching documented for 3.1.2.0.

10-Jun-03 CG Minor formatting; upped rev

27-Jun-03 DM Improved explanation of hronly, HistOnly

8-Oct-03 DM Added /db information and added command-line parameters to sample .bat file.

15-Dec-03 DM Changed one line describing start of history recovery and changed version number.

24-Jan-03 HAB Updated ICU control screen shots (3.1.2.0, doc rev D)

11-Feb-04 DM Added information on failover and incremented version number.

19-Apr-04 DM Changes to failover sections and version change.

02-Jun-04 PW Update ‘Streamlining PItoPI tag configuration’ startup parameters. Update version info for release.

03-Jun-04 CG Version 3.3.0.7 Rev B: Formatting; fixed section breaks, headers & footers, and pages #s; added ICU to installation section.

23-Jul-04 PW Revised Failover section. Incremented version number.

23-Sep-04 PW Increment version number. Fix typo in failover section. Add description of new startup switch (/tnex). Update troubleshooting section, startup messages for new startup messages.

9-Nov-04 MPK Added section on Configuring the Interface with PI-ICU, Configuring Buffering with PI-ICU. Also made a few minor corrections to some of the description in the command line parameter section.

18-Feb-05 PW Update version on title page.

104


Documents

PI to PI TCP/IPcdn.osisoft.com/interfaces/1971/PI_PItoPI_3.4.0.2.doc · Web view-- Name of failover status tag configured on receiving server. This must be specified as: /ist=tagname,