Siemens Spectrum Power TG Linux Interface to the PI System
Siemens Spectrum Power TG
Linux Interface to the PI System
Version 1.0.0.0
Revision A
|OSIsoft, LLC | |International Offices |
|777 Davis St., Suite 250 | |OSIsoft Australia |
|San Leandro, CA 94577 USA | |Perth, Australia |
| | |Auckland, New Zealand |
|Additional Offices | |OSIsoft Germany GmbH |
|Houston, TX | |Altenstadt, Germany |
|Johnson City, TN | |OSIsoft Asia Pte Ltd. |
|Longview, TX | |Singapore |
|Mayfield Heights, OH | |OSIsoft Canada ULC |
|Philadelphia, PA | |Montreal, Canada |
|Phoenix, AZ | |Calgary, Canada |
|Savannah, GA | |OSIsoft, Inc. Representative Office |
| | |Shanghai, People’s Republic of China |
|Sales Outlets/Distributors | |OSIsoft Japan KK |
|Middle East/North Africa | |Tokyo, Japan |
|Republic of South Africa | |OSIsoft Mexico S. De R.L. De C.V. |
|Russia/Central Asia | |Mexico City, Mexico |
|South America/Caribbean | |OSIsoft do Brasil Sistemas Ltda. |
|Southeast Asia | |Sao Paulo, Brazil |
|South Korea Taiwan | | |
|Contact and Support: | | |
|Main phone: | |(01) 510-297-5800 |
|Fax: | |(01) 510-357-8136 |
|Support phone: | |(01) 510-297-5828 |
| | | |
|Web site: | | |
|Support web site: | | |
| | | |
|Support email: | |techsupport@ |
|Copyright: © 2010 OSIsoft, LLC. All rights reserved. |
|No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, |
|photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. |
| |
|OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT Monitor, MCN |
|Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, |
|ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or |
|trade names used herein are the property of their respective owners. |
| |
|U.S. GOVERNMENT RIGHTS |
|Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided |
|in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC. |
| |
|Published: 10/29/2009 |
Table of Contents
Terminology vii
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 4
Principles of Operation 5
Processing of the Event Data File 5
Requesting Initial Values after Point is Added to the Interface 7
Processing of the Alarm Message File 7
Connection to PI Server Lost 8
Failover 9
Installation Checklist 11
Data Collection Steps 11
Interface Diagnostics 12
Advanced Interface Features 13
Interface Installation on Linux 15
Naming Conventions and Requirements 15
Interface Directories 15
PIHOME Directory 15
Interface Installation Directory 15
PI API Installation on a Linux Power TG machine 16
Interface Installation Procedure 17
DumpInputFile Utility 21
DumpAlarmFile Utility 23
BufStat Utility 25
Digital States 27
PointSource 33
PI Point Configuration 35
Point Attributes 35
Tag 35
PointSource 36
PointType 36
Location1 36
Location2 36
Location3 36
Location4 37
Location5 37
InstrumentTag 37
ExDesc 39
Scan 40
Shutdown 40
Startup Command File 43
Command-line Parameters 44
Linux Sample PISIPowerTG.sh File 47
Interface Specific Failover 51
Introduction 51
Point Configuration for Failover 52
Interface Node Clock 55
Linux 55
Security 57
Linux 57
Starting / Stopping the Interface on Linux 59
Interface Startup Script 59
Interface Stop Script 59
Automatic startup and shutdown 60
Automatic startup on a reboot 60
Terminating Background Processes 61
Anomalous Background Job Termination 61
Buffering 63
Linux Interface Nodes 63
How Buffering Works 63
Buffering and PI Server Security 64
Configuring PI API Buffer Server (bufserv) Manually 64
Performance Settings 65
BufServ and n-way buffering 66
Notes for bufserv on Linux 66
Interface Diagnostics Configuration 69
Interface Specific Performance Points 69
UniInt Interface Health Monitoring Points 70
Failover configurations with UniInt Health Points 74
I/O Rate Point 74
Configuring I/O Rate Tags On Linux 74
Configuring PI Point on the PI Server 74
Configuration on the Interface Node 74
Interface Status Point 75
Appendix A: Error and Informational Messages 77
Message Logs 77
Messages 77
System Errors and PI Errors 83
Appendix B : Event Data File Structure 85
Appendix C : Alarm Message File Structure 87
Appendix D : Setting up a PI Archive on the Power TG System 89
PI Server Definition 89
Point Collection Definition 92
Installing Data from the SDB for a PI Archive 95
Revision History 97
Terminology
In order to understand this interface manual, you should be familiar with the terminology used in this document.
Buffering
Buffering refers to an Interface Node’s ability to store temporarily the data that interfaces collect and to forward these data to the appropriate PI Servers.
N-Way Buffering
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-way buffering refers to the ability of a buffering application to send the same data to each of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI Server however it does not guarantee identical archive records since point compressions specs could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)
ICU
ICU refers to the PI Interface Configuration Utility, available only on Windows platforms. The ICU is the primary application that you use in order to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.
ICU Control
ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure and run PI interface programs. You must install the ICU on the same computer on which an interface runs. A single copy of the ICU manages all of the interfaces on a particular computer.
You can configure and run an interface by editing a startup command file. However, OSIsoft discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for interface management tasks.
Interface Node
An Interface Node is a computer on which
• the PI API and/or PI SDK are installed, and
• PI Server programs are not installed.
PI API
The PI API is a library of functions that allow applications to communicate and exchange data with the PI Server. All PI interfaces use the PI API.
PI Collective
A PI Collective is two or more replicated PI Servers that collect data concurrently. Collectives are part of the High Availability environment. When the primary PI Server in a collective becomes unavailable, a secondary collective member node seamlessly continues to collect and provide data access to your PI clients.
PIHOME
PIHOME refers to the directory that is the common location for PI client applications. A typical PIHOME is /opt/piapi. PI interfaces reside in a subdirectory of the interfaces directory under PIHOME. For example, files for the Siemens Power TG Interface are in /opt/piapi/interfaces/SIPowerTG.
PI SDK
The PI SDK is a library of functions that allow applications to communicate and exchange data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of the PI SDK.
PI Server Node
A PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.
PI SMT
PI SMT refers to PI System Management Tools. PI SMT is the program that you use for configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs on either a PI Server Node or a PI Interface Node.
pipc.log
The pipc.log file is the file to which OSIsoft applications write informational and error messages. While a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.
Point
The PI point is the basic building block for controlling data flow to and from the PI Server. For a given timestamp, a PI point holds a single value.
A PI point does not necessarily correspond to a “point” on the foreign device. For example, a single “point” on the foreign device can consist of a set point, a process value, an alarm limit, and a discrete value. These four pieces of information require four separate PI points.
Service
A Service is a Windows program that runs without user interaction. A Service continues to run after you have logged off from Windows. It has the ability to start up when the computer itself starts up.
The ICU allows you to configure a PI interface to run as a Service.
Tag (Input Tag and Output Tag)
The tag attribute of a PI point is the name of the PI point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI System documentation uses the terms “tag” and “point” interchangeably.
Interfaces read values from a device and write these values to an Input Tag. Interfaces use an Output Tag to write a value to the device.
Introduction
The PI SIPowerTG interface allows real-time data from the Siemens Spectrum Power TG system to be written to a PI system.
Reference Manuals
OSIsoft
• PI Server manuals
• PI API Installation manual
• UniInt Interface User Manual
Supported Features
|Feature |Support |
|Part Number |PI-IN-SI-PTG-LNX |
|* Platforms |Linux (RedHat ES4 64-bit) |
|APS Connector |Yes (using Generic_CSV APS Connector) |
|Point Builder Utility |No |
|ICU Control |No |
|PI Point Types |float64 / float32 / float16 / int32 / int16 / digital |
|Sub-second Timestamps |Yes |
|Sub-second Scan Classes |No |
|Automatically Incorporates PI Point Attribute Changes |Yes |
|Exception Reporting |Yes |
|Outputs from PI |No |
|Inputs to PI: Scan-based / Unsolicited / Event Tags |Unsolicited |
|Supports Questionable Bit |Yes |
|Supports Multi-character PointSource |Yes |
|Maximum Point Count |Unlimited |
|Uses PI SDK |No |
|PINet String Support |No |
|* Source of Timestamps |Power TG System |
|* History Recovery |No |
|* UniInt-based |Yes |
|* Disconnected Startup |Yes |
|* SetDeviceStatus |Yes |
|* Failover |Interface specific failover |
|* Vendor Software Required on PI Interface Node / PINet|Yes |
|Node | |
|* Vendor Software Required on Foreign Device |Yes |
|Vendor Hardware Required |No |
|* Additional PI Software Included with Interface |Yes |
|* Device Point Types |All types supported by the Power TG historian software|
| |including alarm and event messages |
|Serial-Based Interface |No |
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the Linux operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.
Please contact OSIsoft Technical Support for more information.
Source of Timestamps
The data received from the Power TG system includes a UTC timestamp for each event. That timestamp is passed to the PI server with the event values.
History Recovery
The Interface does not explicitly support history recovery. But if the interface is not running and processing the data files, then the Power TG system will buffer the data in the data files. When the interface is restarted, the buffered data will be processed normally and no events should be lost.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s 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 Interface User Manual is a supplement to this manual.
Disconnected Start-Up
The PI SIPowerTG interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.
SetDeviceStatus
Functionality has been added to UniInt 4.3.0.15 and later to support health tags. The PISIPowerTG interface is built against a version of UniInt that supports the health tags.
The Health tag with a string point type and the attribute ExDesc = [UI_DEVSTAT], is used to represent the status of the interface. The possible values for this string point are:
• “1 | Starting” – The Interface remains in this state until it has successfully collected data from its first scan.
• “Good” – The interface is able to collect data. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.
• “4 | Intf Shutdown” – The Interface has shut down.
The Interface updates this point whenever the interface is started or stopped.
Failover
The interface itself does not support failover. However, the Power TG system does support failover between stations. This means that if an instance of the interface is run on both stations, when the station fails over, the interface on the active station will send events to the PI server. See section Interface Specific Failover for more details.
Vendor Software Required
Power TG Historian software is required to generate the event data files used by the interface.
Additional PI Software
Two utilities are included with the interface to allow the input files from the Power TG system to be dumped to stdout and can be used to validate the raw data that the interface will be reading. The utilities are “DumpInputFile” and “DumpAlarmFile”.
Device Point Types
The interface can support any measurement point type and field that is encoded in the event data files or any alarm or event message stored in the alarm files produced by the Power TG historian software.
Diagram of Hardware Connection
The following illustrates a simple configuration for sending data from a single Power TG station to a stand-alone PI server.
[pic]
Principles of Operation
The PI SIPowerTG Interface establishes the initial connection to PI and reconnects to PI in the event that the connection is lost for some reason. If the Interface is started while the PI Server is down, the Interface will periodically try to establish a connection until the PI Server is up.
When the Interface starts, the interface searches the PI Point Database for points that belong to the Interface and a point list is created for the interface.
Once startup is complete, the Interface enters the processing loop, which includes:
• Every 0.5 seconds, the interface will check to see whether a measurement data file or an alarm message file has been created by the Power TG system. If a file is found, the interface will process the file. For details on the file processing, see the Processing of the Event Data File and Processing of the Alarm Message File sections below. After processing, if the /renamedata= or /renamealarm= parameter has been specified then the interface will rename the file, so it can be processed by other applications. By default, the interface will delete the processed file and will wait for the next data file.
• The PI Point Database is checked every 2 minutes for points that are added, edited, and deleted. If point updates are detected, the points are loaded (or reloaded) by the Interface as appropriate. The 2-minute update interval can be adjusted with the /updateinterval command-line parameter discussed in the UniInt Interface User Manual. The Interface will only process 25 point updates at a time. If more than 25 points are added, edited, or deleted at one time, the Interface will process the first 25 points, wait 30 seconds (or by the time specified by the /updateinterval parameter, whichever is lower), process the next 25 points, and so on. Once all points have been processed, the Interface will resume checking for updates every 2 minutes (or by the time specified by the /updateinterval parameter). The Interface will write the digital state SCAN OFF to any points that are removed from the Interface while it is running.
Processing of the Event Data File
The interface reads each of the events from the buffer event data file.
For each event, it will first decode the event and extract the value and quality. It will then search for any PI points that are configured for the id@field in the event. When it finds a point, it will format the data in the required format for the PI point and send the data to the PI system.
Depending on the configuration of the PI point, the point can store the value from the Power TG field or the data quality, and the data quality can be represented in several formats. A keyword appended to the InstrumentTag is used to differentiate what the interface will store in the PI point. The interface is able to store
• value or a quality when the quality is bad
• value (regardless of the quality)
• data quality (priority based on data_qualities.ini definition)
• OPC QQSSSS quality
• OPC limit (LL) quality
• OPC special quality
• Alarm status (extracted from the quality flags)
When storing the "value or quality", the interface will check the data quality. If the quality shows the value is meaningless then instead of writing the value to PI, it will write a suitable system digital status. (i.e. “Comm Fail” or “Out of Serv”) . If the quality shows that the value is valid, but not scanned normally (a manual override value etc) then the interface will sent the value to PI, but it will also set the PI questionable flag to highlight the fact that the value is not normal.
Because the PI system is not able to store the entire data quality in the same point as the value, the interface is able to store the quality in a separate PI point. The interface will translate the quality of an event into either a data quality priority (same as the quality displayed on the operator displays), an OPC formatted quality values or an alarm status. This value can then be stored in a PI point. If the PI point is a digital then the interface will store a quality as a offset into the quality digital set. The definitions of the digital state sets expected by the interface are listed in the "Quality Digital State Set" section of the manual.
When the interface processes data quality points (InstrumentTag ends with .QUAL), it uses data quality fields from the event record to calculate the quality priority. The interface reads the priorities from the Power TG configuration file defined with the /qualcodefile= argument. The Power TG system uses the same file to define the quality codes shown on the operator displays. Because it may not be appropriate the store some of the qualities in the PI system, the data_qualities.ini file contains a section called [PI] and qualities listed in this section with a FALSE value will skipped by the interface.
If there are qualities listed in the data_qualities.ini that are not required to be stored in the PI data quality points, these can also be excluded by setting the quality flag in the [PI] section to FALSE. By default, the Selected_Field quality is excluded, but all other qualities are included.
Once all the events in the buffer file have been processed, by default the interface will delete the data file. But, if the command-line parameter /rename= is set then the interface will attempt to rename the processed file. This is a way that the data file can be passed to another application for further processing (sending the same events to multiple historian systems). If the destination file already exists then the interface will NOT overwrite it. Instead, the interface will wait for the other application to process the old file and only after the destination file has been removed will the interface rename its data file.
Finally, the interface will update any interface specific performance PI points. These performance points include a counter of the number of files processed, the timestamp of the latest event, the number events found in the file, the number of events sent to PI and the time taken to process the file. See the Interface Specific Performance Points sections for more details.
Requesting Initial Values after Point is Added to the Interface
The Power TG system can be configured to output new PI tag information or changed PI tag information to a comma separated file (csv file). This csv file is used by the Generic CSV plug-in to the Auto Point Synchronization (APS) utility to create and/or modify PI tags that belong to the interface. After the Power TG system outputs data to the csv, it can be more than 5 minutes before the interface receives this change to the PI point database. For this reason, the interface will not save the initial value from the Power TG system to the PI tag. This can lead to a situation where a PI tag’s value will remain in “Pt Created” until the value of that point on the Power TG system changes. In order to avoid this situation, the interface will request the current value by writing the Power TG point to an ASCII text file. The Power TG system will monitor a folder for a new text file. When the Power TG system sees a new text file, it will read the file and send the current value for any point found in the file.
The location of the file is specified with the /data command line parameter. The /data command line parameter specifies the location and the name of the buffer data file. The location of the new tag file will be the same as the buffer data file. The name of the new tag file will be the same as the buffer data file except the extension will be changed to “.tags”.
Any time the interface receives a new PI tag or a PI tag edit that does not cause the PI tag to be removed from the interface, the interface will write the Power TG point to a temporary new tag file. The temporary new tag file will have the same path and name as the buffer data file except the extension will be “.temp”. After the interface completes processing the current batch of point database edits, the interface will attempt to rename the file to have the “.tags” extension. If the location currently has a file with the “.tags” extension, the interface will wait 30 seconds and then check again to see if the new tags file has been processed by the Power TG system and then deleted. If any new tags come in prior to the Power TG system deleting the new tag file, the interface will append any new Power TG points to the end of the current temporary file.
Processing of the Alarm Message File
The interface loops though all the alarm messages in the alarm file, processing each alarm message in turn. The message is formatted into a string for storing in the PI system. The string consists of the all the fields separated with a pipe ‘|’ character. The fields within the alarm are
0. Sequence (used to define the order of alarms when a group has the same timestamp)
0. Priority
0. AOR_Group
0. Entity
0. Message
For example,
0|3|GEN|ANALOG:AGCGHOST.GENACT_06|PUI_UN_01 GENERATOR ACTUAL MW RETURN TO NORM 34.000 32.759
0|999|GEN||AGC SYSTEM SUMMARY LGS FREQUENCY DEVIATION OFFSET IS -.050 WAS 0.000
The timestamp for the alarm is used by PI when storing the value, so the timestamp itself it not included within the string value.
To locate the PI point that the interface will write an alarm to, it loops though the list of all alarm tags configured in the interface, and applies a filter for each point against the current alarm, and if a match is found then the alarm it written to that PI point. It is possible that one alarm will be sent to multiple PI points, depending on the filters configured for the alarm points.
For example, all the high priority alarms could go to one PI point, or all the alarms from one plant area could go to another PI point. You can also have a PI point with no filter, which would capture all the alarm messages, but when analyzing the alarms there would be a lot of alarms that are irrelevant and would need to be removed. By filtering the alarms when they are stored in PI, it can simplify the analyzes of the alarms later.
The alarm filters are defined in the InstrumentTag attribute of the PI point. The filter allows the alarms to be split into groups with each group being sent to a different PI point. The alarms can be filters on the Priority, AOR_Group and Entity fields. For example, if a PI point was to store all the alarms for the AOR Group labeled “GEN”, then the InstrumentTag would contain
AOR_GROUP=GEN
If a point was to store only the alarms with priority < 10 for the AOR group “GEN”, it use the InstrumentTag
PRIORITY ${WORKDIR}/${PROG}.out 2>&1 &
Note the backslash (\) continuation characters on the command-line. Failing to include these will cause problems.
11. Use the “DumpInputFile” and “DumpAlarmFile” utilities to confirm the format of a sample event data and alarm message files.
12. If you will use digital points, define the appropriate digital state sets. The sample file “SIPowerTG_digital_set.csv” can be imported with PI SMT to create the file status and default quality digital sets.
13. Check the contents of the data code definition file (data_qualitities.ini) and ensure that any data qualities that are not required in PI are set to FALSE in the [PI] section of the file and that the TG_DATA_QUALITY digital state set matches the priorities in the file.
14. To be able to check when the interface is running as background process, add the interface name PISIPowerTG to the end of the $PIHOME/bin/apiprocs file.
15. With the PI API processes running, start the PISIPowerTG.sh script. Use apiverify to check whether the process is running. Check the $PIHOME/dat/PISIPowerTG.log and $PIHOME/dat/pimesslogfile files to check the status of the interface.
16. To stop the interface when it is running as a background process, use the PISIPowerTG_stop script.
DumpInputFile Utility
The “DumpInputFile” utility is installed as part of the interface kit and is located in the PIHOME/interface/SIPowerTG directory.
It is a simple command-line program that can be used to print the contents of a Power TG data file. It will list each of the events within the file, including the point number, field, type, timestamp, value and quality flags.
The command syntax is
DumpInputFile [filename]
where filename is the name of the Power TG data file to be output.
For example:
DumpInputFile /lg/scada/dat/his/ measdata.his.1.PI.dat
1 3528@STATE STATUS_DEFAULT 06-02-2009 14:45:35.000 (1233931535.000) 1 0x00070001 0x00000002
2 3528@TOT_OPS INT_FIELD 06-02-2009 14:45:35.000 (1233931535.000) 0 0x00000000 0x00000000
3 3529@STATE STATUS_DEFAULT 06-02-2009 14:45:35.000 (1233931535.000) 1 0x00010001 0x00000002
4 3529@TOT_OPS INT_FIELD 06-02-2009 14:45:35.000 (1233931535.000) 0 0x00000000 0x00000000
52 28374@VALUE ANALOG_DEFAULT 06-02-2009 14:45:35.000 (1233931535.000) 1.5809 0x00070000 0x00000002
DumpAlarmFile Utility
The “DumpAlarmFile” utility is installed as part of the interface kit and is located in the PIHOME/interface/SIPowerTG directory.
It is a simple command-line program that can be used to print the contents of a Power TG alarm file. It will list each of the events within the file, including the timestamp, sequence, priority, AOR group, entity and alarm message.
The command syntax is
DumpAlarmFile [filename]
where filename is the name of the Power TG alarm file to be output.
For example:
DumpAlarmFile /lg/scada/dat/his/msgdata.his.1.PI.dat
1 18-03-2009 21:28:37.285 (1237411717.285) 0|28|GEN| ANALOG:AGCGHOST.GENACT_06|PUI_UN_01 GENERATOR ACTUAL MW RETURN TO NORM 34.000 32.759
2 18-03-2009 21:28:37.285 (1237411717.285) 1|999|GEN| ANALOG:AGCGHOST.GENACT_06|PUI_UN_01 GENERATOR ACTUAL MW RETURN
3 18-03-2009 21:28:37.285 (1237411717.285) 3|3|GEN| ANALOG:AGCGHOST.BASEPT_06|PUI_UN_01 BASE POINT RETURN TO NORM 34.000 32.759
BufStat Utility
The “DumpAlarmFile” utility is installed as part of the interface kit and is located in the PIHOME/interface/SIPowerTG directory.
This utility can be used to check the current connection status of a buffered PI server. It can also print the configuration of the bufserv parameters and the detailed status of the buffers. Typically, it will be used to allow the Siemens software to retrieve the PI server connection status so that it is able to notify operators when a PI server connection is lost.
The command syntax is
BufStat [options] PIserver
where PIServer is the name of the PI server to be checked. Valid options are
-cfg Configuration of bufserv parameters
-stat Buffer status
-con Connection status
The return status of the utility is
0 Disconnected
1 Connected
-1 Fatal Error
For example,
To print out the current status of the buffers, use the following
BufStat -stat XXXXX
BufServ Status Info
PI Server Status : Connected
BufServ Status : Single
Buffer 1 WriteLoc : 448
Buffer 1 Read Loc : 36
Buffer 1 Wrap Loc : 0
Buffer 1 Entries : 16
Buffer 1 Used : 412 ( 0.04%)
Buffer 2 WriteLoc : 36
Buffer 2 Read Loc : 36
Buffer 2 Wrap Loc : 0
Buffer 2 Entries : 0
Buffer 2 Used : 0 ( 0.00%)
File Entries : 0
File Size : 0 kBytes
To show the current connection status only, use the following
BufStat -con OSLTEST3
CONNECTED
To use the BufStat is a script to get the current connection status, use the return code from the utility. The following script runs the BufStat utility and then outputs the return code ($? is the return code variable)
#!/bin/sh
# Print return value from BufStat
BufStat XXXXX
echo XXXXX =$?
Digital States
For more information regarding Digital States, refer to the PI Server documentation.
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. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.
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.
Typically, these digital sets can be used for data like
OFF, ON
OPEN, CLOSED
UNDEFINED,OPEN,CLOSE,TRANITION
etc.
Quality Digital State Set
The following digital sets define the states for different types of points supported by the interface. These digital sets can be created by importing the SIPowerTG_DigitalSets.csv file with the SMT Digital Set plug-in, or by creating the digital sets manually.
TG_DATA_QUALITY - Quality Priority Digital Set
Location2 = 0, InstrumentTag ends with .QUAL
The Data Quality points can be used to show the status of a Power TG point. It is based on the data qualities displayed on the operator displays and uses the data_qualities.ini file to calculate the quality state to send to the data quality PI points.
Note 1 : Care must be taken to ensure that the definition of the TG_DATA_QUALITY digital set matches the definition given in the data_qualities.ini file (and data_qualities.project.ini if it exists). If there is a mismatch then misleading information will be shown on the PI displays.
Note 2 : If the number of states in the digital set is not sufficient to store the priorities defined in the data_qualities.ini files then the points will be rejected by the interface.
|Offset |State Text |Description |
|0 |(blank) |No quality flags set |
|1 |* |Field Selected (disabled by default) |
|2 |S |State Estimator Update |
|3 |M |Manually entered |
|4 |D |Out of Scan |
|5 |# |Floating Point Exception |
|6 |T |RTU Test Mode |
|7 |F |Telemetry Failure |
|8 |U |Uninitialized |
|9 |Z |Missing |
|10 |R |Reasonability Failure |
|11 |? |Questionable |
|12 |X |Drift |
|13 |Q |Computed Value Based on Manually Entered Data |
|14 |E |State Estimator Error |
|15 |B |Backup Data |
|16 |I |All Alarms Inhibited |
|17 |W |Warning Limit Alarms Inhibited |
|18 |C |Device Comment |
|19 |N |In Control |
|20 |! |Control Connection Failed |
|21 |/ |Local/Remote |
|22 |H |Analog High Operating |
|23 |L |Analog Low Operating |
|24 |H |Analog High Warning |
|25 |L |Analog Low Warning |
|26 |V |Limit Override |
|27 |O |Abnormal |
|28 |Y |Execution of switching control |
|29 |A |Unacknowledged Alarm |
TG_ALARM_STATUS - Alarm Status Digital Set
Location2 = 0, InstrumentTag ends with .ALARM
To show the current alarm status of an analog point, the interface supports an alarm status point which will get the alarm status from the data quality of the event and write one of the following states
|Offset |State Text |Description |
|0 |Normal |No alarm conditions apply |
|1 |Low Warning |Low warning flag is set |
|2 |Low Alarm |Low alarm flag is set |
|3 |High Warning |High warning flag is set |
|4 |High Alarm |High alarm flag is set |
TG_QUAL_QQSSSS - OPC “QQSSSS” Digital Set
Location2 = 0, InstrumentTag ends with .QQSSSS
|Offset |State Text |OPC Quality |
| | |QQ SSSS |Description |
|0 |Good |11 0000 |Good. No special conditions |
|1 |ManOverride |11 0100 |Good. Value has been manually overridden |
|2 |Calc Man Val |11 0111 |Good. Calculation based on manual override |
|3 |Local |11 1000 |Good. Local |
|4 |Test Mode |11 1001 |Good. Test mode |
|5 |Backup |11 1010 |Good. Backup |
|6 |SE Update |11 1011 |Good. SE Update |
|7 |EU Exceeded |01 0101 |Uncertain. Engineering units exceeded |
|8 |Un-Initial |01 0111 |Uncertain. Value un-initialized |
|9 |Question |01 1000 |Uncertain. Value questionable |
|10 |Missing |01 1001 |Uncertain. Missing |
|11 |FP Exception |01 1011 |Uncertain. Floating point exception |
|12 |Comm Fail |00 0110 |Bad. Communications failure |
|13 |Out of Scan |00 0111 |Bad. Out of scan |
|14 |SE Bad |00 1000 |Bad. SE bad |
TG_QUAL_LIMIT - OPC Limit Status Digital Set
Location2 = 0, InstrumentTag ends with .LIMIT
|Offset |State Text |Description |
|0 |Normal |No limit conditions apply |
|1 |Low Alarm |Either a low alarm or a low warning flag is set |
|2 |High Alarm |Either a high alarm or a high warning flag is set |
TG_QUAL_SPECIAL - OPC Special Quality Digital Set
Location2 = 0, InstrumentTag ends with .SPECIAL
|Offset |State Text |Description |
|0 |Normal |No special conditions apply |
|1 |In Control |In Control |
|2 |Alarm Inh |Alarms inhibited |
|3 |Warning Inh |Warnings inhibited |
|4 |Device Cmnt |Device comment present |
|5 |Cmnd Fail |Command failed |
|6 |Drift |Drift flag set |
|7 |Limit Ovrd |Limit override |
|8 |Unack |Unacknowledged alarm |
|9 |Excd Alarm |Exceeded alarm limit (can be either high or low limit) |
|10 |Excd Warning |Exceeded warning limit (can be either high or low limit) |
File Status State Set
One of the interface-specific performance points shows the status of the last file processed. The File Status digital set is used to represent that status.
TG_FILE_STATUS - File Status Digital Set
Location2 = -1,
ExDesc = ”DATA_FILE_STATUS” or ExDesc = ”ALARM_FILE_STATUS”
|Offset |State Text |Description |
|0 |Invalid |File magic number is not valid |
|1 |OK |File processed without errors |
|2 |Corrupt |Events were found that were found to be invalid |
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. Digital States 193-320 are reserved for OSIsoft applications.
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string Boiler1 may be used to identify points that belong to the MyInt Interface. To implement this, the PointSource attribute would be set to Boiler1 for every PI Point that is configured for the MyInt Interface. Then, if /ps=Boiler1 is used on the startup command-line of the MyInt Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of Boiler1. 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 /ps parameter.
Case-sensitivity for PointSource Attribute
The PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.
Point Attributes
Use the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.
Tag
The Tag attribute (or tagname) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI documentation uses the terms “tag” and “point” interchangeably.
Follow these rules for naming PI points:
• The name must be unique on the PI Server.
• The first character must be alphanumeric, the underscore (_), or the percent sign (%).
• Control characters such as linefeeds or tabs are illegal.
• The following characters also are illegal: * ’ ? ; { } [ ] | \ ` ‘ “
For points that have the Power TG system as the data source, typically the tag name will be based on the name of the point within the Power TG system. But, this is not a requirement as the tag name is not used to identify the point within the Power TG system.
Length
Depending on the version of the PI API and the PI Server, this Interface supports tags whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.
|PI API |PI Server |Maximum Length |
|1.6.0.2 or higher |3.4.370.x or higher |1023 |
|1.6.0.2 or higher |Below 3.4.370.x |255 |
|Below 1.6.0.2 |3.4.370.x or higher |255 |
|Below 1.6.0.2 |Below 3.4.370.x |255 |
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 additional information, see the /ps command-line parameter and the “Point Source” section.
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “PointSource” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.
For measurement data points ( Location2=0), the interface supports float16, float32, float 64, int16, int32, digital point types. For quality points, a digital PI point are recommended. See the section "Digital States" for more information on the suggested quality digital set definitions.
For alarm points (Location2=1), the interfaces supports only string points.
The PointType for the interface specific performance points (Location2=-1) is fixed for each performance counter/status. For a list of the required PointTypes for the performance points, refer to section “Interface Specific Performance Points”.
For more information on the individual PointTypes, see PI Server manuals.
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter.
Location2
Location2 indicates whether the interface should store the value or the quality of an event.
|Location2 |Action |
|-1 |Store interface specific performance data |
|0 |Store event values/quality/status (depending on InstrumentTag) |
|1 |Store alarm messages |
Location3
Not used.
Location4
Location4 is normally used by UniInt based interfaces to specify the scan class that a point belongs to.
As this interface only supports unsolicited inputs, all points should be configured with Location4=0.
Location5
Location5 is used to control point debug messages.
|Location5 |Point Debug messages |
|0 |Disabled |
|1 |Enabled |
InstrumentTag
Length
Depending on the version of the PI API and the PI Server, this Interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions.
|PI API |PI Server |Maximum Length |
|1.6.0.2 or higher |3.4.370.x or higher |1023 |
|1.6.0.2 or higher |Below 3.4.370.x |32 |
|Below 1.6.0.2 |3.4.370.x or higher |32 |
|Below 1.6.0.2 |Below 3.4.370.x |32 |
Measurement Data Points (Location2=0)
InstrumentTag is used to specify the Power TG point and field that the interface will use link an event record to the PI point and to specify the type of data to be extracted from the event record.
To identify the source of an event within the Power TG system, the buffer data file includes the Point Id (and integer value) and the Point Field Name (string).
Once the event record has been matched to the PI point, the interface needs to which field from the event to store and how the data should be formatted. To do this, a keyword is appended after the field name. The interface recognizes the following data type keywords
|Keyword |Data to be stored |
|Blank |If the quality is good then the value will be stored. If the quality is questionable then the value is |
| |stored with the PI questionable flag set. If the quality is bad then a system digital will be stored to|
| |indicate the cause of the bad value, |
|.VAL |Store the value regardless of the quality |
|.QUAL |Store the quality priority (as defined in the data_qualities.ini file) |
|.ALARM |Store the alarm status (as defined in the TG_ALARM_STATUS digital set) |
|.QQSSSS |Store the OPC QQSSSS quality field |
|.LIMIT |Store the OPC limit quality field |
|.SPECIAL |Store the OPC special quality field |
To specify this within the InstrumentTag, the interface is expecting the following format
PointId@Field.Keyword
For example:
|3534@STATE |value or system digital, depending on the quality |
|5197@ACT_ACC.VAL |value only (ignores quality) |
|7268@VALUE |value or system digital, depending on the quality |
|7269@VALUE.VAL |value only (ignores quality) |
|7269@VALUE.QUAL |quality priority |
|846@VALUE.ALARM |alarm status |
Alarm Message Points (Location2=1) Filter Expression
InstrumentTag is used to specify the filter to be applied to the alarm messages before the alarm is allowed to be written to the point. This allows alarms to be sorted into various groups, with one PI point for each group.
The filter consists of a list of expressions. Each expression consists of a field name, and comparison operator and a value to compare the field against.
|Field Name |Operators |Value |
|PRIORITY |Equal = or == |Numeric |
| |Not equal != or | |
| |Less than < | |
| |Less than or equal | |
| |Greater than or equal >= | |
|AOR_GROUP |Equal = or == |Wildcard string |
| |Not equal != or | |
|ENTITY |Equal = or == |Wildcard string |
| |Not equal != or | |
If the wildcard string value needs to include space characters then enclose the entire string with quotes (double or single).
A wildcard string value supports the following characters
|Characters in pattern |Matches in string |
|? |Any single character |
|* |Zero or more characters |
|# |Any single digit (0-9) |
|[charlist] |Any single character in charlist. By using a hyphen (-) to separate the upper and |
| |lower bounds of the range, charlist can specify a range of characters. |
|[!charlist] |Any single character that is NOT is charlist. |
Several field expressions can be combined with either AND or OR. Parenthesis () are not supported. All the expressions are evaluated in the order they appear in the filter expression.
For example, if a PI string point is configured with the InstrumentTag
PRIORITY Initial Release
#
INTF_NAME=PISIPowerTG
SCRIPT=$0
#
# function to log script messages
#
log_message()
{
echo "$1"
if [ -x $PIHOME/bin/shootq ]; then
$PIHOME/bin/shootq "${SCRIPT} > $1"
fi
}
#
# Verify the PIHOME Environment Variable
#
if [ ${PIHOME:-notdefined} = "notdefined" ]; then
echo "ERROR > The PIHOME environment variable has not been defined"
exit 1
fi
#
# abort startup if the interface is already running
#
ISRUNNING=`ps -ef | grep "${INTF_NAME} " | grep -v grep | grep -v ${SCRIPT} | grep -v go_pistart`
if [ -n "$ISRUNNING" ]; then
log_message "ERROR > Interface (${INTF_NAME} process) already running"
exit 1
fi
#
# define work directory
#
WORKDIR=$PIHOME/dat
echo "Output file is \"$WORKDIR/${INTF_NAME}.out\""
# if output file exists then rename as .old file
#
if [ -f $WORKDIR/${INTF_NAME}.out ]; then
echo "Renamed existing \"${INTF_NAME}.out\" as \"${INTF_NAME}.old\""
/bin/mv "$WORKDIR/${INTF_NAME}.out" "$WORKDIR/${INTF_NAME}.old"
fi
#
# log message that we are starting the interface
#
log_message "Starting interface \"${INTF_NAME}\""
#=================== Interface Specific Parameters ====================
#
# Required Parameters
# -host=XXXXXX[:portid] PI server hostname and port id.
# -ps=#### Point source.
# -id=# Interface identifier.
# -data=#### Name of the Input Data File.
# -alarm=#### Name of the Input Alarm File.
# -qualcodefile=#### Name of the quality code definition file.
# -uht_id=# UniInt Health Tag ID.
#
# Optional Parameters
# -renamedata=#### Rename Input Data File after processing.
# -renamealarm=#### Rename Input Alarm File after processing.
# -onlyconnected Only process files when connected to PI server.
# -debug=#### Interface specific debug options.
#
#--- Edit the following line ---
./${INTF_NAME} -host=XXXXXXX:5450 -ps=TG -id=1 -uht_id=1 \
-qualcodefile=/lg/scada/fg/en_US/data_qualities.ini \
-data=/lg/scada/dat/his/measdata.his.1.PI.dat \
-alarm=/lg/scada/dat/his/msgdata.his.1.PI.dat \
> ${WORKDIR}/${INTF_NAME}.out 2>&1 &
exit 0
Interface Specific Failover
Introduction
The interface itself does not failover. The failover mechanism is performed by the Power TG system. However, the interface does need to be aware of the failover mechanism to minimize the amount of duplicate data send to the PI system. When there is a pair of redundant Power TG stations that can send data to PI, only one of these will be publishing the input data files for its interface to process. When failover occurs, one will stop generating files (or shutdown entirely) and the other will start publishing the buffer files. Because the interface will only send data to PI when an input data file is available, there are no issues with having both instances of the interface running at the same time.
The diagram below shows the architecture used when using redundant Power TG machines to send data to a high-availability PI server collective.
[pic]
The problem with the above mechanism is that when the secondary station takes over, it can publish an input data file with up to 30 minutes of data so that the data that failed to be sent by the primary station will be sent by the secondary. But some of data would have already been sent to PI via the primary interface before the primary failure occurred. This overlap in data ensures that there is not gap in the data on the PI servers, but this overlap means that the PI system will receive a block of out-of-order data and duplicate events.
Although the PI system can handle this overlapping data, it is better if it can be avoided. Therefore, if an interface has not been processing files for some time (either on startup or it has been on standby) and it receives a data file, the interface will read the snapshot value of the performance PI point containing the timestamp of the latest event. The interface will then process the data file normally, but it will discard the events that are older than the timestamp retrieved. See the “Interface Specific Performance Points” sections for more details on the configuration of the “latest timestamp” performance point.
If the “latest timestamp” performance point does not exist or the interface is unable to read the current value of the point because the connection to the PI server is down, the interface will send all of the events in the data file (discarding none). It will allow the interface to continue processing the files normally. There may be some overlap and out-of-order events in the PI system, but no data will be lost.
When the interface is running normally, it will not attempt to read the “latest timestamp” performance point. The discarding of events from the buffer file is only done when the interface is starting to process files, either on startup or when coming out of standby.
Because it is necessary to inform Power TG users when the connection to a PI server is lost, the BufStat utility can be used to check the status of the connections, and generate the necessary alarm messages with the Power TG system.
Point Configuration for Failover
Point Configuration
Because the interface can process both measurement data files and alarm message file, the interface supports two sets of performance points, one for each file type.
It is not necessary to specifically configure the interface for failover. However, by configuring a X_LATEST_TIMESTAMP performance point (where X is DATA or ALARM), it will help minimize the amount the out-of-order data sent to PI.
When the interface sees a file to process, but it hasn’t processed a file for more than a minute, it assumes that it has been on standby and it becoming the active interface. If a X_LATEST_TIMESTAMP performance point has been configured and the connection to the PI server is good, then the interface will read the value of the performance point and use that time as a cut-off for the events it reads from the file. Any event with a timestamp prior to the cut-off time will be dropped.
If the X_LATEST_TIMESTAMP point is not configured or it is not able to read the value of the timestamp then the interface will send all the events to PI. This will mean some out-of-order events may be sent to PI, but this is not a major issue. The PI server can handle these, although the events will not be compressed and it can affect the performance of the PI server. For this reason, if the interfaces are run with failover, it is recommended that a X_LATEST_TIMESTAMP performance point is configured.
For more information on configuring interface-specific performance points, see section “Interface Specific Performance Points”.
When using failover, both instances of the interface will be writing to the same set of interface specific performance points. This is not a problem, because only one instance of the interface should be processing files at any one time. However, if there is a problem with the Power TG failover mechanism, it is possible for both interfaces to write different values at the same time into the performance points, which could cause some confusion.
When using failover interface with the UniInt performance points, each instance of the interface should be configured with its own set of UniInt performance points. The points use location3 and the UniInt /uht_id= argument to differentiate the two sets of points. See the UniInt Interface User Manual for more information.
Interface Node Clock
Linux
The correct time and time zone must be configured on the interface node. Also, the interface node should be configured to automatically adjust for daylight saving time for locations that use daylight saving time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.
Security
Linux
The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “Managing Security” of the PI Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.
See the PI System Management chapter in the PI Server manual for more details on security configuration.
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
Starting / Stopping the Interface on Linux
This section describes starting and stopping the interface as a background process. See the UniInt Interface User Manual to run the interface as a foreground process.
Interface Startup Script
As part of the interface installation, an interface startup script PISIPowerTG.sh was created. To manually start the interface
1. Ensure that the PI API processes are running
apiverify
NAME PID TIME %CPU VSZ
bufserv 2260 00:00:00 0.0 5480
bufserv 2261 00:00:00 0.0 7672
bufserv 2263 00:00:00 0.0 7672
WARNING: multiple instances of bufserv are running
mqmgr 2252 00:00:00 0.0 4356
mqsrv 2246 00:00:00 0.0 4360
ioshmsrv 2269 00:00:00 0.0 4360
iorates 2275 00:00:00 0.0 8640
WARNING: PISIPowerTG is NOT running
The above is configured for buffering to 2 replicated PI servers, which is why there are 3 bufserv processes running. When buffering is configured there should be n+1 bufserv processes. Ignore the WARNING in the apiverify output.
2. Change to the interface directory
cd $PIHOME/interfaces/SIPowerTG
3. Run the interface startup script
PISIPowerTG.sh
Output file is "/opt/piapi/dat/PISIPowerTG.out"
Renamed existing "PISIPowerTG.out" as "PISIPowerTG.old"
Starting interface "PISIPowerTG"
This should start the interface as a background process. The stdout and stderr messages will be redirected to the $PIHOME/dat/PISIPowerTG.out file. The interface messages will also be logged into the $PIHOME/dat/pimesslogfile file.
Interface Stop Script
In the interface directory, there is a standard script that can be used to stop the interface when it is running in the background. This script is called PISIPowerTG_stop. It will look for a running process with the name PISIPowerTG and send it a terminate signal.
When running multiple instances of the interface, the script should be copied and edited so that each copy will only kill the required interface.
Automatic startup and shutdown
To simplify the management of the system, the interface is normally configured so that it will automatically start and stop when the other PI processes are started and stopped. This is done with the $PIHOME/bin/sitestart and $PIHOME/bin/sitestop scripts. The pistart and pistop scripts use these scripts for any site-specific commands and are typically used to start and stop the interfaces.
Note: Before configuring the sitestart and sitestop scripts, ensure that the interfaces are properly configured and have been manually started and stopped without any problems.
To have the interface automatically start when the pistart script is run, append the following to the sitestart script.
if [ -x $PIHOME/interfaces/SIPowerTG/PISIPowerTG.sh ]; then
cd $PIHOME/interfaces/SIPowerTG
$PIHOME/interfaces/SIPowerTG/PISIPowerTG.sh
else
echo "ERROR - PISIPowerTG.sh not found"
fi
It will check to see if the interface files are present and if so, it will start the interface. If the file is not found then the script will output an error message.
To have the interface stopped when the pistop script is run, append the following to the end of the sitestop script.
verify_stopped PISIPowerTG
This calls the function defined in the script to find the PID of the interface, send a terminate signal to the process and wait for up to 5 minutes for the interface to stop.
Note: Because of problems with the standard pistop, sitestart and sitestop scripts in the PI API installation kit, new versions of these scripts are included in the interface installation kit. The pistop, sitestart and sitestop scripts from the interface directory should be copied into the $PHOME/bin directory.
After copying the updated sitestop script to $PIHOME/bin, it may be necessary to edit the sitestart and sitestop files for the site-specific required.
Automatic startup on a reboot
To have the PI API processes and the interface automatically start on a reboot, startup scripts must be set up in the standard Linux init.d directories. To set up the automatic startup
1. Change to the root user
su
2. Copy the required PIAPI script from the interface directory to /etc/init.d
cp $PIHOME/interfaces/SIPowerTG/PIAPI /etc/init.d
The PIAPI script in the interface kit should be used when the PI API and interface processes are to be run by the root user.
If the PI API and interfaces processes need to be run by a different user (i.e. piadmin), then the PIAPI_nonroot script should be used.
3. Edit /etc/init.d/PIAPI script to set the PIHOME variable to match the requirements for the system.
By default, the PIAPI_nonroot script will set the PIUSER variable to use the owner of the $PIHOME/bin/pistart and PIHOME/bin/pistop files.
If for some reason, the script needs to use a user other then the owner the PI API files, it can be overridden by manually defining the PIUSER variable to be the required user name in the PIAPI script.
4. User chkconfig to add the links and verify the configuration
/sbin/chkconfig --add PIAPI
/sbin/chkconfig --list PIAPI
The PIAPI script should be configured to start at run levels 3, 4 and 5.
5. Verify the configuration by running the commands
PIAPI start - start the PI API processes
PIAPI status - show that status of the PI API processes
PIAPI stop - stop the PI API processes
6. Once the commands above as working as expected, reboot the system and checking that the PI API processes start and are owned by the correct user. If there are problems with the PIAPI script during a reboot, check the /var/log/messages file for the error messages. If there are no error messages logged then, then check the $PIHOME/dat/pimesslogfile and $PIHOME/dat/PISIPowerTG.out files.
Terminating Background Processes
Normally, the PISIPowerTG_stop script can be used to stop the interface process. However, if the script is not working, or you wish to stop a process with a different name, use the following instructions.
First, obtain the process id (PID) of the background job. This is done as follows. First execute the command:
ps -ef | grep PISIPowerTG
which produces output similar to:
powertglocal 2527 1 0 09:24 pts/0 00:00:00 ./PISIPowerTG …
The second column is the pid of the process. That is, 2527 is the PID of the PISIPowerTG interface in the example above.
The process is then stopped by:
kill 2527
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. This is because the shell is passing the terminate signal to the background processes started by that instance of the shell.
A way of insuring that background processes are not accidentally terminated is to use a shell that does not propagate the terminate signal to background processes. If the ksh, bash or csh shells are used then the Ctrl-C from the foreground will not terminate processes in the background.
If the system does not support any of these shells then close the current window or logout immediately after starting the background tasks, the user will not be able to accidentally terminate the job in this manner.
Buffering
Buffering refers to an Interface Node’s ability to temporarily store the data that interfaces collect and to forward these data to the appropriate PI Servers. OSIsoft strongly recommends that you enable buffering on your Interface Nodes. Otherwise, if the Interface Node stops communicating with the PI Server, you lose the data that your interfaces collect.
Linux Interface Nodes
Currently, the PI Buffer Subsystem is not available for Linux platforms. The PI API Buffer Server (bufserv) is the only option available for Linux interface nodes.
Because the ICU is also not available for Linux then bufserv must be configured by editing the piclient.ini file on the interface node. For more details on the configuration of bufserv under Linux, see section “Configuring PI API Buffer Server (bufserv) Manually”.
How Buffering Works
A complete technical description of bufserv is beyond the scope of this document. However, the following paragraphs provide some insights on how buffering works.
When an Interface Node has Buffering enabled, the buffering application (bufserv) connects to the PI Server. It also creates shared memory storage.
When an interface program makes a PI API function call that writes data to the PI Server (for example, pisn_sendexceptionqx()), the PI API checks whether buffering is enabled. If it is, these data writing functions do not send the interface data to the PI Server. Instead, they write the data to the shared memory storage that the buffering application created.
The buffering application (bufserv) in turn
• reads the data in shared memory, and
• if a connection to the PI Server exists, sends the data to the PI Server; or
• if there is no connection to the PI Server, continues to store the data in shared memory (if shared memory storage is available) or writes the data to disk (if shared memory storage is full).
When the buffering application re-establishes connection to the PI Server, it writes to the PI Server the interface data contained in both shared memory storage and disk.
When bufserv writes interface data to disk, it writes to a single file. The name of its buffering file is APIBUF.DAT.
As a previous paragraph indicates, Bufserv creates shared memory storage at startup. These memory buffers must be large enough to accommodate the data that an interface collects during a single scan. Otherwise, the interface may fail to write all its collected data to the memory buffers, resulting in data loss. The buffering configuration section of this chapter provides guidelines for sizing these memory buffers.
When buffering is enabled, it affects the entire Interface Node. That is, you do not have a scenario whereby the buffering application buffers data for one interface running on an Interface Node but not for another interface running on the same Interface Node.
Buffering and PI Server Security
After you enable buffering, it is the buffering application—and not the interface program—that writes data to the PI Server. If the PI Server’s trust table contains a trust entry that allows all applications on an Interface Node to write data, then the buffering application is able write data to the PI Server.
However, if the PI Server contains an interface-specific PI Trust entry that allows a particular interface program to write data, you must have a PI Trust entry specific to buffering. The following are the appropriate entries for the Application Name field of a PI Trust entry:
|Buffering Application |Application Name field for PI Trust |
|PI API Buffer Server |APIBE (if the PI API is using 4 character process names) |
| |APIBUF (if the PI API is using 8 character process names) |
To use a process name greater than 4 characters in length for a trust application name, use the LONGAPPNAME=1 in the PIClient.ini file.
Configuring PI API Buffer Server (bufserv) Manually
The following settings are valid for both Windows and Linux platforms. However, when running on Windows platforms, OSIsoft highly recommends using the ICU to edit the settings. Because the ICU is not available for Linux platforms then the settings can only be changed manually.
PI API 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. Instead, it sends data directly to the PI Server.
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 data to the PI Server.
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. On Linux 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 Linux) to the desired values.
Performance Settings
The following settings are available for PI API 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 PI Server (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). To improve the|
| | | |bufserv throughput, it is recommended that this |
| | | |value be increased to 1048576 (1 MB). |
|BUF2SIZE |64 - 2,000,000 |32768 |Secondary memory buffer size. (bytes) To improve |
| | | |the bufserv throughput, it is recommended that this|
| | | |value be increased to 1048576 (1 MB). |
|SENDRATE |0 - 2,000,000 |100 |The time to wait between sending up to |
| | | |MAXTRANSFEROBJS to the server (milliseconds). To |
| | | |improve the bufserv throughput, it is recommended |
| | | |that this value be decreased to 20. |
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 |On Unix machines, this keyword specifies the |
| | | |default PI Server. |
| | | |On Windows the default PI 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) |
BufServ and n-way buffering
To enable buffering for a PI server, each PI server must be listed in the [BUFFEREDSERVERLIST] section of the piclient.ini file. Each PI server in the list has a unique keyword, BUFSERVx where x is a number counting from 1 upwards.
Note: Because of a bug in the PI API/bufserv when running on Linux, the PI Server names must not be consecutive.
SERVER1 and SERVER2 will cause a conflict in shared memory keys, and bufserv will fail to start.
Independent PI Servers
The following is an example of two independent PI servers that are buffered from the interface node, but are NOT members of a collective.
[BUFFEREDSERVERLIST]
BUFSERV1=PI_PLANT
BUFSERV2=PI_CORPHQ
PI Servers in a Collective
When the PI servers are members of a collective and so the events sent to one must also be sent to the other then as well be being listed in the [BUFFEREDSERVERLIST], the servers must also be [REPLICATEDSERVERLIST] section. Each PI server in the list has a unique keyword, REPSERVx where x is a number counting from 1 upwards.
For example
[BUFFEREDSERVERLIST]
BUFSERV1=PISERVER_PRI
BUFSERV2=PISERVER_SEC
[REPLICATEDSERVERLIST]
REPSERV1=PISERVER_PRI
REPSERV2=PISERVER_SEC
Notes for bufserv on Linux
apiverify Warning
When buffering is enabled, there will be a parent bufserv process running and another bufserv process for each of the PI servers that is buffered. Therefore, when buffering is configured for 2 PI servers, there should be 3 instances of the bufserv process running. When the apiverify is used to check the running processes, ignore "WARNING: multiple instances of bufserv are running".
Note: The following problems occur in PI API 1.6.0.x and 1.6.1.x. It is hoped that both these issues will be resolved when PI API 1.6.2.x is released.
Problem #1
Because of potential problems with case-sensitive PI server names within the piclient.ini file, it is recommended that all PI server names be in uppercase. This includes the -host= parameter in the interface startup scripts, which must match the entries in the piclient.ini file.
Problem #2
There is a bug in the PI API/bufserv (PLI# 11142OSI8) that can cause a conflict in the keys used to access the shared memory and semaphores, used to perform the buffering. If the PI server names are "consecutive" then a conflict will occur and the bufserv processes will not start correctly. This conflict will cause an error to be locked in the pimesslogfile with a message similar to "APIBUFFER: Error creating memory handle - errno is 17". The exact message may vary, but the errno is 17 is likely to be a common factor.
For example, server names PISERVER1 and PISERVER2 will cause a conflict. But PISERVER_PRI and PISERVER_SEC will not.
The cause of the problem is that to calculate the IPC key used to access the shared memory and semaphores, the PI API/bufserv sums the characters in the buffer names. The buffer names include a buffer number and the server name. The result is that SERVER1 buffer 2 would have the same key as SERVER2 buffer 1, and the error occurs. And, because a sum of the characters is used, then order of the characters does not change the result. The sum of "ABC" is the same as the sum of "BCA".
To work-around this problem, create aliases in the /etc/host file, and use the host alias in the piclient.ini file. For example, in /etc/host you might have entries like the following
# PI Server Hosts
192.168.0.20 PISERVER1
192.168.0.21 PISERVER2
Additional aliases can be added to each host
# PI Server Hosts
192.168.0.20 PISERVER1 PISERVER_PRI
192.168.0.21 PISERVER2 PISERVER_SEC
and then the piclient.ini file would use the PISERVER_PRI and PISERVER_SEC entries, but the IP addresses would resolve back to the originally intended machines.
Sample piclient.ini file
The follow are typical samples of the piclient.ini files.
The first sample has buffering enabled for a single PI server named PISERVER. The buffer sizes for both buffer 1 and buffer 2 are set to 1MB each (1048576 bytes). The delay between blocks of events is 100 milliseconds and each block can be up to 5000 events.
[PISERVER]
PIHOMENODE=PISERVER
DSTMISMATCH=3600
[TCP/IP]
PORT=5450
[APIBUFFER]
BUFFERING=1
BUF1SIZE=1048576
BUF2SIZE=1048576
SENDRATE=100
MAXTRANSFEROBJS=5000
[BUFFEREDSERVERLIST]
BUFSERV1=PISERVER
#BUFSERV2=srv2
[REPLICATEDSERVERLIST]
#REPSERV1=srv1
#REPSERV2=srv2
The second sample has a similar configuration for the buffering, but the events are being sent to 2 PI servers that are members of a collective, so the events sent to one must be replaced to the other.
[PISERVER]
PIHOMENODE=PISERVER_PRI
DSTMISMATCH=3600
[TCP/IP]
PORT=5450
[APIBUFFER]
BUFFERING=1
BUF1SIZE=1048576
BUF2SIZE=1048576
SENDRATE=100
MAXTRANSFEROBJS=5000
[BUFFEREDSERVERLIST]
BUFSERV1=PISERVER_PRI
BUFSERV2=PISERVER_SEC
[REPLICATEDSERVERLIST]
REPSERV1=PISERVER_PRI
REPSERV2=PISERVER_SEC
Interface Diagnostics Configuration
The Interface Point Configuration chapter provides information on building PI points for collecting data from the device. This chapter describes the configuration of points related to interface diagnostics.
Interface Specific Performance Points
To monitor the status and performance of the interface as it processes the files, the interface supports a number of performance PI points that are specific to this interface. Because the interface is able to process two different types of input file, there are two sets of performance points. One for the measurement data and the other for the alarm messages.
To indicate that a PI point is an interface-specific performance point, Location2 must be set to -1. To identify the performance value to be stored in the point, the interface checks the ExDesc attribute for the a specific keyword. The following is a list of the keywords, the expected PI PointType and a description of the value.
|ExDesc Keyword |PointType |Description |
|DATA_LATEST_TIMESTAMP |Float64 |Timestamp of the latest event found in the data file. |
|DATA_EVENTS_FOUND |Int32 |Total number of events found in the data file. |
|DATA_EVENTS_SENT |Int32 |Total number of events sent to the PI system from the |
| | |data file. |
|DATA_FILE_STATUS |Digital |Status to indicate whether the data file was processed |
| | |cleanly or whether errors were found. See the section |
| | |File Status State Set for the digital set definition. |
|DATA_TIME_TAKEN |Float32 |Number of milliseconds the interface took to process |
| | |the data file. |
|ALARM_LATEST_TIMESTAMP |Float64 |Timestamp of the latest event found in the alarm file. |
|ALARM_EVENTS_FOUND |Int32 |Total number of events found in the alarm file. |
|ALARM_EVENTS_SENT |Int32 |Total number of events sent to the PI system from the |
| | |alarm file. |
|ALARM_FILE_STATUS |Digital |Status to indicate whether the alarm file was processed|
| | |cleanly or whether errors were found. See the section |
| | |File Status State Set for the digital set definition. |
|ALARM_TIME_TAKEN |Float32 |Number of milliseconds the interface took to process |
| | |the alarm file. |
If the PI point does not have the same PointType as those listed, the PI point will be rejected by the interface.
Note: The xxxx_LATEST_TIMESTAMP performance points are important when the interface is running in a redundant configuration, as it will help to reduce the overlapping data when the failover occurs.
A set of sample interface-specific performance points are included with the interface install kit.
UniInt Interface Health Monitoring Points
UniInt Interface Health Monitoring Points provide information about the health of this Interface.
UniInt looks at several interface startup parameters and PI tag properties to determine if a point is to be loaded as an Interface Health point. The table below lists the applicable tag attributes, the required value and a description for each property. Any PI Tag property not listed in the table is not applicable to the operation of Interface Health points.
|Tag Attribute |Value |Description |
|PointSource |Equal to -PS from the interface |The PointSource property for the tag is not case sensitive |
| |startup parameters | |
|Location1 |Equal to -ID from the interface |If there is no -ID found in the list of startup parameters, |
| |startup parameters |Location1 must be 0. |
|Location2 |0 |Not Used |
|Location3 |Equal to -UHT_ID from the interface |Only applicable -UHT_ID=# is specified in the list of |
| |startup parameters |startup command parameters. A point with every other |
| | |property set correctly will not be loaded by the interface |
| | |if Location3 is not equal to the -UHT_ID parameter. This is |
| | |used allow multiple instances of the interface to write to |
| | |separate health points. |
|Location4 |Specifies the Scan Class to which |Only applicable to Scan Class points, all other Interface |
| |this point pertains. |Health points ignore this value. |
| | |For monitoring unsolicited IO Rate and Bad Value Rate, Total|
| | |Scans Missed or Total Scans Skipped; Location4 must be 0 |
|ExDesc |Must contain the proper Key Word |Key Word must be the first thing in the ExDesc and is case |
| |described below |sensitive. |
UniInt supports collecting a variety of information about the health of an interface. The points that collect data pertaining to the performance of an interface are collectively referred to as Interface Health Points. The following paragraphs describe the supported Interface Health points, including configuration requirements and update intervals.
The non Scan Class Health points update either on change or at the heartbeat rate. The heartbeat rate is determined by the scan classes defined for the interface. If there are no scan classes defined, the heartbeat will update once per second. If there is at least one valid scan class defined for the interface, the heartbeat will update at the rate of the scan class with the highest frequency (smallest value). The other non Scan Class Health points will be updated when the heartbeat is updated. All of the Scan Class Health points will be updated when the class is scanned. For the Scan Class Health points, Location4 must be set to a valid scan class. It cannot be less than zero or greater than the number of valid scan classes specified in the list of startup parameters.
[UI_IF_INFO]
The [UI_IF_INFO] Health Point is the Interface Information Point. This point provides information for all interfaces that connect to a PI Server. The value of this point is a string that indicates:
• the node name on which an interface is running;
• the IP address on which an interface is running;
• an interface’s executable name;
• an interface’s Point Source parameter;
• an interface’s Interface ID parameter;
• an interface’s Scan Classes;
• the number of points in an interface’s point list;
• the number of messages to pipc.log that an interface has written; and
• the number of seconds that an interface has been running.
An example value for the Interface Information Point is:
etamp390 | 192.168.8.72 | ModbusE.exe | MODBUSE | ID 1 | 3 Scan Classes: 5; 60; 120 | Points 0 | Message Count 31 | Up Time 0
This Interface updates the value of the Interface Information Point every 30 minutes. Please consult the “Interface Health Points” section of the UniInt Interface User Manual for details on changing this update frequency.
[UI_HEARTBEAT]
The [UI_HEARTBEAT] Health Point indicates whether the Interface is currently running. The value of this point is an integer that increments continuously from 1 to 15. After reaching 15, the value resets to 1.
The fastest scan class frequency determines the frequency at which the Interface updates this point:
|Fastest Scan Frequency |Update frequency |
|Less than 1 second |1 second |
|Between 1 and 60 seconds, |Scan frequency |
|inclusive | |
|More than 60 seconds |60 seconds |
If the value of the [UI_HEARTBEAT] Health Point is not changing, then this Interface is in an unresponsive state.
[UI_DEVSTAT]
The [UI_DEVSTAT] Health Point provides an indication of the status of the interface. The possible values for this string point are:
• “1 | Starting” – The Interface remains in this state until it has successfully collected data from its first scan.
• “Good” – This value indicates that the Interface is able to connect to all of the devices referenced in the Interface’s point configuration. A value of “Good” does not mean that all tags are receiving good values, but it is a good indication that there are no hardware or network problems.
• “4 | Intf Shutdown” – The Interface has shut down.
The Interface updates this point whenever the interface is started or stopped.
[UI_SCINFO]
The [UI_SCINFO] Health Point provides scan class information. The value of this point is a string that indicates
• the number of scan classes;
• the update frequency of the [UI_HEARTBEAT] Health Point; and
• the scan class frequencies
An example value for the [UI_SCINFO] Health Point is:
3 | 5 | 5 | 60 | 120
The Interface updates the value of this point at startup and at each performance summary interval.
Because this interface supports only unsolicited points, there should be no scan classes defined. Therefore, a [UI_SCINFO] point for this interface should always be
0 | 1
[UI_IORATE]
The [UI_IORATE] Health Point indicates the sum of
1. the number of scan-based input values the Interface collects before it performs exception reporting; and
2. the number of event-based input values the Interface collects before it performs exception reporting; and
3. the number of values that the Interface writes to output tags that have a SourceTag.
The Interface updates this point at the same frequency as the [UI_HEARTBEAT] point’s. The value of this [UI_IORATE] Health Point may be zero. A stale timestamp for this point indicates that this Interface has stopped collecting data.
[UI_MSGCOUNT]
The [UI_MSGCOUNT] Health Point tracks the number of messages that the Interface has written to the pipc.log file since start-up. In general, a large number for this point indicates that the Interface is encountering problems. You should investigate the cause of these problems by looking in pipc.log.
The Interface updates the value of this point every 60 seconds. While the Interface is running, the value of this point never decreases.
[UI_SCPOINTCOUNT]
You can create a [UI_SCPOINTCOUNT] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Point Count.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.
This Health Point monitors the number of tags in a Scan Class.
The Interface updates a [UI_SCPOINTCOUNT] Health Point when it performs the associated scan.
Note: Because this interface only supports unsolicited data points, only the .sc0 scan class is valid.
[UI_SCIORATE]
You can create a [UI_SCIORATE] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class IO Rate.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.
A particular Scan Class’s [UI_SCIORATE] point indicates the number of values that the Interface has collected. If the current value of this point is between zero and the corresponding [UI_SCPOINTCOUNT] point, inclusive, then the Interface executed the scan successfully. If a [UI_SCIORATE] point stops updating, then this condition indicates that an error has occurred and the tags for the scan class are no longer receiving new data.
The Interface updates the value of a [UI_SCIORATE] point after the completion of the associated scan.
Note: Because this interface only supports unsolicited data points, only the .sc0 scan class is valid.
[UI_SCBVRATE]
You can create a [UI_SCBVRATE] Health Point for each Scan Class in this Interface. The ICU uses a tag naming convention such that the suffix “.sc1” (for example, sy.st.etamp390.E1.Scan Class Bad Value Rate.sc1) refers to Scan Class 1, “.sc2” refers to Scan Class 2, and so on.
A particular Scan Class’s [UI_SCBVRATE] point indicates the number System Digital State values that the Interface has collected.
The Interface updates the value of a [UI_SCBVRATE] point after the completion of the associated scan.
Note: Because this interface only supports unsolicited data points, only the .sc0 scan class is valid.
Failover configurations with UniInt Health Points
When using failover interface with the UniInt performance points, each instance of the interface should be configured with its own set of UniInt performance points. The points use location3 and the -uht_id= argument to differentiate the two sets of points. See the UniInt Interface User Manual for more information.
I/O Rate Point
An I/O Rate point measures the rate at which the Interface writes data to its input tags. The value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server.
When the Interface starts, it writes 0 to the I/O Rate point. After running for ten minutes, the Interface writes the I/O Rate value. The Interface continues to write a value every 10 minutes. When the Interface stops, it writes 0.
Configuring I/O Rate Tags On Linux
There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring PI Point on the PI Server
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 SIPowerTG001, and that the name of the I/O Rate on the home node is SIPowerTG001.
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 manual.
Add a line in the iorates.dat file of the form:
SY.SIPOWERTG.IORATE, x
where SY.SIPOWERTG.IORATE is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x parameter 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 parameter 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
sh $PIHOME/bin/pistart
4. Determine that the shared memory server and the I/O Rates Monitor are running with the commands:
ps –ef | grep ioshmsrv
ps –ef | grep iorates
Interface Status Point
The PI Interface Status Utility (ISU) alerts you when an interface is not currently writing data to the PI Server. This situation commonly occurs if
• the monitored interface is running on an Interface Node, but the Interface Node cannot communicate with the PI Server; or
• the monitored interface is not running, but it failed to write at shutdown a System state such as Intf Shut.
The ISU works by periodically looking at the timestamp of a Watchdog Tag. The Watchdog Tag is a tag whose value a monitored interface (such as this Interface) frequently updates. The Watchdog Tag has its excdev, excmin, and excmax point attributes set to 0. So, a non-changing timestamp for the Watchdog Tag indicates that the monitored interface is not writing data.
Please see the Interface Status Interface to the PI System for complete information on using the ISU. PI Interface Status runs only on a PI Server Node.
The PI Interface Status Utility – and not this Interface – is responsible for updating the ISU tag. So, make sure that the PI Interface Status Utility is running correctly.
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name 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 parameter 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 Interface User Manual for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
0. 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.
0. As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
0. If the /db is used on the command-line, then various informational messages are written to the log file.
Messages
The following are the error messages that can be generated by the interface, including the description of the cause of the error and a way of correcting the error.
Startup
Invalid debug option [?] - ABORTING
A debug option given in the -debug= argument is not recognized by the interface. Check that all the debug options listed are valid.
Unable to locate directory "????" - ABORTING
The directory specified by either the -data= or -alarm= argument was not found. Verify that the directory that will contain the either the data input file or alarm input file exists.
"????" is not a directory - ABORTING
The directory specified by either the -data= or -alarm= argument was located , but it not a valid directory. Verify that the directory that will contain the either the data input file or alarm input file exists.
No read/write permission for data directory "????" - ABORTING
The directory specified by either the -data= or -alarm= argument was located , but the user running the interface does not have read/write permissions for the directory. Because the interface needs to be able to read and delete the files from the directory, the interface must have read/write permissions for the directory. Verify that the interface is being run by the correct user, and that user has read/write permissions for the directory.
Cannot rename data file when data file not defined - ABORTING
The -renamedata parameter has been specified, but the -data argument has not. It is meaningless to rename the data file when the data file has not been set. Either remove the -renamedata parameter or set the -data parameter, depending on the requirements for the interface.
Cannot rename alarm file when alarm file not defined - ABORTING
The -renamealarm parameter has been specified, but the -alarm argument has not. It is meaningless to rename the alarm file when the alarm file has not been set. Either remove the -renamealarm parameter or set the -alarm parameter, depending on the requirements for the interface.
Neither -data= or -alarm= arguments specified.
At least one must be specified - ABORTING
The interface can process either data input files or alarm input files or both. The interface will not run if neither of these are defined. Add either a -data or -alarm parameter, or both.
-data= and -alarm= must not refer to the same file - ABORTING
The -data and -alarm arguments refer to the same file. As the files have different formats, they cannot be the same file. Correct either the -data or -alarm argument.
Loading PI points
PITag ?????? (?) - Interface does not support periodic scan points
All data points must have Location4=0
The interface processes input files when a file is available, so all the point updates are unsolicited. It is not able to periodically scan points and so all the points must have Location4=0. This attribute is used by UniInt to define the scan class, and scan classes should not be defined for this interface.
PITag ?????? (?) - Unable to allocate dev_struct
The interface was not able to allocate memory to store the configuration of the given point. Free up memory on the interface node and restart the interface.
PITag ?????? (?) - Invalid interface-specific performance point
ExDesc keyword is empty
An interface-specific performance point (Location2=-1) has an empty ExDesc attribute. Edit the point to include the required performance value keyword in the ExDesc. See “Interface Specific Performance Points” for a list of valid keywords.
PITag ?????? (?) - Invalid interface-specific performance point
Unrecognized ExDesc keyword "???"
The keyword in the ExDesc of an interface-specific performance point (Location2=-1) does not match an of the valid keywords. Edit the point to include a valid performance value keyword in the ExDesc. See “Interface Specific Performance Points” for a list of valid keywords.
PITag ?????? (?) - Invalid interface-specific performance point
PointType mismatch for the given ExDesc keyword
The interface will only accept an interface-specific performance point (Location2=-1) if the PointType of the point matches that of the given performance value. Check to ensure that the PointType is the same as those listed in the “Interface Specific Performance Points” section for the given keyword.
PITag ?????? (?) - Invalid PI PointType for a measurement data point
A measurement data point (Location2=0) PointType can be float64, float32, float16, int32, int16 or digital. It cannot be a string type. Check that the PI point is configured with a valid PointType for a measurement data point.
PITag ?????? (?) - Invalid InstrumentTag for data point
InstrumentTag is empty
A measurement data point (Location2=0) must have the InstrumentTag defined so that the interface will know which Power TG point value to store in the PI point. Ensure that the InstrumentTag for the point has been properly defined.
PITag ?????? (?) - Invalid InstrumentTag attribute "???"
Must be in the format MEASID@FIELD.TYPE where MEASID is an integer value
A measurement data point (Location2=0) must have the InstrumentTag defined with the format MEASID@FIELD.TYPE, where the MEASID is an integer value and matches the Power TG point id of the required point. Ensure that the InstrumentTag for the point has been properly defined.
PITag ?????? (?) - Invalid InstrumentTag attribute "???"
Must be in the format MEASID@FIELD.TYPE where FIELD is NOT blank
A measurement data point (Location2=0) must have the InstrumentTag defined with the format MEASID@FIELD.TYPE, where the FIELD is the name of the field required from the Power TG point. Ensure that the InstrumentTag for the point has been properly defined. The interface is not able to validate the field name, other than making sure it is not blank, so care must be taken to ensure that the correct field name is used.
PITag ?????? (?) - Invalid InstrumentTag attribute "???"
Unrecognized TYPE "???"
A measurement data point (Location2=0) must have the InstrumentTag defined with the format MEASID@FIELD.TYPE. The .TYPE is optional, but if defined it must match the valid keyword types given in the InstrumentTag section of the manual. Ensure that the InstrumentTag for the point has been properly defined.
PITag ?????? (?) - Invalid .QUAL type
Quality code definitions are not defined
Quality code points (InstrumentTag ends with .QUAL) can only be used with the quality code definitions have been loaded from the data_qualities.ini file. Check that the /qualcodefile= argument has been properly defined and that the quality codes were loaded when the interface was started.
PITag ?????? (?) - Invalid digital set for quality priorities
Digital set must have at least ?? states to store the defined quality priorities
Quality code points (InstrumentTag ends with .QUAL) must have a digital set defined that has at least the number of states as the highest priority defined in the data_qualitities.ini file. Check the digital set assigned to the point and compare the digital set with the contents of the data_qualitities.ini file and that the /qualcodefile= argument has been properly.
PITag ?????? (?) - Invalid PointType for an alarm PI point
an alarm point MUST be a string PI point
An alarm point (Location2=1) must have a string PointType. Check the configuration of the point.
PITag ?????? (?) - Unable to parse filter expression from InstrumentTag
An alarm point (Location2=1) can use a filter to limit the alarm messages it will sort. The interface has been unable to parse the filter expression, which is configured in the InstrumentTag attribute. Check the configuration of the point. Refer to the “Point Attribute - InstrumentTag” section for more information of the filter expression syntax.
PITag ?????? (?) - Invalid value for Location2
-1=perf, 0=data, 1=alarm
The value of Location2 is not valid. Check the configuration of the PI point and ensure that Location2 is valid. Refer to the “Point Attribute - Location2” section for a list of valid values.
Data File Processing
Unable to remove input file xxxxx - ABORTING
errno=? - ???????????????
The interface failed to remove the file after processing and has aborted. Use the system error message to find the cause. It may be a permissions problem, so check the credentials of the user running the interface and the permissions of the input file.
Unable to rename xxxxx to yyyyy
yyyyy already exists - Will retry every 2 seconds
Unable to rename the current input file because the previous file still exists. This is probably caused by the downstream process not having finished processing the file itself. Check that the downstream process that should be removing the file is running correctly. The interface will stop at this point and not process any more files until the previous file has been removed.
Unable to rename xxxxx to yyyyy
errno=? - ?????????????
Will attempt to delete yyyyy
Unable to rename the current input file. The previous file does not exist, but some other error is causing the rename to fail. The interface will delete the current file instead of renaming so that processing can continue.
Input data file invalid (does not start with 0x01 0x02)
The measurement data input file is not valid. All data input files must start with the bytes 0x01 0x02. The interface will reject any data input files that do not start with these 2 bytes. Check that the interface is reading the correct file defined by the -data parameter.
TG EVENT ?? > INVALID > ???????????????????????
The interface found an error while validating an event from the data input file. This could be caused by a file corruption. The output of the event data should give an indication of the problem. Use the DumpInputFile utility to check the contents of the file against the event logged by the interface.
TG EVENT ?? > INVALID > ???????????????????????
Event timestamp too far into the future
The interface found an event with a timestamp that was too far into the future to be valid. This could be caused by incorrectly configured time zones, or if the clocks within the system have drifted by more than 5 minutes.
Forced to exit before data file had finished processing
The interface has been asked to stop while it was processing a data input file. This is only ever likely to be seen if the interface is stuck in a loop while processing the file or the input file is very large. If the input file was not large, then keep a copy of the input file and the current point configuration and contact OSIsoft tech support so that the problem can be reproduced.
Alarm File Processing
Input alarm file invalid (does not start with 0x03 0x04)
The alarm input file is not valid. All data input files must start with the bytes 0x03 0x04. The interface will reject any alarm input files that do not start with these 2 bytes. Check that the interface is reading the correct file defined by the -alarm parameter.
TG ALARM ?? > INVALID > ???????????????????????
The interface found an error while validating an alarm message from the alarm input file. This could be caused by a file corruption. The output of the alarm message should give an indication of the problem. Use the DumpAlarmFile utility to check the contents of the file against the alarm message logged by the interface.
TG ALARM ?? > INVALID > ???????????????????????
Event timestamp too far into the future
The interface found an alarm message with a timestamp that was too far into the future to be valid. This could be caused by incorrectly configured time zones, or if the clocks within the system have drifted by more than 5 minutes.
Forced to exit before alarm file had finished processing
The interface has been asked to stop while it was processing an alarm input file. This is only ever likely to be seen if the interface is stuck in a loop while processing the file or the input file is very large. If the input file is not large, then keep a copy of the input file and the current point configuration and contact OSIsoft tech support so that the problem can be reproduced.
Getting Latest Timestamp
The following error messages can only be generated when the interface is attempting to read the LATEST_TIMESTAMP performance point. It does read the point value, so that it can minimize the number of out-of-order events it sends to PI. The interface should only attempt to read the point value when the interface is starting or when the interface has been in standby (has not been receiving input files to process).
Note: If there are any problems with reading the LATEST_TIMESTAMP point, the interface will default to sending all the events in the input file. This may result in more out-of-orders events being sent to PI. As the out-of-order events should only occur when the interface is going from standby to active, it would not happen often and the PI server is able to handle a few out-of-order events.
No LATEST_TIMESTAMP point configured, so all events in the file will be sent to PI
If no LATEST_TIMESTAMP point has been configured then the interface will not be able to minimize the number of out-of-order sent to PI. All events in the file will be sent.
Not connected to PI, so unable to read latest timestamp to reduce OOO events
If the interface does not have a connection to the PI server, it will not attempt to read the current timestamp value from the LATEST_TIMESTAMP performance point, because the read will fail.
Reading LATEST_TIMESTAMP point. pisn_getsnapshotx(??) returned ??????
The interface got an error when attempting to read the LATEST_TIMESTAMP performance point. The PI error appended to the message should give an indication of the cause.
LATEST_TIMESTAMP point returned istat=???, so all events in the file will be sent to PI
The interface was able to read the value of the LATEST_TIMESTAMP point, but it contained a system digital state rather than a valid timestamp. Therefore, all the events in the input file will be sent to PI.
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 Linux
On Linux, descriptions of system and PI errors can be obtained with the pidiag utility:
Linux: /PI/adm/pidiag –e error_number
Appendix B :
Event Data File Structure
The following describes the file structure of the event data file generated by the Siemens Power TG historian software, which is processed by the interface.
The first field of the file is a “magic number”, which is 2 bytes long and MUST contain 0x01 0x02. This is used to verify that the file being read is an event data file. If the file does not start with 0x01 0x02 then the interface will reject the file and output a file status of “Invalid”.
Following the “magic number”, the file contains the actual event data records. Each record is 58 bytes long. The fields within the event record are as followings.
|Offset |Length |Description |
|0 |4 |Point ID (integer) |
|4 |9 |Field Name (string) |
|13 |4 |Type (integer) |
|17 |16 |UTC Timestamp (SQL_TIMESTAMP structure) |
|33 |4 |Milliseconds timestamp (integer) |
|37 |4 |Value (IEEE single precision float) |
|41 |8 |Point Attribute / Quality flags (2 x 4 byte integers) |
|49 |9 |Source (string) |
Appendix C :
Alarm Message File Structure
The following describes the file structure of the alarm message file generated by the Siemens Power TG historian software, which is processed by the interface.
The first field of the file is a “magic number”, which is 2 bytes long and MUST contain 0x03 0x04. This is used to verify that the file being read is an event data file. If the file does not start with 0x03 0x04 then the interface will reject the file and output a file status of “Invalid”.
Following the “magic number”, the file contains the actual alarm message records. The length of each record is variable. The fields within the event record are as followings.
|Offset |Length |Description |
|0 |16 |UTC Timestamp (SQL_TIMESTAMP structure) |
|16 |4 |Sequence number (integer) |
|20 |4 |Priority (integer) |
|24 |9 |AOR Group (string) |
|33 |9 |Source (string) |
|42 |4 |Entity field length in bytes (integer) |
|46 |EntLen |Entity name (string |
|46+EntLen |4 |Message field length in bytes (integer) |
|50+EntLen |MsgLen |Alarm Message |
The sequence number, priority, AOR group, entity and alarm message are concatenated into a single string with “|” characters separating the fields for storing in the PI string points.
Appendix D :
Setting up a PI Archive on the Power TG System
PI Server Definition
The data for the Power TG system is defined using the Source Database Builder (SDB). This database allows the user to configure the Power TG database off line and then install a set of changes in a block to the running system. The archiving of data to the PI system from the Power TG system is also defined using the SDB.
To set up archiving in the SDB, you open the “Data Warehouse” form using the “Data Warehouse” option on the “SCADA” menu or the “Archives” toolbar button. This form is used to define all archiving from the Power TG system including PI as well as to SQL Server and Oracle databases. The form has multiple tabs. The first tab marked “Data Warehouse” defines the attributes of the archive servers. The second tab marked “System Archive Groups” defines the collection of data from the Power TG system and sending that data to an archive server.
To set up a PI archive server, you first define the computer that will contain the PI database using the “Computer Definitions” form from the “Hardware” menu. If a PI collective will be used, you define the computer as the primary member of the collective. Next, you open the “Data Warehouse” form, select the “Data Warehouse” tab and click the “New Data Warehouse” button at the top right of the form. This will present a dialog box where you give the archive server its “entity name”, its “real time database name”, choose the database type of “PI” and select the computer name. After clicking on the checkmark button of the dialog box, the new archive server (data warehouse) object is defined in the SDB database.
[pic]
On the “Data Warehouse” tab, the data entry fields for a PI server are interpreted as follows:
• Longname
This is the name that will be presented to the Power TG operator in alarm messages and status display for this server.
• RTDB Name
This is the “Real Time Database Name” for this server. The sort order of the RTDB names of the archives on a system determines the order they occur in the TG system. This order determines the number used in the name of the buffer files to identify the server to which the data is to be sent. It is also used to define the location of the files used by the Automatic Point Synchronization (APS) application to transfer the PI tag definitions from the SDB to the PI database. This file is created on the SDB server in the directory “\lg\database\dat\PI\” where the “” portion of the path is substituted for this name.
• AOR Group
This is the area of responsibility group in which alarms relating to the archive server will be presented. It also defines which operators have the ability to control the state of the archiving operation.
• Alarm Priority
This the priority at which alarms relating to the status of the archiving will be presented.
• Computer
This is the name of the computer or collective used for the PI database.
• Instance
This is the “Point Source” name used in the PI database. If not specified, “TG” is used.
• Database Type
Choose “PI” for a PI database.
• Database
If PI buffering using “bufserv” is enabled and the status of the PI buffers is to be periodically checked to indicate the state of the archiving process, define this field with a string such as:
bufserv:piserver1,piserver2
That is, the keyword “bufserv” followed by a colon (:) and then a comma separated list (with no imbedded spaces) of the names of the one or more PI servers to which the data is being sent.
When defined in this way, the TG process will run the BufStat utility every 30 seconds for each server listed and post alarms or event messages to the Power TG alarm summary when the connection state of a buffer changes. If all buffers are disconnected, the archiving will receive a status of FAILED.
• PI Interface ID
This is the interface ID number used to identify the instance of the interface from the TG system to the PI server. If not specified, it defaults to a value of 1.
In the lower portion of the form is a list to specify AOR Groups and their retention period in the archive database. For the PI archive, the retention is defined on the PI server. This definition for a PI database indicates only if the messages in the AOR groups are sent to the archive. By default, messages are sent to the archive. If it is desired that a particular AOR group’s messages are not to be archived, it may be entered in this part of the form with a retention period of zero.
Point Collection Definition
The second tab of the Data Warehouse form defines the collection of data from the Power TG system for storage into the archive server.
[pic]
Each collection is defined as an “Archive Type” that defines the Power TG system from which the data are collected and the server to which they are stored.
To define a new archive type, you click the “New Archive Definition” button at the top right of the form. A dialog box will appear where you define the name of the archive type and its source TG system and destination archive server. There can be as many archive types as needed to define the collection of data.
The collection frequency of a set of data is defined by the fields Period, Offset, Delay, Save Changes Only and Force Interval. You can get the specific details of the scheduling from the SDB’s help but there are essentially two collection types:
• Periodic
This is the collection when the “Period” field has a non-zero value defined indicating the interval, in seconds, between collection of the data values. The “Offset” and “Delay” values indicate when relative to the beginning of a clock hour the collection is performed and the timestamp that is stored with the values.
• Spontaneous
This is the collection type when the “Period” field is blank or zero and the “Save Changes Only” box is checked. In this case, changes in value or quality are sent to the archive system as soon as they are detected by the Power TG system.
In both cases, the “Force Interval” specifies an interval, in seconds, where the values will be sent to the archive server regardless of change of value or quality.
The “Measurement List” field defines the Power TG measurements that will be collected on the schedule defined by this archive type. Clicking on the “Edit Measurement List” button to the right of this field opens a form where measurements can be added to or removed from the list.
The “Field List” field defines a list of the attributes that will be collected from the measurement objects in the Power TG database. If left blank, the default attributes of “VALUE” (the current value) for analog measurements, “STATE” (the current state) for status measurements and “DELT_ACC” (the change in value in the most recent sample interval) for accumulators are used. If different or additional attributes are to be archived, a custom list can be created by clicking on the “Edit Field List” to the right of this field.
The “Special Field List” field defines a list of values to be extracted from the Power TG database that are not necessarily associated with station measurements. These can reference any numeric field in the Power TG database using its fully qualified Table/Record/Entry/Field (TREF) string. Knowledge of the Power TG real time database is necessary to define these references.
For a PI database, there are the following fields presented on the form:
• PI Exception (%)
This specifies the exception reporting threshold in percent of full range as default for all values in the archive type. For station analog measurements, this can be overridden by a definition in the “Data Processing” tab of the analog definition.
• PI Compression (%)
This specifies the compression change threshold in percent of full range as default for all values in the archive type. For station analog measurements, this can be overridden by a definition in the “Data Processing” tab of the analog definition.
For all values except analog current values, the range is assumed to be 1000 and the zero value is 0.0. For analogs, the range can be explicitly defined on the “Data Processing” tab or, if that is blank, it is calculated as the first of reasonability limits, telemetry scale values or alarm limits that are defined. If none of the above are defined, the range of the analog value is defaulted to 2000 with a zero value of -1000. If a value is specified in the measurement list of more than one archive type, the lowest value of the exception and compression percentages is used.
There are also a set of check boxes on the archive type definition form for PI collections do define additional tags that will be created to store data qualities and other attributes in addition to the primary value. The “primary” value is the default attribute as defines above for analog, status or accumulator data and any value defined by the “Special Field List”. It is useful to define the special fields in a separate archive type if the data quality attributes are to be created. The data quality is only supplied with a special field if the entry in the real time database from which it is collected contains a telemetry failure (TELEM_F) attribute.
These check boxes are:
• Create PI Tags for Base OPC Quality
This option causes an additional tag to be created in the PI database for all primary fields containing the base quality values as defined in the Power TG archiving system. These qualities are expressed as a value in the form QQSSSS where “QQ” represents the summary quality of 0=BAD, 1=Uncertain and 3=Good. The SSSS portion of the value indicates the additional most significant details of the summary quality. The generated tag has the syntax “@OPCQQSSSS” where “” is the entity name of the primary tag. This is a Digital tag using the state set “TG_QUAL_QQSSSS”.
• Create PI Tags for Limit OPC Quality
This option causes an additional tag to be created in the PI database for the limit portion of the Power TG archive quality for analog value tags. This tag name uses the syntax “@OPC_LL”. This tag indicates the limit conditions of the analogs as a Digital tag using the state set “TG_QUAL_LIMIT”.
• Create PI Tags for Special Quality
This option causes an additional tag to be created in the PI database for all primary fields containing the special quality values as defined in the Power TG archiving system. These qualities represent the most significant of the “in control”, “alarm inhibit”, etc. qualities. This tag uses the syntax “@OPC_SPCL” and is a Digital tag using the state set “TG_QUAL_SPECIAL”.
• Create PI Tags for Analog State
This option causes an additional tag to be created in the PI database for the analog limit state for all analog value tags. This tag name uses the syntax “@AALRM_STATUS”. This tag indicates the limit conditions of the analogs as a Digital tag using the state set “TG_ALARM_STATUS”.
• Create PI Tags for Quality Symbol
This option causes an additional tag to be created in the PI database for all primary fields containing a digital value indicating the data quality symbol for the point as displayed on the Power TG user interface. The tag name uses the syntax “@DATA_QUALITY” and is a Digital tag using the state set “TG_DATA_QUALITY”.
Installing Data from the SDB for a PI Archive
To implement changes defined n the SDB, these changes must be “installed” to the Power TG servers and to the PI server. When station points are added or deleted, these are installed to the TG real time database using the “Power TG Host” tab of the SDB Database Installation form.
If there are changes in the data to be collected into the PI system, that is installed to the PI server and TG archive system on the TG host servers using the “Data Warehouse” tab if the SDB Database Installation form. To perform this install, choose the name of the PI database on this tab and click the Install button. This will cause a new CSV file to be generated for the Automatic Point Synchronization process to update the tags in the PI database. This make take several minutes after the SDB installation completes before these updates are reflected in the PI database. The data collection parameters on the Power TG host servers are also updated with the new lists and collection frequencies so that the data will begin to be sent to the PI database as soon as the tags are available.
Revision History
|Date |Author |Comments |
|11-Feb-2009 |KMillar |Initial Draft: Based on skeleton 3.0.7 |
|09-Nov-2009 |KMillar |Version 1.0.0.0 – Initial Release |
|11-Nov-2009 |MKelly |Version 1.0.0.0 Revision A, Fixed headers and footers, updated formatting, |
| | |fixed all hyperlinks. |
................
................
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
- what happened to the original power rangers
- calculator with the pi button
- fraction to the power calculator
- 10 to the power calculator
- 10 to the power of negative 6
- how to cleanse the lymphatic system naturally
- to the power of calculator
- 2 to the power of 5
- the planets of the solar system song
- 7 to the power of negative 2
- the organs in the circulatory system include
- to the power calculator