PI Interface for Siemens Spectrum Power TG (Linux)cdn.osisoft.com/interfaces/3305/PI_SIPowerTG_LNX_1.0… · Web viewThe PI Interface for Siemens Spectrum Power TG ... {SCRIPT}

$Page 1: PI Interface for Siemens Spectrum Power TG (Linux)cdn.osisoft.com/interfaces/3305/PI_SIPowerTG_LNX_1.0… · Web viewThe PI Interface for Siemens Spectrum Power TG ... {SCRIPT}$
PI Interface for Siemens Spectrum Power TG (Linux)

Version 1.0.2

OSIsoft, LLC777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

OSIsoft Australia • Perth, AustraliaOSIsoft Europe GmbH • Frankfurt, GermanyOSIsoft Asia Pte Ltd. • SingaporeOSIsoft Canada ULC • Montreal & Calgary, CanadaOSIsoft, LLC Representative Office • Shanghai, People’s Republic of ChinaOSIsoft Japan KK • Tokyo, JapanOSIsoft Mexico S. De R.L. De C.V. • Mexico City, MexicoOSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil

PI Interface for Siemens Spectrum Power TG (Linux)Copyright: © 2009-2013 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, PI Asset Framework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event Frames, 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 RIGHTSUse, 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: 05/2013

http://www.osisoft.com/

Table of Contents

Chapter 1. Introduction...................................................................................................1Reference Manuals............................................................................................1Supported Operating Systems...........................................................................1Supported Features...........................................................................................1Diagram of Hardware Connection......................................................................4

Chapter 2. Principles of Operation................................................................................5

Chapter 3. Installation Checklist..................................................................................11Data Collection Steps.......................................................................................11Interface Diagnostics........................................................................................12Advanced Interface Features...........................................................................13

Chapter 4. Interface Installation on Linux...................................................................15Naming Conventions and Requirements..........................................................15Interface Directories.........................................................................................15

PIHOME Directory.................................................................................15Interface Installation Directory...............................................................15

PI API Installation on a Linux Power TG machine............................................16Interface Installation Procedure.......................................................................18

Chapter 5. DumpInputFile Utility..................................................................................21

Chapter 6. DumpAlarmFile Utility................................................................................23

Chapter 7. BufStat Utility..............................................................................................25

Chapter 8. Digital States...............................................................................................27

Chapter 9. PointSource.................................................................................................31

Chapter 10. PI Point Configuration............................................................................33Point Attributes.................................................................................................33

Tag........................................................................................................33PointSource...........................................................................................34PointType...............................................................................................34Location1...............................................................................................34Location2...............................................................................................34Location3...............................................................................................34Location4...............................................................................................34Location5...............................................................................................35InstrumentTag........................................................................................35ExDesc..................................................................................................37Scan......................................................................................................37Shutdown...............................................................................................38


Chapter 11. Startup Command File...........................................................................39Command-line Parameters..............................................................................39Sample PISIPowerTG.sh File..........................................................................44

Chapter 12. Interface Specific Failover.....................................................................47Introduction......................................................................................................47Point Configuration for Failover........................................................................48

Chapter 13. Interface Node Clock..............................................................................51Linux................................................................................................................51

Chapter 14. Security....................................................................................................53Windows and UNIX..........................................................................................53

Chapter 15. Starting / Stopping the Interface on UNIX............................................55Interface Startup Script....................................................................................55Interface Stop Script.........................................................................................56Automatic startup and shutdown......................................................................56Automatic startup on a reboot..........................................................................57Terminating Background Processes................................................................57Anomalous Background Job Termination........................................................58

Chapter 16. Buffering..................................................................................................59Linux Interface Nodes......................................................................................59How Buffering Works.......................................................................................59Buffering and PI Server Security......................................................................60Configuring PI API Buffer Server (bufserv) Manually.......................................60

Performance Settings............................................................................61BufServ and n-way buffering..................................................................62

Notes for bufserv on Linux...............................................................................62Sample piclient.ini file.......................................................................................62

Chapter 17. Interface Diagnostics Configuration.....................................................65Interface Specific Performance Points.............................................................65

Sample Interface Specific Performance Points......................................66Scan Class Performance Points......................................................................66Interface Health Monitoring Points...................................................................67

Failover configurations with UniInt Health Points...................................72Sample UniInt Health Points..................................................................72

I/O Rate Point..................................................................................................72Configuring I/O Rate Tags On UNIX......................................................72

Interface Status Point.......................................................................................74

Appendix A. Error and Informational Messages......................................................75Message Logs..................................................................................................75Messages.........................................................................................................75

Startup...................................................................................................75Loading PI points...................................................................................76


Data File Processing..............................................................................79Alarm File Processing............................................................................80Getting Latest Timestamp......................................................................80

System Errors and PI Errors............................................................................81

Appendix B. Event Data File Structure......................................................................83

Appendix C. Alarm Message File Structure..............................................................85

Appendix D. Setting up a PI Archive on the Power TG System..............................87PI Server Definition..........................................................................................87Point Collection Definition................................................................................90Installing Data from the SDB for a PI Archive..................................................92

Appendix E. Terminology...........................................................................................93

Appendix F. Technical Support and Resources.......................................................97Before You Call or Write for Help...........................................................97Help Desk and Telephone Support........................................................97Search Support......................................................................................98Email-based Technical Support.............................................................98Online Technical Support.......................................................................98Remote Access......................................................................................99On-site Service......................................................................................99Knowledge Center.................................................................................99Upgrades...............................................................................................99OSIsoft Virtual Campus (vCampus).......................................................99

Appendix G. Revision History..................................................................................101


Chapter 1. Introduction

The PI Interface for Siemens Spectrum Power TG (SIPowerTG) allows real-time data from the Siemens Spectrum Power TG system to be written to a PI system.

The interface runs on the Siemens Power TG host station and processes data files generated by the Power TG HIS software.

The interface is available for both Windows and Linux (64-bit) platforms, and both versions have the same functionality. There are differences in the installation and configuration of the interfaces. This manual covers the Linux version of the interface.

The interface does not allow data from the PI system to be written to the Siemens Power TG system. The interface does not support UniInt failover. However, by using the Power TG functionality, interface redundancy is supported.

Reference Manuals

OSIsoft PI Server manuals

PI API Installation Instructions manual

UniInt Interface User Manual

Supported Operating Systems

Platforms 32-bit application 64-bit application

RedHat ES4 Linux32-bit OS N/A No

64-bit OS N/A Yes

RedHat ES6 Linux32-bit OS N/A No

64-bit OS N/A Yes

The interface is designed to run on the above-mentioned UNIX operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported.

Please contact OSIsoft Technical Support for more information.

Supported Features

Feature Support

Interface Part Number PI-IN-SI-PTG-LNX

Auto Creates PI Points Yes (using Generic_CSV APS Connector)


Feature Support

Point Builder Utility No

ICU Control No

PI Point Types float64 / float32 / float16 / int32 / int16 / digital / string

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: 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

* History Recovery No

* UniInt-based* Disconnected Startup* SetDeviceStatus

YesYesYes

* Failover Interface specific failover

* Vendor Software Required on Interface Node / PINet Node

Yes

* 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.

Source of TimestampsThe 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 RecoveryThe Interface does not explicitly support history recovery. However, 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 will be lost.


UniInt-basedUniInt 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-UpThe 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 disconnected startup.

SetDeviceStatusFunctionality 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.

FailoverThe 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 RequiredPower TG Historian (HIS) software version 8.3 SP1or greater is required to generate the event data and message data files used by the interface. The interface runs directly on the Power TG historian machine.

Additional PI SoftwareTwo 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.


Introduction

The utility BufStat is also included to allow the Power TG system to evaluation the status of the connections to the PI Server when bufserv is used.

Device Point TypesThe 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.

Chapter 2. 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 the 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 FileThe 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 an 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 section for more details.

