PI to PI TCP/IP
PI to PI TCP/IP
(NT / Unix)
Interface
Version 2.4.6
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P. O. Box 8256 |
| |San Leandro, CA 94577-0427 |Level One, 6-8 Nugent Street |
| |USA |Auckland 3, New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |Singapore, 189721 |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. 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.
ptpxtcp.doc
( 1997 - 2001 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Deployment Scenarios 1
Interface Requirements 1
Reference Manuals 2
Supported Features 2
Principles of Operation 7
Installation Checklist 9
Interface Installation on NT 11
Installation Kit 11
Naming Conventions and Requirements 12
Microsoft DLLs 12
Interface Directories 13
The PIHOME Directory Tree 13
Interface Installation Directory 13
Manual Interface Installation Procedure 13
Installing the Interface as an NT Service 14
Interface Installation on Unix 15
Naming Conventions and Requirements 15
Interface Directories 15
The PIHOME Directory 15
Interface Installation Directory 16
Interface Installation Procedure 16
Digital States 17
PointSource 19
PI Point Configuration 21
Point Attributes 21
Tag 21
PointSource 21
PointType 21
Location1 21
Location2 22
Location3 22
Location4 23
Location5 23
InstrumentTag 24
ExDesc 24
Scan 24
Shutdown 24
ExcMin, ExcMax, ExcDev and ExcDevPercent 25
Compressing 26
CompDev, CompMin, CompMax, CompDevPercent 26
DataAccess, PtAccess 26
Zero, Span 26
Additional Tag Attributes 27
Performance Point Configuration 29
I/O Rate Tag Configuration 31
Monitoring I/O Rates on the Receiving Node 31
Configuring the PI Point on the Receiving Node 31
Configuration on the Interface Node 31
Tag and Node Security 35
PI 3 Security 35
PI 2 Security 35
Sample Security Files 37
System Manager Responsibilities 38
Receiving System Manager 38
Source System Manager 39
PI 2 Source System Point Limitations 39
Startup Command File 41
Command Line Parameters 41
Sample PItoPI.bat File - NT 43
Sample pitopi.sh File - UNIX 45
Sample pitopi.ini File - NT and UNIX 47
Starting / Stopping the Interface on NT 49
Starting Interface as a Service 49
Stopping Interface Running as a Service 49
Starting / Stopping the Interface on UNIX 51
Command-Line Syntax for Background Processes 51
Terminating Background Processes 52
Anomalous Background Job Termination 52
Buffering 53
Sample piclient.ini File 54
Appendix A: Error and Informational Messages 57
Message Logs 57
System Errors and PI Errors 57
Interface Startup Messages 57
Scan Summary 58
Appendix B: Troubleshooting 59
Revision History 61
Introduction
The PIToPI TCP/IP interface transfers data from one PI server (the source server) to another PI server (the receiving server) via TCP/IP. For each copy of the interface used, several source servers (one for each scan class) may be configured to send data to a single receiving server. The receiving and source servers may be either PI 2 (OpenVMS) or PI 3 (UNIX or Windows NT), but the interface program must run on a UNIX or Windows NT node. The interface program may be located on the receiving PI node, source PI node or a PI-API node separate from both PI servers. Thus, it can be moved to the most convenient or secure location.
Data is transferred for a list of points defined in the receiving PI server point database, each of which has a source PI server tag name with which it is associated. First, historical data is retrieved for the points belonging to the interface. The amount of time for which this history is obtained is configurable. When history recovery is completed, continuous scanning for new data is initiated.
Deployment Scenarios
The PIToPI interface is designed to facilitate the use of PI data in scenarios where the source PI system needs to be isolated from users. Some examples are provided here. In any situation listed below, the original PI server may be protected by a firewall if desired.
Database Load Distribution
If PI data collection must be unhindered by CPU-intensive user queries, the PIToPI interface replicates the original PI data to a second PI system. The second PI system would be able to sustain expensive queries from client tools regardless of the response time while the first PI system would be able to promptly respond to process changes.
Database Centralization
Essential data may be sent to a single central PI server from many PI systems. The central server may contain only those points needed for an overview of operations.
Remote Access Speed
A PI server may be accessible only through a limited bandwidth connection. In this case, the limited bandwidth access to the source PI server would make retrieving data for use in clients unreasonably slow. PIToPI enables faster client queries via the receiving PI server.
Interface Requirements
PIToPI requires the following software versions:
• The minimum operating system versions for the PIToPI interface are Windows NT 4.0, HP-UX 10.10, AIX 4.1, OSF1 3.2, or SunOS 5.4.
• PI-API version 1.3.3 or greater is needed. On Windows NT, the interface installation program automatically installs and/or updates the PI-API library. The PI-API must be manually installed first for UNIX nodes.
• TCP/IP connections are needed to both receiving and source PI servers. This interface also operates using RAS to connect over dial-up or ISDN connections. Dial-up connections of 9600 baud have been used successfully.
Reference Manuals
OSIsoft
• UniInt End User Document
• PI Data Archive Manual
• PI-API Installation Instructions
Supported Features
|Feature |Support |
|Part Number |PI-IN-OS-PI-AIX |
| |PI-IN-OS-PI-DUX |
| |PI-IN-OS-PI-HP |
| |PI-IN-OS-PI-NTA |
| |PI-IN-OS-PI-NTI |
| |PI-IN-OS-PI-SOL |
|Platforms |AIX / DUX / HP-UX / NTA / NTI / SunOS |
|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 |No |
|* 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 |No |
|Device Point Types |N/A |
|* Automatic Point Synchronization Available |Yes |
* See paragraphs below for further explanation.
Source of Timestamps
The PIToPI interface writes values to the receiving PI system with three possible timestamps. A timestamp may be adjusted for time zone (Location2 = 0), unadjusted (Location2 = 1), or adjusted with time zone and clock differences (Location2=2). In the last case, the time differences are checked every two minutes. The mode of adjustment is configurable for each tag.
An unadjusted time stamp means that the local PI time stamp from the source system is used. A time stamp adjusted for time zone is equal to the source time minus the time difference between the source system and the receiving system in integer multiples of 1800 seconds. If the time difference between the servers is greater than 1800 seconds, the time will be adjusted as if the servers are in different time zones even if the time difference is due to errors in the clock settings. Adjusted time stamps should be used when the source system and the receiving system are in different time zones.
When the source and destination 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 timestamps 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, timestamps will be offset by the time zone difference plus the clock difference.)
History Recovery
The PIToPI interface allows specification of the number of hours of history to recover using the /rh= command-line switch or the HistRecovery key in the pitopi.ini file. When the interface starts, it will recover number hours of data from the source PI data archive. If, however, snapshot data exists for a time more recent than this, the time of the oldest snapshot, among all points in the scan class, will be the starting time for history recovery. Then, archived data will be retrieved for each point starting at the last snapshot time for the receiving point, unless the snapshot value is Point Created. If the receiving system snapshot value of a point is “Point Created” and the receiving data archive is a PI 3 system, the interface will recover data from the time of the oldest snapshot, even if the timestamps are before the Point Created status. The amount of history should not, however, contain timestamps before the starting date of the current archive. Any data before the start date of the current archive is discarded by the receiving PI Data Archive.
The interface will also automatically retrieve history after a loss of communication between the receiving and source systems. In addition, when new points are added to the interface, history recovery will be done for these points starting from the current receiving data archive time.
There is no limit to the history recovery time. However, recovering large amounts of data may be slow. The /rh_inc parameter specifies the number of hours spanning each archive call. For example, if /rh=48 and /rh_inc=12, four archive calls will be required for the time ranges *-48h to *-36h, *-36h to *-24h, *-24h to *-12h and *-12h to current time (* indicates the current time). This parameter is provided to protect against filling the archive unevenly on the receiving system by retrieving all the data for some points, and having no space left for the last few points. 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.
History recovery may 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. NOTE: adding data to old archives with no primary record for a given point could cause severe performance degradation to PI servers.
UniInt-Based
UniInt 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 Synchronization
The 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 Operation
The 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, all but one scan class retrieves archived values (i.e., values that have passed the compression test), rather than obtaining exceptions (new snapshot events). If several copies of the interface are used, each copy of the interface and startup script file should be identified by a unique interface number or point source character.
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.
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. If /hronly is used on the command line, none of the scan classes will sign up for exceptions on the source system; all will retrieve archived data when the scan class is scheduled.
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 breach of 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.
PI receiving nodes must allow the PIToPI interface read and write access. PI source nodes must grant read access. In addition to nod 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 the 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; 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 Checklist
For 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 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.)
2. Install the PItoPI interface. For Unix, this means copying the files to the correct directories. For NT, this means using the install kit.
3. Define digital states on receiving node.
4. Choose a point source. If PI 2 home node, create the point source.
5. Configure PI points.
6. Configure performance points.
7. Configure I/O rate tag.
8. Set up tag and node security.
9. Edit startup command file.
10. Start the interface.
11. Verify data.
Interface Installation on NT
OSIsoft recommends that interfaces be installed on PI-API nodes instead of directly on the PI Server node. A PI-API 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. The primary function of the PI Server is to archive data and to service clients that request data.
In most cases, interfaces on PI-API nodes should be installed as automatic services. 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.
Installation Kit
The interface distribution kit installs the files pitopi.exe, pitopi.dbg, pitopi.bat, pitopi.ini, ftp-script.bat, ptpxtcp.doc, releasenotes.txt as well as the PI-API. The interface directory in which the files are placed is PIHOME\interfaces\pitopi. All other interface locations such as PIHOME\interfaces\pitopi2 must be manually upgraded. Manual upgrade involves copying the pitopi.exe, pitopi.bat, and pitopi.ini to the destination directory and checking for any changes in the new pitopi.bat and pitopi.ini files.
Pitopi.ini
All copies of the interface (executable and batch file) may reside in the same directory. In this case, only one pitopi.ini file is required. This file has 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 file. The filename should always be pitopi.ini, without any numbers.
Upgrades
Any existing PIHOME directory will not be changed by this installation program. The pitopi.bat, pitopi.ini and ftp-script.bat files are not overwritten. The API upgrade will not overwrite the sitestrt.bat or sitestop.bat, pilogin.ini or piclient.ini files.
Installing the files
Execute the installation program and follow the directions for the PI-API and interface installation.
The current PIHOME directory is used for the installation path if it exists Otherwise, a location must be chosen for the installation.
The default PI home node must be selected if it is not yet configured. If the default home node is configured, it may be changed by entering the new server information in the installation dialogs. The pilogin.ini file will be updated with this information.
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.
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.
Naming Conventions and Requirements
In 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.
Microsoft DLLs
The following Microsoft DLLs are distributed on the installation CD-ROM. Copy these files to the winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.
|MSVCIRT.DLL |
|MSVCRT.DLL |
|MSVCRT40.DLL |
|MSVCP50.DLL |
|MSVCP60.DLL |
The following additional Microsoft DLLs are also distributed on the CD-ROM. These DLLs are only used by a debug version of the interface. Copy these files to the Winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.
|MSVCIRTD.DLL |
|MSVCRTD.DLL |
|MSVCP50D.DLL |
|MSVCP60D.DLL |
Interface Directories
The PIHOME Directory Tree
The 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 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 Directory
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.
Manual Interface Installation Procedure
In the installation procedure below, assume that interface number 1 is being installed and that all copies of the interface will be installed in the same directory.
1. Copy the interface files from the installation media to
PIHOME\interfaces\pitopi\. Create the directory if necessary.
2. If necessary, rename the command file so that it has the same root name of the executable.
3. Alter the command-line arguments in the .bat file as discussed in this manual.
4. Try to start the interface interactively with the command:
pitopi.bat
If the interface cannot be started interactively, one will not be able to run the interface as a service. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the interface is successfully running interactively, one can try to run it as a service by following the instructions below.
Installing the Interface as an NT Service
One 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-API 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 Unix
One 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? OSIsoft recommends that the interface be installed on a remote PI-API node. The primary function of the server node is to archive data and to service the clients that request that data. The PI Server should not have to compete with interfaces for the machine’s resources. If the interface is installed on a remote PI-API node, then the PI-API must be installed on that node before the interface is installed. Refer to the PI-API Installation Instructions manual.
If the interface is installed on a server node, the interface should be configured to start and stop in conjunction with the PI Server. If the interface is installed on a PI-API node, then the interface should be configured to start and stop with the PI-API. Site-specific scripts can be edited for this purpose, as described in the installation procedure below. The PI Server and the PI-API, in turn, can be configured to start and stop automatically when the system is shut down or rebooted. Procedures for automatic startup and shutdown of PI or the PI-API are platform specific. The automation procedures are discussed in the PI System Management chapter of the PI Data Archive manual.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is pitopi and that the startup command file is called pitopi.sh.
In order to run multiple copies of the interface from the same directory, it is necessary to rename the executable and the command file. It is customary to use pitopi1 and pitopi1.sh for interface number 1, pitopi2 and pitopi2.sh for interface number 2, and so on.
Pitopi.ini
All copies of the interface (executable and batch file) may reside in the same directory. In this case, only one pitopi.ini file is required. This file has 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 file. The filename should always be pitopi.ini, without any numbers.
Interface Directories
The PIHOME Directory
PIHOME is an environment variable that points to the base directory where the PI-API is installed. The setting of environment variables is discussed in the PI-API Installation Instructions manual.
Interface Installation Directory
There are two conventions for the installation directory. The first convention is to place all copies of the interface into a single directory. If this convention is followed, it is recommended to place pitopi1, pitopi2, pitopi3, etc., 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 pitopi1, pitopi2, pitopi3, etc., in the directories:
$PIHOME\interfaces\pitopi1\
$PIHOME\interfaces\pitopi2\
$PIHOME\interfaces\pitopi3\
and so on.
Create the installation directories as necessary.
Interface Installation Procedure
In the installation procedure below, it is assumed that interface number 1 is being installed and that all copies of the interface will be installed in the same directory. To install another copy of the interface, repeat the following procedure with pitopi# used in place of pitopi1, where # is the interface number between 1 and 99.
1. Copy the interface files to $PIHOME\interfaces\pitopi\. Create the directory if necessary.
2. If necessary, rename the executable and command files to pitopi1 and pitopi1.sh. The executable and command file should have the same root name.
3. Alter the command-line arguments in the pitopi1.sh file as discussed in the section “Startup Command File.”
4. Try to start the interface as a foreground process. Follow the instructions in the next two sections to configure the command file and start the interface. It is advantageous to begin with foreground processes because the procedure for starting and stopping foreground processes is easier than for background processes. Once the interface is successfully running as a foreground process, one can try to run the interface in the background by following the appropriate instructions in the section “Starting/Stopping the Interface on Unix.”
Digital States
Digital 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 Node
Digital 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 Sets
PI 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 Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of 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.
PointSource
The 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 Attributes
In 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 Nodes
The 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.
PI 3 Server Nodes
No 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.
PI Point Configuration
The 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
Tag
This 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.
PointSource
The 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.
PointType
The 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, any needed conversions are performed by the server. 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.
Location1
The first location code contains the interface identification number. The pointsource and location1 combination identifies the points for which this copy 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.
Location2
The 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 timezone offsets from UTC time on the source PI server. Thus, if the source and receiving servers are in different timezones, 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.
Location3
The third location parameter is used to suppress the writing of interface-generated digital state codes for a particular point and to utilize the current snapshot when running in history-only mode.
The interface writes I/O Timeout when communication has failed and ACCESS DENIED when the source node has read access denied or the receiving node has read or writtten access denied. Location3 is used to suppress either or both these digital states. The recommended setting is Location3=3, suppression of both states. Invalid Location3 parameters default to 3.
If history only is specified (/hronly on the command line or HistOnly in the .ini file), archived data is retrieved from the source server up until but not including the latest snapshot, by default. By setting Location3 to 4, 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, but would be of interest in only a few cases, such as for manual inputs.
0 - No digital state suppression
1 - Suppress I/O Timeout
2 - Suppress Access Denied
3 - Suppress both I/O Timeout and Access Denied
4 - Add the current snapshot for tags collected in /hronly mode. This may generate extra archived values.
The recommended setting is therefore, Location3 = 3 to suppress interface-generated digital states. If both suppression of the digital states and use of the latest snapshot is desired, set Location3 to the sum of the two codes. For example, to suppress Access Denied, but not I/O Timeout, and to use the latest snapshot, set Location3 = 6. To suppress both I/O Timeout and Access Denied and to use the latest snapshot, set Location3 = 7.
Another digital state, Shutdown, is written to points when the PI server shuts down. (It is actually written when it starts up again.) This can also be suppressed and is discussed below in the Shutdown section.
Location4
The 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.
Location5
The fifth location parameter is used for points that require manual editing (e.g., lab tags.) The default value is 0. Setting the Location 5 to 2 or 3 enables new values to be sent to the receiving server after they have been changed on the source server. The difference between settings 2 and 3 is that with setting 3, a message is printed to the log file stating that the value of the tag was changed and giving the old value and the new value. Below is a table that describes the behavior of the interface with a particular version of the PI server on the receiving node for each Location 5 setting.
|PI Server Version |Location 5 |Edit Snapshot Value |Edit Archived Value |
|3.2.357.17 or higher |0 |Appends new value |Leaves old value |
| |1 |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 |Replaces value |Replaces value |
| |3 |Replaces value |Replaces value |
InstrumentTag
The 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 within them.
ExDesc
The extended descriptor may be used as an alternative source tag specification by using the keyword STAG=. 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.
Scan
If 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.
Shutdown
Note: 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 Nodes
The 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 Nodes
The 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 ExcDevPercent
These 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 batch 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 by
ExcDev = 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 ExcDev
and
the 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.”
Compressing
If 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, CompDevPercent
These 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
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, PtAccess
PI 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, Span
These attributes should match for the source and receiving points.
PI 2 Server Nodes
For 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 Nodes
For 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 Attributes
The following tag attributes are not unique to the PIToPI interface but are required for proper operation. These parameters are listed below: 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.
1. Descriptor
2. Typical Value
3. Engineering Units
4. Filter Code
5. Archiving Flag
6. Resolution Code
Point Attributes not used by the interface are:
7. Square Root Code
8. Totalization Code
9. Conversion Factor
10. Step
Performance Point Configuration
The 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 PI2 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
Performance point configuration is the same on all operating system platforms. Performance points are configured as follows.
1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where 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.
I/O Rate Tag Configuration
An 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 Node
For NT and UNIX nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.
Configuring the PI Point on the Receiving Node
PI 2 Receiving Nodes
A listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:
@PISysDat:
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Receiving Nodes
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
Configuration on the Interface Node
For 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 \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.
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, 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 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. 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
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
Tag and Node Security
PI 3 Security
Security 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 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.,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.
PI 2 Security
There 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.sec where is the name string specified in the PIToPI startup script file. The security file contains tag security information.
PI 2 Node Security
Support for PI 2 node access security first began with PI 2 version 2.0.8. The full documentation for PIServer is available in the
11. PIBUILD:piserver.txt file and
12. 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
13. DEFAULT=RL (upper case), or
14. =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
15. DEFAULT=RW or
16. =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 Security
A 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 not found on node
where 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 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.sec, where is the name of the receiving node.
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 reference 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:
17. explicit tag name
18. tag mask with * and ? wildcards.
19. point source
20. point source plus location 1 parameter
The structure of the security file is as follows:
21. a leading exclamation point (! ) is used to denote a comment.
22. 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.
23. a T! indicates that the following specifications are tags and tag masks.
24. only 1 tag mask specification may be used per line and no comments may be used after the tag mask.
25. asterisks (*) match any tag sub-string and the question mark (?) matches any single character.
26. a S! indicates that the following specifications are point sources and point sources plus location 1 parameters.
27. only 1 point source specification is permitted per line.
28. an E! indicates the end of the file.
29. 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 1
I! 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.
*.al
unit?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.
sinusoid
le420
S! Point source specifications.
! All PE tags included.
C
! Only point source ‘P’ with location1 = 2 included.
P2
E!
System Manager Responsibilities
Securing the source archive data requires that both the source and receiving system managers perform the following tasks.
Receiving System Manager
1. Give the source system manager a copy of the PIToPI interface manual.
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@pi
set USER=anonymous
b) 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@pi
and a similar line for each source node accessed by additional PIToPI interfaces
Source System Manager
30. 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.
31. 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.
32. A PI username and password must be provided which the interface will use as its PI login.
33. 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 Limitations
On 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 ¼ 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 test) 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 ½ the total number of tags on the system. Such processes include DataLink and ProcessBook. The only way to resolve this problem is to contact OSI Software 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.
Startup Command File
The interface startup files must be configured with site-specific startup parameters that consist of information about the source and destination of the data transfer. The command-line parameters may be entered with either a leading slash or a leading dash. Many of the command-line parameters can be entered in the pitopi.ini file, located in the executable directory, instead of in the pitopi.bat or pitopi.sh file. The point source (/ps), interface number (/id), event counters (/ec), scan classes (/f), queuing option (/q), snapshot option (/sn) and receiving host (/host) must, however, be entered in the pitopi.bat or pitopi.sh file.
If the same parameter is specified in both the pitopi.bat (or pitopi.sh) file and the pitopi.ini file, the specification in the pitopi.bat (or pitopi.sh) file will override that in the pitopi.ini file, unless the parameter is specified in a scan-class subsection of the pitopi.ini file. These subsections are the ultimate source of specification information.
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.
Command Line Parameters
|Parameter |Description |
|/id= |Interface number. This switch must be set to the interface number. Each interface |
|/in= |maintains a list of only those points with the pointsource and location1 point attributes |
|required |which match the point source and interface number defined by /ps and /id. /in also defines|
| |the interface number and overrides the /id parameter. |
|/ps= |Point source. The user must specify a unique point source such as P that is currently not |
|required |in use by another process. Only single character point sources are supported. |
|/f= |Scan frequency. The interface checks the source server for new data at this frequency. If |
|required |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. |
|/sn |Snapshot. Use pisn_putsnapshotqx for adding data to the receiving PI server. If this flag |
|optional |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. |
|/q |Queuing. The values sent to the receiving server will be sent in arrays approximately 4 |
|optional |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. |
|/ec= |Event counter. Default = 1. Range allowed is 1-34 and 51-200. Multiple counters may be |
|(EventCounter in .ini |specified on the command line. The first event counter is updated for every value sent to |
|file) |the server. Subsequent counters will be updated by individual scan classes if the scan |
|optional |class section specifies that counter in pitopi.ini. |
|/host= |Name of receiving PI node. The node name may be specified as /host= node_name:tcpip_port |
|(ReceivingHost in .ini |where the port number will be either 545 or 5450. |
|file) | |
|required | |
|/db= |Turns on additional debug messages (see troubleshooting section for possible values). |
|(DebugFlags in .ini | |
|file) | |
|optional | |
|/src_host= |Name of source node to retrieve data from. This must be specified as: |
|(SourceHost in .ini |/src_host=node_name:tcpip_port where the port number will be either 545 or 5450. |
|file) | |
|required | |
|/ln= |Login name of PI user on PI 2 node. This is used for PI 2 source systems. |
|(SourceLogin in .ini | |
|file) | |
|optional | |
|/pw= |Login password of PI user on PI 2 node. This is used for PI 2 source systems. |
|(SourcePassword in .ini| |
|file) | |
|optional | |
|/sf= |Name-suffix of tag security file on a PI 2 system. The full name on the PI2 system is |
|SecurityFile |PITOPI.SEC, where is the portion specified on the command line. The switch |
|required for PI 2 |is used for PI 2 source nodes and is ignored if specified for PI 3 source nodes. |
|/rh_inc= |Number of hours of history to recover in each cycle through the point list. If the number |
|(MaxArcTimespan in .ini|of hours specified by /rh_inc= is greater than or equal to the hours of history|
|file) |recovery requested in /rh=, history will be recovered in one archive call from |
|optional |*- hours to *. If is greater than , the archive calls to |
| |retrieve history will be divided into N calls, where N = / + 1. The |
| |calls, which start from (*-), will each span 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= |Number of hours to recover history for all points. /rh=0 disables history recovery for |
|(HistRecovery in .ini |all points. Defaults to 8 hours if not specified. See “History Retrieval,” in the |
|file) |Principles of Operation section for more information on history recovery. |
|optional | |
|/hronly |If this parameter is set, tags do not sign up for exceptions. Each scheduled scan time |
|(HistOnly in .ini file)|(specified by /f), history recovery is done from the last snapshot value to the current |
|optional |time. |
| |Alternately, specifies a range of history to recover before exiting. The times should be |
| |specified using PI time string formats. 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. |
|/hrpause |Milliseconds to pause between history recovery calls. |
|(HistPause in .ini | |
|file) | |
|optional | |
Sample PItoPI.bat File - NT
The 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 pitopi.bat
REM
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 pitopi.bat to
REM pitopi#.bat where # is the same number passed by /id=# in the command
REM 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 refers
REM to the name of the source node. Previously this was the name of the
REM receiving node.
REM 21-Apr-97 rab> Removed noservice option - no longer needed
REM 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 security
REM parameters to optional.
REM 19-Jan-98 cah> Added /rh_inc parameter.
REM 04-Jun-98 cah> edited /sf parameter description
REM 25-Jan-99 cah> Added /perf parameter description
REM 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 Command line arguments:
REM /ps= point source (required)
REM /f= scan frequency (required)
REM /id= (or /in= ) number to associate with particular interf. (required)
REM /sn use putsnapshot instead of sendexceptions (optional)
REM /q use queueing for snapshots (optional)
REM /host= name of receiving node (required)
REM (ReceivingHost in pitopi.ini file)
REM /src_host= name of source node (required)
REM (SourceHost in pitopi.ini file)
REM /ec= rate counter number(s) (optional)
REM (EventCounter in pitopi.ini file)
REM /perf= Interval between scan performance summaries. (optional)
REM /db= turns on additional debug messages
REM (DebugFlags in pitopi.ini file)
REM /sf= unique part of PI2 security file name on source node (optional)
REM (SecurityFile in pitopi.ini file)
REM /ln= name of PI2 PI user name (optional)
REM (SourceLogin in pitopi.ini file)
REM /pw= name of PI2 PI user password (optional)
REM (SourcePassword in pitopi.ini file)
REM /rh= max number of hours of history to recover, (optional)
REM default=8 hours.
REM (HistRecovery in pitopi.ini file)
REM /rh_inc=hours of history in each archive call. (optional)
REM default=24 hours. Cannot be zero.
REM (MaxArcTimespan in pitopi.ini file)
REM /hronly get history only, not exceptions (optional)
REM (HistOnly in pitopi.ini file)
REM /hrpause= milliseconds to pause between history calls. (optional)
REM (HistPause in pitopi.ini file)
REM
REM Command line arguments need a space between arguments, but no spaces
REM within argument.
REM
REM Note: following configuration requires entries in pitopi.ini
REM
.\pitopi.exe /ps=P /id=1 /sn /q /perf=0 /host=localhost:5450 ^
/ec=11 /ec=12 /f=10,0 /f=300,5
REM
REM end of pitopi.bat
Sample pitopi.sh File - UNIX
The 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.
#
if [ "${1:-undef}" = "undef" ]; then
INTF_NUM=1
else
INTF_NUM=$1
fi
PROG_NAME=pitopi$INTF_NUM
# if PIHOME not in environment, then set for this procedure
if [ "${PIHOME:-undef}" = "undef" ]; then
echo "PIHOME not defined"
PIHOME=$PWD/../..
fi
ISRUNNING=`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"
;;
esac
else
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 UNIX
The startup pitopi.ini file for the interface will reside in the directory PIHOME\interfaces\pitopi. Each section must contain 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 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]. However, if the SourceHost is entered in [PIToPI-1], and not in the scan class sections, 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 numbers.
[PIToPI-1]
; If needed parameters not specified in a scan class section,
; these are used.
EventCounter=11
SourceHost=pi
HistRecovery=48.0
MaxArcTimespan=24.0
[PIToPI-1.1]
EventCounter=11
[PIToPI-1.2]
EventCounter=12
SourceHost=grape
HistOnly = 1
; --- 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 NT
This 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 Service
If 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 Service
If the interface is installed a service, it can be stopped at any time from the services control panel or with the command:
pitopi.exe –stop
The 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.
Command-Line Syntax for Background Processes
Jobs 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 pitopi1.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. HPUX boxes are notorious for sending hang-up signals to jobs that a user has started when that user logs off. Always execute a background job with nohup, either by incorporating it into the startup command file of the interface or by typing nohup pitopi1.sh or nohup sh pitopi1.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 nonexistentfile
fails 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 &
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 Processes
First, obtain the process id (pid) of the background job. This is done as follows. First execute the command:
ps –ef | grep pitopi
which 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 12788
The 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 Termination
On 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.
Buffering
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-API Installation Instructions.
PI-API 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. Buffering 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.
If one wishes to add buffering after installing the interface, the interface should be removed as a service and reinstalled from a DOS command line with the following commands.
cd PIHOME\interfaces\pitopi
pitopi -remove
pitopi -install -auto -depend “tcpip bufserv”
In order to shutdown the interface with buffering, use pistop.bat. To shut down only the pitopi interface, use net stop pitopi, pitopi –stop , or the Control Panel> Services> Stop button.
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 - 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|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) |
Sample piclient.ini File
NT
On 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=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
Unix
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. 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=1
MAXFILESIZE=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 Logs
The 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 Errors
System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
Error Descriptions on NT and Unix
On NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
All 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 Messages
When 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. In the following example, server 0 is the receiving server (localhost), server 1 is the first source server (berry) and server 2 is the second source server (casaba). Each server listing indicates the PI build number, connection status and time offsets (toff indicates the difference in the time clock of the interface node and the server and tzoff indicates the time zone difference of the interface node and the server). The connection status of x1 indicates the interface is connected while x0 indicates the interface is not connected. For servers to which the interface is connected, the build number and time offsets are shown. PI 2 servers are always build 1. The first scan class, denoted by “SCAN 1,” retrieves data from server 1 (srvidx = 1) and the second scan retrieves data from server 2. The amount of data recovered is indicated by hr-time seconds divided into increments of hr-increment seconds. For PI 2 servers, the security file name is listed. The debug settings and scan options are printed as hexadecimal numbers. A scan option of x10000 indicates that history-only mode is enabled.
PIToPI- 1> SERVER 0, LOCALHOST:5450, build 357, stat x101, toff 0, tzoff 0, hr-pause 10
PIToPI- 1> SERVER 1, BERRY:5450, build 357, stat x1, toff 395, tzoff 0
PIToPI- 1> SCAN 1, ec 11, srvidx 1, hr-time 172800, hr-increment 86400, debug flag x80, options x0
PIToPI- 1> SERVER 2, CASABA:545, build 0, stat x0, toff 0, tzoff 1, security-file test1
PIToPI- 1> SCAN 2, ec 12, srvidx 2, hr-time 172800, hr-increment 86400, debug flag x80, options x10000
Scan Summary
After 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:5450
PIToPI- 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.
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: 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, value
maxeventqueue, 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.
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.
Sometimes data mismatch of a few events results from one extra event after history recovery (the snapshot). This resets the starting point for the compression algorithm.
9. Problem: Some or all tags stop updating after a network glitch or an archive backup.
If you observe this phenomenon, please contact Tech Support.
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.
Revision History
|Date |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 |
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- radians 18 to pi converter
- decimal to pi fraction calculator
- number to pi form calculator
- how to find ip port
- number to pi converter
- decimal radians to pi radians
- pi over 4 to degrees
- how to check router ip address
- radians to pi calculator
- convert to terms of pi calculator
- how to find your ip address windows
- my ip address show my ip address