PI Interface for ACS Prism. Version x

Transcription

1 PI Interface for ACS Prism Version x

2 OSIsoft, LLC 777 Davis St., Suite 250 San Leandro, CA USA Tel: (01) Fax: (01) Web: OSIsoft Australia Perth, Australia OSIsoft Europe GmbH Frankfurt, Germany OSIsoft Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal & Calgary, Canada OSIsoft, LLC Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil OSIsoft France EURL Paris, France PI Interface for ACS Prism Copyright: 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 RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Published: 01/2014

3 Table of Contents Chapter 1. Introduction... 1 Reference Manuals... 1 Supported Operating Systems... 2 Supported Features... 2 Diagram of Hardware Connection... 4 Chapter 2. Principles of Operation... 7 Chapter 3. Installation Checklist... 9 Data Collection Steps... 9 Interface Diagnostics Advanced Interface Features Chapter 4. Interface Installation on UNIX Naming Conventions and Requirements Interface Directories PIHOME Directory Interface Installation Directory PI API Installation on a Linux machine Interface Installation Procedure Chapter 5. PIPrismRTChng Parameters Chapter 6. Digital States Chapter 7. PointSource Chapter 8. PI Point Configuration Point Attributes Tag PointSource PointType Location Location Location Location Location InstrumentTag ExDesc Scan Shutdown UserInt Output Points PI Interface for ACS Prism iii

4 Table of Contents Trigger Method 1 (Recommended) Trigger Method Chapter 9. Startup Command File Command-line Parameters Sample piprism.sh File Chapter 10. Interface Node Clock LINUX Chapter 11. Security Linux Chapter 12. Starting / Stopping the Interface on LINUX Interface Startup Script Interface Stop Script Automatic interface startup and shutdown Automatic PIAPI startup on a reboot Terminating Background Processes Chapter 13. Buffering Linux Interface Nodes How Buffering Works Buffering and PI Server Security Configuring PI API Buffer Server (bufserv) Manually Performance Settings BufServ and n-way buffering Notes for bufserv on Linux Chapter 14. Interface Diagnostics Configuration Scan Class Performance Points Configuring Performance Points on LINUX Interface Health Monitoring Points I/O Rate Point Principles of Operation Configuration Troubleshooting Interface Status Point Appendix A. Error and Informational Messages Message Logs Messages System Errors and PI Errors Appendix B. Upgrading the Interface Appendix C. Terminology Appendix D. Technical Support and Resources iv

5 Appendix E. Revision History PI Interface for ACS Prism v

6

7 Chapter 1. Introduction This document describes the PI Interface for ACS Prism, also known as the PI-Prism interface. The interface provides bi-directional transfer of Status and Telemetry data between the Advanced Control System s Precision Real-Time Information System Manager (PRISM ) system and the OSIsoft s PI system. In addition the interface supports outputs of Alarm data to Status and Telemetry points. Version 2.x of the interface supports ACS PRISM versions 9.x & 10.x running on Red Hat Linux systems only. As of version 2.1.x.x, the interface supports RT change events. This allows rapid changes in status points to be captured. These changes might otherwise be missed when using scan based points. For older ACS PRISM systems running on the HP-UX Operating System, the older 1.x version of the interface must be used to transfer data to and from the PI system. Note: ACS must be contacted prior to selling this interface to any new customer. Reference Manuals OSIsoft PI Server manuals PI API Installation Instructions manual UniInt Interface User Manual Vendor PRISM Database User s Manual PI Interface for ACS Prism 1