Requesting Initial Values after a Point is added to the InterfaceThe 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 /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 FileThe 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

Sequence (used to define the order of alarms when a group has the same timestamp)

Priority

AOR_Group

Entity

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


Principles of Operation

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. Filtering the alarms in different PI points when they are stored in PI can simplify the analysis of the collected alarm data.

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 containAOR_GROUP=GEN

If a point was to store only the alarms with priority < 10 for the AOR group “GEN”, it use the InstrumentTagPRIORITY<10 AND AOR_GROUP=GEN

Full details of the filtering are described in the PI Point Configuration section.

Connection to PI Server LostBy default, when the connection to the PI server is lost, the interface will continue to process the input files normally, but the events sent to PI will be buffered by the PI API. When the connection is restored, then buffers are sent to PI. With this configuration, there is no indication to the Power TG system that there is a problem with the connection to PI.

To enable to the Power TG system to know that the events are no longer reaching the PI server, the interface includes the -connected parameter. When this parameter is set, the interface will check the status of the connection to the PI server and if the interface is not able to communicate with the PI server, it will NOT process the current input files. The input files will only be processed when the connection to the PI server is good. The Power TG system is able to see that the input files are not being processed, so the events that it is collected are buffered in its own data files, so no data is lost. It is also able to generate an event to notify the Power TG users of the problem with the connection to the PI server.

FailoverThe 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 servers that can send data to PI, only one of these will be publishing the buffer files for the 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 a buffer file is available it means that as soon as the server publishes the file, the interface will be able to process it.

The problem with the above mechanism is that when the secondary server takes over, it publishes a buffer file with up to 30 minutes of data, some of which would have already been published by the primary interface. This overlap in the data files 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, the interface will do the following. When an interface has not been processing files for some time (either on startup or it has been on standby) and it then becomes active, the interface will attempt to read the snapshot value of the “latest timestamp” performance point, which was updated by the other instance of the interface. Once it has the “latest timestamp” value, the interface will process the data file normally, except that it will discard the all events that are older than the time 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 (not loaded by the interface) 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). Because the interface is down, the events will be buffered by the PI API until the connection to restored, but 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.


Chapter 3. Installation Checklist

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

This checklist summarizes the steps for installing this interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of Buffering for every interface node regardless of how many interfaces run on that node.

The Data Collection Steps below are required. Interface Diagnostics and Advanced Interface Features are optional.

Note: The SIPowerTG interface version 1.0.0.0 on Linux is only compatible with PIAPI 1.6.1.11 on Linux. The interface is NOT compatible with later versions of the PIAPI because of the version of the C++ compiler used to build the interface and the PIAPI.

The SIPowerTG interface version 1.0.1.0 or later on Linux is compatible with PIAPI 1.6.4.x or later.

Data Collection Steps

1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT on the same computer on which you run this interface.

2. Edit the PI Server’s Trust Table to allow the interface to write data.

3. Check the interface nodes time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this interface writes.

4. Run the installation kit for this interface on a Windows machine. Copy the extracted SIPowerTG_x.x.x.x_Linux64.tar.gz file and the PIAPI install kit file to the Power TG machine.

5. Extract the contents of the PI API install kit and run the pi.install installation script.

6. Start the PI API processes and use apisnap to verify the connection to the PI server.

7. Extract the interface installation kit into the $PIHOME directory.

8. Replace the sitestart and sitestop scripts in the $PIHOME/bin directory with the scripts included in the interface directory.

9. In the interface directory, use the template startup script to create the startup script for the interface and edit the command-line parameters. Essential startup parameters for this interface are:

Point Source (-PS=x)PI Interface for Siemens Spectrum Power TG (Linux)

