PI to PI TCP/IP
PI to PI TCP/IP
Interface Documentation
Version 2.4.0
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|Internet |techsupport@ |
|World Wide Web | |
| | |
|Mail |OSI Software, Inc. | |
| |P.O. Box 727 | |
| |San Leandro, CA 94577-0427 | |
| |USA | |
| | | |
| |OSI Software GmbH |OSI Software, Ltd |
| |Hauptstra(e 30 |P. O. Box 8256 |
| |D-63674 Altenstadt 1 |Level One, 6-8 Nugent Street |
| |Deutschland |Auckland 3, New Zealand |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. 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
( 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
Interface Features 2
Principles of Operation 4
Interface Point List 4
Scanning Principles 4
History Retrieval 4
Time Stamp 5
PI Point Configuration 7
Tag Attributes For PIToPI 7
Tag 7
InstrumentTag 7
Exdesc 7
PointSource 8
PointType 8
Location1 8
Location2 8
Location3 9
Location4 9
Location5 10
Shutdown 10
ExcMin, ExcMax, ExcDev and ExcDevPercent 10
Compressing 11
CompDev, CompMin, CompMax, CompDevPercent 11
Zero, Span 12
DigitalSet 12
DigStartCode and DigNumber 12
Scan 12
Dataaccess, Ptaccess 12
Additional Tag Attributes 12
Tag and Node Security 13
PI 3 Security 13
PI 2 Security 13
Receiving and Source System Manager Responsibilities 15
PI 2 Source System Point Limitations 17
Performance Point Configuration 18
Interface Startup Files 19
Interface Startup .bat File - NT 19
Interface Startup .sh File - UNIX Platforms 20
Interface Startup .ini File Used on NT and UNIX 22
Interface Command Line Parameters 24
Interface Installation 26
Windows NT for Intel and Alpha 26
Upgrades 26
Installing the files 26
Modifying the Interface start scripts 27
Modifying the API start and stop scripts 27
Configuring iorate counters 27
UNIX Installation 27
Installing the files 27
Modifying the Interface start scripts 28
Modifying the API start and stop scripts 28
Configuring iorate counters 28
Interface Operation 30
Windows NT Platforms 30
Starting PIToPI interactively 30
Configuring PIToPI to run as a service 30
Shutdown 30
Information and Error Messages 31
UNIX Platforms 31
Starting the PIToPI interface as a foreground process 31
Starting the PIToPI interface as a background process 31
Information and Error Messages 32
Interface Startup Messages 32
Scan Startup Summary 33
Troubleshooting 34
Revision History 36
Introduction
The PIToPI TCP/IP interface transfers data from one PI server (the source server) to another PI server (the receiving server) via TCP/IP. For each copy of the interface used, several source servers (one for each scan class) may be configured to send data to a single receiving server. The receiving and source servers may be either PI 2 (OpenVMS) or PI 3 (UNIX or Windows NT), but the interface program must run on a UNIX or Windows NT node. The interface program may be located on the receiving PI node, source PI node or a PI-API node separate from both PI servers. Thus, it can be moved to the most convenient or secure location.
Data is transferred for a list of points defined in the receiving PI server point database, each of which has a source PI server tag name that it is associated with. First, historical data is retrieved for the points belonging to the interface. The amount of time for which this history is obtained is configurable. When history recovery is completed, continuous scanning for new data is initiated.
Deployment Scenarios
The PIToPI interface is designed to facilitate the use of PI data in scenarios where the source PI system needs to be isolated from users. Some examples are provided here. In any situation listed below, the original PI server may be protected by a firewall if desired.
Database load distribution
If PI data collection must be unhindered by CPU intensive user queries, the PIToPI interface replicates the original PI data to a second PI system. The second PI system would be able to sustain expensive queries from client tools regardless of the response time while the first PI system would be able to promptly respond to process changes.
Database centralization
Essential data may be sent to a single central PI server from many PI systems. The central server may contain only those points needed for overview of operations.
Remote access speed
A PI server may be accessible only through a limited bandwidth connection. In this cas,e the limited bandwidth access to the source PI server would make retrieving data for use in clients unreasonably slow. PIToPI enables faster client queries via the receiving PI server.
Interface Requirements
PIToPI requires the following software versions:
( The minimum operating system versions for the PIToPI interface are Windows NT 4.0, HP-UX 10.10, AIX 4.1, OSF1 3.2, SunOS 5.4.
( PI-API version 1.3.3 or greater is needed. On Windows NT the interface installation program automatically installs and/or updates the PI-API library. The PI-API must be installed first for UNIX nodes.
( TCP/IP connections are needed to both receiving and source PI servers. This interface also operates using RAS to connect over dial-up or ISDN connections. Dial-up connections of 9600 baud have been used successfully.
Interface Features
The PIToPI interface consists of a single executable program, a startup script that contains the interface identification number and startup information, and an initialization file specifying additional startup information. Data from multiple PI source nodes may be transferred by using additional copies of the interface executable and startup script file for each source/receiving PI node combination or by using additional scan classes in a single PIToPI executable, but each copy of the interface can have only one receiving PI node. If an additional scan class is used for each source node, all but one scan class retrieves archived values (i.e., values that have passed the compression test), rather than obtaining exceptions (new snapshot events). If several copies of the interface are used, each copy of the interface and startup script file should be identified by a unique interface number or point source character.
There is no limit to the number of points for which the PIToPI interface can collect data; however, there are limitations on the number of tags for which the interface can obtain exception reports on a PI 2 source node. See the section “PI 2 Source System Point Limitations” for details.
The PIToPI interface monitors point addition, deletion and editing on the receiving PI node and signs up for exceptions on the source PI node. Thus, if PIToPI is located on the receiving PI node, point updates will be monitored on the local PI node and exceptions will be monitored on the remote PI node. If PIToPI is on the source PI node, point updates will be monitored on the receiving PI node remotely and the exceptions will be monitored on the local PI node.
Inputs from the source systems may be scanned on an exception basis as new exceptions are received on the source system or by retrieving archive history. Since only one scan class in any interface copy can sign up for exceptions, the others can obtain only archived data.
The interface also retrieves archived historical data automatically for all points under three other circumstances. The starting point for retrieval under these circumstances is the time of the last event in the receiving server. These three circumstances are
• at startup
0. when points are added
1. when a connection is restored after a breach of communication between the source and receiving nodes.
One can disable history recovery in these situations for all tags with a command-line switch. See the section “Interface Startup Files” for details.
PI receiving nodes must allow the PIToPI interface read and write access. PI source nodes must grant read access. PIToPI supports point security as well as node security. PI 3 point security is configured using the tag attributes for data access (dataaccess) and point access (ptaccess). PI 2 point security is configured using a security file located in the PISYSDAT directory. The interface checks every 10 minutes to see if the security status has changed for points in error and it begins data collection for cleared errors. See “Tag and Node Security” for details.
Another feature is the suppression of interface generated digital states. This is useful when communication is lost or the interface is stopped. The data in the source system is copied to the new system without inserting additional digital states (I/O timeout and Access Denied). This is discussed in the section “PI Point Configuration.”
|Supported Features |
|Platforms |Windows NT (intel and alpha), IBM AIX, Compaq Tru64 |
| |(OSF1), HP-UX, SUN Solaris (SunOS) |
|PI Point Types |Integer (16 and 32 bit), Real (16, 32 and 64 bit), |
| |Digital, String, Blob |
|Sub-second Timestamps |Yes |
|Automatically Incorporates PI Point Attribute |Yes |
|Changes | |
|Exception reporting |Yes |
|PI software required |PI-API |
|Outputs from PI |No (a second interface copy will accomplish this task) |
|Vendor software required |No |
|History recovery |Yes |
|Security |Yes |
|Interface generated digital state suppression |Yes |
|Maximum Point Count |Unlimited |
|UniInt-based |Yes |
|Automatic point attribute synchronization |No [1] |
Principles of Operation
Interface Point List
At startup, the interface scans the PI point database for all points with a pointsource and location1 point attribute that match the specifications in the startup file pitopi.bat or pitopi.sh. During runtime, the interface continues to check the receiving system PI Point Database for point updates (additions, deletions and modifications) and modifies its point list accordingly. If a point has a status of ACCESS DENIED, the interface will keep the point in the list and check periodically for access change.
Scanning Principles
Typically, exception reporting is done on the source system. The receiving system then checks for those exceptions with the frequency specified by the scan class. The use of the /sn flag on the command line is therefore recommended, since this directs the interface to put the exception reports from the source server directly into the PI Snapshot of the receiving server. If this flag is not used, the data obtained from the source server will again be subjected to the exception test before it is logged in the PI Snapshot of the receiving server.
Scan classes that have /hronly or HistOnly=1 enabled will not sign up for exceptions on the source system, but will retrieve archived data when the scan class is scheduled. Only one scan class for each copy of the interface can retrieve snapshot data. By default, this is the first scan class listed on the command line. To change the scan class that retrieves snapshot data to another one listed on the command line, the HistOnly=1 parameter must be specified in the scan-class subsections of the pitopi.ini file for all other scan classes.
If data retrieval fails due to an extended communication failure, the digital state I/O Timeout is written to the PI Snapshot for the affected tags, unless this digital state has been suppressed. It is recommended that I/O Timeout be suppressed since the interface has the ability to retrieve history. The interface attempts to reconnect to the source system at two-minute intervals. As long as history recovery is enabled (the default case), the missing data is recovered when communication has been re-established.
History Retrieval
The PIToPI interface allows specification of the number of hours of history to recover using the /rh= command line switch or the HistRecovery key in the pitopi.ini file. When the interface starts, it will recover number hours of data from the source PI data archive. If, however, snapshot data exists for a time more recent than this, the time of the oldest snapshot, among all points belonging to the interface, will be the starting time for history recovery. Then, archived data will be retrieved for each point starting at the last snapshot time for the receiving point, unless the snapshot value is Point Created. If the receiving system snapshot value of a point is “Point Created” and the receiving data archive is a PI 3 system, the interface will recover number hours of data, even if the timestamps are before the Point Created status. The amount of history should not, however, contain timestamps before the starting date of the current archive.[2] Any data before the start date of the current archive is discarded by the receiving PI Data Archive.
The interface will also automatically retrieve history after a loss of communication between the receiving and source systems. In addition, when new points are added to the interface, history recovery will be done for these points starting from the current receiving data archive time.
There is no limit to the history recovery time. However, recovering large amounts of data may be slow. The /rh_inc parameter specifies the number of hours spanning each archive call. For example, if /rh=48 and /rh_inc=12, four archive calls will be required for the time ranges *-48h to *-36h, *-36h to *-24h, *-24h to *-12h and *-12h to current time (* indicates the current time). This parameter is provided to protect against filling the archive unevenly on the receiving system by retrieving all the data for some points, and having no space left for the last few points.
The historical data that has been retrieved will go through compression on the receiving node if compression is turned on and the receiving server version is less than PI 3.2 SR1 (build 357). This may cause some additional archive values to be eliminated from the data.
History recovery may be disabled for all points by setting /rh=0 in the interface startup script.
Time Stamp
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 3600 seconds. Adjusted time stamps should be used when the source system and the receiving system are in different time zones. The behavior is different, however, with two PI 3 servers. In this case, Location2 = 0 provides the same behavior as Location2 = 1; that is, in both cases, the UTC time is used. The data is therefore archived with identical UTC times in both servers.
If Location2 = 0 and the client tool, PI-DataLink is used to view this data, the values and timestamps will be the same. 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, ProcessBook will display the same times and DataLink will show the times offset by the time difference between the two PI servers.
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 systems. However, the interface must have access permissions to read the data.
Tag Attributes For PIToPI
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.
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); and no source PI system data will be retrieved for this point.
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 “Interface Startup Files” 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 according to the mechanism described in the pisn_putsnapshotx documentation (1. interpret as a float, 2. interpret as an integer, 3. interpret 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 also 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. The recommended setting is Location3=3. Invalid Location3 parameters default to 3, full suppression.
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 till 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 interface shuts down. This can also be suppressed and is discussed below in the Shutdown section.
Location4
The fourth location parameter is used to specify a Scan Class Number to which this point is assigned. The scan class number refers to the ordered frequency specification (/f=) on the interface startup file. The frequency and offset (described in the interface setup description of /f) determine when processing of scan classes occur. 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 |
|3.2 |0 |Replaces value |Leaves old value |
| |1 |Leaves old value |Leaves old value |
| |2 |Replaces value |Replaces value |
| |3 |Replaces value |Replaces value |
Shutdown
In PI 3 the shutdown attribute is set to on (1) by default, and must be turned off (0) to suppress shutdown logging. The digital state Shutdown is written to points listed in shutdown.dat when a PI system is shut down. 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. If you wish to implement Shutdown states for a point in PI, enter the tag name in PISYSEXE:.
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.
Exception values that PIToPI retrieves from the source system queue will undergo exception processing if /sn is not specified. The data entering the source system snapshot may have previously undergone exception processing. The PIToPI interface allows additional exception processing if /sn is not specified. During history recovery, 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.
Zero, Span
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.
DigitalSet
This is a PI 3 Point attribute only. It is not used for PI2. The DigitalSet attribute is used to assign a digital state set to a digital PI Point. For standard usage, see the PI Data Archive Manual for NT and UNIX.
DigStartCode and DigNumber
These attributes are used only with PI 2. They are not used with PI 3. These attributes are used when defining a digital tag on a PI 2 server. For standard usage, see the Data Archive (DA) section of PI System Manual I.
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.
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:”.
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 (point type on PI 3) and compression specifications should match those on the source system.
2. Descriptor
3. Typical Value
4. Engineering Units
5. Filter Code
6. Archiving Flag
7. Resolution Code
Point Attributes not used by the interface are:
8. Square Root Code
9. Totalization Code
10. Conversion Factor
11. Step
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
12. PIBUILD:piserver.txt file and
13. 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
14. DEFAULT=RL (upper case), or
15. =RL
A security file is also required for data retrieval from a PI 2 server. If no security file exists on the PI 2 server ACCESS DENIED status will be written to the tags that allow it and will be written to the log file. 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. Also, the PI-API call to obtain file information was implemented with PI server 2.1.2. Previous version of the PI server must use the ftp script. If the PI-API fails, the next method to obtain the security file contents uses an ftp script. This requires read or read-login access and a VMS login account.
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
16. DEFAULT=RW or
17. =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
All PIToPI interfaces that will access data from a PI 2 source system check that a security file exists on the source system. The name of the 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. If the security file is not there, the following message will be printed.
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. 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
The security file on the source system, PISysDat:PIToPI.sec, 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.
The file structure requires that either I! for INCLUDE mode or X! for EXCLUDE mode be specified, as well as the type specification to use (T! or S! ). There are two tag modes and two specification types. The directives allow the following specification types to be included for reading or excluded from reading:
18. explicit tag name
19. tag mask with * and ? wildcards.
20. point source
21. point source plus location 1 parameter
The security file can contain the following:
22. a leading exclamation point (! ) indicates that the line is a comment and is to be ignored.
23. either an I! or an X! must be specified to set the mode before T!, S! , any tag, or any point source specifications. 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.
24. a T! indicates that the following specifications are tags and tag masks.
25. only 1 tag mask specification per line and no comments after the tag mask.
26. asterisks (*) match any tag sub-string and the question mark (?)matches any single character.
27. a S! indicates that the following specifications are point sources and point sources plus location 1 parameters.
28. only 1 point source specification per line.
29. an E! indicates the end of the file.
30. 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.
The interface will check for changes to the security file on the source node every 10 minutes if any read errors exist, or every 30 minutes if no read errors exist. If the security file has been edited so that the interface no longer has permission to read a tag, the snapshot for the tag will be sent the digital state AccessDenied. 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. The hours of history recovery specified by /rh=# will be recovered or history starting from the current receiving system snapshot time.
Receiving and Source 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) with 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:
31. 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.
32. 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.
33. A PI username and password must be provided which the interface will use as its PI login.
34. 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.
Example Security Files
Example 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!
Example 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!
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.
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 it takes an interface to complete a scan for a particular scan class. The scan time is recorded to millisecond resolution. Multiple scan classes may be offset from one another if processing time for one scan class causes one or more scan classes to miss their scheduled processing time. See the /f command line flag description if configuration of scan offsets is desired.
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 any of the floating-point point types that are supported by the PI server.
Interface Startup Files
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.
Interface Startup .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 \Program Files\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
Interface Startup .sh File - UNIX Platforms
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
#
Interface Startup .ini File Used on 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.
[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=
Interface Command Line Parameters
|Parameters |
|/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 |
| |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 |
| |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 |
| |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 |
| |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 |
| |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 |
| |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) | |
|/db= |Turns on additional debug messages (see troubleshooting section for possible values). |
|(DebugFlags in .ini | |
|file) | |
|/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) | |
|/ln= |Login name of PI user on PI 2 node. This is used for PI 2 source systems. |
|(SourceLogin in .ini | |
|file) | |
|/pw= |Login password of PI user on PI 2 node. This is used for PI 2 source systems. |
|(SourcePassword in .ini| |
|file) | |
|/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 |
| |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 |
| |*- 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. |
|/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 |
| |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) | |
Interface Installation
Before beginning installation of the interface, make sure you have a current backup of the system and PI directories.
Windows NT for Intel and Alpha
The interface distribution installs the files pitopi.exe, pitopi.dbg, pitopi.bat, pitopi.ini, ftp-script.bat, ptpxtcp.doc, releasenotes.txt as well as the PI-API for interfaces. The interface directory in which the files are placed is PIHOME\interfaces\pitopi. All other interface locations such as PIHOME\interfaces\pitopi2 and so on must be manually upgraded. Manual upgrade involves copying the pitopi.exe to the destination directory and checking for any changes in the new pitopi.bat or pitopi.ini files.
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 (PIHOME is defined in %WinDir%\pipc.ini). Otherwise, a location must be chosen for the installation.
Then 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.
The buffer server is installed and configured as well. For the PIToPI interface, it is not recommended to enable buffering. Buffering may be enabled through the control panel\Services applet at a later time 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.
In order to run multiple copies of the interface, create an executable and batch file for each instance with the interface number appended to the name (e.g., pitopi1.exe, pitopi1.bat, and pitopi2.exe, pitopi2.bat). In the .bat files, put the correct interface number in the /id flag; and put the correct executable name at the beginning of the command line. 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.
Modifying the Interface start scripts
The files pitopi.bat and pitopi.ini should be modified to contain the configuration for this installation. Please refer to the section “Interface Command Line Parameters” for configuration parameters.
Modifying the API start and stop scripts
The sitestrt.bat file located in the PIHOME\bin directory is used to start the interface manually. The sitestop.bat file is used to stop the interface. These scripts are called from the pistart.bat and pistop.bat scripts respectively. Modify the sitestrt.bat and sitestop.bat files for the PIToPI interface by adding the following line to sitestrt.bat
..\interfaces\pitopi\pitopi –start
and the following line to the sitestop.bat file.
..\interfaces\pitopi\pitopi –stop
Configuring iorate counters
Configure event counters on the receiving node, if desired, by creating tags with point source ‘L’, point type of float32, and appropriate zero, span and typical value. The rate at which events are added by PIToPI may vary greatly during history recovery, thus a point type of float32 is recommended. Then create an entry in PIHOME\dat\iorates.dat to associate the event counter number with the tag (asterisk or pound signs, ‘*’ or ‘#’, indicate a comment). The event counter numbers are enabled by entering the /ec=# switch on the command line.
* cah 9/25/97; created event counter 11.
sypitopi,11
UNIX Installation
The interface consists of the interface executable file pitopi, add2start, add2stop, pitopi.sh, pitopi.ini, ptpxtcp.doc, and releasenotes.txt.
Installing the files
Prior to installing the interface, you must install the PI-API on the node where the interface will run. Please consult the PI-API Manual for installation instructions. It is recommended that buffering be disabled at this time. In addition, any existing PI-API files should be backed up before continuing to the next step in case settings need to be restored from them.
The next step is to extract the interface distribution. First change to the $PIHOME directory. For example, /opt/piapi on PI API nodes. Then mount the CD-ROM drive and extract the contents of the interface distribution. If you are unable to find the correct device name for mounting your CD-ROM, contact your system administrator to obtain your device name.
The following commands install the interface files in the directory ./interfaces/pitopi.
cd $PIHOME
zcat /cdrom/pitopi234_hpux_tar.Z | tar –xvf –
If multiple copies of the interface are desired, a soft link to the executable and script file entry should be created for each interface number. 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.
Multiple soft links to the pitopi executable may be made by issuing the command, ln -s pitopi pitopi2, for interface 2 as an example. The pitopi.sh start script then needs to be modified to add a case for the interface number just created.
Modifying the Interface start scripts
The files pitopi.sh and pitopi.ini should be modified to contain the configuration for this installation. Please refer to the section “Interface Command Line Parameters” for configuration parameters.
Modifying the API start and stop scripts
In order to automatically start and stop PIToPI when the PI-API software is started or stopped, concatenate the files:
35. add2start and
36. add2stop
to the scripts $PIHOME/bin/sitestart and $PIHOME/bin/sitestop respectively.
Type the following to do the concatenation:
cd $PIHOME/interfaces/pitopi
cat add2start >> $PIHOME/bin/sitestart
cat add2stop >> $PIHOME/bin/sitestop
Important: Use two greater than signs or the files will be overwritten.
The sitestart and sitestop scripts are configured for one interface copy, pitopi, to be started and stopped. If multiple interface copies are needed, then add to the sitestart script additional launches of the start script with the interface number as the argument (pitopi.sh #). The sitestop script should be modified to contain all interface executables started in the PROCNAME list.
Configuring iorate counters
Configure event counters on the receiving node, if desired, by creating tags with point source ‘L’, point type of float32, and appropriate zero, span and typical value. The rate at which events are added by PIToPI may vary greatly during history recovery, thus a point type of float32 is recommended. Then create an entry in $PIHOME/dat/iorates.dat to associate the event counter number with the tag (asterisk or pound signs, ‘*’ or ‘#’, indicate a comment). The event counter numbers are enabled by entering the -ec=# switch on the command line. The example below associates one iorate tag, sypitopi, with the counter number 11.
* cah 9/25/97; created event counter 11.
sypitopi,11
Interface Operation
After configuring the hardware and software and defining points associated with the PIToPI interface, the interface may be started.
Windows NT Platforms
The scripts and mechanisms to start the interface are described for the Windows and UNIX platforms in the following sections. The configuration of the scripts is given in the section “Interface Startup Files”. Also, the location of the log file to which the interface sends messages is given.
Starting PIToPI interactively
The interface can be started interactively by issuing the command pitopi.bat from the interface directory. If the interface is started interactively, the user must stay continuously logged in for the interface to run.
Configuring PIToPI to run as a service
The interface is installed to run as a service with the display name “PI_to_PI Interface” by the installation program. The service is dependent upon tcpip and is configured to start manually by issuing the command pitopi -start from the interface directory, by issuing the command net start pitopi, or by using the “Start” button from the control panel\Services applet. After testing the setup of the interface, the service may be configured to automatically restart after a reboot by the radio button “Auto” located in the control panel\Services\Startup applet.
If buffering is needed, 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”
Auto starting of the PIToPI service after a reboot is now enabled and is dependent upon the startup of the tcpip and bufserv services. The service display name will be the same as the executable name (pitopi in this case).
For multiple interface copies, each numbered executable should be installed as a service. Please see the help menu (pitopi -?) for a full listing of installation options.
Shutdown
With buffering of the interface, use pistop.bat. To shut down only the pitopi interface, use net stop pitopi, pitopi –stop , or the Control Panel> Services> Stop button.
Information and Error Messages
All interface messages, informational and error messages, will be sent to the pipc.log file. The pipc.log resides in the \pipc\dat directory if a pipc.ini file with PIHOME defined exists or the log file will be in the \temp directory in the root path; e.g. C:\temp.
Important messages regarding the status of communication will be shown on the Command Prompt window for PIToPI interfaces running interactively.
UNIX Platforms
Starting the PIToPI interface as a foreground process
The interface is automatically started with pistart on PI API nodes. If interfaces are already running on the node and you only wish to start the PIToPI interface, type the following commands (these are also in $PIHOME/sitestart).
cd $PIHOME/interfaces/pitopi
./pitopi.sh
Shutdown
The interface is automatically stopped when the PI Home or PI API node is stopped when sitestop is called.
See the UniInt End User Document for more information on running the interface as a foreground process.
Starting the PIToPI interface as a background 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 $PHOME/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 kill 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.
Information and Error Messages
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 Startup 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.
The historical data that has been retrieved will go through compression on the
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.
3. Problem: displaying Times for history recovery.
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. Also, flag 8 will print less verbose summary for the scan, but not for every tag.
4. 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.
5. Problem: security file not correctly read or not updated.
Solution: Use debug flags 13 (retrieving specifications), 14 (masks printed out), 15 (reading the specifications).
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. |
|3-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. |
|5-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 |
| | | |
| | | |
| | | |
-----------------------
[1] This will be provided by the PI Auto Point Sync (PI-APS) utility.
[2] 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.
................
................
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