8 Introduction Supported Operating Systems Platforms 32-bit application 64-bit application Red Hat ES4 32-bit OS Yes No 64-bit OS No No Red Hat ES5 32-bit OS Yes No 64-bit OS No No The interface is designed to run on the above-mentioned Linux operating systems. Because it is dependent on vendor software, newer platforms may not yet be supported. The interface must run on the same platform as the ACS Prism software and so is dependent on the OS version supported by the ACS Prism system. The interface is compatible with ACS Prism 9.x and 10.x systems. Please contact OSIsoft Technical Support for more information. Supported Features Feature Interface Part Number Auto Creates PI Points Point Builder Utility ICU Control PI Point Types Sub-second Timestamps Sub-second Scan Classes Automatically Incorporates PI Point Attribute Changes Exception Reporting Outputs from PI Inputs to PI: Supports Questionable Bit Supports Multi-character PointSource Maximum Point Count Uses PI SDK PINet String Support Support PI-IN-ACS-PRM-LX32 No No No digital / int16 / int32 / float64 / float32 / float16 Yes Yes Yes Yes Yes Scan-based / Unsolicited / Event Tags No Yes No No No * Source of Timestamps Interface for scan-based events. Prism system for RTChange unsolicited events. History Recovery * UniInt-based * Disconnected Startup * SetDeviceStatus Failover No Yes Yes Yes No 2

9 Feature * Vendor Software Required on Interface Node Vendor Software Required on Foreign Device Vendor Hardware Required Additional PI Software Included with interface Device Point Types Serial-Based interface Support Yes No No No Telemetry, Status and Alarm No * See paragraphs below for further explanation. Source of Timestamps The scan-based events are time stamped by the interface when the scan occurs. The timestamp for RT change events (unsolicited) are provided by the Prism system. Both time sources are adjusted to allow for time differences between the Prism system and the PI server system time. Note: The timestamp returned by the RTChange mechanism can be generated by field devices. If the time within the device is incorrect, it is NOT possible for the interface to correct for this difference. Normally, these field devices would be synchronized with the ACS Prism system and so this will not cause an issues. UniInt-based UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features. The UniInt Interface User Manual is a supplement to this manual. Disconnected Start-Up The ACSPrism 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. SetDeviceStatus Functionality has been added to UniInt and later to support health tags. The ACSPrism 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: PI Interface for ACS Prism 3

10 Introduction 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. Vendor Software Required The PI Interface for ACS Prism must to run directly on the ACS Prism system. Device Point Types The PI Interface for ACS Prism is capable of accessing the following PRISM point types Telemetry (Read/Write) Status (Read/Write) Alarm (Write) Diagram of Hardware Connection The following is an overview of architecture of how the PI Prism interface works to read and write data between an ACS Prism system and a PI server. 4

11 PI Interface for ACS Prism 5

12

13 Chapter 2. Principles of Operation The PI Interface for ACS Prism (also known as the PI-Prism interface) operates as both a scan-based and unsolicited interface. Scan-based points use the ACS Prism API to communicate with the Prism system and use the standard UniInt-based functionality. Unsolicited points are updated using a second process that captures the raw RT change events and transfers these events to the interface via data files. The interface provides access to the following Prism point types. Telemetry (Read / Write ) Status (Read / Write ) Alarm (Write ) During startup the interface initializes the Prism API and retries every 60 seconds until successful. It then instantiates each point defined that matches the PointSource and Interface copy (location1) specified on the command line. During this phase the interface verifies that the following parameters are valid and rejects any invalid points: Verifies that location3 (Prism Point Type) specifies either Status Read(0), Status Write(1), Telemetry Read(2), Telemetry Write(3), Status Alarm(6) or Telemetry Alarm(7) Verifies that ATTRIBUTE and CATEGORY are specified via the InstrumentTag field. All but Status and Telemetry Alarm type tags require both. Only CATEGORY is required for Alarm types. Verifies that the Attribute and Category are valid based on the Prism Point Type. For example: The CV attribute is valid for Telemetry tags but not Status tags. Verifies that the data type of the Prism attribute and the data type are compatible. Refer to the sections below related to the various PI point definition parameters for more details. For input points, there are two types of updates. All input points loaded by the interface are scan-based and are periodically read using calls to a Prism API library. The events are time stamped as the values are read from the Prism system and sent the PI server. Unsolicited events are initially captured by a second process called PIPrismRTChng. This process writes the timestamp, Prism point ID (station, category, point number and point type) and value to a text-based data file. Periodically, it checks to see if the PI-Prism interface has finished processing any previous RT change data files, and if the PI-Prism interface is available then it renames the current data file so the interface can process the new file. To process the data file, the PI-Prism interface reads the data, finds any PI points configured for that particular Prism point and sends the values to the point. Because this is a changed based mechanism, it is necessary for the interface to explicitly read the current values of the RT PI Interface for ACS Prism 7