Interface ID (-ID=#)PI Server (-Host=host:port) Measurement Data File (-DATA=x)Alarm Message File (-ALARM=x)Quality Code File (-QUALCODEFILE=x)Do NOT configure Scan Classes (-F=##:##:##,offset)

10. Use the DumpInputFile and DumpAlarmFile utilities to confirm the format of a sample event data and alarm message files.

11. 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.

12. Check the contents of the data quality definition file (data_qualitities.ini) and ensure that the TG_DATA_QUALITY digital state set matches the priorities defined in the file.

13. Build input tags and, if desired, output tags for this interface. Important point attributes and their purposes are:

Location1 specifies the interface instance ID.Location2 specifies the point type (performance, value or alarm).Location3 is not used.Location4 MUST be zero. (All points are unsolicited)Location5 specifies whether debug messages will be logs for this point.ExDesc not used by the interface. Normally set to the Power TG point name.InstrumentTag specifies the Power TG point number, field and data type for measurement data points or the filter expression for alarm points.

14. Start the interface interactively and confirm its successful connection to the PI Server without buffering.

15. Confirm that the interface collects data successfully.

16. Stop the interface and configure the buffer server application (bufserv).

17. Start the buffering application and the interface. Confirm that the interface works together with the buffering application by either physically removing the connection between the interface node and the PI Server Node or by stopping the PI Server.

18. Replace the default sitestart and sitestop scripts with those included in the install kit so that the interface will start and stop when the pistart and pistop scripts are used.

19. Restart the interface node and confirm that the interface and the buffering application restart.

Interface Diagnostics

1. Configure the Interface Specific performance points.

2. Configure UniInt Health Monitoring points

3. Configure the I/O Rate point.

4. Install and configure the Interface Status Utility on the PI Server Node.

5. Configure the Interface Status point.


Advanced Interface Features

1. Configure the interface for disconnected startup. Refer to the UniInt Interface User Manual for more details on UniInt disconnected startup.


Chapter 4. Interface Installation on Linux

The interface is installed on the Power TG station. It is recommended that the PI API Bufserv utility is also run on the Power TG station. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the server is down for maintenance, upgrades, backups, and unexpected failures. It is not critical to install Bufserv before the initial installation of the interface. In fact, it is recommended that Bufserv be activated after the interface has been shown to work to ease troubleshooting. Refer to the PI API manual for installation instructions and additional information on Bufserv.

Currently there is no PI Buffer Subsystem for the Linux platform. PI API Buffer Server is the only type of buffering available for the Linux platform.

Naming Conventions and Requirements

In the installation procedure below, it is assumed that the name of the interface executable is PISIPowerTG and that the startup command file is called PISIPowerTG.sh.

Note: UNIX does not enforce file-naming conventions, and it is possible that the file name extensions for the actual interface executable and command files are different than .exe and .sh, or it is possible that the file extensions are eliminated entirely.

To run multiple copies of the interface from the same directory, it is necessary to rename the executable and the command file. It is customary to use PISIPowerTG1 and PISIPowerTG1.sh for interface number 1, PISIPowerTG2.exe and PISIPowerTG2.sh for interface number 2, and so on.

Interface Directories

PIHOME Directory

PIHOME is an environment variable that points to the base directory where the PI API is installed. The setting of environment variables is discussed in the PI API manual.

Interface Installation Directory

There are two conventions for the installation directory. The first convention is to place all copies of the interface into a single directory. If this convention is followed, it is recommended to place PISIPowerTG1, PISIPowerTG2, PISIPowerTG3, etc., in the directory:


[PIHOME]/Interfaces/SIPowerTG

The second convention is to create a separate interface directory for each copy of the interface. If this convention is followed, it is recommended to place PISIPowerTG1, PISIPowerTG2, PISIPowerTG3, etc., in the directories:[PIHOME]/Interfaces/SIPowerTG1

[PIHOME]/Interfaces/SIPowerTG2

[PIHOME]/Interfaces/SIPowerTG3

and so on.

Create the installation directories as necessary.

Note: Because the stop scripts use the name of the executable to locate the process to be stopped, it is important that the executable names used are different. If the same executable name is used for different instances of the interface, the stop scripts are likely to stop the wrong process.

Note: The apiverify on Linux will truncate the process names to 15 characters. Therefore, the interface executable names should be less that 15 characters long.

PI API Installation on a Linux Power TG machine

Before installing the interface, the PI API must be installed first. The following is a summary of the steps required to install the PI API on Linux.

Note: When installing on Power TG 8.2, the owner of the PI API and interfaces should be the ems user. When installing on Power TG 8.3 or later, the owner of the PI API and interfaces should be powertglocal.

Please check with Siemens to confirm the user that the PI API and interface should be owner and run as. It should be the same user as the Siemens software uses to generate the input data files.

Note: The PI SIPowerTG interface version 1.0.0.0 on Linux is only compatible with PIAPI 1.6.1.11 on Linux. The interface is NOT compatible with later versions of the PIAPI because of the version of the C++ compiler used to build the interface and the PIAPI.

These instructions assume that the owner the PI API and interface is powertglocal and the PI API will be installed in the /opt/piapi directory. If the user is not to be powertglocal, then substitute for the correct user name where required.

1. As root, create the PI API directory and change the ownership to the user that will be running the PI API processes.sumkdir /opt/piapi


chown powertglocal /opt/piapiexit

2. Define the PIHOME environment variable to the name of the PI API directory. export PIHOME=/opt/piapi

3. Add the PIHOME definition to the profile of the powertglocal user.For the csh shell (or tcsh), add the following to the ~/.cshrc file# PI API settingssetenv PIHOME /opt/piapisetenv PATH ${PATH}:${PIHOME}/bin::

For the bash shell, add the following to the ~/.bash_profile file# PI API settingsexport PIHOME=/opt/piapiexport PATH=$PATH:$PIHOME/bin::

4. Copy the PI API installation kit piapiLinux64-tar_xxxxx_.gz onto the Power TG machine using FTP/SFTP or similar. Put the file into the /opt/piapi directory.

5. Extract the contents of the piapiLinux64-tar_xxxxx_.gz installation file.cd $PIHOMEgunzip piapiLinux-tar_xxxxx_.gztar xvf piapiLinux-tar_xxxxx_

This will create a directory called build which contains the PI API installation files.

6. Run the PI API installation script pi.install as rootcd $PIHOME/ buildsush ./pi.install

Answer the prompts for your system

Enter an existing user name for PI API [piadmin] ?powertglocalPlease Enter the Node Name of the Default PI Home Node:PISERVER1Is PISERVER1 a PI v3.x (UNIX, NT) system? [Y] or NY

Check the installation messages and verify that there were no errors.

exit (to change back to the powertglocal user)

7. Start the PI API processescd $PIHOME/binpistart

Ignore the message “Warning: USER is not root or piadmin applications may not start.” This warning can be removed from the pistart and pistop scripts by changing the scripts to find the owner the of script and using that instead of the hard-coded “piadmin”.

OWNER=`ls -l $0 | awk '{ print $3 }'`if [ "$USER" != "root" -a "$USER" != "$OWNER" ]; then echo "Warning: USER is not root or $OWNER. Applications may


Digital States

not start."fi

8. Use the apiverify script to check the running PI API processes. Initially, the bufserv process should not be running because buffering is not enabled by default.

9. Use the apisnap utility to verify that the PI API is able to connect to the PI server

Interface Installation Procedure

In the installation procedure below, it is assumed that a single instance of the interface is being installed. If you wish to install multiple instances of the interface in the same directory then copy and rename the executable and startup script to append a number to the end of the name. i.e. with PISIPowerTG#, where # is the interface number between 1 and 99.

1. Copy the SIPowerTG_x.x.x.x.tar.gz file to the $PIHOME directory

2. Extract the contents of the SIPowerTG_#.#.#.#.tar.gz filecd $PIHOMEgunzip SIPowerTG_#.#.#.#.tar.gztar xvf SIPowerTG_#.#.#.#.tar

This will create the $PIHOME/interfaces/SIPowerTG directory for the interface if it does not already exist.

3. Change to the interface directorycd $PIHOME/interfaces/SIPowerTG

4. Verify that the interface will run by checking the interface versionPISIPowerTG –v

5. Copy the sitestop script from the interface directory into the $PIHOME/bin directorymv $PIHOME/bin/sitestop $PIHOME/bin/sitestop.originalcp sitestop $PIHOME/bin

6. Edit the PISIPowerTG_start script to specify the site-specific parameters. Refer to section Command-Line Parameters for details of the command-line parameters available.

7. With the PI API processes running (checked with apiverify), start the interface interactively using the PISIPowerTG_start script. Check the output from the interface to ensure that the interface is running correctly. At this stage the interface probably will not have any PI points to load, but that should not cause any errors.

8. Press Ctrl-C to stop the interface.

9. Once the interface is running correctly as an interactive process, the main background startup script PISIPowerTG.sh script needs to be setup. Copy the template startup script to create the actual startup script to be used by the interfacecp PISIPowerTG.sh_new PISIPowerTG.sh

10. Alter the command-line parameters near the end of the PISIPowerTG.sh file to match those used in the PISIPowerTG_start script.For example : ./${INTF_NAME} -host=PISERVER1:5450 -ps=TG -id=1 \ -alarm=/lg/scada/dat/his/msgdata.his.1.PI.dat \ -data=/lg/scada/dat/his/measdata.his.1.PI.dat \

-qualcode=/lg/scada/fg/en_US/data_qualities.ini \ > ${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.

17. When the interface is working correctly, copy the sitestart script from the interface directory into the $PIHOME/bin directory. This will start the interface when the pistart script is run.


Chapter 5. 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 isDumpInputFile [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

<...snipped...>

52 28374@VALUE ANALOG_DEFAULT 06-02-2009 14:45:35.000 (1233931535.000) 1.5809 0x00070000 0x00000002


Chapter 6. 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 isDumpAlarmFile [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


Chapter 7. BufStat Utility

The BufStat 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 isBufStat [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 followingBufStat -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 : 0PI Interface for Siemens Spectrum Power TG (Linux)

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 followingBufStat -con XXXXXX

CONNECTED

To use the BufStat in 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 =$?


Chapter 8. Digital States

For more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. 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 point. A digital point 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, TRANSITION

Quality Digital State SetThe 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 Description0 (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 TextOPC 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 Description0 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


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)


Digital States

File Status State SetOne 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”


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 SetSimilar to digital state sets is the system digital state set. This set is used for all points, regardless of type, to indicate the state of a point at a particular time. For example, if the interface receives bad data from the data source, 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.

Chapter 9. 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 AttributeThe 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 SourcesSeveral 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 @ for Alarm Tags, G for Group Alarms and Q for SQC Alarm Tags, 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.


Chapter 10. 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.

This document does not discuss the attributes that configure UniInt or PI Server processing for a PI point. Specifically, UniInt provides exception reporting and the PI Server provides data compression. Exception reporting and compression are very important aspects of data collection and archiving, which are not discussed in this document.

Note: See the UniInt Interface User Manual and PI Server documentation for information on other attributes that are significant to PI point data collection and archiving.

Tag

The Tag attribute (or tag name) 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: * ’ ? ; { } [ ] | \ ` ' "

LengthDepending 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 attribute contains 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 chapter.

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, digital point types 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 command-line 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

Location3 is not used by this interface.

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 MUST be configured with Location4=0.


Location5

Location5 is used to control point debug messages.

Location5 Point Debug messages

0 Disabled

1 Enabled

InstrumentTag

LengthDepending 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.



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 [email protected]

For example:

3534@STATE value or system digital, depending on the quality


PI Point Configuration

5197@ACT_ACC.VAL value only (ignores quality)

7268@VALUE value or system digital, depending on the quality

[email protected] value only (ignores quality)

[email protected] quality priority

[email protected] alarm status

Alarm Message Points (Location2=1) Filter ExpressionInstrumentTag 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 ==Not equal != or <>Less than <Less than or equal <=Greater than >Greater than or equal >=

Numeric

AOR_GROUP Equal = or ==Not equal != or <>

Wildcard string

ENTITY Equal = or ==Not equal != or <>

Wildcard string

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<10 AND AOR_GROUP=SUB*

then the interface would store all alarms that had a priority value less than 10 and also belonged to the AOR_GROUP starting with the letters SUB.

Interface Specific Performance Points (Location2=-1)The InstrumentTag for performance points MUST be empty.

ExDesc

LengthDepending on the version of the PI API and the PI Server, this interface supports an ExDesc attribute whose length is at most 80 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.



1.6.0.2 or higher Below 3.4.370.x 80

Below 1.6.0.2 3.4.370.x or higher 80

Below 1.6.0.2 Below 3.4.370.x 80

Power TG data and quality pointsFor Power TG data or quality points, the ExDesc attribute is used as a comment to store the TG tag name. It is not used by the interface to identify points (that is done with the InstrumentTag attribute), but as a PointId is not very convenient format for people to use, the tag name is included in the PI point configuration to make things easier.

Performance Points

To allow for monitoring of the performance of the interface and to help with troubleshooting, the interface supports a number of interface specific performance points as well as the standard UniInt performance points. For more information to the configuration of the Performance points see the section Interface Diagnostics Configuration.

Scan

By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, a message is written to the pipc.log and the tag is not loaded by the interface. There is one exception to the previous statement.

If any PI point is removed from the interface while the interface is running (including setting the scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the Scan attribute. Two examples of actions that would remove a PI point from an interface are to change the point source or set the scan attribute to 0. If an interface-specific attribute is changed that causes the tag to be rejected by the interface, SCAN OFF will be written to the PI point.

Shutdown

The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the


PI Point Configuration

Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

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

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.

Bufserv and PIBufssIt is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss are utility programs that provide the capability to store and forward events to a PI Server, allowing continuous data collection when the PI Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when the PI Server is shutdown, Bufserv or PIBufss will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface. Disabling Shutdown is recommended when sending data to a Highly Available PI Server Collective. Refer to the Bufserv or PIBufss manuals for additional information.

Chapter 11. Startup Command File

Command-line parameters can begin with a / or with a -. For example, the /ps=M and -ps=M command-line parameters are equivalent.

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

There is no ICU available for Linux interface nodes, so the interface startup script must be edited manually.

A sample startup script PISIPowerTG.sh_new is proved as a template. The sample includes functions to check whether the interface is already running and to redirect the stdout and stderr to the file $PIHOME/dat/PISIPowerTG.out. It is recommended that the changes to the sample script be limited to changing the name of the interface with the INTF_NAME variable (if multiple instances are being used) and the site-specific command-line parameters at the end of the script where the interface is actually started.

Command-line Parameters

Command-line parameters can use either a dash (-) or a slash (/). Because a slash on Linux platforms are used to denote a directory, typically the dash is used instead.

Parameter Description

-alarm=filenameRequired for alarm processing

Specifies the name of the buffer alarm file the interface will read the alarm messages from. To ensure that the interface will be checking the correct location, it is recommended that the absolute path to the file is specified.Example:-alarm=/lg/scada/dat/his/msgdata.his.1.PI.dat



-CacheModeRequired when using disconnected startupDefault: Not Defined

Required for disconnected startup operation. If defined, the -CacheMode startup parameter indicates that the interface will be configured to utilize the disconnected startup feature.

-CachePath=pathOptionalDefault: Not Defined

Used to specify a directory in which to create the point caching files. The directory specified must already exist on the target machine. By default, the files are created in the same location as the interface executable.If the path contains any spaces, enclose the path in quotes.Examples:-CachePath=/opt/piapi/interfaces/CacheFiles-CachePath=/opt/piapi/interfaces/CacheFiles/

Example with space in path name:-CachePath="/opt/piapi/Cache Files/MyFiles"-CachePath="/opt/piapi/Cache Files/MyFiles/"

-CacheSynch=#OptionalDefault: 250 ms

NOTE: Care must be taken when modifying this parameter. This value must be less than the smallest scan class period defined with the -f parameter. If the value of the -CacheSynch parameter is greater than the scan class value, input scans will be missed while the point cache file is being synchronized.The optional -CacheSynch=# startup parameter specifies the time slice period in milliseconds (ms) allocated by UniInt for synchronizing the interface point cache file with the PI Server. By default, the interface will synchronize the point cache if running in the disconnected startup mode. UniInt allocates a maximum of # ms each pass through the control loop synchronizing the interface point cache until the file is completely synchronized.Synchronization of the point cache file can be disabled by setting the value -CacheSynch=0. The minimum synchronization period when cache synchronization is enabled is 50ms Whereas, the maximum synchronization period is 3000ms (3s). Period values of 1 to 49 will be changed by the interface to the minimum of 50ms and values greater than 3000 will be set to the maximum interval value of 3000ms.Default: 250 msRange: {0, 50 – 3000} time in millisecondsExample: -CacheSynch=50 (use a 50ms interval) -CacheSynch=3000 (use a 3s interval) -CacheSynch=0 (do not synchronize the cache)

-data=filenameRequired for data processing

Specifies the name of the buffer data file the interface will read the events from. To ensure that the interface will be checking the correct location, it is recommended that the absolute path to the file is specified.Example:-data=/lg/scada/dat/his/measdata.his.1.PI.dat



-debug=xOptional

The debug parameter specifies a list of debug message types that can be logged to help with troubleshooting the interface. The types areI – InitializationL – Load tagsF – File handlingD – Power TG data processingA – Power TG alarm processingP – PI point processingR – Removing tagsN – New Tag added after initial point loadingQ – Interface quittingX – All of the above (equivalent to ILFDAPRQ)V – verbose (show more detail)The messages will be logged in the PIHOME/dat/pimesslogfile file.For example, to log messages to show the raw values of the events from the data file and the values sent to PI, use the parameter-debug=DP

-ec=#Optional

The first instance of the -ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If the # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, every interface that is running without -ec=# explicitly defined will write to the same I/O Rate point. Either explicitly define an event counter other than 1 for each instance of the interface or do not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called I/O Rate Point.

-host=host:portRequired for Windows and UNIX

The -host parameter is used to specify the PI Home node. Host is the IP address of the PI Server node or the domain name of the PI Server node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the -host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults.

Examples:

The interface is running on an interface node, the domain name of the PI home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid -host parameters would be:-host=marvin-host=marvin:5450-host=206.79.198.30-host=206.79.198.30:5450


Startup Command File


-id=xHighly Recommended

The -id parameter is used to specify the interface identifier.The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See Appendix A Error and Informational Messages for more information.UniInt always uses the -id parameter in the fashion described above. This interface also uses the -id parameter to identify a particular interface instance number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For this interface, use only numeric characters in the identifier. For example,-id=1

-onlyconnectedOptional

When the -onlyconnected parameter given, the interface will only process files when the connection to the PI server is good. If the connection is lost then the interface will stop processing files.By default the interface will process files regardless of the connection status and if the connection is down then the events sent will be buffered by bufserv.The default configuration is recommended when sending data to a collective because even though one PI server may not be available, other members of the collectives should be available to receive the events.

-ps=xRequired

The -ps parameter specifies the point source for the interface. X is not case sensitive and can be any multiple character string. For example, -ps=P and -ps=p are equivalent. The length of X is limited to 100 characters by UniInt. X can contain any character except ‘*’ and ‘?’.The point source that is assigned with the -ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.

-qualcodefile=xRequired for data quality code processing

Specifies the name of the Power TG data qualities definition file. The interface reads the data quality priorities from this file and uses the priorities when processing data quality points (Location2=0, InstrumentTag suffix .QUAL).To ensure that the interface will be checking the correct location, it is recommended that the absolute path to the file is specified.Example:-qualcodefile=/lg/scada/fg/en_US/data_qualities.iniNote: the en_US directory of the above path is the locale of the system. This is likely to be different for systems outside the US. For example, in Mexico the locale is likely to be es_MX.

-renamealarm=xOptional

Specifies the filename that the interface to rename the alarm file to, after it has finished processing it. This is to allow other applications to process the same file. If there is already a file existing with the same name, the interface will wait until the other file has been removed.By default, the alarm file is deleted after the interface has finished processing it.


-renamedata=xOptional

Specifies the filename that the interface to rename the data file to, after it has finished processing it. This is to allow other applications to process the same file. If there is already a file existing with the same name, the interface will wait until the other file has been removed.By default, the data file is deleted after the interface has finished processing it.

-stopstat=digstateor-stopstat

-stopstat only is equivalent to-stopstat="Intf Shut"

OptionalDefault = no digital state written at shutdown.

If -stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI point when the interface is stopped. For a PI3 Server, digstate must be in the system digital state table. . UniInt will use the first occurrence of digstate found in the table.If the -stopstat parameter is present on the startup command line, then the digital state Intf Shut will be written to each PI point when the interface is stopped.If neither -stopstat nor -stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.

Note: When using interfaces in a failover or redundant configuration, the -stopstat parameter should not be used as it would interrupt the data streams for the points, when no data was actually lost.

Examples:-stopstat=shutdown-stopstat="Intf Shut"The entire digstate value must be enclosed within double quotes when there is a space in digstate.

-uht_id=#OptionalRequired when using failover

The -uht_id=# command-line parameter is used to specify a unique ID for interfaces that are run in a redundant mode without using the UniInt failover mechanism. There are several OSIsoft interfaces that are UniInt based and implement their own version of failover. In order for health tag(s) to be configured to monitor a single copy of the Interface, an additional parameter is required. If the -uht_id=# is specified; only health tags with a Location3 value equal to # will be loaded.


Startup Command File

Sample PISIPowerTG.sh File

The following is an example startup script file. The file is based on the PISIPowerTG.sh_new file included in the installation kit. The only section of the script that should be edited is the site-specific command-line parameters near the end of the file.#!/bin/sh# "@(#)PISIPowerTG.sh 1.0.2.11 (24-Apr-2013)"## PI Interface for Siemens Spectrum Power TG## Shell script to start 'PISIPowerTG' as a background process## (C)Copyright OSIsoft, LLC. San Leandro, California 2009-2013## Revision# 1.0.0.0 09-Nov-2009 KJM > Initial Release# 1.0.2.0 24-Apr-2013 KJM > Reorder command-line arguments#

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 1fi

## 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 1fi

## define work directory#WORKDIR=$PIHOME/datecho "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 \ -alarm=/lg/scada/dat/his/msgdata.his.1.PI.dat \ -data=/lg/scada/dat/his/measdata.his.1.PI.dat \ -qualcodefile=/lg/scada/fg/en_US/data_qualities.ini \ > ${WORKDIR}/${INTF_NAME}.out 2>&1 &

exit 0


Chapter 12. 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.


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 ConfigurationBecause 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.


Chapter 13. 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.


Chapter 14. Security

Windows and UNIX

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 Server, it writes a -999 error. See the section Appendix A: Error and Info r mational Messages for additional information on error messaging.

PI Server v3.3 and Higher

Security configuration using piconfigFor 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,PIUsera_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 EditorThe 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.2For 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,proxyaccountpiapimachine,piadmin@quit

In place of piapimachine, put the name of the interface node as it is seen by the PI Server.


Chapter 15. Starting / Stopping the Interface on UNIX

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 runningapiverifyNAME PID TIME %CPU VSZbufserv 2260 00:00:00 0.0 5480bufserv 2261 00:00:00 0.0 7672bufserv 2263 00:00:00 0.0 7672WARNING: multiple instances of bufserv are runningmqmgr 2252 00:00:00 0.0 4356mqsrv 2246 00:00:00 0.0 4360ioshmsrv 2269 00:00:00 0.0 4360iorates 2275 00:00:00 0.0 8640WARNING: 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 directorycd $PIHOME/interfaces/SIPowerTG

3. Run the interface startup scriptPISIPowerTG.shOutput 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.shelse 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.

Sample sitestart and sitestop scripts are included in the install kit and can be copied into the $PIHOME/bin directory.

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 usersu

2. Copy the required PIAPI script from the interface directory to /etc/init.dcp $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 than 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. Use chkconfig to add the links and verify the configuration/sbin/chkconfig --add PIAPI/sbin/chkconfig --list PIAPIThe PIAPI script should be configured to start at run levels 3, 4 and 5.

5. Verify the configuration by running the commandsPIAPI start - start the PI API processesPIAPI status - show that status of the PI API processesPIAPI 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 will produce 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, but the process will not be able to shut down in an orderly manner.


Starting / Stopping the Interface on UNIX

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.

Chapter 16. 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. If the shared memory is full, the PI API will write the data to disk.

The buffering application (bufserv) in turn

bufserv checks the status of the connection to the PI Server

if a connection to the PI Server exists

o bufserv reads the data in the shared memory and sends the data to the PI Server

o if the shared memory is empty then data is available on disk, the data is loaded from the disk into the shared memory

if there is no connection to the PI Server, bufserv is wait for recheck the connection.

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 and be forced to write to disk on every scan. This is inefficient and should be


avoided. The buffering configuration section of this chapter provides guidelines for sizing these memory buffers.

When buffering is enabled, it affects all interfaces connecting to the buffered PI Server. That is, you cannot have a scenario whereby the buffering application buffers data for one interface sending data to a PI Server on an Interface Node but not for another interface sending data to the PI Server 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 TrustPI Buffer Subsystem PIBufss.exe

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. 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 128,000 for UNIX/Linux2,000,000 for Windows

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

MAXFILECOUNT 1 - 2,000,000 100 Maximum number buffer files to be created. (UNIX/Linux platforms only)

PUTSNAPARRAYSIZE 1 - 2,000,000 800 Maximum number of events to be sent as a single block.

MAXTRANSFEROBJS 1 - 2,000,000 1600 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.

Use the MAXFILESIZE and MAXFILECOUNT parameters to control the total amount of disk space that the buffered data files can consume. By default, bufserv can create 100 128MB files, for a total of 12.8 GB of data.

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)


Buffering

LONGPROCNAME 0 - 1 0 If set the PIAPI will use up to 8 characters for the PI server procname identifier. By default, the PIAPI will 4 characters followed by an E.This setting can affect the PI Server trust configuration.

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.

Independent PI ServersThe 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_PLANTBUFSERV2=PI_CORPHQ

PI Servers in a CollectiveWhen 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 PI 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_PRIBUFSERV2=PISERVER_SEC

[REPLICATEDSERVERLIST]REPSERV1=PISERVER_PRIREPSERV2=PISERVER_SEC

Notes for bufserv on Linux

apiverify WarningWhen buffering is enabled, there will be a parent bufserv process running and another bufserv process for each of the PI Servers configured for buffering. 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".

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=PISERVERDSTMISMATCH=3600

[TCP/IP]PORT=5450

[APIBUFFER]BUFFERING=1BUF1SIZE=1048576BUF2SIZE=1048576SENDRATE=100MAXTRANSFEROBJS=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_PRIDSTMISMATCH=3600

[TCP/IP]PORT=5450

[APIBUFFER]BUFFERING=1BUF1SIZE=1048576BUF2SIZE=1048576SENDRATE=100MAXTRANSFEROBJS=5000

[BUFFEREDSERVERLIST]BUFSERV1=PISERVER_PRIBUFSERV2=PISERVER_SEC

[REPLICATEDSERVERLIST]REPSERV1=PISERVER_PRIREPSERV2=PISERVER_SEC


Chapter 17. Interface Diagnostics Configuration

The PI 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 set of points for the measurement data and another 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 a specific keyword. The following is a list of the keywords, the expected PI PointType and a description of the value.

ExDesc Keyword PointType DescriptionDATA_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.


A set of sample interface-specific performance points are included with the interface install kit.

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.

Sample Interface Specific Performance Points

The file SIPowerTG_Interface_Health_Tags.csv including in the install kit contains a set of typical Interface Specific Health Points that can be used to monitor the performance of the interface.

Scan Class Performance Points

This interface does not support Scan Class Performance Points.

All the PI points are updated using unsolicited data from the Power TG system and so Scan Classes are not using within the interface.


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 DescriptionPointSource Equal to -PS from the

interface startup parametersThe PointSource property for the tag is not case sensitive

Location1 Equal to -ID from the interface startup parameters

If there is no -ID found in the list of startup parameters, Location1 must be 0.

Location2 0 Not Used

Location3 Equal to -UHT_ID from the interface startup parameters

Only applicable -UHT_ID=# is specified in the list of 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 this point pertains.

Only applicable to Scan Class points, all other Interface 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 described below

Key Word must be the first thing in the ExDesc and is case sensitive.

Note: This interface does not use scan classes. All points have unsolicited updates. For some health points, scan class zero (0) is used for unsolicited point updates.

Note: This interface does not support event-triggered input points or output points. Therefore, some of the counters below will not be updated.

[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:


Interface Diagnostics Configuration

Fastest Scan Frequency Update frequencyLess than 1 second 1 second

Between 1 and 60 seconds, inclusive

Scan frequency

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.

As this interface does not use scan classes, it will use the update frequency of 1 second.

[UI_DEVSTAT]

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.

[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.

[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. 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 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 log messages.

The interface updates the value of this point every 60 seconds. While the interface is running, the value of this point never decreases.

[UI_POINTCOUNT]The [UI_POINTCOUNT] Health Point counts number of PI tags loaded by the interface. This count includes all input, output, and triggered input tags. This count does NOT include any Interface Health tags or performance points.

The interface updates the value of this point at startup, on change, and at shutdown.

[UI_OUTPUTRATE]After performing an output to the device, this interface writes the output value to the output tag if the tag has a SourceTag. The [UI_OUTPUTRATE] Health Point tracks the number of these values. If there are no output tags for this interface, it writes the System Digital State No Result to this Health Point.

The interface updates this point at the same frequency as the [UI_HEARTBEAT] point. The interface resets the value of this point to zero at each performance summary interval.

This interface does not support output points, so this health point is not required.

[UI_OUTPUTBVRATE]The [UI_OUTPUTBVRATE] Health Point tracks the number of System Digital State values that the interface writes to output tags that have a SourceTag. If there are no output tags for this interface, it writes the System Digital State No Result to this Health Point.


This interface does not support output points and so this health point is not required.

[UI_TRIGGERRATE]The [UI_TRIGGERRATE] Health Point tracks the number of values that the interface writes to event-based input tags. If there are no event-based input tags for this interface, it writes the System Digital State No Result to this Health Point.


This interface does not support event-based input tags, so this health point is not required.



[UI_TRIGGERBVRATE]The [UI_TRIGGERBVRATE] Health Point tracks the number of System Digital State values that the interface writes to event-based input tags. If there are no event-based input tags for this interface, it writes the System Digital State No Result to this Health Point.


This interface does not support event-based input tags, so this health point is not required.

[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.

The ICU allows you to create the point with the suffix “.sc0” and this point will contain the IO rate for all points. Scan class zero (0) is used for unsolicited points, as all points on this interface are unsolicited.

[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.

The ICU allows you to create the point with the suffix “.sc0” and this point will contain the bad value rate for all points. Scan class zero (0) is used for unsolicited points, as all points on this interface are unsolicited.

[UI_SCSCANCOUNT]You can create a [UI_SCSCANCOUNT] 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 Scan Count.sc1) refers to scan class 1, ".sc2" refers to scan class 2, and so on.

A particular scan class's [UI_ SCSCANCOUNT] point tracks the number of scans that the interface has performed.

The interface updates the value of this point at the completion of the associated scan. The interface resets the value to zero at each performance summary interval.

Although there is no "Scan Class 0", the ICU allows you to create the point with the suffix ".sc0". This point indicates the total number of scans the interface has performed for all of its Scan Classes.

[UI_SCSKIPPED]You can create a [UI_SCSKIPPED] 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 Scans Skipped.sc1) refers to scan class 1, ".sc2" refers to scan class 2, and so on.

A particular scan class’s [UI_SCSKIPPED] point tracks the number of scans that the interface was not able to perform before the scan time elapsed and before the interface performed the next scheduled scan.

The interface updates the value of this point each time it skips a scan. The value represents the total number of skipped scans since the previous performance summary interval. The interface resets the value of this point to zero at each performance summary interval.

As all the points for the interface are unsolicited, there are no skipped scans and so this health point is not required.

[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.

The ICU allows you to create the point with the suffix ".sc0", and this point will contain the point count for all the points.

[UI_SCINSCANTIME]You can create a [UI_SCINSCANTIME] 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 Scan Time.sc1) refers to scan class 1, ".sc2" refers to scan class 2, and so on.

A particular scan class's [UI_ SCINSCANTIME] point represents the amount of time (in milliseconds) the interface takes to read data from the device, fill in the values for the tags, and send the values to the PI Server.

The interface updates the value of this point at the completion of the associated scan.

This health point is not supported for unsolicited updates and so is not required for this interface.



[UI_SCINDEVSCANTIME]You can create a [UI_SCINDEVSCANTIME] 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 Device Scan Time.sc1) refers to scan class 1, ".sc2" refers to scan class 2, and so on.

A particular scan class's [UI_ SCINDEVSCANTIME] point represents the amount of time (in milliseconds) the interface takes to read data from the device and fill in the values for the tags.

The value of a [UI_ SCINDEVSCANTIME] point is a fraction of the corresponding [UI_SCINSCANTIME] point value. You can use these numbers to determine the percentage of time the interface spends communicating with the device compared with the percentage of time communicating with the PI Server.

If the [UI_SCSKIPPED] value is increasing, the [UI_SCINDEVSCANTIME] points along with the [UI_SCINSCANTIME] points can help identify where the delay is occurring: whether the reason is communication with the device, communication with the PI Server, or elsewhere.

The interface updates the value of this point at the completion of the associated scan.

This health point is not supported for unsolicited updates and so is not required for this interface.

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.

Sample UniInt Health Points

The file SIPowerTG_UniInt_Health_Tags.csv including in the install kit contains a set of typical UniInt Health Points that can be used to monitor the performance of the interface. Two sets of points are included to support a pair of failover interfaces.

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 UNIX

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 ServerCreate an I/O Rate Tag with the following point attribute values.

Attribute ValuePointSource LAB

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeFor the following examples, assume that the name of the I/O Rate PI point is SIPowerTG001 on the PI Server PISERVER01.

1. Edit/Create a file called iorates.ini 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.

Within the iorates.ini file define the [PISERVERS] section to contain a list of the PI Servers that iorates will access and a section names for each of the PI Servers, which will contain the iorates points for that PI Server and their corresponding event counter index number and corresponds with the /ec=x parameter in the startup command file.

The event counter index 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. Each event counter should be unique.

For example,[PISERVERS]SERVER1=PISERVER01

[PISERVER01]IOTAG1=SIPowerTG001,1

For more details, refer to the PIHOME/help/iorates.txt file and the sample PIHOME/dat/iorates.ini file.

2. Set the /ec=x parameter on the startup command file of the interface to match the event counter in the iorates.ini 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

Determine that the shared memory server and the I/O Rates Monitor are running with either the apiverify script or 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 Utility Interface for complete information on using the ISU. PI Interface Status Utility Interface runs only on a PI Server Node.

Note: The PI Interface Status Utility Interface – and not this interface – is responsible for updating the ISU tag. So, make sure that the PI Interface Status Utility Interface 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/pimesslogfile at the following times.

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

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

If the UniInt -dbUniInt parameter is found in 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

Message Invalid debug option [?] - ABORTING

Cause A debug option given in the -debug= argument is not recognized by the interface.

Resolution Check that all the debug options listed are valid.

Message Unable to locate directory "????" - ABORTING

Cause The directory specified by either the -data= or -alarm= argument was not found.

Resolution Verify that the directory that will contain the either the data input file or alarm input file exists.

Message "????" is not a directory - ABORTING

Cause The directory specified by either the -data= or -alarm= argument was located, but it not a valid directory.


Resolution Verify that the directory that will contain the either the data input file or alarm input file exists.

Message No read/write permission for data directory "????" - ABORTING

Cause 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.

Resolution Verify that the interface is being run by the correct user, and that user has read/write permissions for the directory.

Message Cannot rename data file when data file not defined - ABORTING

Cause 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.

Resolution Either remove the -renamedata parameter or set the -data parameter, depending on the requirements for the interface.

Message Cannot rename alarm file when alarm file not defined - ABORTING

Cause 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.

Resolution Either remove the -renamealarm parameter or set the -alarm parameter, depending on the requirements for the interface.

Message Neither -data= or -alarm= arguments specifiedAt least one must be specified - ABORTING

Cause The interface can process either data input files or alarm input files or both. The interface will not run if neither of these arguments is defined.

Resolution Add either a -data or -alarm parameter, or both.

Message -data= and -alarm= must not refer to the same file - ABORTING

Cause The -data and -alarm arguments refer to the same file. As the files have different formats, they cannot be the same file.

Resolution Correct either the -data or -alarm argument.

Loading PI points

Message PITag ?????? (?) - Interface does not support periodic scan pointsAll data points must have Location4=0

Cause 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.

Resolution Edit the PI point to set the Location4 attribute to zero (0).


Message PITag ?????? (?) - Unable to allocate dev_struct

Cause The interface was not able to allocate memory to store the configuration of the given point.

Resolution Free up memory on the interface node and restart the interface.

Message PITag ?????? (?) - Invalid interface-specific performance pointExDesc keyword is empty

Cause An interface-specific performance point (Location2=-1) has an empty ExDesc attribute.

Resolution Edit the PI point to include the required performance value keyword in the ExDesc. See Interface Specific Performance Points for a list of valid keywords.

Message PITag ?????? (?) - Invalid interface-specific performance pointUnrecognized ExDesc keyword "???"

Cause The keyword in the ExDesc of an interface-specific performance point (Location2=-1) does not match an of the valid keywords.

Resolution Edit the PI point to include the required performance value keyword in the ExDesc. See Interface Specific Performance Points for a list of valid keywords.

Message PITag ?????? (?) - Invalid interface-specific performance pointPointType mismatch for the given ExDesc keyword

Cause 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.

Resolution Check to ensure that the PointType is the same as those listed in the Interface Specific Performance Points section for the given keyword.

Message PITag ?????? (?) - Invalid PI PointType for a measurement data point

Cause A measurement data point (Location2=0) PointType can be float64, float32, float16, int32, int16 or digital. It cannot be a string type.

Resolution Check that the PI point is configured with a valid PointType for a measurement data point.

Message PITag ?????? (?) - Invalid InstrumentTag for data pointInstrumentTag is empty

Cause 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.

Resolution Ensure that the InstrumentTag for the point has been properly defined.

Message PITag ?????? (?) - Invalid InstrumentTag attribute "???"Must be in the format [email protected] where MEASID is an integer value

Cause A measurement data point (Location2=0) must have the InstrumentTag defined with the format [email protected], where the MEASID is an integer value and matches the Power TG point id of the required point.



Error and Informational Messages

Message PITag ?????? (?) - Invalid InstrumentTag attribute "???"Must be in the format [email protected] where FIELD is NOT blank

Cause A measurement data point (Location2=0) must have the InstrumentTag defined with the format [email protected], where the FIELD is the name of the field required from the Power TG point.

Resolution 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.

Message PITag ?????? (?) - Invalid InstrumentTag attribute "???"Unrecognized TYPE "???"

Cause A measurement data point (Location2=0) must have the InstrumentTag defined with the format [email protected]. The .TYPE is optional, but if defined it must match the valid keyword types given in the InstrumentTag section of the manual.


Message PITag ?????? (?) - Invalid .QUAL typeQuality code definitions are not defined

Cause 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.

Resolution Check that the -qualcodefile= argument has been properly defined and that the quality codes were loaded when the interface was started.

Message PITag ?????? (?) - Invalid digital set for quality prioritiesDigital set must have at least ?? states to store the defined quality priorities

Cause 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.

Resolution 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.

Message PITag ?????? (?) - Invalid PointType for an alarm PI pointan alarm point MUST be a string PI point

Cause An alarm point (Location2=1) must have a string PointType.

Resolution Check the configuration of the PI point.

Message PITag ?????? (?) - Unable to parse filter expression from InstrumentTag

Cause 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.

Resolution Check the configuration of the point. Refer to the Point Attribute - InstrumentTag section for more information of the filter expression syntax.

Message PITag ?????? (?) - Invalid value for Location2-1=perf, 0=data, 1=alarm

Cause The value of Location2 is not valid.

Resolution 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

Message Unable to remove input file xxxxx - ABORTINGerrno=? - ???????????????

Cause The interface failed to remove the file after processing and has aborted.

Resolution 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.

Message Unable to rename xxxxx to yyyyyyyyyy already exists - Will retry every 2 seconds

Cause 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.

Resolution 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.

Message Unable to rename xxxxx to yyyyyerrno=? - ?????????????Will attempt to delete yyyyy

Cause Unable to rename the current input file. The previous file does not exist, but some other error is causing the rename to fail.

Resolution The interface will delete the current file instead of renaming so that processing can continue.

Message Input data file invalid (does not start with 0x01 0x02)

Cause 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.

Resolution Check that the interface is reading the correct file defined by the -data parameter. Use the DumpInputFile utility to check the contents of the file.

Message TG EVENT ?? > INVALID > ???????????????????????

Cause 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.

Resolution Use the DumpInputFile utility to check the contents of the file against the event logged by the interface.

Message TG EVENT ?? > INVALID > ???????????????????????Event timestamp too far into the future


Error and Informational Messages

Cause The interface found an event with a timestamp that was too far into the future to be valid.

Resolution This could be caused by incorrectly configured time zones, or if the clocks within the system have drifted by more than 5 minutes.

Message Forced to exit before data file had finished processing

Cause 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.

Resolution 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

Message Input alarm file invalid (does not start with 0x03 0x04)

Cause 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.

Resolution Check that the interface is reading the correct file defined by the -alarm parameter.

Message TG ALARM ?? > INVALID > ???????????????????????

Cause 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.

Resolution Use the DumpAlarmFile utility to check the contents of the file against the alarm message logged by the interface.

Message TG ALARM ?? > INVALID > ???????????????????????Event timestamp too far into the future

Cause The interface found an alarm message with a timestamp that was too far into the future to be valid.

Resolution This could be caused by incorrectly configured time zones, or if the clocks within the system have drifted by more than 5 minutes.

Message Forced to exit before alarm file had finished processing

Cause 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.

Resolution 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.

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) and is going active.

http://techsupport.osisoft.com/


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.

Message No LATEST_TIMESTAMP point configured, so all events in the file will be sent to PI

Cause 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.

Resolution To reduce the chance of Out-Of-Order events, configure LATEST_TIMESTAMP Performance PI points.

Message Not connected to PI, so unable to read latest timestamp to reduce OOO events

Cause 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.

Resolution N/A

Message Reading LATEST_TIMESTAMP point. pisn_getsnapshotx(??) returned ??????

Cause 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.

Resolution Use the PI error message to resolve the pisn_getsnapshotx() error.

Message LATEST_TIMESTAMP point returned istat=???, so all events in the file will be sent to PI

Cause 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.

Resolution Check the LATEST_TIMESTAMP PI point is being updated correctly.

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 Windows and UNIX Descriptions of system and PI errors can be obtained with the PISDKUtility , or with the pidiag utility

Windows: %PIHOME%\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)

Binary values are in are little endian format.


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

Binary values are in are little endian format.

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.


On the “Data Warehouse” tab, the data entry fields for a PI server are interpreted as follows:

LongnameThis is the name that will be presented to the Power TG operator in alarm messages and status display for this server.

RTDB NameThis 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\<rtdb-name>” where the “<rtdb-name>” portion of the path is substituted for this name.

AOR GroupThis 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 PriorityThis the priority at which alarms relating to the status of the archiving will be presented.

ComputerThis is the name of the computer or collective used for the PI database.


InstanceThis is the “Point Source” name used in the PI database. If not specified, “TG” is used.

Database TypeChoose “PI” for a PI database.

DatabaseIf 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 IDThis 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.


Setting up a PI Archive on the Power TG System

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.

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:

PeriodicThis 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.

SpontaneousThis 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 QualityThis 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


Setting up a PI Archive on the Power TG System

quality. The generated tag has the syntax “<entity-name>@OPCQQSSSS” where “<entity-name>” 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 QualityThis 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 “<entity-name>@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 QualityThis 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 “<entity-name>@OPC_SPCL” and is a Digital tag using the state set “TG_QUAL_SPECIAL”.

Create PI Tags for Analog StateThis 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 “<entity-name>@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 SymbolThis 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 “<entity-name>@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 in 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 may 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.

Appendix E. Terminology

To understand this interface manual, you should be familiar with the terminology used in this document.

BufferingBuffering 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 BufferingIf 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 Servers however it does not guarantee identical archive records since point compressions attributes could be different between PI Servers. With this in mind, OSIsoft recommends that you run PIBufss instead.)

ICUICU refers to the PI Interface Configuration Utility. The ICU is the primary application that you use to configure 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 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.

ICU ControlAn ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces have an associated ICU Control.

Interface NodeAn interface node is a computer on which

the PI API and/or PI SDK are installed, and

PI Server programs are not installed.

PI APIThe 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 CollectiveA 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.

PIHOMEPIHOME refers to the directory that is the common location for PI 32-bit client applications.

A typical PIHOME on a 32-bit operating system is C:\Program Files\PIPC.

A typical PIHOME on a 64-bit operating system is C:\Program Files (x86)\PIPC.

PI 32-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME.

For example, files for the 32-bit Modbus Ethernet Interface are in

[PIHOME]\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PIHOME64PIHOME64 is found only on a 64-bit operating system and refers to the directory that is the common location for PI 64-bit client applications.

A typical PIHOME64 is C:\Program Files\PIPC.

PI 64-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.

For example, files for a 64-bit Modbus Ethernet Interface would be found in

C:\Program Files\PIPC\Interfaces\ModbusE.

This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64 directory path. For example, ICU files in [PIHOME]\ICU.

PI Message LogThe PI message log is the file to which OSIsoft interfaces based on UniInt 4.5.0.x and later write informational, debug and error messages. When a PI interface runs, it writes to the local PI message log. This message file can only be viewed using the PIGetMsg utility. See the UniInt Interface Message Logging.docx file for more information on how to access these messages.

PI SDKThe 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 NodeA PI Server Node is a computer on which PI Server programs are installed. The PI Server runs on the PI Server Node.


PI SMTPI 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 interface node.

Pipc.logThe pipc.log file is the file to which OSIsoft applications write informational and error messages. When a PI interface runs, it writes to the pipc.log file. The ICU allows easy access to the pipc.log.

PointThe 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.

ServiceA 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.


Appendix F. Technical Support and Resources

You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site:

http://techsupport.osisoft.com (http://techsupport.osisoft.com)

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

Product name, version, and/or build numbers

Computer platform (CPU type, operating system, and version number)

The time that the difficulty started

The log file(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table below to find the most appropriate number for your area. Dialing any of these numbers will route your call into our global support queue to be answered by engineers stationed around the world.

Office Location Access Number Local Language OptionsSan Leandro, CA, USA 1 510 297 5828 English

Philadelphia, PA, USA 1 215 606 0705 English

Johnson City, TN, USA 1 423 610 3800 English

Montreal, QC, Canada 1 514 493 0663 English, French

Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese

Frankfurt, Germany 49 6047 989 333 English, German

Manama, Bahrain 973 1758 4429 English, Arabic

Singapore 65 6391 181186 021 2327 8686

English, MandarinMandarin

Perth, WA, Australia 61 8 9282 9220 English



Support may be provided in languages other than English in certain centers (listed above) based on availability of attendants. If you select a local language option, we will make best efforts to connect you with an available Technical Support Engineer (TSE) with that language skill. If no local language TSE is available to assist you, you will be routed to the first available attendant.

If all available TSEs are busy assisting other customers when you call, you will be prompted to remain on the line to wait for the next available TSE or else leave a voicemail message. If you choose to leave a message, you will not lose your place in the queue. Your voicemail will be treated as a regular phone call and will be directed to the first TSE who becomes available.

If you are calling about an ongoing case, be sure to reference your case number when you call so we can connect you to the engineer currently assigned to your case. If that engineer is not available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, click Search Support.

Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions, Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

[email protected]

When contacting OSIsoft Technical Support by email, it is helpful to send the following information:

Description of issue: Short description of issue, symptoms, informational or error messages, history of issue

Log files: See the product documentation for information on obtaining logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.

Using OSIsoft’s Online Technical Support, you can:

Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)

View or edit existing OSIsoft calls that you entered

View any of the calls entered by your organization or site, if enabled

See your licensed software and dates of your Service Reliance Program agreements


mailto:[email protected]

Remote Access

From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.

OSIsoft Support Engineers may remotely access your server in order to provide hands-on troubleshooting and assistance. See the Remote Access page for details on the various methods you can use.

On-site Service

From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.

OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.

The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center on the Technical Support Web site.

The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).

System Manager Resources include tools and instructions that help you manage: Archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, PI System sizing and configuration, PI trusts for interface nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.

You are eligible to download or order any available version of a product for which you have an active Service Reliance Program (SRP), formerly known as Tech Support Agreement (TSA). To verify or change your SRP status, contact your Sales Representative or Technical Support (http://techsupport.osisoft.com / ) for assistance.

OSIsoft Virtual Campus (vCampus)

The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that focuses on PI System development and integration. The Web site's annual online subscriptions provide customers with software downloads, resources that include a personal development PI System, online library, technical webinars, online training, and community-oriented features such as blogs and discussion forums.

OSIsoft vCampus is intended to facilitate and encourage communication around PI programming and integration between OSIsoft partners, customers and employees. See the



Technical Support and Resources

OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or contact the OSIsoft vCampus team at [email protected] for more information.

http://vCampus.osisoft.com/

Appendix G. 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.

21-Apr-2011 KMillar Version 1.0.0.0 Revision C - Version 1.0.0.0 of the interface is only compatible with PIAPI 1.6.1.11

23-Nov-2011 KMillar Version 1.0.1.0 - Updated Vendor Software Required with “Power TG software must be version 8.3.SP1 or greater.” and updated PIAPI compatibility notes.

19-Apr-2013 KMillar Version 1.0.2.0 - Update to skeleton 3.0.36


Documents

PI Interface for Siemens Spectrum Power TG (Linux)cdn.osisoft.com/interfaces/3305/PI_SIPowerTG_LNX_1.0… · Web viewThe PI Interface for Siemens Spectrum Power TG ... {SCRIPT}