14 Principles of Operation change points on startup, or else the PI point would not show the correct value until the point value changed. The timestamps for both scanned and change driven events are based on the PI Server time. If there is a difference between the PI Server and the Prism system, the PI Server is used as the master time source. Timestamps for scanned events use the PI Server time. The timestamps received from the Prism system for the change-driven events have an offset applied to align them with the PI Server time before they are written to the PI Server. For output points, the data value is converted to the required Prism data type prior to calling the Prism API function. If an error is indicated via the return status, the db_errno variable is checked to determine the exact nature of the error. The error status is then translated into one of the system digital states defined for this interface. If the status is good, the data is then converted into the appropriate PI data type (Inputs only) and the status for the point is set to good. 8

15 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. 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. If you are running the interface on an interface node, edit the PI Server s Trust Table to allow the interface to write data. 3. Check the computer s time zone properties. An improper time zone configuration can cause the PI Server to reject the data that this Interface writes. 4. Extract the PI API install kit. As the root user, run the pi.install installation script. The Enter an existing user name for PI API must be set to acs (not the default piadmin). 5. After the PIAPI installation is complete, as the acs user, start the PI API processes with pistart and use apisnap to verify the connection to the PI server. 6. Extract the interface installation kit into the $PIHOME directory. 7. In the interface directory, run the link_all.sh script to compile and link the piprism and PIPrismRTChng executables. 8. In the interface directory, use the template startup script piprism.sh_new to create the startup script piprism.sh for the interface and edit the command-line parameters. Essential startup parameters for this Interface are: Point Source (-ps=x) Interface ID (-id=#) PI Server (-host=host:port) Scan Class(-f=period,offset) Start System Digital State (-ds=nnn) RTChange data file (-rtchange=xxxx) - required for unsolicited values PI Interface for ACS Prism 9

16 Installation Checklist For details on the command-line arguments, refer to the Command-line Parameters section. 9. If RTChange points are used, the parameters required to configure PIPrismRTChng are in the ConfigFile data file. Essential parameters for PIPrismRTChng are: Location of the RTChange data files (PIDataDirectory=) Name template of the temporary data files (PIDataFileName=) Name of file to be transferred to the interface (PITransferFileName=) Send transfer file time enable (EnableTimer1=true) Send transfer file period (Timer1=) RTChange Device ID (Device=) 10. If you will use digital points, define the appropriate digital state sets. 11. Add the Prism error states to the System Digital State Set. See the System Digital State Set section for details. 12. Build input tags and, if desired, output tags for this Interface. Important point attributes and their use are: Location1 specifies the Interface instance ID. Location2 specifies the Prism point number. Location3 specifies the Prism point type. Location4 specifies the scan class. Location5 specifies the station ID. InstrumentTag specifies the Prism point category and attribute. 13. Start the Interface interactively and confirm its successful connection to the PI Server without buffering. 14. Confirm that the Interface collects data successfully. 15. Stop the Interface and the PIAPI processes (pistop) 16. Configure a buffering application (bufserv). It is recommended that the following parameters be edited in the piclient.ini BUFFERING=1 BUF1SIZE= BUF2SIZE= SENDRATE=10 MAXTRANSFEROBJS=5000 This will optimize the throughput for buffering and is recommended by OSIsoft. 17. Start the PIAPI and buffering application and the Interface (pistart). 18. 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. 19. Replace the sitestart and sitestop scripts in the $PIHOME/bin directory with the scripts included in the interface directory. 20. Edit the Linux startup scripts so that the pistart script will be run on startup. 21. Restart the Interface Node and confirm that the Interface and the buffering application restart. 10

17 Interface Diagnostics 1. Configure Scan Class Performance points. 2. Configure UniInt Health Monitoring points 3. Configure the I/O Rate points and the $PIHOME/dat/iorates.ini file. 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. PI Interface for ACS Prism 11

18

19 Chapter 4. Interface Installation on UNIX The interface is installed on the Prism machine. It is also a good idea to install and run Bufserv on the interface node. 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 installed 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 UNIX platform. PI API Buffer Server is the only type of buffering available for the UNIX platform. The interface should be configured to start and stop with the PI API. Site-specific scripts can be edited for this purpose, as described in the installation procedure below. The PI API can also be configured to start and stop automatically when the system is shut down or rebooted. Procedures for automatic startup and shutdown of PI or the PI API are platform specific. Naming Conventions and Requirements In the installation procedure below, it is assumed that the name of the interface executable is piprism and that the startup command file is called piprism.sh. Note: Linux 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 piprism1 and piprism1.sh for interface number 1, piprism2 and piprism2.sh for interface number 2, and so on. Note: The scripts provided with the interface use the process name to locate the process PID. Therefore, each instance of the interface executable file running MUST have a unique name. Note: Linux can truncate the names of the processes. To ensure that the scripts work properly, the executable filenames should be no more than 15 characters long. PI Interface for ACS Prism 13

20 Interface Installation on UNIX 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 piprism1, piprism2, piprism3, etc. executables, in the directory: $PIHOME/Interfaces/piprism 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 piprism1, piprism2, piprism3, etc., in the directories: $PIHOME/Interfaces/piprism1 $PIHOME/Interfaces/piprism2 $PIHOME/Interfaces/piprism3 and so on. Create the installation directories as necessary. Note: Because of the requirements of the start/stop scripts to identify the running processes, the interface executable files MUST have unique names, even when located in different directories. PI API Installation on a Linux 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 the ACS Prism system, the owner of the PI API and interfaces must be the acs user, or a user with sufficient priviledges to access the Prism database. These instructions assume that the owner the PI API and interface is acs and the PI API will be installed in the /opt/piapi directory. If the user is not to be acs, 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. su mkdir /opt/piapi chown acs /opt/piapi exit 14

21 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 acs user. For the bash shell, add the following to the ~/.bash_profile file # PI API settings export PIHOME=/opt/piapi export PATH=$PATH:$PIHOME/bin: For the csh shell (or tcsh), add the following to the ~/.cshrc file # PI API settings setenv PIHOME /opt/piapi setenv PATH ${PATH}:${PIHOME}/bin: 4. Copy the PI API installation kit piapilinux-tar_#####_.gz onto the Prism machine using FTP or something similar. Put the file into the /opt/piapi directory. 5. Extract the contents of the piapilinux-tar_#####_.gz installation file. cd $PIHOME tar xzvf piapilinux-tar_#####_.gz This will create a directory called build which contains the PI API installation files. 6. Run the PI API installation script pi.install as root cd $PIHOME/ build su sh./pi.install Answer the prompts for your system Enter an existing user name for PI API [piadmin]? acs Please Enter the Node Name of the Default PI Home Node: PISERVER1 Is PISERVER1 a PI v3.x (UNIX, NT) system? [Y] or N Y << installation messages>> Check the installation messages and verify that there were no errors. Change back to the acs user exit 7. Start the PI API processes cd $PIHOME/bin pistart 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 of the 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 not start." fi PI Interface for ACS Prism 15

22 Interface Installation on UNIX 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, and no suffix is added to the interface name. To install multiple copies of the interface, the executable file and the various scripts need to renamed and modified to include a number on the end of the interface name. Refer to the Naming Conventions and Requirements section above. Note: The installation kit does NOT include the piprism and PIPrismRETChange executable files. This is because of changes to the libraries used by the interface in the different versions of the ACS Prism system. Therefore it is necessary to compile and link the executables on the system that will be running the programs. This is done in step 4 below. Note: If upgrading to a new version of the interface over an existing installation, please refer to Appendix B: Upgrading the Interface for additional steps. 1. Copy the ACSPrism_x.x.x.x.tar.gz file to the $PIHOME directory 2. Extract the contents of the ACSPrism_#.#.#.#.tar.gz file cd $PIHOME tar xzvf ACSPrism_#.#.#.#.tar.gz This will create the $PIHOME/Interfaces/piprism directory for the interface if it does not already exist. 3. Change to the interface directory cd $PIHOME/Interfaces/piprism 4. Run the script link_all.sh to build the piprism and PIPrismRTChng executable files. link_all.sh Note: The message /home/acs/scripts/standard_link[447]: mib: not found is expected and does not cause any problems. Check that the piprism and PIPrismRTChng executables have been created in the interface directory. 5. Verify that the interface will run by checking the interface version piprism -v 6. If you will use digital points, define the appropriate digital state sets. Ensure the required system digital states have been created. See the section Digital States for details. 16

23 7. To be able to check when the interface is running as background process, add the interface name piprism (and PIPrismRTChng if used) to the end of the $PIHOME/bin/apiprocs file. 8. Edit the piprism_start script to specify the site-specific parameters. Refer to section Command-Line Parameters for details of the command-line parameters available. 9. With the PI API processes running (checked with apiverify), start the interface interactively using the piprism_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. 10. Press Ctrl-C to stop the interface. 11. Once the interface is running correctly as an interactive process, the main background startup script piprism.sh script needs to be setup. Copy the template startup script to create the actual startup script to be used by the interface cp piprism.sh_new piprism.sh 12. Alter the command-line parameters near the end of the piprism.sh file to match those used in the piprism_start script. For example:./${intf_name} -host=piserver1:5450 -ps=prism -id=1 \ -ds=184 -rtchange=data/rtchange.dat \ -f=2 -f=5 -f=10 \ -stopstat \ > ${WORKDIR}/${PROG}.out 2>&1 & Note the backslash (\) continuation characters on the command-line. Failing to include these will cause problems. 13. With the PI API processes running, start the piprism.sh script. Use apiverify to check whether the process is running. Check the $PIHOME/dat/piprism.out and $PIHOME/dat/pimesslogfile files to check the status of the interface. 14. To stop the interface when it is running as a background process, use the piprism_stop script. At this point, the interface is installed and can be run. PI Points should now be configured to collect the necessary data. If the PIPrismRTChng process is to be used to capture real-time changes from the Prism system, refer to Chapter 5: PIPrismRTChng for the configuration and scripts. The final step in the setup is to configure the interface to start and stop automatically when the system is started and stop. The steps for this are detailed in Chapter 12: Starting / Stopping the Interface on LINUX. PI Interface for ACS Prism 17

24

25 Chapter 5. PIPrismRTChng The PIPrismRTChng process is used to capture real-time changes from the SCADA database, and sends these values via a data file to the piprism interface and through to the PI server. If the interface is scan based only, a rapid change in a point could be missed by the interface if the change was to happen between scans. Although all points are still scanned periodically, the changes detected by PIPrismRTChng are also sent to the points to ensure the point values are accurate. The PIPrismRTChng process runs independently of the piprism interface. Most of the functionality is implemented within an ACS framework and handles the connection to the Prism real-time database, detects the changes and then calls the PIPrismRTChng specific functions. It is configured with a separate text-based file, which contains a number of parameters, most of the parameters control the operations of the ACS framework, but there are a few PIPrismRTChng specific parameters. The details of the PIPrismRTChng specific parameters are detailed below in the Parameters section. When running, the PIPrismRTChng process detects the changes in the real-time point values. It writes these values along with a Prism Point ID and timestamp to a temporary data file. Periodically, it checks to see the transfer data file read by the piprism interface exists. If the file does not exist, then it means that the piprism interface is ready to read a new data file. So, PIPrismRTChng closes the temporary data file, and renames it to the name expected by piprism. When PIPrismRTChng checks the existence the transfer file, if the file still exists then it knows that the piprism interface has not finished processing the old file, and so PIPrismRTChng continues to write events to the temporary file. The configuration of the PIPrismRTChng process also allows it to use multiple temporary files. When configured to use multiple temporary files, each filename includes an index number. If a temporary file reaches a configured maximum size (128MB by default), it is closed and a new temporary file is created. PIPrismRTChng configuration also allows a maximum number of temporary files to be set. By limiting the number and size of the data files, the PIPrismRTChng process can be limited in the total amount of disk space it can use. A sample configuration file named ConfigFile is including in the install kit, and should be used as a template. PIPrismRTChng is normally run as a background process. The script PIPrismRTChng.sh is provided to start the process. By default the stdout output messages are redirected to the file $PIHOME/dat/PIPrismRTChng.out. The script PIPrismRTChng_stop is provided to stop the background process. Note: In previous versions of the interface, the executable file was called PIPrismRTChange. Because of issues with long file names in scripts when running PI Interface for ACS Prism 19

26 PIPrismRTChng multiple instances, the executable was renamed in version x to PIPrismRTChng. Parameters The following are the PIPrismRTChng specific parameters from the configuration file. Parameter PIDebug=# optional PIDataDirectory=<d irectory path> Required PIDataFileName=<fi lename> Optional PITransferFileName =<filename> Required PIMaxFileSize=#[un it] Optional PIMaxNumFiles=# Optional EnableTimer1=true Required Description PIPrismRTChng specific debug flags (bitmapped) 1 = Initialize 2 = Timer / Send File 4 = RTChange events 8 = Write event to File To set multiple flags, add the values together. For example, to get initialization messages and RTChange event messages logged, the setting would be PIDebug=5 If not specified, all debug messages are disabled (PIDebug=0) Defines the directory that PIPrismRTChng will use to store the temporary data files and the transfer data file for the piprism interface to read. For example: PIDataDirectory=./data This parameter is a filename template and is used to define the filename of the temporary data file(s). When using multiple data files, include [idx] as place marker for the file index For example : PIDataFileName=RTChange[idx].tmp If not specified, the default filename is RTChange.tmp Name of the transfer file. This is the file that will be read by the piprism interface process. For example: PITransferFileName=RTChange.dat Sets the maximum data file size. The value is given in bytes, but can include a suffix to set the units. The value can range from 256 bytes to bytes (2GB-1). The recognized units are B, KB, MB and GB. Can be used in conjunction with PIMaxNumFiles to limit the total amount of disk space used by PIPrismRTChng. For example: PIMaxFileSize=512MB If not specified, the default value is 128MB. Sets the maximum number of data files supported. The range is 1 to Can be used in conjunction with PIMaxFileSize to limit the total amount of disk space used by PIPrismRTChng. For example: PIMaxNumFiles=100 If not specified, the default is 16. EnableTimer1 is PrismInterface parameter used to enable the Timer1 functionality. Timer1 is required by the PIPrismRTChng process and is used to trigger the function to check whether a temporary data file can be sent to the piprism interface. EnableTimer1 MUST be set to true for the PIPrismRTChng process to work correctly. For example: EnableTimer1=true 20

27 Parameter Timer1=#.# Recommended Device=# Description Timer1 value is used to define how often PIPrismRTChng will check to see whether the temporary data file can be transferred to the piprism interface. The value is in seconds, and can range from seconds to 864,000 seconds (10 days). It is recommended to use a value of approximately 1 second, as a compromise between not checking too often (which would load the system unnecessarily) and still being responsive when data is available to be sent. For example: Timer1=1 If not specified, the default is 0.1 seconds. Device with the required Area-of-Assignment (AOA) bits set. For use with PIPrismRTChng, which is event driven, the display and alarm AOA should be set for the specified AOA bit used for the status points of interest. Scripts and Configuration Files The install kit includes the templates files, PIPrismRTChng.sh_new and ConfigFile_new. These files should be copied to PIprismRTChng.sh and ConfileFile and then edited as required for the site. 1. Copy the template startup script to create the actual startup script to be used by the interface cp PIPrismRTChng.sh_new PIPrismRTChng.sh 2. If required, alter the command-line near the end of the PIPrismRTChng.sh file. The default script uses the configuration names ConfigFile. The script will not need to be edited if used ConfigFile as the name of the configuration file. 3. Copy the template configuration file to create the actual configuration file to be used cp ConfigFile_new ConfigFile 4. Alter the parameters in the ConfigFile file for the site. Normally, the default values will work. The critical parameter to change is the Device= parameter. This will vary depending on the Prism configuration and is often different on different systems. 5. With the PI API processes running, start the PIPrismRTChng.sh script. Use apiverify to check whether the process is running. Check the $PIHOME/dat/PIPrismRTChng.out to check the status of the interface. 6. To verify the PIPrismRTChange process is working correctly when Prism tags change, a. When piprism is not running, view the contents of the text files in the $PIHOME/interfaces/piprism/data directory. These should contain the timestamp, point ID and value of the events captured. If the.dat file is deleted, then the.tmp file should replace the.dat file. b. If piprism is running, then configure PI points and check the values sent to PI, or run the piprism interface with the -db=c command-line option so that RTChange related debug messages will be logged to pimesslogfile. 7. Use the PIPrismRTChng_stop script to stop the process. PI Interface for ACS Prism 21

28 Digital States Chapter 6. Digital States For more information regarding Digital States, refer to the PI Server documentation. Digital State Sets PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals. An interface point that contains discrete data can be stored in PI as a digital point. A digital point associates discrete data with a digital state set, as specified by the user. System Digital State Set Similar to digital state sets is the system digital state set. This set is used for all 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 are reserved for OSIsoft applications. The following system digital states should be created for the ACSPrism interface and are used to convey error information returned from the ACS Prism API when an error occurs. SINVSP Invalid station and/or point number SINVPC Invalid point category SINVA Invalid attribute SLOCKED The Points referred to by station n are currently locked SATTRRO Attribute is read only Undefined Undefined Prism Error The digital states described above must be contiguous and in the same order as shown. The starting digital state defaults to 500, but can be overridden via the use of the -ds=nnn option on the command line when starting the interface. 22

29 Chapter 7. 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. If the PI API version being used is prior to 1.6.x or the PI Server version is prior to x, the PointSource is limited to a single character. Case-sensitivity for PointSource Attribute The PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=p and /ps=p are equivalent. Reserved Point Sources Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem 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. PI Interface for ACS Prism 23

30

31 Chapter 8. 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: *? ; { } [ ] \ ` ' " Length Depending on the version of the PI API and the PI Server, this interface supports tags whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions. PI API PI Server Maximum Length or higher x or higher or higher Below x 255 Below x or higher 255 PI Interface for ACS Prism 25

32 PI Point Configuration PI API PI Server Maximum Length Below Below x 255 PointSource The PointSource attribute contains a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the 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. Float16, float32, float64, int16, int32, digital point types are supported. 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 specifies the Prism point number. The Prism point number is unique for each Station ID, which is specified in Location5. 26 Location3 Location3 specifies the Prism point type and I/O direction. The following values are supported. Location4 0 Read Status Point - Input 1 Write Status Point - Output 2 Read Telemetry Point - Input 3 Write Telemetry Point - Output 5 Write Status Alarm - Output 7 Write Telemetry Alarm - Output Scan-based Inputs For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for

33 new values. For more information, see the description of the -f parameter in the Startup Command File chapter. Note: For compatibility with the ACS RT Gateway (PI-ACSRT) interface, if an input point is configured with Location4=0, then the piprism interface will assume the point belongs in the scan class 1. Location5 Location5 specifies the Prism Station ID. This is used in conjunction with the Prism point number in Location2 to identify the point within the Prism system. InstrumentTag Length Depending on the version of the PI API and the PI Server, this interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Server versions. PI API PI Server Maximum Length or higher x or higher or higher Below x 32 Below x or higher 32 Below Below x 32 The InstrumentTag attribute is used to specify the Prism Category and Attribute to read or write. The format is as follows. CAT[EGORY]=I ATT[RIBUTE]=CV Note: Must be specified as UPPER case. The valid values for the CATEGORY parameter are: I - Internal D - Diagnostic R - Remote S - Sequence of Events P - Pseudo A - (Telemetry Points Only) Accumulator C - (Telemetry Points Only) Calculated PI Interface for ACS Prism 27

34 PI Point Configuration The valid values for the ATTRIBUTE parameter are shown in following table. Valid for 28 Attribute Description Status Telemetry Prism Data Type AD Abnormal Definition State X int AI Alarm Inhibit X X int AS Abnormal State X int CA Caution Authority Tag X int CI Caution Inhibit Tag X int CO Caution Order Tag X int CS Current State X int CV Current Value X float CW Control Warning X X int DIVZ Divide By Zero Flag X int EE Estimated Error X int ERRF Error Flag X int EVF Estimated Value Flag X int FCS FEP Current State X int FCV Current Value X float HH High Emergency Limit X float HHF High Emergency Flag X int HI High Operational Limit X float HIF High Operational Flag X int HLO Hot Line Order Tag X X int HR High Reasonability Limit X float HRF High Reasonability Flag X int INFO Info Tag X X int LADB Limit Alarm Dead Band X int LIDX Limit Index X int LL Low Emergency Limit X float LLF Low Emergency Flag X int LN Link Next X int LO Low Operational Limit X float LOF Low Operational Flag X int LP Link Previous X int LR Low Reasonability Limit X float LRF Low Reasonability Flag X int MAXV Maximum Value X float MC Momentary Change X int MINV Minimum Value X float MO Manual Override X X int ND No Data X int NORM Normal Flag X int OD Old Data X int OP Other Priority Processing X int

35 Valid for Attribute Description Status Telemetry Prism Data Type OPP Other Priority Processing X int QU Questionable Data X int ROC Rate of Change Value X float ROCF Rate of Change Flag X int RQUA Remote Quality (NOT USED) X int SI Scan Inhibit X X int TC Trip Count X int TCLIM Trip Count Limit X int TCLIMF Trip Count Limit Flag X int TI Transmit Inhibit X X int TRIG Trigger Enabled/Disabled (NOT USED) X X int TRUECV True Current Value X float UA Unacknowledged Alarm X X int UACNT Unacknowledged Alarm Count X X int Note: Refer to the Prism Database User manual for a detailed description of the Categories and Attributes described above. Note: For compatibility with the ACS RT Gateway (PI-ACSRT) interface, if the attribute (ATT=) is not given, then the interface will assume the attribute CV for telemetered points or CS for status points. ExDesc Length Depending 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. PI API PI Server Maximum Length or higher x or higher or higher Below x 80 Below x or higher 80 Below Below x 80 There are no PI-Prism Interface specific uses of the ExDesc attribute. PI Interface for ACS Prism 29

36 PI Point Configuration Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string PERFORMANCE_POINT. If this character string is found, UniInt treats this point as a performance point. See the section called Scan Class Performance Points. Trigger-based Inputs For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form: keyword=trigger_tag_name where keyword is replaced by event or trig and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute. An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value. Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows: Event='trigger_tag_name' event_condition The trigger tag name must be in single quotes. For example, Event='Sinusoid' Anychange will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot. The keywords in the following table can be used to specify trigger conditions. Event Condition Anychange Increment Decrement Nonzero Description Trigger on any change as long as the value of the current event is different than the value of the previous event. System digital states also trigger events. For example, an event will be triggered on a value change from 0 to Bad Input, and an event will be triggered on a value change from Bad Input to 0. Trigger on any increase in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 0 to 1, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. Trigger on any decrease in value. System digital states do not trigger events. For example, an event will be triggered on a value change from 1 to 0, but an event will not be triggered on a value change from Pt Created to 0. Likewise, an event will not be triggered on a value change from 0 to Bad Input. Trigger on any non-zero value. Events are not triggered when a system digital state is written to the trigger tag. For example, an event is triggered on a value change from Pt Created to 1, but an event is not triggered on a value change from 1 to Bad Input. 30