PI Server System Management Guide

Transcription

1 PI Server System Management Guide PI3 Server Version OSIsoft, Inc. All rights reserved

2 OSIsoft, Inc. 777 Davis St., Suite 250 San Leandro, CA USA Telephone (01) (main phone) (01) (fax) (01) (support phone) North American Offices Houston, TX Johnson City, TN Mayfield Heights, OH Phoenix, AZ Savannah, GA Seattle, WA Yardley, PA Worldwide Offices OSIsoft Australia Perth, Australia Auckland, New Zealand OSI Software GmbH Altenstadt, Germany OSIsoft Canada ULC Montreal, Canada OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSI Software Asia Pte Ltd. Singapore OSIsoft, Inc. Representative Office Shanghai, People s Republic of China Sales Outlets and Distributors Brazil Middle East / North Africa Republic of South Africa Russia / Central Asia South America / Caribbean Southeast Asia South Korea Taiwan Revised: January 2006 Send documentation requests, comments and corrections to [email protected]. OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, grecipe, srecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind. Restricted Rights Legend Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS Copyright Notice Unpublished -- rights reserved under the copyright laws of the United States

3 PREFACE USING THIS GUIDE About this Guide The PI Server System Management Guide is an in-depth manual that provides the information and instructions that system administrators need to operate the PI System. This guide includes comprehensive instructions to assist you in: Using PI Server command-line tools such as PIConfig, PIDiag, and PIArtool Configuration and tuning of your PI Server for optimum performance Monitoring system health, and ensuring data preservation and integrity Managing the Snapshot, Event Queue and Data Archive Troubleshooting and repair To effectively manage a PI System, follow the recommendations and procedures for each of the following topics: Starting and Stopping PI Systems Backing Up PI Servers Managing Archives Managing Interfaces Managing Security Monitoring PI System Health Moving, Copying or Merging PI Servers For troubleshooting and performance issues, this guide includes Appendices of error messages provided in the System Message Log, and an extensive list of performance measurements (statistics) you can use to optimize the System. PI Server System Management Guide Page iii

4 Preface - Using this Guide The PI Server Documentation Set The PI Server Documentation Set includes seven user guides, described below. Tip: Updated user guides, which provide the most up-to-date information, may be available for download from the OSIsoft Technical Support Web site ( Title Introduction to PI System Management PI Server Installation and Upgrade Guide PI Server System Management Guide PI Server Reference Guide Auditing the PI Server PI Server Applications User Guide PINet and PIonPINet User Guide Subject Matter A guide to the PI Server for new users and administrators. It explains PI system components, architecture, data flow, utilities and tools. It provides instruction for managing points, archives, backups, interfaces, security and trusts, and performance. It includes a glossary and resource guide. A guide for installing, upgrading and removing PI Servers on Windows and UNIX platforms, including cluster and silent installations. An in-depth administration guide for the PI Server, including starting and stopping systems, managing the Snapshot, Event Queue and Data Archive, monitoring system health, managing backups, interfaces, security, and moving and merging servers. Includes comprehensive instructions for using command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth troubleshooting and repair information. A comprehensive reference guide for the system administrator and advanced management tasks, including: databases; data flow; PI Point classes and attributes, class edit and type edit; exception reporting; compression testing; security; SQL subsystem; PI time format; and overviews of the PI API, and PI-SDK System Management Tool (SMT). An administration guide that explains the Audit Database, which provides a secure audit trail of changes to PI System configuration, security settings, and Archive Data. It includes administration procedures to enable auditing, to set subsystem auditing mode, to create and archive database files, and to export audit records. A guide to key add-on PI Server Applications: Performance Equations (PE), Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality Control). Includes a reference guide for Performance Equations, and Steam calculation functions. A systems administration guide, including installation, upgrade and operations, for PINet for OpenVMS and PIonPINet, which support migration and interoperability between PI2 and PI3 Systems. Page iv

5 Preface - Using this Guide Conventions Used in this Guide This guide uses the following formatting and typographic conventions. Format Use Examples Title Case Italic text PI Client Tools PI System Elements PI Server Subsystems Files, Directories, Paths Emphasis New Terms Fields References to a chapter or section Use the client tool, PI ProcessBook, to verify that all data has been recovered. All incoming data is queued in the Event Queue by the Snapshot Subsystem. The backup script is located in the \PI\adm directory. Archive files can be either fixed or dynamic. The archive receiving current data is called the Primary Archive. See Section 4.2, Create a New Primary Archive. Bold Italic text References to a publication See the PI Server Reference Guide. Bold text Monospace type: "Consolas" font Light Blue - Underlined System and Application components: Subsystems Tools / Utilities Processes / Scripts / Variables Arguments / Switches / Options Parameters / Attributes / Values Properties / Methods / Events / Functions Procedures and Key Commands Interface components Menus / Menu Items Icons / Buttons / Tabs Dialog box titles and options Consolas monospace is used for: Code examples Commands to be typed on the command line (optionally with arguments or switches) System input or output such as excerpts from log files and other data displayed in ASCII text Bold consolas is used in the context of a paragraph Links to URL / Web sites, and addresses The Archive Subsystem, piarchss, manages data archives. Piarchss must be restarted for changes to take effect. On UNIX, invoke site-specific startup script, pisitestart.sh, and on Windows, invoke pisrvsitestart.bat. Three Point Database attributes affect compression: CompDev, CompMin, and CompMax. These are known as the compression specifications. On the Tools menu, click Advanced Options. Press CTRL+ALT+DELETE to reboot Click Tools > Tag Search to open the Tag Search tool. Click the Advanced Search tab. Use the search parameters PImean Value = 1. To list current Snapshot information every 5 seconds, use the piartool -ss command. For example: [email protected] PI Server System Management Guide Page v

6 Preface - Using this Guide Related Documentation OSIsoft provides a full range of documentation to help you understand and use the PI Server, PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client application has its own online help and/or user guide. The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is recommended reading for PI Server system managers. Many PI Interfaces are based upon UniInt, and this guide provides a deeper understanding of principals of Interface design. Using PI Server Tools The PI Server provides two sets of powerful tools that allow system administrators and users to perform system administration tasks and data queries. The PI Server includes many command-line tools, such as pidiag and piartool. The PI Server Documentation Set provides extensive instruction for performing PI Server administrative tasks using command-line tools. The PI System Management Tools (SMT) is an easy-to-use application that hosts a variety of different plug-ins that provide all the basic tools you need to manage a PI System. You access this set of tools through a single host application. This host application is sometimes referred to as the SMT Host, but it is more commonly called System Management Tools or SMT. You can download the latest version of SMT from the Technical Support Web site: In addition to extensive online help that explains how to use all of the features in the SMT, the SMT includes the Introduction to PI System Management User Guide. Page vi

7 QUICK TABLE OF CONTENTS Chapter 1. Starting and Stopping PI...1 Chapter 2. Monitoring PI System Health...17 Chapter 3. Managing Archives...33 Chapter 4. Backing up the PI Server...63 Chapter 5. Managing Interfaces...93 Chapter 6. Managing Security Chapter 7. Moving PI Servers Chapter 8. Copying a PI Server Chapter 9. Merging Two PI Servers Chapter 10. The piconfig Utility Chapter 11. PI Troubleshooting and Repair Chapter 12. Finding and Fixing Problems: the pidiag Utility PI Server System Management Guide Page vii

8

9 TABLE OF CONTENTS Preface Using this Guide...iii Table of Tables...xix Table of Figures...xxi Chapter 1. Starting and Stopping PI Starting PI Starting PI on Windows Systems Starting PI on UNIX Systems Stopping PI Stopping PI on Windows Systems Stopping PI on UNIX Systems Automatic Startup Automatic Startup and Shutdown on UNIX Systems Shutting Down an Individual Subsystem...16 Chapter 2. Monitoring PI System Health Checking Key System Indicators Viewing System Messages Available Log History Viewing System Messages with pigetmsg Viewing Messages When the Message Subsystem Goes Down Viewing Message Log Files Generated on other Servers Interpreting Error Messages (pidiag) Subsystem Healthchecks (RPC Resolver Error Messages) Monitoring Snapshot Data Flow Listing Current Snapshot Information with piartool -ss Monitoring the Event Queue piartool -qs Monitoring the Archive piartool -as...27 PI Server System Management Guide Page ix

10 Table of Contents 2.6 Monitoring the Update Manager Adjusting the Pending Update Limit System Date and Time...31 Chapter 3. Managing Archives Tasks for Managing Archives About Archives About Archive Shifts About Archive Files About Primary Archives About Fixed and Dynamic Archives About Read-Only Archives Tools for Managing Archives Using the piartool Utility Using the Offline Archive Utility (piarchss) Listing the Registered Archives Determining an Archive Sequence Number from a Listing Listing Archive Record Details Performing an Archive Walk with piartool -aw Estimating Archive Utilization Editing Archives Creating Archives Naming Archives Choosing an Archive Size Selecting an Archive Type: Fixed or Dynamic Specifying the Number of Points in the Archive Specifying the Maximum Archive Size Creating Data Archives Prior to the Installation Date Creating a New Primary Archive Registering an Archive Unregistering an Archive Deleting an Archive Moving an Archive Managing Archive Shifts Archive Shift Enable Flag Forcing Archive Shifts Combining and Dividing Archives...59 Page x

11 Table of Contents Combining Archives into a Single Archive Event Queue Recovery...61 Chapter 4. Backing up the PI Server Planning for Backups Choosing the Backup Platform (VSS vs. Non-VSS) Choosing a Backup Strategy Other Backup Considerations Guidelines for VSS Backups Guidelines for non-vss Backups Guidelines for Backing Up Before Upgrading Automating PI Backups Automating Backups on Windows Do a Test Backup Do a Test Restore Automating Backups on Windows with a 3rd Party Backup Application Automating Backups on a Windows Cluster Automating Backups on UNIX How The PI Backup Subsystem Works Principles of Operation Selecting Files or Components for Backup The Backup Components of PI The Files and Components for each Subsystem Lifetime of a Backup Launching Non-VSS Backups with piartool -backup <path> Managing Backups with piartool Backup Command Summary piartool -backup -query piartool -backup -identify Timeout Parameters Troubleshooting Backups Log Messages VSSADMIN...90 Chapter 5. Managing Interfaces Introduction General Interface Principles About PI Interfaces...94 PI Server System Management Guide Page xi

12 Table of Contents About PI Interface Nodes About Data Buffering About the PI API About the PI SDK About UniInt-Based Interfaces Basic Interface Node Configuration Install the PI SDK and/or the PI API Connect to PI with apisnap.exe Connect with AboutPI SDK.exe Configure PI Trusts for the Interface Node Install the Interface Set the Interface Node Time Connect to the PI Server with the Interface Configure Points for the Interface Configure Buffering Configure Interface for Automatic Startup Configure Site-Specific Startup Scripts Configure PointSource Table Monitor Interface Performance Configure the PI Interface Status Utility Configure Auto Point Synchronization Chapter 6. Managing Security Physical Security Network Security Operating System Security PI Server Security Running applications on the system console Running applications remotely Firewall Security Firewall Database Database Security PIDBSEC PIARCADMIN PIARCDATA PIBatch PICampaign Page xii

13 Table of Contents PIDS PIHeadingSets PIModules PIPOINT PITransferRecords PIUSER Individual Subsystem Tokens Point Security Point Data Access Point Attribute Access Access Algorithm Assigning and Changing Ownership and Access Permissions How to Make All Points Accessible Security for Default Points in the PI Server User Security Group Database User Database Trust Login Security Connection Credentials Defining Trust Records in the Trust Database Evaluating the Match Between Trust Records and Connection Credentials New PI Server Installations Trust changes on System Startup Multiple Network Cards Examples Resolving Ambiguities Chapter 7. Moving PI Servers Preparation Different Computer Same Computer Chapter 8. Copying a PI Server Understanding the Server ID Situations where Server ID must be Addressed Chapter 9. Merging Two PI Servers Server Merging - Procedures PI Server System Management Guide Page xiii

14 Table of Contents 9.2 Server Merge Procedure - Example Shut Down the Retired System Add Retired Point Configuration to Destination System Add PI Batch Unit Configuration to Destination System Convert the Archives Merge the PI Batches Chapter 10. The piconfig Utility PI TagConfigurator & PI SMT Point Builder plug-in A Note to Pidiff Users Key Concepts for Using Piconfig Starting and Stopping Piconfig Interactive Session vs. Batch Method Selecting PI Tables Table Attributes Records Piconfig Commands Mode Structure Type Select Command Operators Wildcards The Ellipsis ( ) Construct for Repeating Attributes Endsection Exit Batch Methods Security on Piconfig Sessions Remote Piconfig Sessions Piconfig Commands and Tables Point Database Table PI Attribute Set Table Point Class Database Point Source Database Digital States Table Snapshot and Snapshot2 Tables Archive Table PI Batch Unit Table Page xiv

15 Table of Contents PI Batch Alias Table PI Batch Table PI Subsystem Table PI Subsystem Statistics Table PINet Manager Statistics Table PI Users Table PI Group Table PI Thread Table PI Database Security Table PI Trust Database PI General Table Interface Helpful Hints Abbreviations Case-sensitivity Command Input Files Input Line Length Using Quoted Strings Sending Values as Strings Boolean Values Configuration Persistence Command Line Parameters Changing Special Characters Convert Mode Example Converting Point Database Information from PI2 to PI Server Hexadecimal and Octal Numbers Chapter 11. PI Troubleshooting and Repair Troubleshooting Checklist Verifying PI Processes Verifying PI Processes on Windows Systems Verifying PI Processes on UNIX Systems Communication with PINet Manager Pimsgss PI Update Manager PI Base Subsystem Snapshot Subsystem Archive Subsystem PI Server System Management Guide Page xv

16 Table of Contents Pishutev Random Interface RampSoak Interface Running PI Processes Independently UNIX Process Quotas IBM AIX Compaq Tru HP-UX Sun Solaris PI Server Data Files Identifying the Update Manager Issues: the pilistupd utility Repairs Recovering Data from Corrupted Archives Restoring a Complete Server from Backup Restoring Archives From Backup Restoring Subsystem Databases From Backup Correcting Archive Event Timestamps Repairing the Archive Registry How to Repair the Snapshot Recovering from Accidental Change to System Time How to Repair the Point Database How to Repair the Module Database Tuning the PI Server Communications Layer of the PI Server Resolving Excessive CPU Usage by Utilities Identifying Abusive Usage Solving Other Problems Failed Backups Slow Reverse Name Lookup Slow Domain Controller Access Flatline in a PI ProcessBook Trend COM Connectors Redirector Troubleshooting COM Connector Troubleshooting Chapter 12. Finding and Fixing Problems: the pidiag Utility General Information Page xvi

17 Table of Contents Version Information Error Code Translation Time Utilities Time Translations Time Zone File-base Utilities Dump File-base Data File Compact a File-base Data File Recover File-base Data File Index Archive Management Dump the Archive Manager Data File Automatic Recovery of the Archive Manager Data File Manual Recovery of the Archive Manager Data File Information about Unregistered Archives Verify the Integrity of Archive Files Downgrade Archive File to Older Versions Server ID Utilities Performance Counter Utilities (Windows Only) Get Performance Counter Path Uninstall Performance Counters Get Performance Counter Values Miscellaneous Wait for Passed Milliseconds Testing Crash Dump Capability of an OS Reset Password to Blank Display Network Definitions Register a COM Component Replaceable Parameter GUID Generation Machine-specific Programming Information Appendix A: PI Messages Appendix B: PI Performance Counters Technical Support and Resources Index of Topics PI Server System Management Guide Page xvii

18

19 TABLE OF TABLES Table 3 1. Options for Use with piartool...37 Table PI Tables Accessible Through piconfig Table Piconfig Commands Table Snapshot and Snapshot2 Tables Attributes Table Archive Table Attributes Table PI Batch Unit Table Attributes Table PI Batch Alias Table Attributes Table PI Batch Table Attributes Table Subsystem Table Attributes Table PI Subsystem Statistics Table Attributes Table PINet Manager Statistics Table Attributes Table PI Users Table Attributes Table PI Group Table Attributes Table PI Thread Table Attributes Table PI Thread Table Actions Table PI Database Security Table Attributes Table Trust Table Attributes Table PI Timeout Table Attributes Table PI Firewall Table Attributes Table A 1. Error Codes 1-99, With Messages Table A 2. Error Codes , With Messages Table A 3. Error Codes , With Messages Table A 4. Error Codes , With Messages Table A 5. Error Codes , With Messages Table A 6. Error Codes , With Messages Table A 7. Error Codes , With Messages Table A 8. Error Codes , With Messages Table A 9. Error Codes , With Messages Table A 10. Error Codes , With Messages PI Server System Management Guide Page xix

20 Table of Tables Table A 11. Error Codes , With Messages Table A 12. Error Codes , With Messages Table A 13. Error Codes , With Messages Table A 14. Error Codes , With Messages Table A 15. Error Codes , With Messages Table B 16. PI Performance Counters Page xx

21 TABLE OF FIGURES Figure 6-1. Establishing PI Performance Monitor as a Windows Service Figure Distributed COM Configuration Properties Figure Windows Task Manager Processes Figure Application Log Properties Figure COM Connector Loading PI Server System Management Guide Page xxi

22

23 Chapter 1. STARTING AND STOPPING PI The PI Server includes several separate processes that participate in startup and shutdown. These are referred to as PI processes or PI subsystems. This section describes the relationship between the processes, and the startup and shutdown scripts used to control them. PI should only be started or stopped by the PI System manager. It is important to remember that stopping PI affects all client applications, performance equation calculations, and the archiving of data. PI Server startup is performed with a pair of scripts: a generic PI startup script starts all PI processes, which then calls a site-specific script to start interfaces and other site specific programs. The system manager should modify only the site-specific script since the generic startup script may be replaced during a PI Server upgrade. The actual file names of these scripts vary with the operating system. Platform-specific details are provided in the following subsections. In general, the PI Server shutdown scripts are similar: a generic PI shutdown script calls a site-specific script to shut down interfaces and site specific programs, and then shuts down all PI processes. Note: The only exception to this is shutting down PI processes running as individual command windows. In this case, you must bring each window in focus and type <CTRL-C>. Running PI subsystems in command windows is very rare; and usually only encountered in troubleshooting scenarios. It is important to configure Shutdown Events. Generally, points collected by interfaces running on the PI Server node should be configured for shutdown events; points collected on remote, buffered nodes usually are not configured for shutdown events. See Stopping PI on page 3. Production systems are usually configured so that PI is automatically started when the computer is powered on. See Automatic Startup on page 6 for more information. 1.1 Starting PI The PI Subsystems may take several minutes to start. Remote or PI API based interfaces and other applications are blocked from connecting until the core PI Subsystems have completed startup. The connection blocking is accomplished by opening the TCP/IP listener when the core subsystems are ready to service requests. The following message is posted to the PI Server log when the listener is opened: PI Server System Management Guide Page 1

24 Chapter 1 - Starting and Stopping PI >> TCP/IP connection listener opened on port: 5450 Connection attempts before the listener is opened will fail. Interfaces will retry until a connection is made Starting PI on Windows Systems On Windows systems, the Manager can be logged into any account that allows full access to the PI Server files and enough privileges to start services. To start PI, change to the PI\adm directory. PI normally runs as Windows services. For diagnostic purposes, you can also start PI in interactive mode. Starting PI as Windows Services To start PI as Windows services: 1. Log in to a Windows account that has full access to the PI Server files, and permission to start PI services 2. Open a Windows Command Prompt window. 3. Change to the PI\adm directory. 4. Use the pisrvstart.bat script to start PI as Windows services: pisrvstart.bat [-nosite] [-base] Nosite is an optional parameter to indicate that the site-specific script file should not be called. This results in the interfaces not being started. Base starts only the core subsystems and is used for troubleshooting. The pisrvstart.bat script starts all the PI Server processes, and then calls pisrvsvrappsstart.bat if PI Server Applications are installed. Then, it calls pisrvsitestart.bat to start all of the interfaces. Starting PI in Interactive Mode To start PI in interactive mode: pistart.bat [-nosite] [-stdout] [-base] The pistart.bat script calls pisitestart.bat. Nosite is an optional parameter to indicate that the site-specific script file should not be called. This results in the interfaces not being started. Base starts only the core subsystems and is used for troubleshooting. Stdout is an optional parameter to indicate that all messages for the processes should be sent to the standard output instead of to the message log. When you use this parameter, the PI Message Subsystem is not started. The error Control service unknown error 5 opening Service Control Manager is returned if the PI startup is attempted by a user without enough privileges. Page 2

25 1.2 - Stopping PI Some interfaces on Windows cannot be run as services. Check the interface documentation Starting PI on UNIX Systems On UNIX systems the manager should be logged in as root or piadmin. For a UNIX system, type: pistart.sh [-nosite] [-stdout] [-base] [M] This starts all the PI Server processes, calls piappstart.sh if Server applications are installed, and then calls the interfaces and programs that are listed in the site-specific script file, pisitestart.sh. Nosite is an optional parameter for pistart used to indicate that the site-specific script file should not be called. This results in the interfaces not being started. Base starts only the core subsystems and is used for troubleshooting. Stdout is an optional parameter to indicate that all messages for the processes should be sent to the standard output instead of the Message Log. When you use this parameter, the PI Message Subsystem is not started. M starts only PI Network Manager, PI License Manager, and the PI Message Subsystem. 1.2 Stopping PI The procedure for stopping PI is slightly different, depending on whether you re running on Windows or UNIX Stopping PI on Windows Systems To stop PI on a Windows system, if PI processes are running as Windows services, type: pisrvstop.bat This stops all of the interfaces and programs listed in pisrvsitestop.bat, and then the PI processes. PI services are shut down automatically when you shut down your system. The order of the shutdown in this case is determined by the operating system. Windows has a registry entry that defines the maximum wait for a service to exit. On PI Systems with large point counts, the maximum wait time may need to be increased to allow PI enough time to shut down properly. The PI installation procedure increases the default value of 20,000 milliseconds to 300,000 milliseconds, or 5 minutes. This is generally enough time for proper shutdown on systems with fewer than 50,000 points. Larger systems may require more time. This can be determined by manually stopping the PI Server using pisrvstop.bat and record the time to shutdown. If it is longer than 5 minutes, the registry entry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WaitToKillServiceTimeout should be set to reflect the actual shutdown time. Failing to allow proper shutdown of the PI Server can result in lost data or corrupted data files. PI Server System Management Guide Page 3

26 Chapter 1 - Starting and Stopping PI To shut down an interactively started PI Server, type <CTRL-C> in each of the command windows corresponding to the PI processes. These should be stopped in the following order: Utilities (for example, piconfig) Interfaces (for example, Ramp Soak and Random) pinetmgr (When you instruct pinetmgr to stop, the remaining processes are told to exit in the proper order and, finally, pinetmgr will stop.) Stopping PI on UNIX Systems To stop PI on a UNIX system, change to the PI/adm directory and type: pistop.sh This stops all the interfaces and programs that are listed in the site-specific script file pisitestop.sh. Then it stops all the PI processes. If some processes do not stop successfully, run the pistop.sh script again. If you still have problems stopping the individual programs, use the UNIX kill command. Distributed systems use PINet and Interface Nodes as data source machines. Normally these systems buffer data if the PI Server is not available. The buffered data is sent to the PI Server when it becomes available. There are a few instances in which data is not buffered when the home node is down. Examples include cases where an interface is loaded on the PI Server machine and the PI Server is shut down or where the data is generated locally with performance equations. In these cases, you may wish to record intervals when the PI Server on the home node was shut down. This is accomplished by inserting a shutdown event. A shutdown event is a timestamp and a digital state, typically shutdown, which are written to one or more points. The digital state prevents the interpolation of data over periods with possible missing data, and also records system status, providing a clear indication of a gap in the data. The PI Server provides a utility, pishutev, to insert shutdown events for points that are configured to receive them. The pishutev utility uses a configuration file, shutdown.dat, to determine which points should receive events. Note: Interfaces may also be configured to record instances when no data is received from an interface. Shutdown Flag The shutdown point attribute in the point database is set to TRUE (1) by default. If the shutdown attribute for a point is set to TRUE, the point is able to receive shutdown events if the shutdown.dat file targets the point. Page 4

27 1.2 - Stopping PI pishutev Shutdown events are written at system startup by the pishutev interface. The utility reads a configuration file to determine which tags should receive shutdown events. It also supplies a configurable timestamp for the PI Server shutdown. Unlike most PI processes, pishutev exits after completion. The startup command line for pishutev is located in the PI startup files PI/adm/pistart.sh (UNIX), PI\adm\pistart.bat and PI\adm\pisrvstart.bat. By default, the configuration file is PI\dat\shutdown.dat. It is sometimes useful to create additional shutdown configuration file(s) with additional point selections. These files are processed by starting another instance of the interface. The new shutdown configuration file name is passed as a parameter using the -f flag in the pishutev command line: For example: pishutev -f myshutdown.dat This command line should be added to the PI site-specific startup files PI/adm/pisitestart.sh (UNIX) and PI\adm\pisitestart.bat. Starting a second instance of pishutev in order to process an additional shutdown configuration file is not supported when starting PI as Windows services. By default, pishutev determines the shutdown event timestamp from a file written by the Snapshot Subsystem. This file is updated whenever the Snapshot is flashed to disk, usually every 10 minutes. Hence, in the event of a power failure, the timestamp of the shutdown event are accurate to within 10 minutes. When PI is shut down normally, the timestamps are the actual shutdown time. If the file that is written by the Snapshot Subsystem is missing, the shutdown events interface uses the current time to timestamp the shutdown events. The default time may be overridden by a user-specified time using the -t flag and passing the time as a parameter in the command line. For example: pishutev -t 11:00 By default, the digital state of shutdown is written for each shutdown event. To write a digital state other than shutdown, use the -s flag and pass the digital state as a parameter in the command line. The specified state must already be configured in the System Digital State Set in the Digital State Table. For example: pishutev -s SpecialState The -f, -t, and -s flags may be used in any combination. Shutdown.dat The points receiving shutdown events are specified using the file PI\dat\shutdown.dat. The PI Server is delivered with a shutdown.dat file that selects all points whose shutdown flag is TRUE. This file is shown below. You may wish to edit the file to restrict shutdown events to certain groups of /24/96! default shutdown events file PI Server System Management Guide Page 5

28 Chapter 1 - Starting and Stopping PI! login info - only localhost is supported localhost! tag mask *! attrib selection! add here point attributes,value to select points receiving shutdown shutdown,1! pointsource,r*! location1, 1! etc... To specify more than one tag name use a tag mask. The tag mask may contain the wildcards * and?. The symbol * matches all possibilities with any number of characters. The symbol? matches a single character and may be used any number of times. Caution: Do not specify additional tags by appending comma separated tag masks or by using additional lines. Only one tag mask may be specified. If you do not specify a tag-mask, the interface exists with an error. To prevent all shutdown events, specify a tag mask that does not match any tag. Other point attributes and values may be used in addition to or instead of the shutdown flag. These conditions are logically ANDed together. For example, the following configuration file selects only tags that start with s, have the location1 attribute set to 0, and Pointsource set to H. No other tags will receive shutdown events.! tag mask s*! point attributes location1,0 pointsource,h If no point attributes are specified, all tags specified by the tag mask are selected to receive shutdown events. Caution: The Shutev process is used to execute post installation procedures; therefore the Shutev process should not be disabled or removed from the normal startup procedures. The shutdown.dat file, or point shutdown attribute should be used to prevent writing shutdown events. 1.3 Automatic Startup The procedure to configure PI for automatic startup depends on the operating system. PI Server on Windows is normally run as a collection of services. The installation procedure provides a dialog to optionally set automatic startup on reboot. The reboot startup behavior of PI can also be set using the Control Panel Services applet. Page 6

29 1.3 - Automatic Startup Automatic Startup and Shutdown on UNIX Systems Shutdown and startup for UNIX systems varies with platform, but there are generally two varieties: BSD style systems use one file, /etc/inittab, which specifies what scripts to run in each run level, while System V flavors of UNIX use scripts which reside in a set of directories called rcn.d, where n is an number ranging from 0 on up. Usually these subdirectories are in the /etc directory, but can be in others (HP-UX 10 has them under /sbin, for example). Here, we're going to give examples of how to configure each of the systems we support. No matter which UNIX platform you're using, if you want to have PI automatically start up when the system boots or reboots, and shut down when the system shuts down, you MUST ensure that the.profile or.login file for piadmin does not require interaction with a terminal. This means that if you use, for example, tset to set the TERM variable, you must first check to see if there is a terminal attached to the current process. One way to do this is: if tty -s ; then tset... fi Automatic Startup/Shutdown for Solaris 2.x Solaris recognizes numerous run levels: Run Level s or S Purpose single user (used for administering the system) 2 standard level, non-networked 3 default level 4 standard level, user-defined Which processes run at each level is determined by a set of scripts, /etc/rcs through /etc/rc6. These scripts look in the directories /etc/rc#.d (where # = 0, 2, 3, etc.) for scripts that begin with a K or an S. The K scripts are used to kill processes, and the S scripts are used to start processes. When the system moves from level 3 to level 2, the K scripts in /etc/rc2.d are executed first, then the S scripts. The scripts are run in ASCII collated sequence, so K02stop is run before K04metoo. On shutdown or reboot, the system runs the scripts in /etc/rc0.d. If you are using the default run level, you will need to put the PI startup in /etc/rc3.d. The shutdown script for PI needs to be in /etc/rc2.d, so PI will be shut down if the system goes to non-networked mode, and also in /etc/rc0.d, so PI will be shut down if the system is halted or rebooted. Note: Solaris systems should be restarted using shutdown -i 6. This will cause the shutdown scripts to be run before running reboot. The reboot command simply restarts the kernel, without taking the time to shut down processes properly. The command shutdown -i 5 is for powering down. Script files are actually kept in /etc/init.d, with links placed in the /etc/rc#.d directories. So, in /etc/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to change the lines that specify where to find PI on your system. PI Server System Management Guide Page 7

30 Chapter 1 - Starting and Stopping PI #!/bin/ksh # # Filename: /etc/init.d/pi # # become piadmin to start/stop PI PATH=/sbin:/usr/sbin:/usr/bin export PATH case "$1" in 'start') if [ -f /etc/init.d/pistart ] ; then su - piadmin -c "/etc/init.d/pistart" > /dev/console 2>&1 fi ;; 'stop') if [ -f /etc/init.d/pistop ] ; then su - piadmin -c "/etc/init.d/pistop" > /dev/console 2>&1 fi ;; *) echo "usage: $0 {start stop}" ;; esac #!/bin/ksh # # Filename: /etc/init.d/pistart # Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/init.d/pistop # Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi Next, set the owner, group, and permissions on these files to match the other files in this directory: root> chgrp sys /etc/init.d/pi* root> chmod 755 /etc/init.d/pi* Page 8

31 1.3 - Automatic Startup Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on the startup file is higher than the S## number for inetd, and that the K## number for the kill file is lower than the K## number for inetd (in both directories). root> ln -s /etc/init.d/pi /etc/rc3.d/s96pi root> ln -s /etc/init.d/pi /etc/rc2.d/k04pi root> ln -s /etc/init.d/pi /etc/rc0.d/k04pi Verify that these files have the same owner, group, and permissions as other startup files in those directories. Finally, test your scripts before you restart your machine. To stop PI: root> sh /etc/rc0.d/k04pi stop Verify that PI processes shut down. root> sh /etc/rc3.d/s96pi start Verify that PI starts properly. If there is any problem with stopping or restarting PI, remove the links in the /etc/rc#.d directories until you've debugged and fixed the problems. The files in the /etc/init.d directory will not affect your system as long as there are not links in the /etc/rc#.d directories. Automatic Startup/Shutdown for HP-UX 10 HP-UX 10 recognizes numerous run levels: Run Level s or S Purpose Single user (used for administering the system) 1 6 standard levels (1 is single-user, 2 is default, 3 and up are user-defined) Which processes run at each level is determined by the /sbin/rc script. This script looks in the directories /sbin/rc#.d (where # = 1, 2, 3, etc.) for scripts that begin with a "K" or an "S". The "K" scripts are used to kill processes, and the "S" scripts are used to start processes. When moving down from a higher level to a lower level, all "K" scripts in all the intervening levels are run. When moving up to a higher level, all "S" scripts in all intervening levels are run. So when the system moves from level 4 to level 2, the "K" scripts in /sbin/rc3.d are executed, then the "K" scripts in /sbin/rc2.d. The scripts are run in ASCII collated sequence, so K002stop is run before K004metoo. If you are using the default run level of 2, you must put the PI startup in /sbin/rc3.d. The shutdown script for PI needs to be in /sbin/rc%.d, where % is the default run level, minus 1, so PI will be shut down if the system goes out of the default run level to any other level, or if the system is halted or rebooted. To determine your default run level, check the line in /etc/inittab that reads "init:#:initdefault:." The # is the default run level for the system. Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So, in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to change the lines that specify where to find PI on your system. #!/bin/ksh PI Server System Management Guide Page 9

32 Chapter 1 - Starting and Stopping PI # # Filename: /sbin/init.d/pi # # become piadmin to start/stop PI PATH=/sbin:/usr/sbin:/usr/bin export PATH case "$1" in 'start') if [ -f /sbin/init.d/pistart ] ; then su - piadmin -c "/sbin/init.d/pistart" > /dev/console 2>&1 fi ;; 'stop') if [ -f /sbin/init.d/pistop ] ; then su - piadmin -c "/sbin/init.d/pistop" > /dev/console 2>&1 fi ;; 'start_msg') echo "Starting PI" ;; 'stop_msg') echo "Shutting down PI, please wait" ;; *) echo "usage: $0 {start stop}" ;; esac #!/bin/ksh # # Filename: /sbin/init.d/pistart # Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /sbin/init.d/pistop # Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi Next, set the owner, group, and permissions on these files to match the other files in this directory: Page 10

33 1.3 - Automatic Startup root> chgrp sys /sbin/init.d/pi* root> chmod 755 /sbin/init.d/pi* Then, you'll need to set the links in the rc#.d directories. Make sure the S### number on the startup file is higher than the S### number for inetd, and the K### number for the kill file is lower than the K### number for inetd (in both directories). Note that HP-UX uses three digits in the link file names as opposed to the two digits used by other varieties of UNIX. Here, run level 3 is our default run level, so we're putting the start script in /sbin/rc3.d, and the kill script in /sbin/rc2.d: root> ln -s /sbin/init.d/pi /sbin/rc3.d/s960pi root> ln -s /sbin/init.d/pi /sbin/rc2.d/k004pi Verify that these files have the same owner, group, and permissions as other startup files in those directories. Finally, test your scripts before you restart your machine. To stop PI: root> sh /sbin/rc2.d/k004pi stop Verify that PI processes shut down. root> sh /sbin/rc3.d/s960pi start Verify that PI starts properly. If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d directories until you've debugged and fixed the problems. The files in the /sbin/init.d directory will not affect your system as long as there are no links in the /sbin/rc#.d directories. Automatic Startup/Shutdown for PI on Compaq Tru64 and Tru64 UNIX 4.0x This operating system was originally known as DEC UNIX. Compaq Tru64 UNIX recognizes four run levels: Run Level Purpose 0 shutting down s single user (used for administering the system) 2 local (non-networked) 3 default, networked Which processes run at each level is determined by a set of scripts, /sbin/rc0, /sbin/rc2, and /sbin/rc3. These scripts look in the directories /sbin/rc#.d (where # = 0, 2, 3) for scripts that begin with a "K" or an "S". The "K" scripts are used to kill processes, and the "S" scripts are used to start processes. When the system moves from level 3 to level 2, the "K" scripts in /sbin/rc3.d are executed first if the system is not coming from single-user mode, then the "S" scripts are run (remember the system goes to single-user on boot, then goes to the default run level). The scripts are run in ASCII collated sequence, so K02stop is run before K04metoo. On shutdown or reboot, the system will run the scripts in /sbin/rc0.d. PI Server System Management Guide Page 11

34 Chapter 1 - Starting and Stopping PI You should put the PI startup in /sbin/rc3.d. The shutdown script for PI must be in /sbin/rc2.d, so PI will be shut down if the system goes to non-networked mode, and also in /sbin/rc0.d, so PI will be shut down if the system is halted or rebooted. Note: Compaq Tru64 systems should be restarted using shutdown to go to singleuser mode, then shutdown -r to reboot or shutdown -h to halt. This will cause the shutdown scripts to be run. Using shutdown -r or shutdown -h from run level 3 or 2 will bypass the scripts and simply kill all processes, without taking the time to shut down processes properly. Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So, in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to change the lines that specify where to find PI on your system. #!/bin/ksh # # Filename: /sbin/init.d/pi # # become piadmin to start/stop PI PATH=/sbin:/usr/sbin:/usr/bin export PATH case "$1" in 'start') if [ -f /sbin/init.d/pistart ] ; then su - piadmin -c "/sbin/init.d/pistart" > /dev/console 2>&1 fi ;; 'stop') if [ -f /sbin/init.d/pistop ] ; then su - piadmin -c "/sbin/init.d/pistop" > /dev/console 2>&1 fi ;; *) echo "usage: $0 {start stop}" ;; esac #!/bin/ksh # # Filename: /sbin/init.d/pistart # Make sure to set the directory in these # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistart.sh ] ; then cd /opt/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /sbin/init.d/pistop # Make sure to set the directory in these Page 12

35 1.3 - Automatic Startup # files to your PIHOME directory, in all # places # if [ -f /opt/pi/adm/pistop.sh ] ; then cd /opt/pi/adm ksh pistop.sh fi Next, set the owner, group, and permissions on these files to match the other files in this directory (check the setting on your system): root> chown bin /sbin/init.d/pi* root> chgrp bin /sbin/init.d/pi* root> chmod 755 /sbin/init.d/pi* Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on the startup file is higher than the S## number for inet, and that the K## number for the kill file is lower than the K## number for inet (in both directories). root> ln -s /sbin/init.d/pi /sbin/rc3.d/s96pi root> ln -s /sbin/init.d/pi /sbin/rc2.d/k04pi root> ln -s /sbin/init.d/pi /sbin/rc0.d/k04pi Verify that these files have the same owner, group, and permissions as other startup files in those directories. Finally, test your scripts before you restart your machine. To stop PI: root> sh /sbin/rc2.d/k04pi stop Verify that PI processes shut down. root> sh /sbin/rc3.d/s96pi start Verify that PI starts properly. If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d directories until you've debugged and fixed the problems. The files in the /sbin/init.d directory will not affect your system as long as there are no links in the /sbin/rc#.d directories. Automatic Startup/Shutdown for IBM AIX IBM AIX recognizes numerous run levels: Run Level s (S) or m (M) Purpose Single user (used for administering the system) 2 default multi-user run level 3-9 user defined levels The system determines what processes should run at each level by reading the /etc/inittab file. The lines in this file tell the system what scripts to run at what run levels. The line with the initdefault in it (init:#:initdefault:, where # is some number 2-9) tells the system the default PI Server System Management Guide Page 13

36 Chapter 1 - Starting and Stopping PI run level. Each line with this number after the first colon is executed when entering the default run level. Thus, we need to add a line to the /etc/inittab file: pisystem:2:once:su - piadmin -c /etc/rc.pistart > /dev/console 2>&1 # Start PI Caution: Before editing /etc/inittab, you must save the original under another name. If you do not and make an error while editing, your system will not boot. If your initdefault level is not 2, you should replace the 2 with the appropriate number from initdefault. For shutdown and reboot, the system uses the /etc/rc.shutdown script. If this file does not exist, you should create it. Otherwise, just add the last line below to your current file. If you have to create the /etc/rc.shutdown file, you should give it the same owner, group, and permissions as the /etc/rc file. As before, you are strongly advised to save a copy of the original file under another name before editing this file. #! /bin/ksh # # Filename: /etc/rc.shutdown # su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1 Now you'll have to create these two files you've told the system to use, /etc/rc.pistart and /etc/rc.pistop. Be sure to change the directory in these files to the PI Server directory on your system. #!/bin/ksh # # Filename: /etc/rc.pistart # if [ -f /usr/pi/adm/pistart.sh ] ; then cd /usr/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/rc.pistop # if [ -f /usr/pi/adm/pistop.sh ] ; then cd /usr/pi/adm ksh pistop.sh fi You'll need to change the permissions on these files so that piadmin can run them: root> chmod 755 /etc/rc.pi* Finally, test your scripts before you restart your machine. To stop PI: root> su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1 Verify that PI processes shut down. Page 14

37 1.3 - Automatic Startup root> su - piadmin -c /etc/rc.pistart > /dev/console 2>&1 Verify that PI starts properly. If there is any problem with stopping or restarting PI, you'll need to restore the previous versions of /etc/inittab and /etc/rc.shutdown until you can find and fix the problem. Automatic Startup/Shutdown for HP-UX 9 PI Server is no longer supported on HP-UX Version 9.x. The information in this section is provided as a reference in case you are still running a previous version of PI. You should be aware that Hewlett-Packard no longer supports HP-UX 9.x and recommends upgrading. HP-UX 9 uses the /etc/rc file to control system startup. An individual site may also have additional scripts specified in the /etc/inittab file, to stop and start processes when moving from one run level to another. If so, the PI System Manager needs to determine which run levels should have PI running and which should not, and should put suitable entries in the scripts to stop and start PI when moving from one run level to another. Here, we'll just deal with the basic system, which uses only the standard /etc/rc file. Caution: Before editing /etc/rc, save the original under another name. If an error is made while editing, the system will not boot. In /etc/rc, there is a section intended for use by the local PI System Manager, "localrc()". In this section, add the following lines (be sure to add them before vuelogin, if you have it): # # start PI # su - piadmin -c /etc/rc.pistart > /dev/console 2>&1 There's another directory, /etc/shutdown.d, which has the shutdown scripts for applications on the system. This directory may be empty. In any case, you should create a file, /etc/shutdown.d/pistop, that looks like this: #! /bin/ksh # # Filename: /etc/shutdown.d/pistop # Stop PI gracefully su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1 This file should have the same owner, group, and permissions as the /etc/rc file. For our systems, that means running these commands: root> chown bin /etc/shutdown.d/pistop root> chgrp bin /etc/shutdown.d/pistop root> chmod 555 /etc/shutdown.d/pistop Next create the two files in /etc. Make sure you set the directories in these files to point to your PI Server directory. #!/bin/ksh # # Filename: /etc/rc.pistart PI Server System Management Guide Page 15

38 Chapter 1 - Starting and Stopping PI # if [ -f /export/pi/adm/pistart.sh ] ; then cd /export/pi/adm nohup ksh pistart.sh fi #!/bin/ksh # # Filename: /etc/rc.pistop # if [ -f /export/pi/adm/pistop.sh ] ; then cd /export/pi/adm ksh pistop.sh fi Again, you need to set the owner, group, and permissions: root> chown bin /etc/rc.pi* root> chgrp bin /etc/rc.pi* root> chmod 555 /etc/rc.pi* Then test these scripts before restarting your machine. root> sh /etc/shutdown.d/pistop Verify that PI shuts down. root> su - piadmin -c "/etc/rc.pistart" > /dev/console 2>&1 Verify that PI starts up properly. If there is any problem with stopping or restarting PI, you will need to restore your original /etc/rc file, and remove the new file from the /etc/shutdown.d directory. 1.4 Shutting Down an Individual Subsystem Shutting down an individual subsystem depends on the operating system. On Windows, look in the file adm\pisrvstop.bat for the shutdown procedure; on UNIX, adm/pistop.sh. For restart procedure check adm\pisrvstart.bat and adm/pistart.sh onwindows and UNIX, respectively. Page 16

39 Chapter 2. MONITORING PI SYSTEM HEALTH 2.1 Checking Key System Indicators Each day, check the key elements of your PI System to make sure PI is working efficiently and correctly. By checking the PI System daily, you can catch problems quickly and you also familiarize yourself with the normal state of the system. This makes it easier to interpret system metrics (such as I/O rates) and to find abnormal messages, when they occur. Area What to check Tools Backups Have PI System backups been run? piartool -al Message Log Update Manager Tag Data Snapshot data flow Check the System Message Log to see whether unusual events have occurred. Are the clients connecting to the PI Server normally? Does the Archive data for a reference tag look normal? Is the Snapshot data flow normal? pigetmsg pilistupd pisnap.bat or pisnap.sh piartool -ss Archive data flow Is the Archive data flow normal? piartool -as and piartool -qs Archive Shift Interface Logs IO Rate Counters Performance Counters (Windows) License limits and usage Verify that the expected archives are registered and that you have prepared for the next archive shift. Check the interface logs to see whether unusual events have occurred. Interfaces support writing snapshot rates to PI Points. The IO rate values and timestamps are a good indicator of interface health. All Subsystems publish key performance counters to Windows. Subsystem counters are discussed in this chapter. Check the usage statistics and point counts for your system. Anticipate license increase needs. piartool -al PI Datalink or PI ProcessBook to view or trend the IO rate points. Windows Performance Monitor. PI Performance Monitor Interface. piartool -lic PI Server System Management Guide Page 17

40 Chapter 2 - Monitoring PI System Health 2.2 Viewing System Messages During normal operation, the PI Message Subsystem maintains a central log file for messages from all PI subsystems. PI creates a new log every day, on universal time coordinate (UTC) time. PI puts the log files in the PI\log directory and names each log according to the date. The file names are of the form, pimsg_yymmdd.dat, where: YYY is years since 1900 (for example,if the year is 2000, YY is 100) MM is the month (for example, if the month is January, MM is 01) DD is the day (for example, if it is the fifth of the month, DD is 05) For example, the log file for January 5, 2000 is named pimsg_ dat. PI Message log files are binary files that you can view using the pigetmsg utility.the pigetmsg utility lets you view messages according to time, subsystem, or sender s identity. The pigetmsg utility requires PI to be running Available Log History The number of files left on the system determines the amount of log history available. PI creates a new log file every day. PI keeps log files for 35 days, at which point it automatically purges them from the system. If you want to keep the log files longer than 35 days, you can back them up before PI deletes them. If necessary, you can restore the backed up files at a later date for investigation. Note: The message log can be written (but not read) using function calls in the PI API. It can be both read and written using the function calls in the PI SDK. You can also view the log files from PI SMT Viewing System Messages with pigetmsg In general, the message source is a PI subsystem, but it can be a facility within a subsystem, such as pipoint if a point database error is recorded. You can run pigetmsg in interactive or non-interactive mode. The pigetmsg utility is located in the PI/adm directory. To get help on usage of the pigetmsg utility, type: pigetmsg /? Using pigetmsg in Non-Interactive Mode When you use pigetmsg in non-interactive mode, you specify all necessary parameters on the command line when you call pigetmsg. In this mode, There are no defaults for the start time (-st), end time (-et), or maxcount (-mc) options because the utility requires that at least two of these three parameters (start time, end time, max count) be defined. If start time and end time are specified, the utility returns messages from the start time to the end time. Page 18

41 2.2 - Viewing System Messages If start time and max count are specified, the utility returns the number of messages specified by the max count beginning from the start time. If end time and max count are specified, the utility returns the number of messages specified by the max count up to and including the end time. If start time, end time, and max count are all specified, the utility returns messages beginning at the start time and finishing when either the number of messages specified in the max count or the end time is reached. All the command line options for pigetmsg are listed in the following table. Argument -st -et -mc -id -pn -msg -dc Description Start time. This should be entered in PI time format. End time. This should be entered in PI time format. Max count. This is an integer the total number of messages to return. This is an integer that represents the specific message identification number from the text-file: 0 for the free-format messages. The default is all messages. This is the message source, either a specific program name (pinetmgr) or a wildcard mask (* for all programs, *arc* for all archive related sources, etc.). The default is all programs. A string mask selection for the message text. The default is * (show everything). Number of message to display at one time. The default is to display all messages. Using pigetmsg in Interactive Mode When you run pigetmsg without specifying at least two of the required parameters (-st, -et, and -mc), the pigetmsg utility goes into interactive mode. In the interactive mode, you are prompted to enter these parameters. The standard defaults for the parameters are obtained by entering a carriage return, <Enter>, after each prompt. In the interactive mode, there is a default for the start time, end time, and max count. The default for the start time is *-15m, which is 15 minutes prior to the current time. The end time is * which is the current time and the max count default is no limit. Searching and Sorting the Messages To list all messages received from a specific subsystem such as the Totalizer for today, use: pigetmsg -st t -et "*" -pn pitotal On UNIX systems, * on the command line is expanded to perform a directory search. Thus for pigetmsg it must be specified either as \* or *. The same is true for any mask containing *. To list the last 100 messages that have the word error as part of the message and then display these messages 10 at a time, use: PI Server System Management Guide Page 19

42 Chapter 2 - Monitoring PI System Health pigetmsg -et "*" -mc 100 -msg "*error*" -dc 10 To send pigetmsg results to a file, use the standard output redirection operator (>): pigetmsg -st "*-1h" -et "*" > myfile.txt Using pigetmsg Remotely The pigetmsg utility also supports remote logins to other PI Server systems. An interactive remote pigetmsg session is initiated with the -remote argument: pigetmsg -remote pigetmsg prompts the user for the required connection details: node name, TCP/IP port, user name, and password. The term node refers to the TCP/IP host name or TCP/IP Address of the PI Server. Alternatively, you can initiate a remote passing all arguments on the command line. Parameter -username -port -node -password Description Remote PI Server username TCP/IP port number Remote PI Server node name Remote PI Server password For example, to begin an interactive session as the user, piadmin, with the password, buddy on a remote NT host named Samson, use: pigetmsg -remote -node Samson -username piadmin -port password buddy Viewing Messages When the Message Subsystem Goes Down If the Message Subsystem is not available, messages are written to the Windows error log (or to standard output on UNIX). On Windows, use the Event Viewer to see messages when PI is running as Services, or check the command windows if running interactively. The PI Server messages that went to the event log messages are stored back to the PI Message Log on system startup and on regular time intervals every 3 minutes. On UNIX, you will find a log file for each subsystem in the PI/log directory. On both platform types, some startup messages may be written to these locations before the PI Message Subsystem is active Viewing Message Log Files Generated on other Servers There are times when it is useful to read message log files that were generated on a different PI Server. The PI Message Subsystem executable can be run in an offline mode for this purpose. Running the PI Message Subsystem in offline mode is very similar to pigetmsg; the significant difference is that the log file must be specified. Message log files are created Page 20

43 2.2 - Viewing System Messages daily; each file covers one day. The file naming convention contains the year month and date. The log files are created in the PI\log directory. Even though all messages will be read from the log file, pinetmgr must be running. The PI Message Subsystem executable, pimsgss, is located in the PI\bin directory. Here is an example of running pimsgss offline to view messages from February 27, 2003: D:\PI\bin>pimsgss -file..\log\pimsg_ dat Message ID [A], (0-n) (A)ll (H)ead (T)ail (Q)uit (?): Once the log file is specified, the behavior is identical to pigetmsg. Only messages in the time period covered by the specified file can be viewed. Offline use also allows specifying all arguments on the command line, just like pigetmsg. Messages that match the command line arguments are immediately displayed. Here is an example: D:\PI\bin>pimsgss -file..\log\pimsg_ dat -st "27-feb-03 12:00" - et "27-feb-03 15:00" 0 pinetmgr 27-Feb-03 12:07:16 >> Connection accepted: Process name: piconfig(1696) ID: 88 0 pinetmgr 27-Feb-03 12:11:54 >> Deleting connection: Piconfig(1696), Shutdown request received from piconfig(1696) (8), ID: 88 0 pinetmgr 27-Feb-03 12:35:20 >> Connection accepted: Process name: Piconfig(1484) ID: 89 0 pinetmgr 27-Feb-03 12:38:08 >> Deleting connection: Piconfig(1484), GetQueuedCompletionStatus error: Broken Pipe [109] The pipe has been ended. Connection: Piconfig(1484) (14, 109), ID: 89 0 pinetmgr 27-Feb-03 13:24:08 >> PInet accepted TCP/IP connection, cnxn ID 90 Hostname: olive.osisoft.com, Interpreting Error Messages (pidiag) Sometimes the message log includes error messages. Use the pidiag utility to interpret error codes: pidiag -e errorcode This will display the associated error message. For example, if the error code is 10722, you would type: pidiag -e [-10722] PINET: Timeout on PI RPC or System Call You can also use the pidiag utility to translate operating system error codes, which are always positive numbers. Note that the error code translation takes place on the operating system running pidiag. For example, on Windows, you could issue the command: pidiag -e 2 [2] The system cannot find the file specified. PI Server System Management Guide Page 21

44 Chapter 2 - Monitoring PI System Health Avoid reading error codes from the PI Server message log on one operating system and translating them with pidiag -e on another Subsystem Healthchecks (RPC Resolver Error Messages) Every few minutes, the pinetmgr sends a healthcheck message to each of the PI subsystems. If one doesn t respond within a given amount of time, pinetmgr will report the following message and the subsystem (RPC resolver) is marked off-line. >> Deleting connection: pisnapss, Subsystem Healthcheck failed. If an RPC is made to a subsystem that is marked off-line, the following message is generated. [-10733] PINET: RPC Resolver is Off-Line The following message indicates that the first part of a message was retrieved. This contains the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout occurred. >> Deleting connection: pisnapss, Connection lost(1), [-10731] PINET: incomplete message 2.3 Monitoring Snapshot Data Flow Windows-based PI Server exposes the Snapshot data displayed by piartool -ss as Windows Performance Counters. These counters may be viewed with the Windows Performance Monitor or recorded to the PI Server with the OSI Performance Monitor Interface Listing Current Snapshot Information with piartool -ss The piartool -ss command lists the current Snapshot information every 5 seconds until you type <CTRL-C>. This utility is a quick way to view the overall state of the PI System. It shows the total number of events received and sent to the archive. (The third column gives the difference in the counters over 5 second periods.) Under normal steady state conditions, the Snapshot event count as well as archive posts should increase regularly. Events in overflow queue and Event Queue record count should be zero. Output of piartool -ss should look similar to listing below. $ piartool -ss Counters for 7-Aug-03 14:35:56 Point Count: Snapshot Events: Out of Order Snapshot Events: Snapshot Event Reads: Events Sent to Queue: Events in Queue: 0 0 Number of Overflow Queues: 0 0 Total Overflow Events: 0 0 Primary Capacity Remaining: Page 22

45 2.3 - Monitoring Snapshot Data Flow Each of the counters in the output is explained in the following sections. Note: The piartool utility can monitor a remote PI Server by specifying the -remote argument after all other arguments. piartool prompts the user for remote connection information. Point Count The Point Count is the number of points that are currently defined in the Point Database. It is incremented when a point is created and decremented when a point is deleted. Snapshot Events Counter An Event is the fundamental PI data element. It represents a value or status of a unique data source at a specific time. Specifically an event is a Value, Timestamp, and PointID. Most events come from PI API- or PI-SDK-based interfaces. The PI Subsystems ( Applications ) PI Batch, PI Performance Equations, PI Total, and PI Alarm, as well as manual input and laboratory systems are also event sources. Every Snapshot event increments the Snapshot Events Counter. The PI Snapshot Subsystem applies a compression algorithm to every event. The compression algorithm determines if the previous Snapshot event is passed on to the archive. Out of Order Snapshot Events Counter Events older than the current Snapshot event are out-of-order events. These events bypass compression and are sent directly to the archive. This counter shows the number of times this has occurred. The Archive Subsystem maintains a similar counter; see the Monitor Archive section in this chapter. Large out of order event counts might indicate a problem with the PI Server; this may lead to poor performance. A common cause is an erroneous system clock changes of the server machine or a data source machine. To identify the tags receiving out of order data use: piartool -ooo This gives a list of all the tags with any out of order events since the Snapshot Subsystem started or since the out of order flags reset. To reset the flags use: piartool -ooo -r When the -r flag is used, only tags that received an out-of-order event since the last piartool - ooo query are listed. The utility can run repeatedly with or without the -r flag by specifying a wait time (in seconds) between repeats. This is useful for catching the offending tags as new events come in: piartool -ooo 10 Whenever a repeat time is specified, a current timestamp appears in the output each time the utility writes data. When using repeats, the utility is stopped with <CTRL-C>. $ piartool -ooo -r 10 PI Server System Management Guide Page 23

46 Chapter 2 - Monitoring PI System Health 7-Aug-03 14:42:12> The following points had out-of-order Snapshot events: 15: pitot1 17: pitot3 18: pitot4 19: pitot5 20: pitot5run 21: pitot5ramp 22: pitot5est 23: pitot_avg 24: pitot_max 25: pitot_min 26: pitot6count 27: pitot6time 28: pitot6timene 29: pitot_1 7-Aug-03 14:42:22> No out-of-order Snapshot events found 7-Aug-03 14:42:32> No out-of-order Snapshot events found Snapshots Events Read Counter Count of all Snapshot reads. This is a simple measurement of how many Snapshot values are read by all applications. Events Sent to Queue Counter Events that pass compression, or are out of order are sent to the Event Queue, and thus increment this counter. Under normal operating conditions this count indicates the number of events that passed the compression test (that is, the events were different from existing events and could not be eliminated) and are being sent to the archive. The ratio of Snapshot events to Events Sent to Queue is the system aggregate compression ratio. This ratio gives a quick view of overall system compression tuning. Ratios less then 2:1 indicate low compression; a compression tuning evaluation should be performed. Ratios greater than 10:1 indicate over compression; a compression tuning evaluation should also be performed. Three Point Database attributes affect compression: CompDev, CompMin, and CompMax. These are known as the compression specifications. If a point has its Compressing point attribute set to FALSE, all new events are sent to the Archive Subsystem. Events in Queue Counter Events passed to the EventQueue are put in First-In-First-Out order. The Events in Queue Counter is incremented when the event is put in the Queue; it is decremented when the Archive Subsystem successfully retrieves and processes an event. When the system is shutdown, the Event Queue is preserved in the file PI\dat\pimapevq.dat. This assures no data loss when the system shuts down or when the archive subsystem is not processing events at the same rate as they come in. Page 24

47 2.4 - Monitoring the Event Queue Number of Overflow Queues Counter If the queue PI\dat\pimapevq.dat becomes completely full, a new queue is created. This should not occur under normal circumstances and this number will be 0. However, if the archive is not processing events, a number of such queues (up to 65536) can be created. This counter shows how many queues were created. These additional queues are automatically deleted after the archive subsystem processes them. Note: When multiple Event Queues exist, the file pimapevq.dat is renamed to pimq0000.dat and additional queues are named pimq<id>.dat where id is the queue number in hexadecimal representation (from 0000 to FFFF). The piartool -qs command always shows information from the queue to which the Snapshot Subsystem is writing (primary queue). Total Overflow Events Counter This is the total number of events in all Overflow Queues. The sum of this counter and the Events in Queue counter are all the events not yet processed by the archive. Primary Capacity Remaining Counter This counter shows the estimated number of additional events that can be placed in the primary queue. 2.4 Monitoring the Event Queue After installation and regularly after significant changes, the System Manager should verify the proper sizing and functioning of the Event Queue. The command piartool -qs allows you to look at internal counters and statistics about the queue activity piartool -qs The piartool -qs command lists the Event Queue statistics every 5 seconds until you type <CTRL-C>. The column at the right margin gives the difference in the count since the previous 5 seconds. The counters are reset to 0 when the Archive Subsystem is started. $ piartool -qs Counters for 7-Aug-03 17:22:45 Physical File Size (MB): 64 0 Page Size (KB): Total Data Pages: 63 0 Write Page Index: 0 0 Read Page Index: 0 0 Total Page Shifts: 0 0 Available Pages: 63 0 (100.0%) Average Events per Page: Estimated Remaining Capacity: (2.2 hr) Total Bytes Written (MB): 0 0 Total Event Writes: (579/sec) PI Server System Management Guide Page 25

48 Chapter 2 - Monitoring PI System Health Total Event Reads: (579/sec) Current Queue Events: 0 0 Overflow Queues: 0 0 Total Overflow Events: 0 0 Current Queue Id: 0 0 Queue Size The Physical File Size shows the current size of the Event Queue on disk (the file pimapevq.dat or any overflow queues). The Page Size is the portion of the file that is loaded into memory for faster access. The Event Queue is a circular buffer of pages and each page is a circular buffer of events. When a page is full, the Snapshot Subsystem tries to write into the next one and the Archive Subsystem reads the pages in the same order they were written. The Total Data Pages shows the number of pages, obtained by dividing the queue size by the page size (minus one for the queue header). Page Activity The Write Page Index shows the page the Snapshot Subsystem is currently writing to. Similarly, the Read Page Index indicates the page from which the Archive Subsystem is reading. Under normal conditions, these two numbers are identical. If the Archive Subsystem is not reading at the same pace the Snapshot is writing, page shifts will occur and the Total Page Shifts counter will increment. At any time, the Available Pages counter shows how many free pages are left in the current queue. Queue Capacity Based on the average size of all events, the Snapshot Subsystem maintains the number of Average Events per Page. From this it derives an Estimated Remaining Capacity in number of events (also shown by piartool -ss). Total Bytes Written shows the volume of data that transited through the Event Queue since the Snapshot Subsystem was last started. Note: A System Manager should try to configure the queue so that it is big enough to hold a few days worth of data. To configure the queue size, see Tuning the PI Server in Chapter 3, Troubleshooting and Repair. Event Rates Every time the Snapshot sends an event to the archive, the Total Event Writes counter gets incremented. Similarly, when events are read by the Archive Subsystem, the Total Event Reads is incremented. The difference between these counters shows the Current Queue Events (total events per queue). Overflow Queues When the current queue is entirely full, the Snapshot Subsystem creates additional queue files of the same size. The Overflow Queues counters and Total Overflow Events (same as in piartool -ss) indicates how many queues exist and how many events they hold. The Current Page 26

49 2.5 - Monitoring the Archive Queue Id shows the sequence number of the primary queue (always 0 under normal conditions). 2.5 Monitoring the Archive On a daily basis, the System Manager should look at the internal counters for the Archive Subsystem. This enables you to predict the next archive shift as well as to monitor ongoing system behavior and performance. You can use piartool -as and piartool -al for this purpose. Other piartool commands are discussed in the chapter, Managing Archives. Note: Windows-based PI Server exposes the Archive data displayed by piartool -as as Windows Performance Counters. These counters may be viewed with the Windows Performance Monitor or recorded to PI Server with the OSI Performance Monitor Interfaces. This subject is covered in detail later in this chapter piartool -as The piartool -as command lists the Archive Subsystem (piarchss) internal counters every 5 seconds until you type <CTRL-C>. The column at the right margin gives the difference in the count since the previous 5 seconds. The counters are reset to 0 when the Archive Subsystem is started. $ piartool -as Counters for 7-Aug-03 14:51:10 Archived Events: Out of Order Events: 0 0 Events Cascade Count: 0 0 Events Read: 5 0 Read Operations: 0 0 Cache Record Count: 0 0 Cache Records Created: 6 0 Cache Record Memory Reads: 5 0 Cache Clean Count: 0 0 Archive Record Disk Reads: Archive Record Disk Writes: Unflushed Events: Unflushed Points: Point Flush Count: Primary Archive Number: 5 0 Archive Shift Prediction (hr): 1 0 Archiving Flag: 1 0 Archive Backup Flag: 0 0 Archive Loaded Flag: 1 0 Shift or System Backup Flag: 0 0 Failed Archive Shift Flag: 0 0 Overflow Index Record Count: 0 0 Overflow Data Record Count: These counters are explained below. PI Server System Management Guide Page 27

50 Chapter 2 - Monitoring PI System Health The piartool utility can run remotely by specifying some additional parameters on the command line as described in Table 3 1. Options for Use with piartool on page 37. Archived Events Counter The Archived Events counter is incremented for every new event written to the archive (via the archive cache). This count includes delete and edit events. Out-of-Order Events Counter The Archive Subsystem receives events from the Snapshot Subsystem. If the timestamp of the event is older than the last event in the target record, it is considered an out-of-order event and is added to this counter. Excessive out-of-order events might lead to system problems such as excess CPU consumption, excessive disk I/O, and archives filling faster than expected. Events Cascade Count Out of order events are inserted into the target record. The insert requires moving other events within the record. If the record is full, one or more events are forced out of the record into the adjacent record. This counter is incremented each time an insertion forces an event out of a record. This counter is an indication of the impact of out of order events on the archive. Events Read Counter Number of events read by all applications. For example, a trending application requests an array of events over a specified time period. This counter is incremented for each event returned. Read Operations Counter Number of archive read requests. Each archive read request increments this counter once, regardless of the number of events returned. Archive Memory Cache Counters The Archive Subsystem uses a memory cache when handling events sent to the archive disk file. During routine operation, the cache is automatically flushed to disk at least every 15 minutes. Abrupt system shutdowns, such as power loss, should lose no more than the last 15 minutes of data. This value may be changed via a configurable timeout table parameter. The data archive cache architecture provides large performance gains over reading and writing directly to disk. The cache even provides significant performance over the Operating System file cache. As with all file cache designs, the disk image will often be slightly inconsistent; therefore archive backup cannot be performed without coordination with the Archive Subsystem. The utility piartool -bs places the archive in a safe consistent state for backups; piartool -be returns the archive to normal operation. This is discussed in detail in the system backup section in Chapter 3, Troubleshooting and Repair. Page 28

51 2.5 - Monitoring the Archive The cache consists of archive records loaded into memory. Records are added as needed; they are deleted when unused for a certain length of time. Cache Record Count yields the current count. Cache Records Created is incremented when memory is allocated for a new record. When archive data is requested (for example, the user is trying to trend a point in PI ProcessBook), the Archive Subsystem goes to the cache to retrieve the event data. If the record is not there, the Archive Subsystem loads the record from disk to the cache; Archive Record Disk Reads is incremented. When writing events to the archive, they are stored first in memory. Unflushed Events Counter indicates the total number of events not yet flushed to disk. Unflushed Points counter indicated the number of points with any number of events not yet flushed. Archive Record Disk Writes is incremented each time a record is written to disk. This occurs during the regular cache flush every 15 minutes. It also occurs when the number of unflushed events for a point exceeds the configured maximum. Cache Record Memory Reads is incremented for each read access. Cache Clean Count indicates the number of records that were removed from the cache. The archive cache contains a finite number of records. Old or low use records are removed from memory to make room for most recently accessed records. Primary Archive Number The Primary Archive Number is an internal identifier and should be ignored. It is not to be confused with the sequence number of the archive, as listed by piartool -al. Archive Shift Prediction Archive Shift (hr) estimates the predicted time to the next archive shift. Use piartool -al to list the target archive file for shift. The target archive will be initialized on shift; if it contains data, make sure it is backed up. If this data is required to remain online, a new archive of adequate size should be created and registered. When the current archive is less then 20% full, the estimate is 0. In order to determine whether a zero estimate means the archive is nearly full or not, run piartool -al. The message will tell you if there is not enough data for a prediction. Shift Time: Not enough information for prediction The shift prediction in piartool -as differs slightly from the one in piartool -al. The piartool -al figure is calculated when called. piartool -as shows the latest 10 minutes average. The latter number is available as a Windows Performance Counter. Archiving Flag Indicates whether or not events may be written to the archive; a value of 1 indicates events may be written, a value of 0, events may not be written. The Archiving Flag is set to 1 when there is a mounted Primary Archive. A Primary Archive may be registered but not mounted, for example during an archive shift. In this case, the Archiving Flag would be set to 0. This flag is also set to 0 when in backup mode. PI Server System Management Guide Page 29

52 Chapter 2 - Monitoring PI System Health All registered archives may be viewed using piartool -al. The Archive Flag is set to 0 if the Primary Archive becomes full and there is no other archive file available into which to shift. Note that the Primary Archive will never overwrite itself. Archive Backup Flag This flag is set to 1 when the archive is in backup mode. Backup mode indicates the archive file is in a consistent state unlocked state and may be backed up. The value is 0 when the archive is available for normal access. Backup mode is entered and exited by running piartool -bs and piartool -be, respectively. Archive Loaded Flag This flag is 1 when a valid primary archive is mounted. 0 if the primary archive is not mounted. Shift or System Backup Flag This flag is 1 when the archive is in shift mode or the Archive Subsystem has been placed in backup mode. Shifts occur automatically or can be forced via piartool -fs. System backup mode is entered with piartool -systembackup. Failed Archive Shift Flag Set to 1 when a shift should occur but no shiftable archive exists. Under normal conditions this flag is 0. Overflow Index Record Count Number of index records. Index records speed up access to overflow records. Index records are created when two overflow records for a point are full and third one is being created. This counter is a measurement of archive file consumption. Overflow Data Record Count Number of non-primary data records. Each archive has a primary record for each point. When this record is full, data is written to overflow records. This counter gives a measurement of archive consumption. 2.6 Monitoring the Update Manager The Update Manager provides change notification of Snapshot events, Point Database, Module Database, Batch Database and Archive changes for applications such as PI ProcessBook, Interfaces, and other PI API or PI-SDK-based applications. For example, a trend application can request Snapshot update notification on points being trended. The Update Manager queues all new Snapshots for these points. Periodically the trend application retrieves and plots the new events. Page 30

53 2.7 - System Date and Time Adjusting the Pending Update Limit By default, the PI Update Manager maintains up to 4095 pending updates per consumer. Similarly, TotalUpdateQueue parameter sets the maximum events queued in the entire update-manager database. The default is 100,000. If either these limits is reached, a message is sent to the PI Message Log. Another message sent when the level goes back below 99% of the limit and queuing is resumed. Messages for consumers using less then 0.1% of the TotalUpdateQueue limit (100 for the default) are still queued even when the total limit is reached. It is possible to change this number by adding an entry named MaxUpdateQueue to the PITimeout Table using piconfig: C:\PI\adm>piconfig * (Ls - ) pi_gen,pitimeout * (Ls - PI_GEN) create * (Cr - PI_GEN) name,value * (Cr - PI_GEN) Piconfig> maxupdatequeue,6000 *> maxupdatequeue,6000 * (Cr - PI_GEN) When to Change the Pending Update Limit The default is suitable for most systems, with the following exceptions: The number should be increased on systems with very large physical memory, high frequency of updates (normally snapshots) and applications that might retrieve these updates slowly. Changes to the MaxUpdateQueue parameter take effect only after the PI Server restarts. If a PINet node or PItoPI interface is connected to the PI Server, the default MaxUpdateQueue value is too small. It should be increased to at least the point count of the PI Server. This value ensures that all point updates requested by PINet can be queued on the PI Server if a system manager performs an edit operation on every point. How to Change the Maximum Number of Events in the Queue It is possible to change this number by adding an entry named TotalUpdateQueue parameter in the PITimeout Table sets the maximum events queued in the entire updatemanager database. The default is 100,000. You can use piconfig to change the limit. 2.7 System Date and Time The PI server uses the Windows clock, including the time zone and Daylight Savings Time (DST) settings to track time. If the system clock isn't right, the PI data isn't right either. You might even lose data if the system clock is wrong. As the PI System Manager, you must: Check the system clock regularly PI Server System Management Guide Page 31

54 Chapter 2 - Monitoring PI System Health Adjust the clock toward the correct time Adjust the clock only in small increments (for example, one second per minute) Keep a record of all adjustments you make Internally, PI stores all data in UTC time and translates back to local time when serving the data to a client application. If you set all the Windows machines involved to the correct time, time zone, and DST settings, PI can seamlessly handle clients in multiple time zones as well as DST transitions. Challenges a PI system administrator may face when configuring the clock on a PI server include irreconcilable differences in the clocks of the PI server, the data systems from which the data is being collected, and the clocks of the PI users on the corporate LAN or WAN. Complications will most commonly arise when data is collected from legacy systems with clocks that have been configured inaccurately or allowed to drift. The best thing to do in this case is to set all clocks to the correct time. If this is not possible, you need to decide on a workaround. may be available depending on the data collection interface process being used. The most common workaround is for the interface process to read the current values from the legacy system and send them to the PI with the current PI server time as the timestamp. Page 32

55 Chapter 3. MANAGING ARCHIVES 3.1 Tasks for Managing Archives PI Archive Management includes significant tasks for the PI System Manager, including: Archive creation and deletion Archive sizing Archive shifting Archive backups Archive splitting/combining/compressing Archive repair 3.2 About Archives The PI System stores your data in Archives, which are just files for holding PI data. Archive files can be either fixed or dynamic. Fixed archive files are always the same size, regardless of how much data they contain. Dynamic archive files grow in size as they get data. (See About Fixed and Dynamic Archives for a complete explanation.) The archive receiving current data is called the Primary Archive. When the Primary Archive becomes full, an Archive Shift occurs and the next available archive becomes the new Primary Archive About Archive Shifts PI actually performs the archive shift before the Primary Archive is completely full. This leaves some extra space in the archive file so that you can add data later, if you need to. For an archive file to be eligible to be the new Primary Archive, it must be writeable, and large enough to handle the current size of the Point Database and it must also be registered. Registering an archive file is how you make an archive file accessible by PI. When an archive file is registered, it is made visible to the PI Server. The data in unregistered archives are not accessible by the PI Server or its client applications. See Registering an Archive on page 56 for more information. PI Server System Management Guide Page 33

56 Chapter 3 - Managing Archives If no eligible archives are available for an Archive Shift, PI uses the oldest available filled archive as the new Primary Archive, overwriting the data in the old archive. For example in the preceding illustration, after the shift from piarch.003 to piarch.004, no empty registered archives are left on the Server. If the System Manager does not create new archives on this PI Server, then at archive shif piarch.001 becomes the next Primary Archive and the PI Server overwrites the existing data in that archive. It takes PI a few minutes to complete an Archive Shift. During that time, you are not allowed to add, edit or delete points. PI stores incoming data in the Event Queue until the shift is complete and then writes the queued events into the new Primary Archive About Archive Files Each archive file contains events for a time period specified by the archive start time and end time. The archive files on each PI Server should cover all time ranges, without overlapping time ranges or gaps in time. Archives range in size from 2 megabytes to 2 terabytes (2,048 gigabytes) on Windows NT. On UNIX, the maximum size is 2 gigabytes About Archive Gaps Archive gaps are times for which no archive file exists. If an event is sent to the Archive and no archive file with the appropriate time range exists, the event is discarded and an error is logged. If data retrieval is attempted for a time range that is not covered by the set of registered archives, an error or a no data status is returned. About Archive Records PI archive files stores events as data records. Data records are either primary records or overflow records. Each point in the Point Database has one primary record allocated in every archive file. Primary records are stored at the very beginning of the archive file. When the primary record for a point fills up, the data for that event goes to an overflow record in the Page 34

57 3.2 - About Archives archive file. Overflow records start at the end of the archive file and are filled backwards. Each record is one kilobyte. A point can have as many overflow records as needed. Points that receive events at a slow rate might never need to allocate an overflow record, whereas points that receive events at a fast rate might need to allocate many overflow records. (PI uses index records to keep track of multiple overflow data records for a point). Note: When the Archive allocates a new overflow record for a point, it writes the new record to disk immediately, along with any existing records that reference the new record. About Index Records Index records are records that index a point s data records by time. After one overflow record is full for a point, PI creates an index record for the point, along with a new overflow record. An index record can hold between record points. When the record index is full, PI creates a second record index and these are chained. Archive access for points with chains of index records are marginally slower than for points with zero or one index record About Primary Archives The Primary Archive is the archive file that covers the current time range. The Primary Archive has a defined start time but no defined end time (it is always assumed to be now. ) The end time for the Primary Archive is defined when an archive shift occurs. An archive shift is the process of replacing the primary archive with a new or cleared archive. If it exists, an empty archive is selected to be the new Primary. If no empty archive exists, then the oldest archive becomes the Primary and its existing data is overwritten. Another option is automatic creation of archives. If this is in effect, a new archive file with the same characteristics as the current Primary Archive is created during the shift. PI ensures that some space is still available at the time of the shift. This way, out-of-order events can still be stored in the archive after it is no longer the primary archive. For more information, see the Archive Shift section in this Chapter About Fixed and Dynamic Archives There are two types of Archive files, fixed and dynamic. PI Server System Management Guide Page 35

58 Chapter 3 - Managing Archives Fixed Archives The default archives that are installed with a PI System are fixed archives. They have the following characteristics: Fixed archive files have all of their disk space allocated at creation time. An empty archive and a full archive take the same amount of disk space. Fixed archives may or may not participate in archive shifts, depending on the point count to archive size ratio and the state of the shift and write flags. New points may be added to a primary fixed archive. Use fixed archives for all normal operations. Filling up Fixed Archives It is possible for a fixed (non-primary) archive to get completely filled up. Once an archive is full, incoming data events for that time range have nowhere to go, and are discarded. This can occur if a large quantity of old data is to be added to the Data Archive, and go to an old archive which is already full. In such cases it is best to stop the Archive Subsystem to prevent any further data loss. Then create a new, larger, fixed archive with the same time range of the full archive and copy the contents of the full archive to the new large archive using the Offline Archive Utility. When the new large archive is registered in place of the full archive, incoming data events for that time range is no longer discarded. Dynamic Archives Dynamic archives have the following characteristics: Like fixed archives, dynamic archives are for a specific time range. Dynamic archives that already contain data are not eligible for Archive Shift. Newlycreated dynamic archives participate in the standard shift algorithm, if they are registered. Dynamic archives do not contain unallocated space waiting to be used for overflow records. Rather, the file grows as overflow records are added. Dynamic archives have a maximum archive size (specified at archive creation). The default maximum archive size is 1 Gbyte or 10% less than the maximum available disk space, whichever is less. Dynamic archives are initialized with a fixed number of primary point records. Once a dynamic archive is created, the number of primary records cannot grow beyond the initial allocation, even if there is space in the file. Note: You can create dynamic archives with a number of primary records higher than the current number of points. This allows users to create additional points in a dynamic primary archive. Users can add new points as long as the number of points does not exceed the number of primary records specified when you created the dynamic archive. To create this type of dynamic archive, use the piarcreate -acd command. Page 36

59 3.3 - Tools for Managing Archives Using Dynamic Archives To understand the usage of dynamic archives, consider this example. A PI System Manager wishes to combine the data in two old archives into a single archive file. The Offline Archive Utility is run twice: once to copy data from the earlier archive and again to add data from the second archive. Assuming that the Offline Archive Utility is allowed to create the archive file on its first pass (or piarcreate was used to create a dynamic archive in advance), the resulting archive contains data from the two input archives and has no free records. This potentially makes the new archive smaller than the combined size of the input archives and able to accommodate additional data as long as the maximum growth size is not exceeded About Read-Only Archives Archive files that have a read-only file-system attribute, or files on a read-only device (CD ROM) are mounted as read-only. Their status will show up on the piartool -al display as not writable. Read-only files cannot participate in archive shifts. New events in the time range of such an archive go into the archive cache, but when flushed to disk, an error message is logged for each event. This includes attempts to edit, delete or annotate events in a read-only archive. 3.3 Tools for Managing Archives There are three main command line tools for managing archives: piartool: The main archive management utility. You can use it to create, register and unregister archives, force archive shifts, list details of archive files, and much more. You can use piartool only when PI is running. piarchss: The Archive Subsystem, piarchss, includes an Offline Archive Utility. You use this utility to process existing offline archives. For example, you use piarchss to combine multiple archives into one, to divide large archives into multiple archives, to recover corrupted archives, and so on. piarcreate: Use thie piarcreate utility to create new archives Using the piartool Utility The following table lists the command line options for the piartool utility. You can only use piartool when PI is running. Table 3 1. Options for Use with piartool Option Name Action -aag Archive Activity Grid Enable/Disable the archive activity grid, and list the Archive access information. -ac Archive create Create an archive for specified period -acd Dynamic archive create Create a dynamic archive for specified period. PI Server System Management Guide Page 37

60 Chapter 3 - Managing Archives Option Name Action -ads -aes Archive disable shift Archive enable shift Removed specified archive from shift participation. Add specified archive to shift participation. -al Archive list List all registered archives -ar <path> Archive register Register a specified archive -as Archive statistics Archive Subsystem activity monitor and statistics -au <path> Archive unregister Unregister a specified archive -aw Archive walk List details of the records in an archive file -Backup ['path'] [- component <comp>] [-numarch <number>] [More Options listed under Action] Perform a System Backup Start/End/Query a backup of the PI system. The path points to where the resulting backup files are placed. The optional component specifies which part of the PI system is backed up. The numarch option specifies how many archives (starting from the current archive and working backupwards) are backed up. By default all archives are backed up. Additional options include: -query [-verbose] Inquire about the current backup status. -abort Abort a running backup. -identify [-numarch <number>] [-cutoff <date>] [- verbose] Identify files able to be backed up. In verbose mode the individual components are listed. The numarch and cutoff options override default until next backup. -test <freeze,component thaw> Test but don t actually perform a PI system backup. -block Block Wait for a specified subsystem to become responsive. Used in PI start scripts. -cad 'tagname' [-reset] -cas ['tagmask'] -cs [For troubleshooting only] -de <path> [-pt tagname] [recno] Archive cache diagnostics Archive cache summary PINetmgr connection stress test Dump eventqueue Archive cache diagnostics for a specified point. Display the events sitting in the read and write cache. Display a summary of the contents of the archive cache, including the number of events in the Read and Write caches for every point that matches the tagmask. PI Network Manager connection stress test. Dump specified Event Queue file. Optionally select a specific tag and/or specific record in the file. Page 38

61 3.3 - Tools for Managing Archives Option Name Action -disconnect - subsystem <name> [- id <id>] [For troubleshooting only] Force Subsystem Disconnect Force the specified subsystem to disconnect from pinetmgr, or if pinetmgr is specified, instruct pinetmgr to disconnect the connection based on the connection ID passed. The -graceful option causes a disconnection notice to be first sent by pinetmgr or the target subsystem. -fs Force shift Force an archive shift. -idci <in file> -idco <outfile> -lic [Options listed under Action] -mpt <0 1> [For troubleshooting only] -msg "message" [-pro "procname"] [-nrep m] [-nbuf l] [-nmps n] [For troubleshooting only] -msgtest <startsize in bytes> <endsize in bytes> [For troubleshooting only] ID conversion file creation Licensing Information Message protocol trace Message Subsystem Test PINetmgr Communications Test Create ID conversion file from specified input file. Usage List options for viewing license info Def List all licenses User List all licenses in use Lic List all licenses and users AllowedApps <-List <type,type...> -Check <app,app,...>> List the types of licenses or check whether a specific feature is licensed Log all communication coming to and from the server. To enable tracing run with -mpt 1. Call a second time with -mpt 0 to stop tracing. The resulting output file appears in the \pi\temp directory with the.mpt extension. The file can be read with the mptconsolveview utility, which OSISoft provides on request, e.g.: Mptconsolveview.\24-Aug-05_ mpt Sends a series of test messages to the PI message log. Can emulate sending messages from any process. Nrep sets how many messages are sent, nbuf sets how many messages are sent at a time, nmps attempts to throttle how many messages are sent per second. Send a series of test messages to the PInetmgr. Message size increases by one byte increments starting from startsize to endsize. PI Server System Management Guide Page 39

62 Chapter 3 - Managing Archives Option Name Action -netstress [-SendBlocks 1] [- RecvBlocks 1] [-loops 1] [For troubleshooting only] -ooo <-r><sec> PINetmgr stress test. Out of order snap events Test PINetmgr subsystem by sending and receiving specified 4k blocks. Show tags with Out of Order events. Optional Reset and Repeat. -qs Queue statistics Monitor Event-Queue activity and statistics -re [-subsystem <name> -pid <#> ] [For troubleshooting only] Raise Exception Raise exception in specified subsystem (force a crash). This call only works locally; remote is not supported. -remote Remote system Run utility against a remote system. When this argument is included as the last argument in any valid command the utility prompts for remote system login information. If successful the utility runs against the remote system. -rpctest <subsystem> <count> [For troubleshooting only] Inter-process Communication Test -ss Snapshot statistics Snapshot Subsystem activity monitor and statistics -standalone <n> Standalone mode Place PI Server in standalone mode. Possible values for n are: 1 Enter standalone 0 Exit standalone 2 Query current state -systembackup System Backup Start/End backup for a specified subsystem. Deprecated in favor of -backup. -thread 'subsystem' [Options listed under Action] Subsystem Thread Control Times the RPC round trip to the specified subsystem. -info List a subsystem's threads -id <Thread ID> <-disable -enable -suspend -resume -terminate hang -add -break -priority <Direction>> Perform an action on a particular thread -v Version Get version and build information Using the Offline Archive Utility (piarchss) The Offline Archive Utility is actually the same Archive Subsystem executable, piarchss that is a part of a running PI system. To use the archive utility functions of piarchss, you run it in Page 40

63 3.3 - Tools for Managing Archives console mode using special command line arguments. The offline archive utility can be used even while PI is running. You typically use the piarchss utility to work with archive files outside the context of a running PI Server. This enables you to continue archiving current data on your PI Server, while manipulating other archives offline. Typical applications of the offline tool include: Combining a number of archives together Dividing a big archive file into smaller archives Extracting specific time period from an archive Recovering a corrupted archive Recovering events from an Event Queue file Converting PI2 archive file to the PI3.x format. Note: The archives that are created by the Offline Archive Utility may be either fixed or dynamic. Their format is not different from any other archives created by piartool -ac. Running the Offline Archive Utility When you run piarchss as the offline archive utility, you give it an input archive file and an output archive file, along with relevant command parameters. The basic format is: piarchss -if inputpath -of outputpath where inputpath is the full path and filename of the input archive file and outputpath is the full path and filename of output archive file. The piarchss utility takes the input file, processes it according to the command parameters, and then outputs the processed file to whatever location you specified. The piarchss utility does not modify the input file under any circumstances. The piarchss Utility Command-Line Parameters This section provides a list of all the command line parameters for the piarchss offline archive utility. Some of these options are discussed in more detail in the following subsections. The parameters may be specified in any order. Parameter Name Notes -if <full path name> -of <full path name> -ost <option> -oet <option> Input Archive File Output Archive File Output file Start Time Output file End Time Required. The full path, including drive letter is required. This is true for all file arguments passed. Required. Options: Input, Event, <time>, NFE See Specifying a Start Time for the Output File (-ost). Options: Input, Event, <time>, NFE, Primary, NoChange PI Server System Management Guide Page 41

64 Chapter 3 - Managing Archives Parameter Name Notes See Specifying an End Time for the Output File (-oet). -f <size in Mbytes> Make output archive a fixed archive If size = 0, the input file size is used. Default is dynamic archive. -tzf <full path name> TimeZone specification file Use when PI2 input different from standard DST - see also the PI Server Reference Guide, Appendix D. -filter <start end> Filter Process events only within the time range specified. Both timestamps must be provided. See Time Filtering (-filter). -dup Duplicate Records Allow input archive records with duplicate times. By default duplicates are ignored. -tfix Time Fix Apply a specified time transformation to input data. See Transforming Event Timestamps (-tfix). -silent Silent Mode Suppresses warning messages. -vah Validate Annotation Handles Apply a validation algorithm. Multiple events referencing a single annotation are detected and fixed. Batch Database annotations are checked for consistency. Specifying a Start Time for the Output File (-ost) The -ost flag specifies the start time for the output file. The usage is as follows: -ost option Where option is one of the following: input event time (where time is specified in absolute PI time format) NFE Sets the start time to the start time of input. This is the default behavior. Sets the start time to time of first event in input. Sets the start time to the specified time string. Times are specified in absolute PI time format. Relative times are not supported. Times must be enclosed in double quotes when containing spaces. If only date is specified the time defaults to 00:00:00 (midnight) For example: 22-JAN-02 23:59:59 23-JAN Feb Output file start and end times must differ by at least one second. Sets the start time to time of first event which passes the time filter. Page 42

65 3.3 - Tools for Managing Archives Specifying an End Time for the Output File (-oet) The -oet flag specifies the end time for the output file. The usage is as follows: -oet option Where option is one of the following: input event time (where time is specified in absolute PI time format) NFE primary NoChange Sets the end time to the end time of input file.this is the default behavior. Sets the end time to the time of last event in input file. Sets the end time to the specified time string. Times are specified in absolute PI time format. Relative times are not supported. Times must be enclosed in double quotes when containing spaces. If only date is specified the time defaults to 00:00:00 (midnight). For example: 22-JAN-02 23:59:59 23-JAN Feb Output file start and end times must differ by at least one second. Sets the end time to time of last event which passes the time filter. Sets the end time to indicate the archive is a primary archive. End time is not altered. Time Filtering (-filter) The -filter flag specifies a time range (inclusive) beyond which events are discarded. The usage is as follows: -filter starttime endtime Start time must be before end time. Specifying an ID Conversion File (-id) Use the -id option to specify an ID conversion file (used to move a PI archive to a different PI Server). The ID conversion file is a binary file that maps the source archive point ID into the target system point ID. When ID conversion file is used, only points included in this file are converted. This is always necessary when archives are migrated from a PI2 system, or when data is brought from another PI3 system. The binary file is created from an input text using the piartool utility. piartool -idci <id conversion input file> -idco <id conversion binary file> The ID conversion input file is the full path and file name to the input text file. The ID conversion binary file is the full path and name to the binary file to be created. piartool reports any point in the input file that does not exist in the target system. PI Server System Management Guide Page 43

66 Chapter 3 - Managing Archives ID Conversion Input File Format Every record of the input file must have this format: Point ID, Recno, TagName On a foreign PI3 system you can create this file as follows: e:\pi\adm>piconfig * (Ls - ) pipoint * (Ls - PIPOINT) pointid, recno, tag * (Ls - PIPOINT) Note: The piartool -idci input file does not allow for comment characters. The comment character ( * ) generated by piconfig must be removed. Transforming Event Timestamps (-tfix) Offsets, as a function of time, are defined in the time conversion file. This can be used to apply corrections to times on some systems that had incorrect timestamps due to run-time library problems, or non standard DST setting. This adds a given time offset to every event: -tfix <conversion file> Time Conversion File Format Lines starting with # are comments. Empty lines and white spaces are ignored. Data lines have the format: Starttime, offset Start-time may be expressed as UTC - seconds since 1/1/70 or as PI local timestamp string: dd-mmm-yyy hh:mm:ss * *-1s UTC timestamps and strings cannot be intermingled, the first format is assumed for all entries. Offset is a number of seconds added to the timestamp of every event within the time range. Fractional seconds are not supported. Offset applies from timestamp up to, but not including the next timestamp. Time Conversion File Examples Move entire archive ahead by 1 hour: 0, ,3600 Move entire archive ahead by 1 hour (another format): Page 44

67 3.3 - Tools for Managing Archives 01-Jan-70 00:00:00, Jan-10 00:00:00,3600 Applies a missed DST conversion to an archive that covers the summer of 1997: 01-Jan-02 00:00:00,0 06-Apr-02 02:00:00, Oct-02 02:00:00,0 31-Dec-02 23:59:59,0 A series of UTC values and offsets: , , , , Tips for Using the Offline Archive Utilty If you re working with the piarchss offline archive utility, note the following: The full path name of the input archive must be specified. (Note that piartool -al lists only registered archives.) If the input file is registered, the Offline Archive Utility un-registers it when processing begins. If the input archive is the Primary Archive, it cannot be unregistered. To work around this, force an archive shift using piartool -fs or temporarily shut down the Archive Subsystem. If the output file does not exist, the utility creates it. If a full path name is not specified for the output archive, the utility places the output archive in the current directory. At the end of processing, neither the input nor the output archives are registered. By default, the piarchss offline archive utility creates dynamic archives. Use the -f argument to specify a fixed archive. Note that dynamic archives become nonshiftable once a single overflow record is generated, but remain shiftable if no overflow records are generated. You can run the piarchss offline archive utility while the PI System, including piarchss itself, is running. At a minimum, the pinetmgr, pibasess, and pisnapss subsystems must be running, because the utility needs to access the Point Database during offline operations. How the Offline Utility Works During processing, two passes are made through the input archive file. On the first pass, the utility checks all records in the input archive file. Every record containing valid data, and within the specified time range, is added to a sorted list. The list is indexed by time and point ID. This assures loading in chronological order. The point ID of the input record is verified. Any required point ID conversion is performed using the specified conversion table. For example, conversion is required when migrating archives from a PI2 or from another PI3 PI Server System Management Guide Page 45

68 Chapter 3 - Managing Archives System to your PI Server. An error message is issued for every record for which a point could not be found in the local PI Server. These messages can be suppressed if desired. Statistics are displayed after every 200 records are processed, at the end of the first pass, and at the end of the second pass. During the second pass, records from the sorted list are written to the output file. The input data is optionally filtered or modified. If the output archive file does not exist, it is created. The archive header is initialized based on command line specifications. If the output file already exists, the input data is added. If a primary record does not exist for a given point ID, the data for that point ID is discarded. The input data is converted to the output point type, if different from the input point type. All auxiliary data, such as index records and record chaining, are recreated during the load. Only actual data are read from the input, and thus, any errors in the input file auxiliary data are repaired. Piarchss Offline Archive Utility Exit Codes To facilitate batch file processing, the offline utility returns an exit code to the operating system: Code What it Means 0 No errors at least one input record processed 1 Errors during input phase 2 No processing errors 0 records processed possibly an empty input file <0 An error returned from the output processing check log messages 3.4 Listing the Registered Archives Archives must be registered before the PI Server can use them. If an archive is not registered, its data are not accessible. The piartool -al command lists the registered archives. Archives are listed in reverse chronological order archives with the newer data before archives with older data. The first archive listed is the Primary Archive, which covers the current time range. The dates that are spanned by each archive are also shown. There cannot be an overlap in dates between archives. Attempting to register an archive that overlaps an already registered archive will fail. Unused archives have start and end times shown as Current Time. The display order of unused archives is arbitrary and may change. Here is a sample archive listing: D:\PI\adm>piartool -al Archive shift prediction: Shift Time: 5-Oct-05 19:42:01 Target Archive: e:\pi\arc\piarch-2gb.1 Archive[0]: e:\pi\arc\piarch-2gb.3 (Used: 53.4%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Page 46

69 3.4 - Listing the Registered Archives Version: 7 Path: e:\pi\arc\piarch-2gb.3 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: / Overflow: / Annotations: 1/65535 Annotation File Size: 2064 Start Time: 5-Oct-05 06:11:09 End Time: Current Time Backup Time: Never Last Modified: 5-Oct-05 13:26:21 The piartool -al, command displays the following information for every currently mounted archive: Label Shift Prediction Used Version Path State Type Write Flag Shift Flag Description Provides estimated time for the next shift and the target archive. This is important for backup planning. Percentage of archive records used. This is an estimate, as only empty records are considered in the calculation. Identifier of the archive's internal architecture. This label allows PI Server to mount and upgrade archives from older versions of PI. Full path of the archive file. Current condition of the archive. In piartool -al, this will always be displayed as 4, which means mounted and ready. All other states correspond to unmounted states, in which case the archive is not visible in piartool -al. 0 = Fixed, 1 = Dynamic. 1 = Archive is currently writeable, 0 otherwise. 1 = Archive is potentially a target for archive shift, 0 otherwise. Record Size Size in bytes of one record. This is always Count Add Rate Offsets: Primary Offsets: Overflow Annotations Number of records in the archive file. Average number of overflow-records added per hour, over the archive lifetime. Start and end record numbers for primary records. The end record number is always 1/2 of the Record Count. Start and end record numbers for overflow records. Number of annotations used and the maximum number available. The archive shifts when this number is reached Determining an Archive Sequence Number from a Listing Some piartool commands require an archive sequence number; for example, archive backup (piartool -backup) and archive walk (piartool -aw). The archive sequence number is PI Server System Management Guide Page 47

70 Chapter 3 - Managing Archives chronologically assigned with zero being the primary archive. The archive sequence number is shown in with the archive list command (piartool -al); it is the number in the brackets immediately following Archive. Here is a sample archive listing: C:\pi\adm>piartool -al Archive shift prediction: Shift Time: 27-Sep-05 14:46:56 Target Archive: g:\pi\arc\piarc.144 Archive[0]: g:\pi\arc\piarc.045 (Used: 72.2%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: g:\pi\arc\piarc.045 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: 19273/98304 Overflow: 55751/ Annotations: 10/65535 Annotation File Size: 1623 Start Time: 11-Aug-05 12:59:35 End Time: Current Time Backup Time: Never Last Modified: 9-Sep-05 22:26:55 Archive[1]: g:\pi\arc\piarc144.arc (Used: 16.2%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: g:\pi\arc\piarc144.arc State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: 19273/65536 Overflow: / Annotations: 1/65535 Annotation File Size: 1552 Start Time: 11-Aug-05 09:12:35 End Time: 11-Aug-05 12:59:35 Backup Time: Never Last Modified: 16-Aug-05 19:08:48 Archive[2]: g:\pi\arc\piarc145.arc (Used: 99.8%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: g:\pi\arc\piarc145.arc State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: 77.9 Offsets: Primary: 19273/65536 Overflow: 19511/ Annotations: 1/65535 Annotation File Size: 1552 Start Time: 2-Jun-05 09:21:00 End Time: 11-Aug-05 09:12:35 Backup Time: Never Last Modified: 7-Sep-05 09:41:50 Archive[3]: g:\pi\arc\piarch.011 (Used: 99.8%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: g:\pi\arc\piarch.011 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: 36.8 Offsets: Primary: 19473/98304 Overflow: 19740/ Annotations: 1/65535 Annotation File Size: 1552 Start Time: 5-Jan-05 08:15:06 End Time: 2-Jun-05 09:21:00 Page 48

71 3.5 - Listing Archive Record Details Backup Time: Never Last Modified: 7-Sep-05 09:41:50 Archive[4]: g:\pi\arc\piarc.144 (Used: 99.3%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: g:\pi\arc\piarc.144 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: 18472/65536 Overflow: 19440/ Annotations: 1/65535 Annotation File Size: 1552 Start Time: 2-Jan-05 10:43:06 End Time: 5-Jan-05 08:15:06 Backup Time: Never Last Modified: 7-Sep-05 09:41:50 C:\pi\adm> Archive sequence numbers are arbitrarily assigned to unused archives. Unused archives can be recognized by both start and end time set to Current Time. When unused archives are unregistered or specified for a backup, the assigned number will likely change on subsequent reregister or backup end. Generally, there is no reason to back-up unused archives. 3.5 Listing Archive Record Details Use piartool -aw to read the contents of an Archive directly from file. The key to reading archive data this way is to understand that every PI point has a unique Record Number (RecNo) which corresponds to a primary record in the Archive. This can be found through piconfig or PI-SMT tools. When a new archive is created, data for each point flows into its own separate primary record (archives are divided into fixed size records, the number of which is either static or can grow dynamically.) When this primary record fills up, then an overflow record is set aside for the data to flow into. The primary record points to the first overflow record which can point to a second and so forth. It is following this chain of records that is referred to as an Archive Walk. Finally when the number of free unused overflow records in an archive gets down below a certain number, this is when an automated archive shift will occur Performing an Archive Walk with piartool -aw This command gives a detailed listing of archive records. After issuing this command, you are prompted for the target archive number and the target record. The record is displayed. You are then prompted to select another archive record to view. You can determine the archive number by issuing piartool -al. Archives are listed in order, starting with 0 for most current data. Example Displaying Archive Records with Record Headers Only The example below demonstrates how to use piartool to display archive record headers. C:\pi\adm>piartool -aw Enter Archive Number: 0 Enter Record Number: 40 PI Server System Management Guide Page 49

72 Chapter 3 - Managing Archives Point ID: 18 Record Number: 40 Chain Record Mumber - Next: Prev: 0 Index: 0 Record Version: 3 Data type: 11 Zero: 600 Span: 500 Flags - Index:0 Step:0 Del:0 Dirty:0 Sizes - Record 1024 Data: 998 Parent Archive Data Head: 26 Event Count: 214 Storage (bytes) - Available: 990 Used: 987 Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: Understanding Event Data Displayed by piartool -aw By default, the piartool -aw command displays only the record header. If you wish to view the data in the record, enter the letter "e" when prompted for the next record ID. This toggles on the display of event data. To toggle off the display, enter "h" at the Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: prompt. Event data will be displayed as shown in this example. Every archive record must contain at least one event. Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: e PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 68 $]:: Point ID: 4 Record Number: Chain Record Mumber - Next: 0 Prev: Index: 4 Record Version: 3 Data type: 101 Digital State Set: 3 Flags - Index:0 Step:1 Del:0 Dirty:0 Sizes - Record 1024 Data: 998 Parent Archive Data Head: 26 Event Count: 121 Storage (bytes) - Available: 994 Used: Event(s): 0: 9-Sep-05 18:57:04, S,O,A,S,Q [3,1,0,0,0]: 1: 9-Sep-05 18:58:14, S,O,A,S,Q [3,2,0,0,0]: 2: 9-Sep-05 18:59:24, S,O,A,S,Q [3,3,0,0,0]: 3: 9-Sep-05 19:00:34, S,O,A,S,Q [3,2,0,0,0]: 4: 9-Sep-05 19:01:44, S,O,A,S,Q [3,1,0,0,0]: 5: 9-Sep-05 19:05:14, S,O,A,S,Q [3,2,0,0,0]: 6: 9-Sep-05 19:06:24, S,O,A,S,Q [3,3,0,0,0]: etc. The S,O,A,S,Q array indicates values as shown in the table below. Event Type Coding S O A S Q Meaning StateSet Offset in StateSet; 248 corresponds to "No Data" Annotated (0=no, 1=yes) Substitute (0=no, 1=yes) Questionable (0=no, 1=yes) Page 50

73 3.6 - Estimating Archive Utilization Index shows whether the values in the records are data values or pointers to data records, where 0 indicates that it is NOT an index record. If they are pointers, the pointers are actually record numbers corresponding to the start time. When events for a point exceed two records in a single archive, an index record is created. An index record holds about 150 pointers to data records. RecNo (Record Number) is a read-only point attribute which contains a pointer to the point's primary record in the archive. This is useful when using tools such as piartool -aw to examine the archives. Do not confuse RecNo with the PointID attribute. If the point is deleted, the RecNo will be reused but the PointID will not. Data Type Meaning 8 Int32 (all records which have the index flag set will also show datatype 8) 12 Float digital 102 Blob Broken Pointers In rare cases of hardware failure, record chains can become inconsistent. The archive check utility pidiag -archk 'path' can be used to examine archive integrity. For more details on this pidiag command, refer to Verify the Integrity of Archive Files on page 272. The archive offline utility will repair any chaining problem. 3.6 Estimating Archive Utilization The space that a fixed archive uses is completely allocated at archive creation time. Use piartool -al to list the registered archives. For each archive an estimate of the used space is displayed. 3.7 Editing Archives The piconfig utility, the PI API and the PI-SDK may be used to add, edit, or delete archive values. Note: Contrary to the above title Editing an Archive, all archive edits are first handled by the Snapshot Subsystem. The Snapshot Subsystem performs some security and data checks then, if appropriate, forwards the edit events to the Archive Subsystem. PI Server System Management Guide Page 51

74 Chapter 3 - Managing Archives For large scale changes and repair use the Offline Archive Utility (piarchss). For example, inadvertently moving the computer system clock ahead may cause considerable problems. You can configure a time limit on insertion and editing of events. The Snapshot rejects events with timestamps earlier than the limit. By default there is no limit, which is consistent with earlier versions of PI. To configure, add an entry to PITimeout Table: EditDays, nnn where nnn is the number of days (prior to current time) in which changes and additions are allowed. The Snapshot Subsystem loads PI Timeout table parameters on startup, therefore, this subsystem must be restarted for the changes to take effect. 3.8 Creating Archives To create a new archive, use piarcreate, piartool -ac, or piartool -acd. These utilities allow you to name the new archive, specify its location, create it, and initialize it. In general, use piarcreate for all archive creation, unless you need to specify start and end times. piartool - ac creates a fixed size archive, piartool -acd creates a dynamic archive. With piarcreate, you may specify the size of the archive, but you will need to do a second step to register it. This utility creates a dynamic archive if you use the -d flag. With piartool -ac, the created archive size matches the current Primary Archive size, and registration is automatic. The piartool utility allows you to optionally specify the start and end times of the new archive. Option -ac specifies a fixed size archive, -acd specifies a dynamic archive. Every archive has a parallel annotation file that has the extension.ann. The file is created automatically by either utility. It must remain in the same directory as its archive file at all times Naming Archives There are no limitations on the archive file name, other than being a valid file name for the underlying operating system. The default archive file names are piarch.xxx, where xxx is 001, 002, 003 and so on. The location must have sufficient disk space. The associated annotation file has the same full path name as its archive file with.ann appended. For example, the annotation file for the piarch.001 archive file would be piarch.001.ann Choosing an Archive Size Archives have a maximum and minimum size: Minimum Archive Size: Determined by point count. The minimum archive size, in megabytes, is twice the number of points divided by For example, to allow for 20,000 configured points, the minimum archive size is: (20,000 x 2) / 1000 = 40 MB Page 52

75 3.8 - Creating Archives Maximum archive size is 2 Terabytes (2000 Gigabytes). The archive size affects backups, frequency of shifting, and total number of points allowed The general rule is to size your archives such that they last three to five weeks before shifting. How Archive Size Affects Shifting Frequency If the PI Server has larger archive files, the shift will occur less frequently. To decide what archive size is optimal for your system, consider the backup device, available disk space and average incoming data rate. These will determine the shift frequency. How Archive Size Limits Point Count It is important to note that the archive size limits the number of points that may be created. No more than 1/2 of the archive records of a fixed archive can be primary records. If the allotment of primary records gets used up, you will get an error if you try to create an additional point, even though the primary archive is not full. To resolve this, force the archives to shift into a larger archive in order to create additional points. Archive shifting can be forced using the command piartool -fs Selecting an Archive Type: Fixed or Dynamic By default, a fixed archive is created. If you specify the -d parameter, a dynamic archive will be created instead. Dynamic archives grow as they get filled, up to the specified maxsize, but not above two Terabytes. The difference between fixed and dynamic archives is discussed in the section on About Fixed and Dynamic Archives Specifying the Number of Points in the Archive This number, specified by the maxpoints parameter, should be taken from the piartool -al listing for the Primary Archive. The primary archive is always listed first. Point count is equal to the number of used primary records; in the example below it would be 253,063. One half of all records are reserved for primary records. This also determines the maximum number of points that can be created. The listing below is for a 2048 Mb archive; the maximum number of configurable points for the archive is 1,048,576. D:\PI\adm>piartool -al Archive shift prediction: Shift Time: 5-Oct-05 19:42:01 Target Archive: e:\pi\arc\piarch-2gb.1 Archive[0]: e:\pi\arc\piarch-2gb.3 (Used: 53.4%) PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: e:\pi\arc\piarch-2gb.3 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: / Overflow: / Annotations: 1/65535 Annotation File Size: 2064 Start Time: 5-Oct-05 06:11:09 End Time: Current Time Backup Time: Never Last Modified: 5-Oct-05 13:26:21 PI Server System Management Guide Page 53

76 Chapter 3 - Managing Archives Specifying the Maximum Archive Size The parameter maxsize is usually specified to be equal to the size of the Primary Archive, in megabytes, but it doesn t have to be the same. A dynamic archive will not grow larger than maxsize. 3.9 Creating Data Archives Prior to the Installation Date Some sites may find it useful to make data available in PI that was collected prior to the PI installation. Several applications can be used for backfilling, including a PI API or PI-SDK application, piconfig, or the batch file interface. This depends mainly on the way the data to be entered into PI is currently stored. Backfilling Data with Compression The installation procedure is the following: 1. Install PI, start PI, create all points, Stop PI. 2. Isolate the PI Server from all incoming process data. This means shutting down PI interfaces on all PI API and PINet nodes. Another way to do this is to disallow all PI API connections at the server. To due this, start piconfig without starting PI (ignoring messages about failure to connect) and issue the following hostmask,value "*.*.*.*",DISALLOW Note: Entries that allow access to specific names or addresses override the above disallow. Edit all other entries to Disallow. Local connections are not affected by pifirewall entries; make applications that may write data are not running. 3. Start PI with the -base parameter. This ensures that PI starts up with only the minimum required subsystems. On Windows hosts, issue the command: pisrvstart.bat -base 4. Create and register archive files for the backfilling period (using piartool -ac or - acd). 5. Insert one event for every point at the earliest time on-line. 6. Delete all the PointCreated events from the snapshot. This will bring into the snapshot the old events. Steps 5,6 can be done with a PI API or PI-SDK program or using the piconfig utility. Make sure that the old event is in the snapshot. Page 54

77 Creating a New Primary Archive 7. Backfill the archives by reading in the data In Time Sequential Order. This way the data is compressed. Caution: The Archive Subsystem assumes the archive end time is the most recent time stamp written to any point. It is important to keep all current data sources from writing to the PI Server. This is why Random, Ramp Soak, Performance Equations, PI Total, PI Alarm, or any other interfaces cannot be running. 8. If you used the technique of modifying the PIFIREWALL table in Step 4 above, run piconfig to either change the hostmask value to Allow or to delete the above hostmask altogether. 9. Start the interfaces using pisitestart.sh or pisrvsitestart.bat. Backfilling Data without Compression 1. Install PI Server and create all points. The points that you want to backfill must be created prior to the archive initialization, otherwise the archive has no primary records for these points. Note: An archive can be created with a start time prior to point creation time, as long as the point exists when that archive is created. Reprocessing an old archive with the offline utility adds to that archive all existing points, while preserving all the old data. 2. Use piartool -ac to create and initialize back fill archives. The start and end times must be specified (that is why piarcreate cannot be used). The start time should be the timestamp of the oldest data to be backfilled; the end time should be just prior to the oldest archive time specified using piartool -al. 3. Backfill the data. The data that you backfill will not be compressed, since it is prior to the snapshot time. 4. If the backfill archive is filled before all of the backfill data is entered, you must delete the backfill archive, and create two backfill archives, dividing the target time range between the two, or creating a single larger archive, and then retry the data backfilling Creating a New Primary Archive In some situations it is useful to create and register a primary archive with specific start-time, for example, when recovering from setting the time into the future, or when backfilling archives, or after using pidiag -ar to recover from any situation of corrupted archives. To create a new primary archive, use piartool -ac and specify the start time as required and the end time as *. Note the following restrictions: Registering a new primary archive will fail whenever there is a current valid primary archive registered. PI Server System Management Guide Page 55

78 Chapter 3 - Managing Archives A valid primary archive must have a specified start time and null end-time, which signifies current time Registering an Archive The PI Server Archive Registry contains the name, location, size, count of records, and record size for each archive file. This information is stored in the binary file, PI\dat\piarstat.dat. piartool -ar <path> This command allows new or old archives to be added to the list of registered archives. Once an archive is registered it is available to the system, participating in shifts and storage and retrieval of event data. The specified path must be a complete (not relative) path of an existing archive file Unregistering an Archive piartool -au <path> Use this command to drop an archive from the list of registered archives. Any archive may be unregistered except the Primary Archive (archive number 0), which stores the current data Deleting an Archive To delete an archive, first unregister it using the piartool -au command, discussed below. Delete the archive using the normal file deletion commands available on your operating system. Then delete the related annotation file Moving an Archive To move an archive you must unregister it, move it to a new directory, and then re-register it. Remember to move the associated annotation file as well. Moving the primary archive requires some additional steps, since you cannot unregister it while the PI archive process is running. To move the primary archive, do the following: 1. If any empty archives exist in the original directory, move them to the new directory and register them there. One of these archives will become the new primary archive. 2. Verify that there is at least one empty archive registered in the new directory (create one if there is not one). 3. Force an archive shift using piartool -fs. This will result in a new primary archive, which is one of the empty archives in the new directory. 4. Move the previous primary archive to the new directory by the usual method: unregister it, copy it to the new directory, and then re-register it. Note: Renaming archive files is generally not necessary. If you must do this, remember to rename the annotation file as well. Check the release notes for a description of issues associated with archive file renaming. Page 56

79 Managing Archive Shifts 3.11 Managing Archive Shifts When the primary archive file becomes full, the next empty (shiftable, writeable) archive is used to store the new data. If none of the archives are empty, the archive file with the oldest data (which is also shiftable and writeable) is cleared and used for new data. The start time of this archive is set to the end time of the archive file that just became full. The process of clearing the oldest archive and preparing it to be the new primary archive is called an archive shift. It is important that all eligible archives are backed up prior to the archive shift to ensure that no data is lost. When an archive is assigned a start time, it is initialized. Archives are only initialized at installation and during an archive shift. The archive shift process takes a few minutes to initialize a new archive file. Adding, editing, or deleting points is not allowed during archive shift. Events sent to the Archive during an archive shift are queued. When the shift is complete, the queued events are written to the Archive. Which Archives are Shiftable For an archive file to be eligible to be the new primary archive, it must be registered, shiftable, writeable, and large enough to handle the current size of the Point Database. If an archive does not meet these criteria, it will be skipped over during an archive shift. By making an archive non-shiftable or read only, an archive may be excluded from the shift cycle. Predicting Time of Next Archive Shift The command piartool -as is used to monitor archive activity, performance and to estimate the next archive shift The utility piartool -as predicts the time for the next archive shift. The prediction is based on the average number of archive records consumed per hour, plus the rate of consumption. If the primary archive is less than 20% full, the prediction is based on the previous archive rates. Archive Shift Enable Flag Fixed archives of varying sizes can be shifted. However, archives that are too small to accommodate the number of points in the Point Database are automatically excluded from archive shifts. Used dynamic archives are never shiftable. Both fixed and dynamic archives have a shift-enable flag. If the flag is 0 then the archive will not participate in archive shifts. A user can view or set this flag using the piartool utility. Failed Archive Shifts If an archive shift fails for any reason, all further shifts are disabled and a message is sent to the log. When the cause of the failure is resolved, restart the Archive Subsystem to enable archive shifts. If the cause of failure was a lack of available archive to shift into, then PI Server System Management Guide Page 57

80 Chapter 3 - Managing Archives registering a new empty archive automatically resolves the situation and a shift into the new archive will occur. Failed shifts do not cause any data loss since the archive goes into read-only mode. All incoming data is queued in the Event Queue by the Snapshot Subsystem Archive Shift Enable Flag Each archive has a Shift Enable Flag. If the Shift Enable Flag is set to 1 then the archive is eligible to participate in archive shifts. The status of the flag may be viewed using piartool - al. Archives can be excluded from shift participation by running piartool -ads 'path'. Shift disabled archives can be re-enabled by running piartool -aes 'path'. Dynamic archives that contain data do not participate in archive shifts. That is, newly created dynamic archives may be shifted into, but they are shift disabled after the first archive event is written to it. piartool -aes does not re-enable dynamic archives for shifting. Archive shifts happen automatically whenever the Primary Archive nears full. An archive shift normally begins when the Archive Subsystem detects that the primary archive is almost full. It dismounts the last empty archive, or oldest shiftable archive if no empty archives are available. It then initializes this archive. This can take some time, depending on the current point count. Messages are written to the log during the initialization to indicate progress. Once the new archive cleared, it is initialized to start at the current time and is mounted as the primary archive. Note: The oldest shiftable archive is the oldest writable archive large enough for the current point count. Also, dynamic archives containing data are not shiftable Forcing Archive Shifts The command piartool -fs forces an immediate archive shift. During normal operations, the piartool -fs command should not be used. However, it may be useful to force an archive to shift while testing your system or to do advance archive management. For example, this command is sometimes useful if you are building a large number of new points. Since primary records may occupy no more than one half of the records in an archive file, it may be necessary to build a larger primary archive. You can then force an archive shift to make the larger archive your primary archive. For systems with large point counts, archive shifts may require a long time. As soon as the shift starts, messages are written to the PI message log, such as: 0 piarcmgr 2-Apr-03 14:32:39 >> Forced archive shift requested. 0 piarcmgr 2-Apr-03 14:32:39 >> Beginning Archive Shift. Current Primary Archive: d:\pi\dat\piarch piarcmgr 2-Apr-03 14:32:39 >> Target Archive for Shift: d:\pi\dat\piarch piarsrv 2-Apr-03 14:32:39 Page 58

81 Combining and Dividing Archives >> Clear and Initialize archive file: d:\pi\dat\piarch piarsrv 2-Apr-03 14:32:48 >> Archive clear progress: records cleared. 0 piarsrv 2-Apr-03 14:32:58 >> Archive clear progress: records cleared. 0 piarsrv 2-Apr-03 14:33:08 >> Archive clear progress: records cleared. 0 piarsrv 2-Apr-03 14:33:19 >> Archive clear progress: records cleared. 0 piarsrv 2-Apr-03 14:33:28 >> Archive successfully cleared records 0 piarsrv 2-Apr-03 14:33:28 >> Archive successfully initialized points. 0 piarsrv 2-Apr-03 14:33:28 >> Archive file Clear and Initialize completion status[0] Success 0 piarcmgr 2-Apr-03 14:33:28 >> Completing Archive Shift. Current Primary Archive: d:\pi\dat\piarch piarcmgr 2-Apr-03 14:33:28 >> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary Archive is d:\pi\dat\piarch.003 Do not shut down the PI Server until the shift has completed. To determine when this has occurred, check the message log for a message like: 0 piarcmgr 2-Apr-03 14:33:28 >> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary Archive is d:\pi\dat\piarch Combining and Dividing Archives From a user perspective, archive files are organized according to their size and the time ranges that they span. It is useful sometime to change the initial file organization of the archive. The Offline Archive Utility can be used to accomplish each of the following tasks: Combining archives with overlapping dates into one archive Combining archives with adjacent time ranges into one archive Dividing an archive into smaller archives, each covering a portion of the original time span Combining Archives into a Single Archive To combine several archives, invoke the Offline Archive Utility once for each input file, using the same output file for all these inputs. Start from the oldest input, going in ascending time order. Note: The Offline Archive Utility will not work in descending or random time order. PI Server System Management Guide Page 59

82 Chapter 3 - Managing Archives The end-time of the output file can be moved forward as required, but the start-time cannot be changed after creation. Archives with an unknown end time should be processed into a new archive to determine the actual end time. The resulting archive can then be merged chronologically. Merging a series of archives with overlapping dates requires processing the archive with the oldest start time first, then process the remaining in chronological order based on the archive end times. Example of Combining Archives piarchss -if D:\pi\dat\oldest.dat -of D:\pi\dat\bigfile.dat piarchss -if D:\pi\dat\newer.dat -of D:\pi\dat\bigfile.dat piarchss -if D:\pi\dat\newest.dat -of D:\pi\dat\bigfile.dat In this example, bigfile.dat does not exist prior to the operation. It is created in the first session and events are added to it in the second and third session. It is created as a dynamic archive by default. After it is created, it may be registered using piartool -ar, and then events may be added to the archive through the Snapshot Subsystem. Any of the three input files that were registered prior to the operation are unregistered during the operation. When the operation is complete, they may be registered using piartool -ar. Dynamic archives, which is the default type created by the offline utility, are not shiftable. Dividing an Archive into Smaller Archives To break a single archive into smaller archives, invoke the Offline Archive Utility once for each output file, using the same input file for all the outputs. Each time, a different start and end time is specified. These times are specified in absolute PI time format. Example of dividing an archive into two smaller archives: piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat -filter "1-jan" "31-jan-02 23:59:59" -ost "1-jan" -oet "31-jan-02 23:59:59" piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\february.dat -filter "1-feb" "28-feb-02 23:59:59" -ost "1-feb" -oet "28-feb-02 23:59:59" In this example, january.dat and february.dat do not exist prior to the operation. They are created as dynamic archives by default. After they are created, they may be registered using piartool -ar, and then events may be added to the archive files in the usual way. Both output archives are not shiftable because they were created by the Offline Archive Utility as dynamic archives. The filter start time of january.dat is specified as 1-jan. This defaults to 1-jan, of the current year, at 00:00:00. The filter end time is enclosed in double quotes because of the embedded space character. The output archive start and end times are explicitly specified. Failing to include the -ost and -oet flags will get the default behavior. See the above discussion of output archive time settings for more information. If the input file were registered prior to the operation, it would be unregistered during the operation. When the operation is complete, it may be registered again using piartool -ar. Page 60

83 Combining and Dividing Archives Event Queue Recovery It might be desirable sometimes to remove an Event Queue file from the system. For example when the system cannot manage the load of a large backlog of events. To do this: 1. Stop the Snapshot and Archive Subsystems. 2. Rename PI\dat\pimapevq.dat to PI\dat\ pimapevq.save 3. Restart the Snapshot and Archive Subsystems. Later, the renamed Event Queue file can be loaded into an offline archive. The input file is the saved Event Queue data file. The argument -evq indicates the input file is an Event Queue. The resulting output archive might have dates that overlap existing archives. Offline processing, as discussed above, is required to combine these archives. Here is an example command line using piarchss to recover an Event Queue: piarchss -if D:\pi\dat\pimapevq.save -of D:\pi\dat\piarch099.dat -evq Note: In most cases the Event Queue is the above file. But, it is possible to have multiple Event Queues. The utility, piartool -qs, will indicate if your system uses multiple queues. The queue naming convention, if multiple queues are used is pimapnnnn.dat where NNNN is a four digit integer. Prior to version 3.4, the Event Queue was pi\dat\pieventq.dat. PI 3.4 and newer does not support processing this format. These files should be processed before upgrading. Also, the memory mapped file approach introduced in version 3.4 and other enhancements allows PI to handle out of order data much more efficiently in most cases offline processing of the Event Queue will not be necessary. PI Server System Management Guide Page 61

84

85 Chapter 4. BACKING UP THE PI SERVER It s important to back up the PI Server at least once a day, so that you don't lose data and configuration information if something goes wrong with your equipment. All backups of PI that are done while the PI System is running are managed by the PI Backup Subsystem (PI\bin\pibackup.exe). 4.1 Planning for Backups Choosing the Backup Platform (VSS vs. Non-VSS) Volume Shadow Copy Services (VSS) is available on Windows 2003 Server and Windows XP. The role of the PI Backup Subsystem during an actual backup depends upon whether a VSS or a non-vss backup is being performed. Non-VSS backups are the only option on UNIX, Windows NT Server, and Windows 2000 Server. During a VSS backup, the PI Backup Subsystem takes appropriate actions by responding to VSS events, but the actual files are backed up by a separate application such as NTBackup (NTBackup.exe). During a non-vss backup, the Backup Subsystem itself backs up the files of the PI System. Windows XP can be used to test VSS backups for staging purposes, but you should always run PI on a server platform. For Windows 2003 Server, it is highly recommended to upgrade to Windows 2003 Server Service Pack 1 which includes a large number of bug fixes related to backups Choosing a Backup Strategy The easiest backup strategy is to set up PI to automatically run the backup scripts every day (see Automating PI Backups, on page 66). You can also run the scripts manually (see Customize Your Backup, on page 68). The backup script initiates backups via NTBackup on platforms that support VSS, and/or with the piartool -backup command on platforms that do not support VSS. It is highly recommended that you run PI on a platform that supports VSS because VSS backups cause minimal disruption to the operation of PI. On Windows 2003 server, as an alternative to using the backup scripts, you can backup PI with any third-party backup application that supports VSS. Third-party backup applications may support features that are not supported by NTBackup. For example, NTBackup currently supports only non-component mode backups (see Selecting Files or Components for Backup, on page 75). PI Server System Management Guide Page 63

86 Chapter 4 - Backing up the PI Server 4.2 Other Backup Considerations While PI is running, PI cannot be backed up with standard operating system commands such as copy (Windows) or cp (UNIX) because PI opens its databases with exclusive read/write access. This means that the copy commands will outright fail. PI prevents access by the operating system because a lot of the information that is needed to backup the databases of PI is in memory and a simple file copy would most likely lead to a corrupt backup. When PI is not running, PI can be backed up with standard operating system commands such as copy (Windows) or cp (UNIX). Do not try to include the PI folder in your daily system backup. The PI archives typically consist of a large number of huge files that undergo frequent small changes. The PI backup scripts are designed to back up the archive files efficiently. Make sure you have enough space on the disk where PI creates the backup files. Check the disk space regularly. Run a trial backup and restore to make sure everything works correctly. Test your backups in this way periodically. See the section, Restoring Archives from Backup. To avoid losing incoming data while the backups are running, turn on PI API buffering for your interfaces wherever possible. On VMS PINet nodes, buffering is done automatically, so buffering does not need to be turned on for VMS PINet nodes. After PI Server installations or upgrades, shut down the PI Server and make a complete backup of all PI directories and archives. Note that archives may not be located under the PI\dat directory. On Windows, include the registry entries under HKEY_LOCAL_MACHINE/SOFTWARE/PI System/PI. On UNIX, include the /etc/piparams.default file. When you make a major change to PI, such as a major edit of the Point Database or User Database, consider immediately making a backup that includes those changes, rather than waiting for the automated backup Guidelines for VSS Backups All archives to be backed up must be on the PI Server Node. The VSS backup will fail if the archive to be backed up is on remote drive, such as a mapped network drive. Once a subsystem registers for backup, the subsystem must remain online during the next VSS backup or else the backup will fail. The subsystems that are currently registered for backup can be listed with piartool -backup -query. The list of registered subsystems is reset when the Backup Subsystem is restarted. If the backup fails because a subsystem is offline, the PI System Administrator should do one of the following. Fix the problem with the faulty subsystem and do a backup manually. VSS backups can be done during the middle of the day because they are not disruptive to the PI Server. Page 64

87 4.3 - Guidelines for Backing Up Before Upgrading Restart the PI Backup Subsystem, wait for all of the subsystems except for the problematic subsystem to register for backup, and then do a backup manually. During VSS backups, PI databases are unavailable for writes for a very brief period of time, typically on the order of milliseconds. This time period is less than the timeout period for write operations such as point edits. This means backups could potentially be done several times a day without disrupting normal server operation. Backups should not be done while configuration changes are being made since the changes may not take effect properly. Although the disruption from a Freeze/Thaw cycle is relatively small, unnecessary Freeze/Thaw cycles should be avoided. It is possible to unintentionally put PI through a Freeze/Thaw cycle if you are using a non-component mode VSS backup application such as NTBackup to do backups on your system. If any file on a volume is backed up with a non-component mode backup, any VSS writer that has files on that volume will go through a Freeze/Thaw cycle. This means that PI may think that it is being backed up when you are really backing up a file that is completely unrelated to it but happens to share a volume that is common to the PI databases Guidelines for non-vss Backups Try to prevent users from making changes to the PI System during non-vss backups. At the very least, schedule backups to occur at a time when users do not typically make changes to the PI System. This is because the PI databases are briefly unavailable for writes during non-vss backups, which could cause operations, such as point edits, to fail. Also, non-vss backups backup up one component at a time. This means that a point edit could occur between backing up the primary archive and the point database, which could cause an inconsistency between the PI databases in the backup. 4.3 Guidelines for Backing Up Before Upgrading Before and after an upgrade, do a complete backup of the PI Server by shutting PI down and copying all PI files to a backup medium. Follow these steps. Make sure that your Interface Nodes are buffering your data. Shut down PI, so that all files are closed. Back up all files in all subdirectories under the PI directory. Since PI is not running, you can use any standard operating system utility such as copy or tar. On UNIX, include the /etc/piparams.default file. On Windows, include the registry entries under HKEY_LOCAL_MACHINE/SOFTWARE/PI System/PI. PI Server System Management Guide Page 65

88 Chapter 4 - Backing up the PI Server 4.4 Automating PI Backups The exact instructions for automating PI backups depend on the operating system on which your PI Server is installed. Refer to the appropriate section for your PI Server: Automating Backups on Windows Automating Backups on Windows with a 3rd Party Backup Application Automating Backups on UNIX Automating Backups on Windows The procedure supplied below is an out-of-the box solution that works on Windows NT, Windows 2000, and Windows 2003 server without needing to install any 3rd party software. If you wish to implement a backup solution from a particular vendor, then follow the guidelines under Automating Backups on Windows with a 3rd Party Backup Application on page 72. The procedure for automating the PI backup script can be summarized as follows. Install PIBackup.bat as a scheduled task View and edit the scheduled tasks Customize your backup Do a test backup Do a test restore Install PIBackup.bat as a scheduled task The pibackup.bat script in the PI\adm directory can be used to start a backup from the command line or to install backup task. The default backup task will run automatically every day at 2 AM. On Windows NT and Windows 2000, the default task name will be Atn, where n is an integer. On Windows 2003 Sever, the default task name will be PI Server Backup. When the scheduled task is run, the PI\adm\pibackuptask.bat script is executed. The pibackuptask.bat script calls the backup script pibackup.bat and redirects the standard output to a log file with a name similar to pibackup_dd-mmm-yy_hh.mm.ss.txt in the PI\backup directory. The pibackup.bat backup script will automatically determine whether or not VSS is supported, and the script will perform either a VSS or non-vss backup as appropriate. The syntax for using the pibackup.bat file is as follows. PIbackup.bat <path> [number of archives] [archive cutoff date] [-install] where < > indicates a required parameter and [ ] indicates an optional parameter. The command line parameters must be specified in the above order. If the -install flag is not specified, a backup is performed immediately. The more restrictive of [number of archives] and [archive cutoff date] takes precedence. Regardless of [number of archives] and [archive cutoff date] archives that do not contain data are not backed up. Page 66

89 4.4 - Automating PI Backups Parameter Example Description <path> E:\PI\backup Path must be the complete drive letter and path to a directory with sufficient space for the entire backup. [number of archives] 2 The number of archives to backup. For example, "2" will backup the primary archive and archive 1. [archive cutoff date] *-10d The cutoff date is specified in PI time format. For example, "*-10d" restricts the backup to archives archives that contain data between 10 days prior to current time and current time. The more restrictive of [number of archives] and [archive cutoff date] takes precedence. [-install] Installs a scheduled task to run pibackup.bat daily at 2:00 am. If the -install flag is not specified, then a non-vss backup is performed immediately. For example, the following command installs a task to backup the primary archive, archive1, and archive2. PIbackup.bat e:pi\backup 3 1-Jan-70 -install All archives contain data later than midnight on 1-Jan-70, so the number of archives to be backed is not restricted by the cutoff date. Note, however, only archives that contain data are actually backed up. This means that if archive1 and archive2 are empty archives, then these archives are not backed up. The next example installs a task to backup all archives that contain data for the last 60 days to the current time. PIbackup.bat e:pi\backup *-60d -install The assumption above is that less than archives are mounted, so does not restrict the number of archives to be backed up. The next example installs a task to backup PI using the default number of archives and the default cutoff date. PIbackup.bat e:pi\backup -install The default number of archives for backup is 3, unless otherwise specified by the Backup_NumArchives timeout parameter (see Timeout Parameters on page 87). The default cutoff date is 1-Jan :00:00, unless otherwise specified by the Backup_ArchiveCutoffDate timeout parameter. View and Edit the Scheduled Tasks After installing the scheduled backup tasks with the pibackup.bat script, you might want to edit the scheduled task to change the task name or to set the Run As user to a different account. For example, renaming the task is necessary if you want to install multiple scheduled tasks via the pibackup.bat script. For VSS backups, it is recommended to change the Run As user for the PI Server Backup scheduled task from NT AUTHORITY\SYSTEM to the account of the user who will be PI Server System Management Guide Page 67

90 Chapter 4 - Backing up the PI Server administering the backups. This recommendation is simply for convenience purposes for viewing the NTBackup log file. This is discussed further in Do a Test Backup on page 69. Scheduled tasks can be viewed and edited via the Scheduled Tasks control panel. Alternatively, tasks can be viewed and edited via the command line. On Windows NT and Windows 2000, the scheduled tasks can be displayed with the at command. C:\pi\adm>at Status ID Day Time Command Line Each M T W Th F S Su 2:00 AM C:\PI\adm\pibackuptask.bat c:\pi\backup." 3 "*-60d"" On Windows 2003 Server, the scheduled tasks can be displayed and edited with the schtasks command. Although the at command is still available on Windows 2003 Server, the schtasks command should be used instead. For example, any task created with the at command on Windows 2003 server cannot be edited. e:\pi\adm>schtasks TaskName Next Run Time Status ==================== ======================== =============== PI Server Backup 02:00:00, 7/29/2005 Customize Your Backup Backups are customized by creating the pisitebackup.bat and pintbackup.bat file in the PI\adm directory. These files do not exist by default. You should never customize your backup by editing the pibackup.bat or the pibackuptask.bat files because these files are overwritten during an installation or upgrade. The pisitebackup.bat File If the pisitebackup.bat file exists, then the pibackup.bat backup script calls it right before exiting. If you have any tasks you want pibackup.bat to execute each day after the backup, then add these tasks to a file called pisitebackup.bat in the PI\adm directory. Typically, PI System Managers use the adm\pisitebackup.bat file to move the backup directory to tape. PI System Managers may also use the script to back up specific files that are not included in the PI Server backup. The pintbackup.bat File If the pintbackup.bat file exists, the pibackup.bat backup script will execute pintbackup.bat instead of executing NTBackup. By default, the backup script will execute NTBackup with the following command line. ntbackup.exe backup "@%PISERVER%dat\pibackupfiles.bks" /d "PI Server Backup" /v:yes /r:no /rs:no /hc:off /m normal /j "PI Server Backup" /l:f /f "%BackupPath%\PI_Backup.bkf" This command line causes the files of PI to be backed up to PI\backup\PI_Backup.bkf. Since the /a flag is not on the command line, the PI_Backup.bkf will be overwritten every time the Page 68

91 4.4 - Automating PI Backups backup is performed. The second argument on the command tells NTBackup to backup the files listed in the PI\dat\pibackup.bks backup selection file. The backup selection file is re-created every time that the piartool -backup -identify command is run. If you want to use different command line options for NTBackup or if you want to execute a different backup command, create a pintbackup.bat file in the PI\adm directory. Note: If you want to do a non-vss backup on a platform that supports VSS, you would alter the pintbackup.bat file to specify your preferred backup tool, either piartool -backup or some other backup tool Do a Test Backup Unless overridden by a pintbackup.bat file, the PI backup script will do a VSS backup when it is executed on Windows XP or Windows 2003 server. The PI backup script will perform a non-vss backup on Windows NT and Windows The following procedure applies to both VSS and non-vss backups except where noted. 1. Open a command prompt and type the command pigetmsg -f so that you can view messages that are written to the message log during the course of the backup. 2. Open the Scheduled Tasks control panel, right-click on the PI Server Backup scheduled task, and select Run. For VSS backups, if the Run As user for the scheduled task is the same as your account, you will see NTBackup being launched and you will be able to monitor the progress of the backup via the NTBackup GUI. 3. Run the command piartool -backup -query. You should see information about the current state of the backup. If the query command indicates that the backup was not launched, the backup script may have failed to launch the backup. The output of the script is written to a log file in the PI\backup directory with a name of the form pibackup_dd-mmm-yy_hh.mm.ss.txt. If the backup script log does not reveal the source of the error, there are two additional logs that can be examined as explained in steps 5 and After the backup is complete, run the piartool -backup -query command. The command should indicate that the backup completed successfully. 5. Examine the PI Message Log for backup related messages. Run pigetmsg and use pibacku* as a mask when prompted for Message Source. If the backup started and completed, you should at least see Backup operation started and Backup operation completed in the log file. 6. For non-vss backups skip to step 7. For VSS backups, examine the NTBackup backup log for errors. The procedure for examining the NTBackup log is described under Troubleshooting Backups. 7. After the backup is complete, verify that the files were successfully backed up. Files are backed up to PI\backup\. For VSS backups, the backed up files will be in a file called PI_Backup.bkf, which can only be opened by NTBackup. For non-vss PI Server System Management Guide Page 69

92 Chapter 4 - Backing up the PI Server backups, the actual files will be copied to subdirectories of PI\backup\. For example, if the original file was located in PI\dat\, the file will be backed up to PI\backup\dat\. 8. For VSS backups, run vssadmin list writers. The output should indicate that the state of the OSISoft PI Server VSS writer is stable Do a Test Restore General Considerations The following files require special treatment during a restore. File Name Pisubsys.cfg Piarstat.dat Special Treatment This file contains the full path name to the rendezvous file piv3.rdz. This path may be incorrect if the restore is not to the original location. There is no need to restore the pisubsys.cfg file after a new installation because this file is installed by the installation kit. The piarstat.dat file contains the full path names to all of the registered archives and database security information for the archives. If the destination directory of the archives to be restored is different than the original, then you may need to generate a new piarstat.dat file with the piartool - ar command. You will need to re-register your archives and re-create the database security. Restoring from NTBackup The NTBackup application keeps track of the files that is has backed up via a catalog that is stored under \Documents and Settings\All Users.WINDOWS\Application Data\Microsoft\Windows NT\NTBackup\catalogs51 All NTBackup catalogs are stored in the above directory no matter which user account the backup is run under. When NTBackup is run in advanced mode, these catalogs can be browsed from the Restore and Manage Media tab. Page 70

93 4.4 - Automating PI Backups To test the restore, use the following procedure. 1. Change the Restore files to location to Alternate Location and typing in an alternate location. Typically, it is a good idea to temporarily restore files to an alternate location even if the final destination of the restored files is the original location. 2. Review the files to be restored by double-clicking on the Backup Identification Label for your backup. Select all files for restore except possibly those files discussed under General Considerations above. PI Server System Management Guide Page 71

94 Chapter 4 - Backing up the PI Server 3. Review the options for the restore from the Tools > Option menu. 4. Click Start Restore. The files should be restored to the alternate location. 5. After the restore is complete, click Report The report should indicate that all files were restored successfully. Restoring from NTBackup if the Catalog was Lost All that is required to restore from NTBackup is the original PI_Backup.bkf file that was saved during the backup. The catalogs are not essential for restoring from backup. 1. Run NTBackup in advanced mode. 2. Select Restore and Manage Media. 3. Select Tools > Catalog a backup file 4. Browse to the PI_Backup.bkf file that you saved and click OK. The catalog should be added to the Restore and Manage Media tab. Once the bkf file is cataloged again, you can restore the files with the restoration procedure described above Automating Backups on Windows with a 3rd Party Backup Application If your PI Server is installed on Windows 2003 Server operating system, then you can do your PI backups with any third-party backup software that supports VSS. On Windows 2003 server, the PI Backup scripts use NTBackup to launch a VSS backup. The advantage of Page 72

95 4.5 - Automating Backups on a Windows Cluster using NTBackup is that it comes with Windows free of charge, which allows OSISoft to provide a default backup solution without requiring a third-party backup application. However, you might want to use a third-party backup application if, for example, you already use a third-party backup application and you want to use the same backup strategy for all of your applications. A second reason may be that the third-party backup application has particular features that make it easier for you to maintain backups. However, in order to use any third-party backup application, the backup application must support VSS backups. One limitation of NTBackup is that it only supports non-component mode VSS backups, which means that NTBackup cannot use the components of PI to select files for backup. A list of file names must be provided to NTBackup via the backup selection file PI\dat\pibackup.bks. A big disadvantage of non-component mode backups is that if any file is backed up on a volume where there is a PI database, PI will think that it is being backed up even though none of its files are actually affected by the backup. Most third-party backup applications support component mode backups, which mean that the backup application will be able to detect the PI Backup Subsystem as a registered VSS writer and will be display the components of the PI System that are available for backup. The backup components of PI might appear in a third-party backup application as discussed in Selecting Files or Components for Backup on page Automating Backups on a Windows Cluster If you are using the PI Backup Scripts for your backups, then the backups must be scheduled to run on both nodes in the cluster. That is, the command PIbackup.bat <path> [number of archives] [archive cutoff date] [-install] must be run on both nodes in the cluster. Installing the backup scripts as a scheduled task is discussed in detail under Automating Backups on Windows on page 66. Only one of the scheduled backup tasks will succeed at any given time because the pibackuptask.bat and pibackup.bat files are on the shared drive. Other than the need to schedule the backups on both nodes, backups on clustered and nonclustered Windows nodes are the same. 4.6 Automating Backups on UNIX Contact OSIsoft technical support for updated instructions, at PI Server System Management Guide Page 73

96 Chapter 4 - Backing up the PI Server 4.7 How The PI Backup Subsystem Works Principles of Operation VSS Backups Overview VSS backups are initiated by VSS requestors, which are backup applications such as NTBackup. A VSS provider forwards the backup request in the form of COM+ events to the appropriate VSS writer or writers that have registered with the provider. Windows XP and Windows 2003 Server come with a default VSS provider, and a VSS writer is an application that performs the necessary actions to back up a particular system. The PI Backup Subsystem is an example of a VSS writer. Information is passed between the VSS requestor and the VSS writer(s) over the course of the backup via a sequence of VSS events. The most important of these VSS events for understanding the significance of VSS backups for backing up the PI System are the Freeze and Thaw events. During the Freeze event, the PI Backup Subsystem requests each of the PI Subsystems to suspend data writes to disk. After all subsystems have suspended data writes, the PI Backup Subsystem responds to the VSS provider. The VSS provider then takes a Snapshot of all of the local disk volumes that are affected by the backup. The Backup Subsystem then receives the Thaw event, which means that it is OK for all PI Subsystems to resume writing to their databases. Although data writes are suspended between the freeze and thaw events, all PI databases remain readable by client applications. This means that historical data, configuration information, etc., can be read by client applications without any disruption during a VSS backup even between the Freeze and Thaw events. Even on busy systems, however, the disruption to data writes is minimal because the total time between the Freeze and Thaw events is typically on the order of a few milliseconds, and the duration must be less than 60 seconds or else the backup will be aborted. The disruption to data writes is so short that users should not even notice that a backup has occurred. For example, users should be able to edit, create, or delete PI Points without disruption because the timeout period for these operations is less than the typical time period between the freeze and thaw events. After the Freeze event, the backup application begins to backup the files that were requested for backup. Although data is being written to the files that are being backed up, the state of the file at the time of the Snapshot is preserved via a difference file. After all files are backed up, which may take hours, the difference file is discarded. More information about Volume Shadow Copy Services can be found online at then browsing the tree as follows. WIN32 AND COM DEVELOPMENT SYSTEM SERVICES FILE SERVICES VOLUME SHADOW COPY SERVICE Page 74

97 4.7 - How The PI Backup Subsystem Works Non-VSS Backups Overview Whereas VSS backups are initiated via a backup application, non-vss backups are initiated via the piartool -backup commands, which are discussed in the next section. For non-vss backups, the PI Backup Subsystem itself is the backup application. As with VSS backups, all PI Subsystems remain online, and all PI databases remain readable over the entire course of the backup. However, some databases will remain in a read-only state for a significantly longer period of time than for VSS backups. For example, archives and annotation files can be very large and writes to all archives and annotation files must be suspended for the duration of time that it takes to copy them for backup. Due to the architecture of the PI Archive Subsystem, writes must be suspended to all archives no matter which archive is being backed up Selecting Files or Components for Backup The files in the PI System are divided into backup components. A backup component is a convenient way to select a group of files for backup. Typically, there is one component per subsystem, but the PI Archive Subsystem has multiple components because there is one component per archive/annotation file pair. Some subsystems have no components either because the subsystem has no files that need to be backed up (such as the Totalizer and Alarm Subsystems) or because the files for the subsystem do not require a Freeze/Thaw cycle for the backup (such as the SQL and Shutdown Subsystems). Non-VSS Backups (Component Mode) All non-vss backups are considered to be component mode backups. The piartool - backup commands allow you either to backup a particular component or to backup all currently identify components. Typically, the PI Archive Subsystem identifies only a subset of its archives, as determined by timeout parameters, by arguments to the piartool -backup commands, and by the actual number of archives that contain data. This is discussed in more detail below. VSS Backups (Component Mode or Non-Component Mode) VSS backups are either component-mode backups or non-component mode backups. Individual files are selected for backup with non-component mode backups. To a certain extent this is an advantage because you can control exactly which files you want to backup. However, if any file is backed up on a disk volume where there is a PI database file, PI will think that it is being backed up even though none of its files are actually affected by the backup. This means if you backup a file that is completely unrelated to PI but shares a disk volume with a PI database, PI will undergo an unnecessary VSS Freeze/Thaw cycle. This is not as bad as it sounds because data writes are suspended only for a short amount of time during a VSS Freeze/Thaw cycle, but you should be aware that PI could be unintentionally put through a VSS Freeze/Thaw cycle when non-component mode backups are employed. The default backup solution for PI on Windows XP and Windows 2003 Server uses NTBackup, which supports only non-component mode backups. A second disadvantage to non-component mode backups is that all VSS writers that have a disk volume in common with PI will always be backed up at the same time as PI. This could lengthen the time period between the Freeze and Thaw events because the Thaw event cannot PI Server System Management Guide Page 75

98 Chapter 4 - Backing up the PI Server occur until all participating VSS writers have been frozen. Since the system drive is associated with several VSS writers, you should not install PI or any of its databases on the system drive, especially if you plan to use a non-component mode backup application to do your backups. You can use any third-party backup application to backup PI as long as the backup application supports VSS. Most third-party backup applications that support VSS also support component mode backups. At the request of a backup application the, PI Backup System identifies the files and components of the PI System. The backup application can use this information to display the components in a graphical user interface. If the component of a different application is selected for backup, then the PI system will not go through a Freeze/Thaw cycle, even if that component has files on a disk volume that is common to the PI databases. A backup application that supports component mode backups has the following information available to it for display purposes. The registered name of the PI VSS writer. The registered name is OSISoft PI Server. The friendly name of each component. Each component has a name and description. The component description is intended to be used as a friendly name for display purposes. A component path. The component path provides a means of logically organizing a group of components. The PI Archive Subsystem is the only subsystem that has a non-null component path. The PI System may appear as follows in a graphical user interface of a backup application that supports component mode backups. Each entry in the above tree view is a friendly name of a component except OSISoft PI Server, which is the registered name of the PI VSS writer, and PI Archive Subsystem, which is a component path. Typically, a backup application will use different icons to distinguish between a registered writer, a component path, and a component, but this is dependent on the particular backup application. Also, the component path PI Archive Subsystem may not be selectable in some backup applications because there is no component at that point in the tree. Page 76

99 4.7 - How The PI Backup Subsystem Works A user can select one or more components for backup. However, for a typical, automated backup one should configure the backup application to backup the OSISoft PI Server as a whole because new archive components are added after each archive shift. These new archives will not be selected for backup by default unless the OSISoft PI Server is selected for backup as a whole The Backup Components of PI The following table summarizes the backup components of PI. Component Name Component Path Friendly Name (Component Description) SettingsAndTimeoutParameters NULL Settings and Timeout Parameters Pilicmgr NULL PI License Manager Pimsgss NULL PI Message Subsystem Pibasess NULL PI Base Subsystem Pisnapss NULL PI Snapshot Subsystem Piarchss Piarchive_<UTCprimary>_<GUID> Piarchive_<UTCarch1>_<GUID> PI Archive Subsystem PI Archive Subsystem PI Archive Subsystem Archive Registry and Archive Audit Database Archive0 dd-mmm-yy hh:mm:ss to Current Archive1 dd-mmm-yy hh:mm:ss to ddmmm-yy hh:mm:ss... Piarchive_<UTCarchN>_<GUID> PI Archive Subsystem ArchiveN dd-mmm-yy hh:mm:ss to ddmmm-yy hh:mm:ss Pibatch NULL PI Batch Subsystem The Components in the Archive Subsystem The Archive Subsystem has one component for each archive/annotation file pair. The name has the form piarchive_<utctime>_<guid>, where <UTCTime> is the start time of the archive/annotation file in UTC seconds since midnight 01-Jan-70 and <GUID> is the GUID that uniquely identifies each archive/annotation file pair. For example, the name of an archive component with a start date of 5-Aug-05 17:56:08 might be: piarchive_ _{1a0fbff1-bfe4-45f3-82db-5cf5b64b088e} The description of an archive component has the form Archive0 dd-mmm-yy hh:mm:ss to Current for the primary archive and ArchiveN dd-mmm-yy hh:mm:ss to dd-mmm-yy hh:mm:ss for all other archives. The name of an archive component stays the same for the lifetime of an archive/annotation file pair, but the component description or friendly name changes every time there is an archive shift. For example, in the above example, the archive will begin its life as a primary archive with a friendly name of PI Server System Management Guide Page 77

100 Chapter 4 - Backing up the PI Server Archive0 5-Aug-05 17:56:08 to Current If the above archive shifts at 25-Aug-05 14:23:01, the friendly name of the archive becomes Archive0 5-Aug-05 17:56:08 to 25-Aug-05 14:23:01 The friendly names of all other components for the PI System do not change The Files and Components for each Subsystem PIBackup The PIBackup Subsystem has a single component called SettingsAndTimeoutParameters. The Settings and Timeout Parameters component contains files that are owned by various subsystems. The owning subsystems do not need to participate in backup because there is no special need to suspend data writes to these files during a backup. The subsystems that are associated with these files are not listed in the list of registered subsystems for backup with the piartool -backup -query command. The file names are hard-coded in the PI Backup Subsystem. The files backed up with this component are: File Name File Description Pe314.dfa PI-Performance Equation Scheduler parsing rules database (1 of 2) Pe314.llr PI-Performance Equation Scheduler parsing rules database (2 of 2) Pifirewall.tbl Pipeschd.bat pisql.ini pisql.res Pisubsys.cfg PISysID.dat Pisystem.res Pitimeout.tbl Shutdown.dat Firewall database PI-Performance Equation Scheduler command file Initialization settings for the SQL Subsystem Parsing resource for the SQL Subsystem Inter-process communication information file used by PI Network Manager Server ID data file PI-Performance Equation Scheduler equation parsing symbol database Timeout database Shutdown event configuration file used by the Shutdown Subsystem (pishutev) Plicmgr The Pilicmgr subsystem has a single component called Pilicmgr. The files backed up with this component are: File Name pilicense.dat File Description License Information Page 78

101 4.7 - How The PI Backup Subsystem Works Pimsgss The Pimsgss subsystem has a single component called Pimsgss. The PI Message system contains all message log files from the PI\log directory. The message file log names all begin with pimsg_ and end with.dat. The files backed up with this component are: File Name Pimsg_*.dat File Description PI Message Log Files Pibasess The Pibasess subsystem has a single component called Pibasess. The files backed up with this component are: File Name pidbsec.dat pidignam.dat pidigst.dat PIModuleDb.dat pipoints.dat piptalia.dat piptattr.dat piptclss.dat piptsrcind.dat piptunit.dat pitrstrl.dat piusr.dat piusrctx.dat piusrgrp.dat pibasessaudit.dat File Description PI Database Security Database Digital State Name Database Digital Set Database PI Module Database PI Point Database PI Point Aliases Database PI Point Attributes Database PI Point Class database PI Point Source Index Database PI Point Unit Database PI Trust Table PI User Database User Context Database PI User Group Database Base Subsystem Audit Database Pisnapss The Pisnapss subsystem has a single component called Pisnapss. The files backed up with this component are: PI Server System Management Guide Page 79

102 Chapter 4 - Backing up the PI Server File Name piarcmem.dat pisnapssaudit.dat File Description Snapshot Information Snapshot Subsystem Audit Database Piarchss The Piarchss subsystem has a component called Archive Registry and Archive Audit Database plus one component for each archive. The files backed up with the Archive Registry and Archive Audit Database component are: File Name piarstat.dat piarchssaudit.dat File Description PI Archive Manager Data File (Contains list of registered archives) Archive Subsystem Audit Database The following files are backed up with the archive components: File Name Archive and Annotation (.ann) files for all components File Description Archive file names can be anything. The annotation file name is the same as the archive file name with.ann appended to it. Each archive is contained in a separate component as described in The Components in the Archive Subsystem on page 77. PIBatch The Pibatch subsystem has a single component called Pibatch. The files backed up with this component are: File Name pibaalias.nt pibaunit1.nt File Description Batch Alias Database PI Batch Unit Database Lifetime of a Backup Lifetime of a VSS Backup During a backup, the PI Backup Subsystem receives a series of VSS events from the VSS provider. The Backup Subsystem takes the appropriate actions and then asynchronously forwards the VSS event to each subsystem that is participating in backups and then waits for all subsystems to reply. The Backup Subsystem can veto the backup if a fatal error occurs during any one of the events. If the backup is vetoed, then no further events will be sent to the Backup Subsystem. Page 80

103 4.7 - How The PI Backup Subsystem Works The Identify event always occurs at the beginning of every backup, but it can also occur at any time before or during a backup. The other VSS events always occur in the order specified in the following table. Backup Event Identify PrepareBackup PrepareSnapshot Freeze Thaw Description The PI Backup Subsystem requests a list of files and components from each subsystem that participates in backups. The PI Backup Subsystem returns the compiled list to the VSS provider. During a non-component mode backup, this information is simply not used by the backup application. A backup application can use the information from the Identify event to display the components of the PI System in its graphical user interface. If the PI Backup Subsystem takes a long time to reply to a particular VSS event, a backup application may send an Identify event to make sure that the PI Backup Subsystem is still alive. There is no way for the Backup Subsystem to be able to distinguish an identify event at the beginning of a backup from an Identify event that occurs merely for information gathering purposes. This event signifies the start of a backup. For a component mode backup, this event is received only if one or more components of the PI System have been selected for backup. The PI Backup Subsystem is told which of its components have been selected. The event is forwarded to the subsystems that are affected by the backup. For non-component mode backups, the event is forwarded to every subsystem that participates in backups. When this event is received by the PI Archive Subsystem, the subsystem sets a flag to indicate that a VSS backup is in progress. The archive backup flag as displayed by the piartool -as command will be set to 5. For all other subsystems, the PrepareBackup event is ignored. For a non-component mode backup, the PI Backup Subsystem determines if any PI databases are on one or more of the disk volumes that are affected by the backup. This cannot be determined before the PrepareSnapshot event. If none of the disk volumes corresponding to the PI databases are affected, then PI vetoes the backup and no other backup events are received. Otherwise, only those subsystems that are affected by the backup will receive subsequent VSS events. Each subsystem that is participating in the backup stops writing data to its files when it receives the freeze event. For example, any data that is sent to the PI archives will go to the queue and will not be readable until after the thaw event. Data that is already in the archive remains readable between the Freeze and Thaw events. Similarly, configuration information (such as point configuration and the module database) also remains readable. After the PI Backup Subsystem and all other VSS writers that are participating in the backup have indicated that all files are frozen, the VSS provider will take a snapshot of all disk volumes that are affected by the backup. Each subsystem that is participating in the backup resumes writing data to each of its files. The time between Freeze and Thaw is typically on the order of a few milliseconds and cannot be greater than 60 seconds without timing out. The time period between Freeze and Thaw is typically short enough so that database configuration operations should not time out. For example, a user should be able to edit PI points during a backup without even noticing that a PI Server System Management Guide Page 81

104 Chapter 4 - Backing up the PI Server Backup Event Description backup has occurred. The time period between the Freeze and Thaw events can be affected by a 3rd-party VSS writer that is being backed at the same time that the PI System is being backed up. The Thaw event will not occur until all VSS writers have indicated that their files have been frozen. This means that a misbehaving VSS writer or a VSS writer that simply takes a long time to freeze can significantly increase the time period between the Freeze and Thaw events. PostSnapshot BackupComplete BackupShutdown No actions are taken during the PI Backup Subsystem for the PostSnapshot event. Backup applications back up files between the PostSnapshot and the BackupComplete events. Although data is being written to the files that are being backed up, the state of the files at the time the snapshot is preserved via a difference file. The difference file is maintained by the operating system and is completely transparent to the PI system. After the backup is complete or aborted, the difference file is discarded. Backup completion may take hours if large files are being copied. This event indicates that a backup has completed successfully. The last backup time will be updated for each of the PI System s database files that keep track of such information. A summary of last backup times can be displayed with the piartool -backup -identify -verbose command. The last backup time for archive files are displayed by piartool -al command. When the PI Archive subsystem received this event, the output of piartool -as should indicate that the archive backup flag has been reset to 0. If the PI Backup Subsystem gets the BackupShutdown event without getting the BackupComplete event, then this means that the backup did not complete successfully. If the PI Archive Subsystem never receives a BackupComplete event, it will turn its archive backup flag off if it gets the BackupShutdown event. Lifetime of a non-vss Backup Data writes need to be suspended the entire time that a file is being backed up for non-vss backups. Like a VSS backup, data that is already on disk remains readable to all databases while the databases are being backed up. Unlike a VSS backup, each component is backed up one at a time, which means that there is one Freeze/Thaw cycle for each component. Archiving is turned off to all archives whenever any of the archives are being backed up. This is because there is no way to tell which archive will receive the data before the data is processed. Time is allotted for the queue to be emptied between each archive component that is backed up. The PI Backup Subsystem sends the same backup events to each subsystem for a non-vss backup as for a VSS backup, except for the PrepareSnapshot and PostSnapshot events, which the Backup Subsystem does not send. Another difference is that the Backup Subsystem generates the events instead of responding to events from a VSS provider. Like a VSS backup, the Identify, PrepareBackup, BackupComplete, and BackupShutdown events are sent to each subsystem asynchronously. It is only the Freeze and Thaw events that are sent one time for each component. Page 82

105 4.8 - Launching Non-VSS Backups with piartool -backup <path> The backup events are summarized in the following table. Backup Event Identify PrepareBackup Freeze Thaw BackupComplete BackupShutdown Description The PI Backup Subsystem requests a list of files and components from each subsystem that participates in backups. The Backup Subsystem uses the list of files to determine which files it should backup. When this event is received by the PI Archive Subsystem, the subsystem sets a flag to indicate that a non-vss backup is in progress. The archive backup flag as displayed by the piartool -as command will be set to 21. Currently, all other subsystems ignore the PrepareBackup event. Like a VSS freeze, each subsystem that is participating in the backup stops writing data to its files. Also like a VSS freeze, all PI databases remain readable after the freeze event. On Windows, each subsystem duplicates its handles for the files that it has open so that the Backup Subsystem can copy the files. On UNIX, the Backup Subsystem can copy the open files without a duplicate handle. There is one Freeze event per component. The Frozen component resumes writing data to each of its files. The time between Freeze and Thaw can be long, especially for large archive files that are being copied. If all selected components have been backed up, then the BackupComplete event follows the Thaw event. Otherwise, the Freeze event follows the Thaw event to backup the next component. There is a delay between archive components that are backed up to allow the queue to be emptied. After each component is successfully backed up, the last backup time is updated for the files of that component. This is different than for a VSS backup, where the last backup time is updated for every component during the BackupComplete event. A summary of last backup times can be displayed with the piartool -backup -identify -verbose command. The last backup time for archive files are displayed by piartool -al command. This event indicates that a backup has completed successfully. When the PI Archive subsystem received this event, the output of piartool -as should indicate that the archive backup flag has been reset to 0. No action is taken by other subsystems when the BackupComplete event is received. If the PI Backup Subsystem gets the BackupShutdown event without getting the BackupComplete event, then this means that the backup did not complete successfully. If the PI Archive Subsystem never receives a BackupComplete event, it will turn its archive backup flag off if it gets the BackupShutdown event. 4.8 Launching Non-VSS Backups with piartool -backup <path> The syntax of the piartool -backup command for starting a non-vss backup is piartool -backup <path> [-component <comp>][-numarch <number> [-cutoff <date>][-wait <sec>] where <> indicates a required parameter and [] indicates an optional parameter. PI Server System Management Guide Page 83

106 Chapter 4 - Backing up the PI Server Argument <path> -component <comp> -numarch <number> -cutoff <date> -wait <sec> Description Path must be the complete drive letter and path to a directory with sufficient space for the entire backup. Backup only component specified by <comp>. For example, piartool -backup c:\pi\backup -component pibasess will only backup the files that belong to the PI Base Subsystem. A full list of the components are available from the command piartool -backup -identify -verbose The -component flag overrides the -numarch and -cutoff flags, which are used only to restrict the number of archive components that are backed up. If the -component flag is not specified, all components are backed up except for the archive components that are restricted from backup by the -numarch and -cutoff flags. The number of archives to backup. For example, "2" will backup the primary archive and archive1, provided that the primary archive and archive1 contain data. In no case will an empty archive be identified for backup. The default number of archives for backup is 3, unless otherwise specified by the Backup_NumArchives timeout parameter. The cutoff date is specified in PI time format. For example, "*-10d" restricts the backup to archives that contain data between 10 days prior to current time and current time. The more restrictive of -numarch <number> and -cutoff <date> takes precedence. The default cutoff date is 1-Jan :00:00, unless otherwise specified by the Backup_ArchiveCutoffDate timeout parameter. Wait up to <sec> seconds for the non-vss backup to complete before returning from the piartool -backup command. The progress of the backup is reported every 15 seconds and when the backup is complete, the status of the backup is reported via a piartool -backup - query. 4.9 Managing Backups with piartool Backup Command Summary The piartool -backup commands are typically used for troubleshooting and for monitoring the course of a backup. The piartool -backup commands can also be used to start a non-vss backup. The pibackup.bat script, for example, uses the piartool -backup commands to start non-vss backups when the script is run on an operating system that does not support VSS backups. The basic syntax for the piartool -backup command is piartool -backup <Arg1> [Arg2] [Arg3]... where <> indicates a required parameter and [] indicates an optional parameter. If <Arg1> does not begin with a hyphen (-), then <Arg1> is assumed to be the destination directory for a Page 84

107 4.9 - Managing Backups with piartool non-vss backup. If <Arg1> begins with a hyphen (-), then <Arg1> is assumed to be a backup command. The following backup commands are valid. Backup Command -abort -query [-verbose] -identify [-numarch <number>] [-cutoff <date>] [-verbose] -trace <level> Description Abort a current running backup. Example: piartool -backup -abort The query command does the following. Reports a list of subsystems that are currently registered for backup. If a backup is not in progress, the query reports the status of the last backup. If a backup is in progress, the type of backup and the status of the backup is reported. Example: piartool -backup -query The identify command reports the list of files that PI will backup. If the - verbose flag is specified, PI will report a list of files and components. A component is a logical grouping of files. For example, all of the files for the base subsystem are grouped under the pibasess component. The purpose of a component is to identify a group of files for backup. The -numarch and -cutoff flags have the same meaning as the backup command for non-vss backups, which is described below. The identify command creates a \pi\dat\pibackupfiles.bks file. This file is used in the pibackup.bat backup script to specify the list of files to backup using NTBackup. NTBackup is used by the backup script for performing VSS backups on Windows 2003 Server. Example: piartool -backup -identify -verbose Debug messages are written to the log file when the trace level is nonzero. The higher the trace level, the more messages that are written. The maximum number of messages is written with a trace level of 100. Tracing should be off unless you are troubleshooting a problem to avoid unnecessary messages in the log file. If the trace level is non-zero, the trace level is displayed by the piartool -backup -query command. Example: piartool -backup -trace piartool -backup -query When the PI System if first started and whenever the PI Backup Subsystem is restarted, the output of a piartool -backup -query will appear as follows once all of the subsystems have registered for backup. e:pi\adm>piartool -backup -query Backup in Progress: FALSE Last Backup Start: NEVER VSS Supported: TRUE PI Server System Management Guide Page 85

108 Chapter 4 - Backing up the PI Server Subsystems Registered for Backup Name, Registration Time, Version, Status pibatch, 29-Jul-05 12:09:36, , [0] Success pilicmgr, 29-Jul-05 12:09:52, , [0] Success piarchss, 29-Jul-05 12:10:37, , [0] Success pibasess, 29-Jul-05 12:11:53, , [0] Success pisnapss, 29-Jul-05 12:11:54, , [0] Success pimsgss, 29-Jul-05 12:11:56, , [0] Success Last Backup Start will appear as Never when the backup subsystem is restarted because the backup subsystem does not keep track of previous backups between restarts. Pibatch may not appear in your list of subsystems that are registered for backup if you are not licensed to use the old batch subsystem. If the PI System is started normally, then subsystems should appear as registered within about 30 seconds of the PI Backup Subsystem startup time. Normal startup is, for example, starting the PI System with the pisrvstart.bat command file or letting the PI System services automatically start after a reboot. However, if the PI Backup Subsystem is shutdown and restarted, it may take up to 10 minutes for the individual subsystems to register for backup. All of the following subsystems must be running in order for a backup to succeed. PI Network Manager PI Backup Subsystem PI License Manager PI Message Subsystem PI Snapshot Subsystem PI Archive Subsystem PI Base Subsystem PI Batch Subsystem Registers for backup Registers for backup Registers for backup Registers for backup Registers for backup Registers for backup if you are licensed to use the old PI Batch Subsystem The other subsystems either do not have files that need to be backed up or they do not need to be running for a backup to succeed. The above subsystems that register for backup should appear in the list of registered subsystems in the output of the piartool -backup -query command. After doing a backup, the query will show information about the last backup. The following shows an example of a query that was done after a successful non-vss backup. e:pi\adm>piartool -backup -query Backup in Progress: FALSE Last Backup Start: 29-Jul-05 02:00:04 End: 29-Jul-05 02:01:11 Status: [0] Success Last Backup Type: FULL, NON-VSS Last Backup Event: BACKUPSHUTDOWN Last Backup Event Time: 29-Jul-05 02:01:22 Page 86

109 Timeout Parameters VSS Supported: TRUE Subsystems Registered for Backup Name, Registration Time, Version, Status pibatch, 28-Jul-05 16:09:18, , [0] Success pisnapss, 28-Jul-05 16:09:51, , [0] Success piarchss, 28-Jul-05 16:09:51, , [0] Success pilicmgr, 28-Jul-05 16:09:51, , [0] Success pibasess, 28-Jul-05 16:09:52, , [0] Success pimsgss, 28-Jul-05 16:09:53, , [0] Success piartool -backup -identify The piartool -backup -identify command displays the list of files that need to be backed up for the PI system. The output has the form. e:\pi\adm>piartool -backup -identify <FileName_1> <FileName_2> <FileName_3>... Whenever the backup identify command is run, a backup selection file, PI\dat\pibackup.bks, is created. This backup selection file can be read by NTBackup to determine which files it should backup. The piartool -backup -identify -verbose command identifies the components and files for backup. A component is simply a logical grouping of files. If a component is selected for backup, all of its associated files are backed up. The verbose output of the backup identify has the following form. e:\pi\adm>piartool -backup -identify -verbose FileList Name, ComponentName, LastBackup <FileName_1>, <ComponentName_A>, <BackupDateFile_1> <FileName_2>, <ComponentName_A>, <BackupDateFile_2> <FileName_3>, <ComponentName_B>, <BackupDateFile_3>... ComponentList Name, ComponentDescription, ComponentPath <ComponentName_A>, <Description_A>, <ComponentPath_A> <ComponentName_B>, <Description_B>, <ComponentPath_A>... The output should correspond to the expected components listed in the section The Backup Components of PI on page 77 and the expected files listed in the section on page Error! Bookmark not defined Timeout Parameters The timeout parameters that are specifically related to backup operations are reproduced here for convenience. For a full list of all timeout parameters, see PI Server Reference. PI Server System Management Guide Page 87

110 Chapter 4 - Backing up the PI Server Subsystem(s) Name Default Value Min Max Read Description Archive archive_back upleadtime 1800 sec On backup startup Number of seconds before the predicted archive shift that a non-vss archive backup may start. The PI Backup Subsystem waits up to 30 minutes for the archive shift to complete. This timeout parameter has no effect on VSS backups. Archive Archive_BSTi meout 1800 sec Once a minute This timeout parameter is obsolete. It is for internal use only. Backup Backup_Num Archives Before every backup If the number of archives to be backed up is not explicitly specified in arguments to the pibackup.bat backup script, then this timeout parameter defines the default number of archives to back up. Backup Backup_Archi vecutoffdate 01-Jan Jan- 70 N/A Before every backup If the cutoff date is not explicitly specified in arguments to the pibackup.bat backup script, then this timeout parameter defines the default cutoff date. Archives that contain any data between Backup_ArchiveCutoffDate and current time are backed up. For example, if "*-30d" is specified, then at least 30 days of data is backed up. Both Backup_NumArchives and Backup_ArchiveCutoffDate restrict the number of archives for backup. Whichever timeout parameter is most restrictive takes precedence. Backup Backup_Trac elevel Startup only The default backup trace level. Nonzero backup trace levels cause debug messages to be written to the PI Message Log. The default trace level can be overridden while the PI Backup Subsystem is running with the piartool -backup -trace <level> command. Page 88

111 Troubleshooting Backups Subsystem(s) Name Default Value Min Max Read Description All <subsysname >_WriteModTi mestofileper iod 60 sec Startup only PI internally keeps track of the last modified date of most of the files that it needs to back up. The last modified times for each subsystem are updated every WriteModTimesToFilePeriod. The smaller the period, the more accurate the last modified time is. A complete list of backed up files along with their last modified dates can be listed with the piartool - backup -identify -verbose command. For archives, the last modified date can also be viewed with piartool -al. Note for archive files: When a value is written to a PI point, the value is not actually written to the archive until the archive cache is flushed. The maximum period between archive flushes is set by the Archive_SecondsBetweenFlush timeout parameter. After the cache is flushed, the last modified time is updated within WriteModTimesToFilePeriod seconds. All <subsysname >_BackupTim eout 1800 sec Periodically when in system backup mode The maximum number of seconds to remain in system backup mode. This timeout parameter only pertains to the piartool -systembackup command, which is used to take the audit databases offline. The parameter has no effect for VSS backups or non-vss backups that are started with the piartool -backup command Troubleshooting Backups Log Messages The following log files should be examined for errors. The backup script log. The backup script log is written to the target directory of the backup and the log file has a name of the form pibackup_dd-mmm-yy_hh.mm.ss.txt. An example backup script log file name is pibackup_5-aug-05_ txt. The PI Message Log. Messages from the PI Backup Subsystem have a message source of pibackup. Backup-related messages from all other subsystems have a message source of pibackup<subsysname>, such as pibackup_piarchss. You can search for all backup related messages in the log by using pibacku* as a text mask for Message Source. PI Server System Management Guide Page 89

112 Chapter 4 - Backing up the PI Server The NT Event Log. From the Application Log, look for messages from VSS, COM+, and ntbackup sources. The NTBackup.exe log file (VSS Backups only). If there was a problem creating a VSS shadow copy during a backup, the reason for the failure is logged at the beginning of the NTBackup.exe log file. If the Run As user for the PI Server Backup scheduled task is the same as your account, then you can view the NTBackup log from the Tools > Report menu of NTBackup. Launch NTBackup from a DOS command prompt and choose to run in advanced mode VSSADMIN If the PI Server Backup scheduled task was run under the system account, you must browse to the NTBackup.exe log file with Windows explorer to the following directory. C:\Documents and Settings\Default User.WINDOWS\Local Settings\Application Data\Microsoft\Windows NT\NTBackup\data If the scheduled task is run under a user name other than the system account, then replace Default User.Winodows with the specific user name to get the path to which the NTBackup.exe log file is written. Vssadmin.exe is the Volume Shadow Copy Service administrative command line tool. You can use the tool to view the status of the VSS writers, VSS Providers, and VSS shadow copies on the system. Page 90

113 Troubleshooting Backups VSSADMIN LIST SHADOWS A shadow copy is created during the freeze event. If a backup is not currently in progress, the output of vssadmin list shadows should look like the following output that was generated on Windows XP. e:\pi\adm>vssadmin list shadows vssadmin Volume Shadow Copy Service administrative command-line tool (C) Copyright 2001 Microsoft Corp. No shadow copies present in the system. If there were problems create the shadow copy, look for errors in the NTBackup.exe log file and run vssadmin list shadows to check the status of the failed shadow copy. VSSADMIN LIST PROVIDERS Windows XP and Windows 2003 server comes with a default VSS provider. The following is sample output generated on Windows XP. e:\pi\adm>vssadmin list providers vssadmin Volume Shadow Copy Service administrative command-line tool (C) Copyright 2001 Microsoft Corp. Provider name: 'MS Software Shadow Copy provider 1.0' Provider type: System Provider Id: {b b9f-4925-af80-51abd60b20d5} Version: VSSADMIN LIST WRITERS The following is sample output for the vssadmin list writers command. When a backup is not in progress, the status of all writers should appear as stable. The name of the writer for the PI System is OSISoft PI Writer. The PI Backup Subsystem registers as a VSS writer with this name. The following is sample output from Windows XP. e:\pi\adm>vssadmin list writers vssadmin Volume Shadow Copy Service administrative command-line tool (C) Copyright 2001 Microsoft Corp. Writer name: 'OSISoft PI Server' Writer Id: {0fd0891d-b731-4e59-a35d-48f } Writer Instance Id: {cf8d5ded-e a0-6b3064c756c3} State: [1] Stable Writer name: 'Microsoft Writer (Bootable State)' Writer Id: {f2436e37-09f5-41af-9b2a-4ca2435dbfd5} Writer Instance Id: {c89ae65c-9f26-4bd db66757defc7} State: [1] Stable Writer name: 'MSDEWriter' Writer Id: {f8544ac fa5-b04b-f7ee00b03277} Writer Instance Id: {190c16a5-d378-43d6-bdb abea2b} State: [1] Stable PI Server System Management Guide Page 91

114 Chapter 4 - Backing up the PI Server Writer name: 'WMI Writer' Writer Id: {a6ad56c2-b509-4e6c-bb19-49d8f43532f0} Writer Instance Id: {26a1f92f-779d-45d1-900a-21b8af6f0590} State: [1] Stable Writer name: 'Microsoft Writer (Service State)' Writer Id: {e38c2e3c-d4fb-4f4d-9550-fcafda8aae9a} Writer Instance Id: {f8dd1e16-4e36-4ed2-9a53-ea4e05bacdb6} State: [1] Stable Page 92

115 Chapter 5. MANAGING INTERFACES 5.1 Introduction This chapter is split into two sections. The first section covers basic principles of interface operation. The second section describes the basic steps involved with installing, configuring, and administering a typical interface. There are several manuals in addition to this document that provide general information with regard to interface configuration and management. Manual Name PI API Installation Instructions UniInt End User Manual PI Interface Configuration Utility User Manual PI Performance Monitor Interface Manual PI Interface Status Utility PI AutoPointSync User Manual Notes On Windows, this manual is installed into the pipc\bin directory by the PI SDK installation kit. The manual provides several important post-installation details for configuring the PI API and buffering. Most interfaces are based on the OSIsoft Universal Interface (UniInt) and therefore share a common set of features. Certain UniInt features may be described in more detail in the UniInt End User Manual document than in the interface-specific documentation. However, not all features that are described in UniInt End User Manual are supported by all UniInt interfaces. The Interface Configuration Utility provides a graphical user interface for configuring the interface command line, interface services, and various PI points that are useful for monitoring interface performance. The PI Performance Monitor interface, PIPerfMon, obtains Microsoft Windows performance counter data and sends it to the PI System. The PI Interface Status Utility is an interface that runs on the PI Server node. The utility writes events such as I/O Timeout to PI Points that have not received values for a configurable period of time from a particular interface. Some interfaces, such as the OPC Interface, support auto-point synchronization. PI AutoPointSync (PI APS) is a utility that synchronizes the PI Server points for an interface with the tag definitions on the interface s data source. PI Server System Management Guide Page 93

116 Chapter 5 - Managing Interfaces 5.2 General Interface Principles For the most part, this section discusses general interface principles that apply to interfaces running on Windows, UNIX, and VMS. If a particular topic in this section applies to a particular operating system, then this is mentioned up front. For example, interfaces can only use the PI Software Development Kit (PI-SDK) on Windows, but the PI-SDK is such a fundamental part of the PI System that it is discussed under general principles About PI Interfaces PI interfaces are software modules for collecting data from any computing device with measurements that change over time. Typical data sources are Distributed Control Systems (DCSs), Programmable Logic Controllers (PLCs), OPC Servers, lab systems, and process models. However, the data source could be as simple as a text file. Most interfaces can also send data in the reverse direction, from PI to the foreign system. Typically, interfaces use the PI Application Programming interface (PI API) to retrieve configuration information from the PI Server and to write data to the PI Server. Many interfaces also use the PI Software Development Kit (PI-SDK) to retrieve configuration information from the PI Server and to create PI Points, Digital States, etc. A handful of interfaces use the PI-SDK to write batch data to PI, the most notable of which is the PI Batch Generator interface (PIBaGen). The PI API and the PI-SDK are described in more detail below. Most interfaces written by OSISoft are written using UniInt, OSISoft s so-called Universal Interface. UniInt performs many tasks that need to be performed by most interfaces such as loading points, parsing command line, arguments, scheduling scans for data, etc. As a result, most OSISoft interfaces have a common set of features that are configured in the same way. UniInt uses the standard PI API and the PI-SDK to write and read data from the PI Server. Although UniInt itself is not publicly available, customers could use the PI-SDK and PI API to write their own custom interfaces that do the same tasks as UniInt About PI Interface Nodes A PI Interface Node is a computer that runs one or more interfaces to collect data from a foreign system and send that data to a PI Server. The Interface Node might be a computer that is a part of the foreign data system, such as a Foxboro AW51 workstation; it might be a stand-alone dedicated interface computer; or it might be the PI Server itself. Typically, you should avoid running interfaces on the PI Server node. Running interfaces on a separate node allows the PI Server to be taken down for maintenance while data is still collected and buffered on the Interface Node. Also, you do not want interfaces competing for computer resources with the PI Server. As discussed later in this document, there are a few interfaces that are intended to run on the PI Server, but these interfaces are the exception. From an administrative standpoint, the best thing about PI Interface Nodes is that they are typically configured once, backed up, and then left to run indefinitely without human intervention. Exceptions to this include software upgrades, security patches, network infrastructure changes, and some configuration changes driven by a change in the foreign data system. Interface nodes are the first line focus for data reliability and availability, so user interaction with interface nodes is usually restricted to PI system administration only. Page 94

117 5.2 - General Interface Principles Interface Nodes on VMS An Interface Node on an OpenVMS-based VAX or Alpha computer is also known as a PINet Node. PINet is a stripped-down version of a PI 2 server. PINet does not contain a data archive, but it does contain a local Snapshot Subsystem and a local point database. In addition, PINet provides utilities to access the point configuration information and data that reside on the PI Server. PINet automatically buffers data when it cannot connect to the PI Server. PINet sends data to PI over a TCP/IP connection. PIonPINet is similar to PINet in that it is a subset of PI that runs on OpenVMS. PIonPINet includes all of the functionality of PINet. In addition, it includes analysis, reporting and graphical display utilities About Data Buffering Data flow from a typical interface to the PI Server can be summarized by the following diagram. When buffering is enabled, the data flows through the interface to the buffering service and from there to the Snapshot Subsystem on the PI Server. On Windows and UNIX interface nodes, data is buffered with the bufserv service, which must be installed and configured separately from the interface. On VMS, data buffering comes built-in with the interface node. The above diagram shows the buffering application sending data to only one PI Server node. As of PI API version 1.6, buffering supports collecting data from one interface and distributing the data to multiple PI Servers. On VMS Interface Nodes, buffering supports data sends to one PI Server only. Some interfaces do not require buffering because the data source itself is buffered. For example, the Batch File Interface and the Event File interface do not require buffering. The interface-specific documentation should be consulted to see if your interfaces require buffering. If the PI Server is not available for some reason (such as an upgrade on the Server) then the data is stored in a file buffer on the Interface Node. The size of the file buffer is configurable (up to nearly 2GB on Windows and UNIX). When the PI Server becomes available again, the buffering application sends all the stored data from the buffer, in chronological order, back to PI Server System Management Guide Page 95

118 Chapter 5 - Managing Interfaces the PI Server. If you then look ProcessBook, for example, your data appears as a continuous flow of data, with no gaps About the PI API The PI Application Programming Interface (PI API) is a library of functions that allow you to read and write values from the PI Server, and also let you retrieve point configuration information. OSIsoft has used the API to create interfaces that run on a variety of platforms. The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to be taken offline for software or hardware upgrades without compromising data collection. When PI becomes available again, the buffered data are then forwarded to PI. API Nodes are UNIX or Windows workstations that run programs such as interfaces that are based on the PI API. In practice, the term API Node is sometimes used as a synonym for Interface Node, because historically, most interfaces are API based. This document does not use the term API Node. You can call PI API from C, Visual Basic, or other languages. A complete list of supported platforms and functions is available in the PI API Manual About the PI SDK The PI Software Development Kit, (PI-SDK), is an ActiveX in-process server that provides COM access to OSI historians. The product provides an object-oriented approach to interacting with PI systems in contrast to the procedural methods used in the PI API. The PI-SDK can only be installed on Windows. Only interfaces that run on Windows can take advantage of the functionality provided by the PI-SDK. All interfaces written for UNIX or VMS must use the PI API exclusively for all communication with the PI Server. Some interfaces use the PI-SDK because certain functionality is not provided via the PI API. For example, the PI-SDK allows interfaces to create points, digital sets. Also, any interface that writes batch data to PI, such as the PI Batch Generator Interface (PIBaGen), must use the PI-SDK to write its data. Any data that is written to PI via the PI-SDK is not buffered via the bufserv service. For this reason all interfaces write time-series data to the PI Server via the PI API. Interfaces that connect to the PI Server with both the PI-SDK and the PI API must maintain two separate connections to the PI Server About UniInt-Based Interfaces There are hundreds of different PI interfaces and each interface is fully documented in its own dedicated manual. However, most interfaces are based on UniInt therefore share a common set of features. UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoftdeveloped template used by the OSI developers, and is integrated into many interfaces. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt based interface, the interface uses some of the UniInt supplied configuration Page 96

119 5.3 - Basic Interface Node Configuration parameters and some interface specific parameters. UniInt is constantly being upgraded with new options and features. 5.3 Basic Interface Node Configuration The steps outlined in this section describe the basic steps for interface configuration. The steps are provided in a logical sequence for you to follow. However, there is nothing preventing you from doing the many of the steps in a different order than specified below. This discussion applies to VMS, UNIX, and Windows interface nodes. However, the majority of the details are provided for Windows and UNIX Interface Nodes. Differences between the platforms are pointed out as necessary. Also, for the most part, the configuration steps apply whether the interface is on the PI Server Node or on a remote node. Distinctions are made as necessary. These basic interface configuration steps can be summarized as follows. Install the PI-SDK and/or the PI API Connect to PI with apisnap.exe Connect with AboutPI-SDK.exe Configure PI Trusts for the Interface Node Install the Interface Set the Interface Node Time Connect with the Interface Configure Points for the Interface Configure Buffering Configure Interface For Automatic Startup Configure Site-Specific Startup Scripts Configure the PI3 PointSource Table Monitor Interface Performance Configure Auto Point Synchronization Configure the Interface Status Utility Install the PI SDK and/or the PI API On a Windows Interface Node you must install the PI-SDK. The PI-SDK setup kit installs the PI API. After installing the PI-SDK, you should consult the PI API Installation Instructions manual that is installed in the pihome\bin directory. Look for the file API_Install.doc. This manual has many helpful suggestions for post-installation configuration of the PI API and buffering. On a UNIX Interface Node you must install the PI API. See the document entitled PI API Installation Instructions. On a VMS Interface Node, the PI API comes installed with PINET. PI Server System Management Guide Page 97

120 Chapter 5 - Managing Interfaces Connect to PI with apisnap.exe On Windows or UNIX Interface Nodes, one of the first things you should do is to try to connect with apisnap.exe to the PI Server Node. On VMS, the corresponding program is snap.exe. See the PI 2 documentation for details on use of snap.exe. The apisnap.exe program is installed with the PI API in the pihome\bin directory. On Windows, the pihome directory is determined by the pihome entry in the pipc.ini file, which is always located in the Windows directory. On UNIX, the pihome directory is determined by the $pihome environment variable. The syntax for running the apisnap.exe program is apisnap.exe HostName:5450 or apisnap.exe IPAddress:5450 where HostName is the fully-qualified host name for the PI Server Node (i.e., apollo.osisoft.com). The :5450 after the host name or IP address is optional. It specifies the port for the connection. If you can connect with apisnap.exe, you should be able to establish a PI API connection with your interface. If you cannot connect to the PI Server Node with apisnap.exe, try the following troubleshooting steps. Make sure the computer running the PI Server is accessible. Ping by name in both directions. Try adding the Interface Node to the hosts file on the PI Server node if you are having trouble connecting with apisnap.exe. For PI API connections, the PI Server uses reverse name lookup on the IP Address in the connection to look up the host name of the interface node. Most commonly, the lookup is done from a Domain Name Server (DNS). Alternatively, the Interface Node name can be resolved from the hosts file on the PI server node. Check the Firewall security on the PI Server node (see the section, Managing Security) Connect with AboutPI SDK.exe This step applies only to interfaces on Windows that require both PI API and PI-SDK connections. You can start the AboutPI-SDK.exe program from Start >All Programs> PI System >AboutPI-SDK Configure PI Trusts for the Interface Node Once you establish that you can connect with apisnap.exe and AboutPI-SDK.exe, you must configure PI Trusts for the interface node. An interface that connects without a PI Trust is granted world access rights or no access rights depending on the DefaultUserAccess timeout parameter. Since world access rights are read only by default, an interface that sends data to PI without being granted a PI Trust will generate the following message in the interface log on the Interface Node. Page 98

121 5.3 - Basic Interface Node Configuration [-10401] No Write Access - Secure Object Connect with apisnap.exe from the Interface Node to the PI Server node. You will see messages similar to the following in the PI Server Message Log on the PI Server Node: and New Pinet 1 connection: snape No Trust established for: apollo.osisoft.int snape using default login Access Denied: [-10413] No trust relation for this request ID: 64. Address: Host: apollo.osisoft.int. Name: snape The log messages tell us the following. The application name of the connection was snape. The IP Address was The host name was a fully-qualified host name (apollo.osisoft.int). The exact application name, IP Address, and host name as displayed in the message log must be used when configuring PI Trusts. Note that that application name is snape, not apisnap.exe. Also note that using apollo in the PI trust for the above connection would not work. The fully qualified name apollo.osisoft.int must be used. Connect with AboutPI-SDK.exe from the Interface Node. You will a message similar to the following. Trust request from: OSI\MATZEN apollo AboutPI SDK.exe failed: [-10413] No trust relation for this request (110 ms) Unlike the connection from apisnap, host name is apollo, not apollo.osisoft.int. This example illustrates that configuring trusts is sometimes experimental in nature. You must examine the credentials as displayed in the PI Message Log. Below are basic guidelines for creating simple trusts for interface connections. For a comprehensive understanding of trusts and security, read the chapter Managing Security in the PI Server System Management Guide. The discussion below assumes that you are familiar with the information in that chapter. Interface Trusts for PI API Connections When configuring a trust for an API connection, do not specify the Windows Domain or the Windows Username because these credentials are not passed in the PI API connection credentials because PI API connections can come from UNIX and VMS nodes as well as Windows nodes. Trusts with these fields configured will not work for PI API connections. If you use the PI System Management Tools to configure a trust for a PI API application, then the trust configuration wizard will not let you specify these fields. That is, the wizard will prevent you from over specifying the PI API trust. Although it is possible to use the application name in trusts for PI API applications, it is not part of the default recommendations. See the section Using the Application Name in Interface Trusts if you are interested in using the application name in your trusts. We recommend one of two options for configuring trusts from an API application. Option 1 involves configuring the following two trusts. One trust based on IP address and netmask One trust based on fully-qualified host name (i.e., apollo.osisoft.com) * PI Server System Management Guide Page 99

122 Chapter 5 - Managing Interfaces Option 2 provides slightly tighter security. Instead of configuring the above two trusts, set up the following trust. One trust based on IP address, netmask, and fully-qualified host name In Option 2 if the IP address or fully-qualified host name changes, the trust will fail, whereas in Option 1, it will not fail. Interfaces Trusts for PI API and PI SDK Connections Check your interface-specific documentation to see if your interface requires PI-SDK connections in addition to PI API connections. We recommend configuring trusts in one of two ways for applications that require both connection types. Option 1 involves setting up the following 3 trusts. One trust based on IP address and netmask. This trust works for both PI API and PI- SDK connections. One trust based on fully-qualified host name (i.e., apollo.osisoft.com). The PI API always uses the fully-qualified host name as opposed to an abbreviated form of the name. One trust based on the simple host name (i.e. apollo). The SDK typically uses the abbreviated simple host name. To verify the host name the PI-SDK will use, run pidiag -host on the Interface Node. With these 3 trusts established, the interface first attempts to connect by IP address. If the IP address changes, then a trust is granted based on the host name. Because the PI-SDK and PI API host name processing may differ, you should set up two trusts, one for each form of the host name. Option 2 provides slightly tighter security. Set up just 2 trusts, one for the PI API and one for the SDK. In each trust, include host name, IP address, and netmask as qualifications for connection. One trust based on IP address, netmask, and fully-qualified host (i.e., apollo.osisoft.com). This trust works for the PI API connection. One trust based on IP address, netmask, and simple host name (i.e. apollo). This trust works for the PI-SDK connection. To verify the host name the PI-SDK will use, run pidiag -host on the Interface Node. Trusts for Interface Nodes with Multiple NICs If your Interface node has multiple NICs, you must set up a trust for each IP address, even if you just see the connection with one. To see all IP addresses for a given computer, type ipconfig -all at a command prompt. Using the Application Name in Interface Trusts Although it is possible to use the application name in trusts for PI API applications, the additional security gains is typically not warranted by the increase in complexity. Before adding complexity to your trusts be aware that interfaces is only as secure as the room the Page 100

123 5.3 - Basic Interface Node Configuration interfaces are in. Interfaces are configured to allow writing data to the PI Server, so physical access to the machine allows any user who can log on to that machine to run PI applications that could write data to the PI Server and a malevolent user could use an application name for which a trust is already configured. Part of the complexity arises when buffering is configured on the Interface Node because a PI Trust must be configured for the buffering application as well as the interface. For Windows and UNIX, the buffering application (bufserv.exe) has an application name of APIBE. For VMS, the buffering application has an application name of EXCP plus a 4-digit process identifier. There is additional complexity for interfaces that connect with both the PI API and PI-SDK because the PI API and PI-SDK pass different Application Names in their connection credentials. For example, the OPC interface uses opcie for the API and opcint.exe for the SDK. The application name for PI API interface connections can be determined by examining connection messages in the PI Message Log on the server, whereas the PI-SDK uses the actual file name of the executable Install the Interface The basic next step after configuring PI Trusts is to install the interface. The particulars of interface installation are highly platform dependent. For example, on Windows most interfaces can be installed from an installation kit. On VMS, most interfaces come preinstalled on the VMS PINet node. Consult the interface-specific documentation for details. On Windows the installation kit typically installs the PI Interface Configuration Utility (PI- ICU), which is a GUI for making several interface configuration tasks easier. You can start the PI-ICU from the Start > All Programs > PI System > PI-Interface Configuration Utility. On Windows interfaces are installed by default in a subdirectory of the pihome\interfaces directory. As mentioned above, the pihome directory is defined by the pihome entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the Windows directory. A typical pipc.ini file contains the following lines: [PIPC] PIHOME=D:\Program Files\PIPC The above lines define the D:\Program Files\PIPC directory as the root of the pihome directory tree. For example, an interface called MyInterface would be installed to D:\Program Files\PIPC\interfaces\MyInterface by default Set the Interface Node Time In order for PI to accurately store and retrieve data, interface computers must have the correct settings for time, time zone, and Daylight Savings Time (DST). Most interfaces send correct timestamps even if the Interface Node is located in a different time zone than the PI Server. That is, for most interfaces you should set the clock to its correct local time, time zone, and DST setting. Also, you should configure the clock to automatically adjust for daylight saving changes. PI Server System Management Guide Page 101

124 Chapter 5 - Managing Interfaces If the interface-specific documentation does not give specific instructions for setting time, time zone, and DST, these guidelines should typically result in the correct timestamps being set to PI. Exceptions are noted in the documentation for each interface. The most common exception is for Foxboro Interface nodes, which must have their time zone settings set to GMT. Caution: In all cases, the PI Server clock should be set to its correct local time, time zone, and DST setting Connect to the PI Server with the Interface The next step is to connect to the PI Server with the interface. PI Points do not need to be configured before this is done. On Windows, it is best to try to connect by running the interface interactively instead of trying to run the interface as a Service. Successful execution of the interface requires that a certain minimum number of required command line parameters be specified. The PI Interface Configuration Utility makes the task of configuring these command line parameters considerably easier. Although the interfacespecific documentation must be consulted, the following command line parameters should be mentioned because they are fundamental to most UniInt-based interfaces. Parameter /ps=x required /id=x sometimes required /host=host:port recommended parameter Description The /ps flag specifies the point source for the interface. x is not case sensitive and can be any single character. For example, /ps=p and /ps=p are equivalent. The point source that is assigned with the /ps flag corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. Consult the PI3 PointSource table to make sure you are not using a PointSource that is already configured for another interface. The /id flag is used to specify the interface identifier. For example, /id=1 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. Many interfaces also use the /id flag to identify a particular interface copy number that corresponds to an integer value that is assigned to one of the Location code point attributes, most frequently Location1. For these interfaces, one should use only numeric characters in the identifier. The /host flag is used to specify the PI Home node. host is the IP address of the PI Sever node or the domain name of the PI Server node. port is the port number for TCP/IP communication, which should always be specified as 5450 for communication to a PI 3 server. Page 102

125 5.3 - Basic Interface Node Configuration Parameter /f=ss or /f=ss,ss or /f=hh:mm:ss or /f=hh:mm:ss,hh:mm:ss required for scan-based interfaces /stopstat recommended parameter Description Each occurrence of the /f flag on the command line specifies a scan class for the interface. A particular PI Point is associated with a scan class via the Location4 PI Point attribute. The /f flag defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. If the /stopstat flag 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. After starting the interface, do the following. Examine the PI Message Log to make sure that the interface connects with a successful trust logon. Examine the message log on the interface node for error messages. On Windows, the message log is pihome\dat\pipc.log. On UNIX, the message log is $pihome\dat\pimesslogfile. On VMS, the message log is PIsysmgr:pimesslog.txt Configure Points for the Interface Configure PI Points for the interface. Although you must consult the interface-specific documentation to configure your PI Points, there are a few attributes that are configured in the same way fore most UniInt-based interfaces. Point Attribute PointSource Location1 Description The PointSource is a single or multiple character sequence that is used to identify the PI point as a point that belongs to a particular interface. For example, you may choose the letter R to identify points that belong to the Random interface. Note that multi-character PointSources are supported only with PI API 1.6 and greater. The PointSource attribute must correspond to the /ps flag in the startup command line of the interface. Consult the PI3 PointSource table to make sure you are not using a PointSource that is already configured for another interface. The Location1 attribute is used by many interfaces to identify an interface number. When used in this fashion, the Location1 attribute must correspond to the /id flag on the startup command line of the interface. PI Server System Management Guide Page 103

126 Chapter 5 - Managing Interfaces Point Attribute Location4 Scan Shutdown Description For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. For example, a PI Point with Location4=1 will be scanned according to the first occurrence of the /f flag in the startup command file. A PI Point with Location4=2 will be scanned according to the second occurrence of the /f flag, and so on. If the Scan attribute is set to OFF for a UniInt based interface, the point will be removed from the interface. This can be useful when troubleshooting the interface. When PI is restarted, the default behavior of the PI Shutdown Subsystem is to write Shutdown events to all PI Points that have their Shutdown attribute set to 1 (true). Typically, it is undesirable for the PI Server to write shutdown events for Interfaces Nodes that have a buffered data source on a node that is remote to the PI Server Node. The Shutdown attribute should be set to 0 for PI Points that belong to these interfaces. These remote, buffered interfaces should write their own shutdown events when the interfaces are shut down. This is typically configured with the /stopstat command line parameter for UniInt-based interfaces. After configuring a few PI Points, do the following. Restart the interface and examine the log file to make sure that the points are loaded by the interface. For UniInt-based interfaces, you will see a message similar to the following. 07-Nov-05 23:10:44 Total Number of points matching pointsource 'R' is 5 Look for error messages in the interface log. If PI Trusts are not configured correctly for the interface you will see the following error when the interface tries to write data to PI. [-10401] No Write Access - Secure Object Use apisnap.exe to verify that the interface is writing data to your PI Points Configure Buffering Once you have demonstrated that you can collect data with your interface, it is time to configure buffering. Some interfaces do not require buffering or work better without buffering. You must consult the interface-specific documentation to determine this. On VMS, there is no need to configure buffering because it comes as part of PINet. The information below applies only to UNIX and Windows Interface Nodes. For more details see the PI API Installation Instructions. On Windows, the PI API Installation Instructions is installed by the PI-SDK setup kit in the pihome\bin directory. The file name is API_install.doc. If buffering is enabled on UNIX and Windows, the pihome\dat\piclient.ini file will contain the following two lines. [APIBUFFER] BUFFERING=1 Page 104

127 5.3 - Basic Interface Node Configuration The file can be edited with a text editor. Setting buffering=0 turns buffering off. Any changes that are made to the pihome\dat\piclient.ini will only take effect when bufserv is restarted. The default and maximum size limit of buffer files is 2,000,000 KB (~2GB). If there is not 2GB of disk space available, then the buffer will grow as large as possible before failing. The maximum size limit can be set to a value less than 2,000,000 KB with the maxfilesize parameter in the piclient.ini file. For a full list of configuration options, refer to the PI API Installation Instructions. The following applies to buffering for PI API version 1.6 and greater on Windows and UNIX. In PI API version 1.6 and greater, data that is sent via the PI API can be buffered to multiple PI server Nodes. The PI Server Nodes for which buffering is enabled is configured in the pihome\dat\piclient.ini file in the [BUFFEREDSERVERLIST] section. In addition to the parent process, one buffer server process will be spawned for each buffered server specified in the list. See PI API Installation Instructions for more details. The connection name for the interface (usually specified in the /host parameter) must exactly match the buffer server name configured in the pihome\dat\piclient.ini file. For example, in order for buffering to work for a UniInt-based interface, the IPAddress or HostName specified by the /host command line parameter would need to be identical to a PI Server listed in one of the entries specified in the [BUFFEREDSERVERLIST] section in the pihome\dat\piclient.ini file. The IPAddress and HostName are not interchangeable in this case, if the IPAddress is used in the interface and the HostName in the pihome\dat\piclient.ini file, then interface connection via the IPAddress would be unbuffered. Bufserv now supports event distribution to multiple PI servers. This is sometimes referred to as n-way buffering or buffering to replicated servers. Event distribution to multiple PI servers consists of the taking data sent to one buffered server distributing of the same event to multiple buffer servers. The list of PI servers to receive distributed events is configured in the [REPLICATEDSERVERLIST] section in the piclient.ini file. The distributed event is not manipulated in any way, which means that the event does not have the point ID or the timestamp altered. Therefore, the replicated PI servers must all have synchronized point databases. PI servers in the [REPLICATEDSERVERLIST] section must also be in the [BUFFEREDSERVERLIST] section. The following applies to versions of the PI API prior to version 1.6. Prior to PI API version 1.6, buffering could only be enabled for the default PI Server node. The default PI-Server node is specified in the pihome\dat\pilogin.ini on Windows and in the pihome\dat\piclient.ini node on UNIX. The connection name for the interface (usually specified in the /host parameter) must exactly match the name of the default PI-Server node. configured in the pihome\dat\piclient.ini file. The following applies to Windows only, but it applies to all version of the PI API. PI Server System Management Guide Page 105

128 Chapter 5 - Managing Interfaces Buffering should be installed as an automatic service. This can be accomplished though the Tools > API Buffering menu in the PI Interface Configuration Utility. You can enable and disable buffering from the PI-Interface Configuration Utility from the Tools > API Buffering... menu. The PI-Interface Configuration Utility makes all of the necessary changes to the piclient.ini file. The interface service must be configured to depend on bufserv to ensure that buffering starts first. Otherwise the interface might establish an unbuffered connection to PI before bufserv starts. Monitoring Buffering To ensure that buffering is functioning properly, check the interface log each day. You can also use the buffering utility, bufutil.exe, to check the buffering service. For example, bufutil.exe can be used to list the number of events that are currently in the buffer. When connected to the PI server, the number of unprocessed events should generally be zero, but may show a finite number since events are streaming through the buffers. For version 1.6 and greater of the PI API, when bufutil.exe is started, the currently selected buffered server is listed. There is a menu option to change the selected server Configure Interface for Automatic Startup Once you have demonstrated that you can collect data while running the interface interactively, configure the interface for automatic startup. On Windows, this is done by configuring automatic services. On UNIX, this can be handled by adding your interface to sitestart.sh script and configuring pistart.sh for automatic startup as described in Chapter 1, Starting and Stopping PI. Site-specific startup scripts are discussed later in this chapter. It is recommended to install services with the Interface Configuration utility from the services tab. If you plan to enable buffering, you should install the interface service to depend upon the following services. bufserv tcpip You can start and stop your interface service either though the Interface Configuration Utility or though the command line. If the interface service is called MyInterfaceService you could run the following command from a command prompt. To start a service, type the command: net start MyInterfaceService To stop a service, type the command: net stop MyInterfaceServic When an interface starts as a service, the interface service opens the corresponding MyInterfaceService<ServiceID>.bat file to determine its command line arguments. ServiceID s and the manner in which interface services get their command line arguments are discussed in detail in the UniInt End User Manual. These details are managed by the PI Interface Configuration Utility. Page 106

129 5.3 - Basic Interface Node Configuration Configure Site-Specific Startup Scripts The following discussion has been limited to UNIX and Windows nodes. On each node, there is at least one shutdown script that calls a site-specific shutdown script. Likewise, there is at least one startup script that calls a site-specific startup script. You should only modify the site-specific scripts because the main startup and shutdown scripts are overwritten by the installation script when PI is upgraded. In all cases, the site-specific startup scripts must be edited manually with a text editor. PI Server Node on Windows If for some reason you must run an interface on the PI Server, you can configure the interface to start and stop with the PI Server by adding it to the site-specific startup and shutdown scripts. For interfaces that connect only via the PI API, the scripts provide a convenient means of shutting down all programs that use the PI API. However, for an interface that depends on the PI-SDK, it is more important to add the interface to the site-specific stop and start scripts because PI-SDK programs depend upon pinetmgr.exe, and pinetmgr.exe cannot be shut down until all services that depend upon it are shutdown. The most common PI-SDK interface that is configured to run on the PI Server node is the PI Batch Generator Interface. By default, the PI Batch Generator interface installed on the PI Server node, but the interface is configured as a manual service, and the interface is not configured to be stopped and started by the site-specific scripts. The startup scripts on the files are as follows. Startup script Corresponding shutdown scripts and site-specific scripts Shutdown script Site-Specific startup script Site-Specific stop script Script location pistart.bat None pisitestart.bat None \PI\adm pisrvstart.bat pisrvstop.bat pisrvsitestart.bat pisrvsitestop.bat \PI\adm On Windows the difference between pistart.bat and pisrvstart.bat is that the former is used to start PI interactively and the latter is used to start PI as a service. To start your interface interactively, add a line similar to the following to pisitestart.bat. program files\pipc\interfaces\myinterface\myinterface.bat To start your interface as a service, add a line similar to the following to pisrvsitestart.bat. net start myinterface PI Interface Node on Windows The site-specific startup scripts are named differently on an Interface Node, than on the PI Server node. The scripts provide a convenient means of shutting down all programs that use the PI API and PI-SDK that communicate to the PI Server node. PI Server System Management Guide Page 107

130 Chapter 5 - Managing Interfaces Startup script Corresponding shutdown scripts and site-specific scripts Shutdown script Site-Specific startup script Site-Specific stop script Script location pistart.bat pistop.bat sitestrt.bat sitestop.sh pihome\bin\ PI Server Node on UNIX The following are the startup and shutdown scripts on a UNIX PI Server node. Startup script Corresponding shutdown scripts and site-specific scripts Shutdown script Site-Specific startup script Site-Specific stop script Script location pistart.sh pistop.sh pisitestart.sh pisitestop.sh $pihome/adm/ Interface Nodes on UNIX The following are the startup and shutdown scripts on a UNIX Interface node. Startup script Corresponding shutdown scripts and site-specific scripts Shutdown script Site-Specific startup script Site-Specific stop script Script location pistart.sh pistop.sh sitestart.sh sitestop.sh $pihome/bin/ Configure PointSource Table When you create a PI Point with a given PointSource, the PointSource is automatically added to the PIPTSRC table. The PIPTSRC table tells you how many PI Points there are for each PointSource. As mentioned above, you should consult the PIPTSRC table before configuring points for a new interface because you want to make sure that you are not using a PointSource that is already being used by another interface. Automatically generated entries in the PIPTSRC table have a blank description. You should edit the PIPTSRC with the piconfig utility to add a description Monitor Interface Performance Most UniInt-based interfaces have built-in ways of monitoring interface performance. Most of these require PI Points to be configured. However, performance summary log messages are written to the interface log file by default. For interfaces that run on Windows, all of the performance statistics for an interface can be collected via Windows Performance Counters. That is, there are Windows performance counters that correspond to the performance summary log messages, I/O Rate Points, and Performance Points for Scan Classes. There are also additional Windows Performance Counters that extend the number of interface statistics beyond that which can be gathered on non-windows platforms. Page 108

131 5.3 - Basic Interface Node Configuration Windows Performance Counters Many UniInt based interfaces now support Windows Performance Counters. Without any PI Point configuration, the counters for the interface can be viewed from the Windows Control panel under Administrative Tools > Performance. The one restriction is that the interface must be running as a service in order for the counter to be visible. The following diagram shows how the counters may appear for the PI Random Interface on the PI Server node. In order to save the Windows Performance Counter data to PI, you must configure the PI Performance Monitor Interface, which is available as basic or full versions. The basic version is installed on the PI Server Node by default. You can collect performance counter data with the interface from local and remote interface nodes. For more information, see the PI Performance Monitor Interface documentation. The following performance counters are available for most UniInt-based interfaces that run as a service. Counter Name Interface up-time (seconds) IO Rate (events/second) Description The number of seconds since the interface has started. This counter is incremented once a second. The number of events per second received by the interface. If this counter is viewed from the NT performance monitor, one should increase the update time of the performance monitor to the minimum scan period for the interface. For example, say that the minimum scanning period for the interface is 5 seconds (/f=5). One can set the PI Server System Management Guide Page 109

132 Chapter 5 - Managing Interfaces Counter Name Description update rate of the performance monitor to 5 seconds by selecting the Chart command from the Options menu. In the dialog box, change the periodic update time to 5 seconds. If the update time is left at 1 second, then the IO Rate will appear to go to zero between scans because no events are received between scans. Point Count Scan Time (milliseconds) Scheduled Scans: % Missed Scheduled Scans, % Skipped Scheduled Scans: Scans this interval Log file message count Points edited in the interface Points added to the interface Points removed from the interface Number of points loaded by the interface. Time in milliseconds to call developer function and to write values to PI. There is one Scan Time counter per scan class. Percentage of missed scans since starting the interface. If a scan occurs more than 1 second after its scheduled time, the scan is considered missed. There is one Missed Scans counter per scan class. Related counters: Scheduled Scans: % Skipped Scheduled Scans: Scans this interval Percentage of skipped scans since starting the interface. If a scan occurs 1 scan period or more after its scheduled time, then 1 or more scans are considered skipped. There is one Skipped Scans counter per scan class. Related counters: Scheduled Scans, % Missed Scheduled Scans, Scans this interval The total number of scans in the current performance interval. This total is the current sample size that is used to evaluate the % Missed Scans and the % Skipped scans. The performance interval is 8 hours by default, but this can be changed by the /perf command-line argument. The minimum performance interval is 60 seconds (see the /perf argument for more information). When the performance interval is exceeded, the previous samples are discarded and the sampling starts again from scratch. Related counters: Scheduled Scans, % Skipped Scheduled Scans, % Missed Number of messages that have been written to the log file. Only applies to the instance _Total. Number of point edits that have occurred. Only applies to the instance _Total. Number of point that have been added to the interface. Only applies to the instance _Total Number of point that have been removed from the interface. Only applies to the instance _Total Page 110

133 5.3 - Basic Interface Node Configuration Performance Summary Log Messages If the performance of a UniInt-based interface falls below a particular level, the interface will periodically write a performance summary to the interface log file. For each scan class, the summary shows the percentage of scans hit, the percent of scans missed, and the percent of scans skipped. Scans that occur on time are considered hit. If a scan occurs more than 1 second after its scheduled time, the scan is considered missed. If a scan occurs 1 scan period or more after its scheduled time, then 1 or more scans are considered skipped. Say that a particular scan class has a period of 2 seconds. If a scan for this class occurs 1.1 seconds after its scheduled time, then 1 scan has been missed. However, no scans have been skipped because the next scan still has the opportunity to occur at its scheduled time, which happens to be 0.9 seconds after the last scan in this case. For scans that have periods of 1 second or less, the above definition of a missed scan does not make sense. In these cases, scans are considered either hit or skipped. Since every skipped scan is also considered to be a missed scan, the scan performance summary should indicate the same percentage of skipped and missed scans for scan classes with periods of 1 second or less. The performance summary is logged every 8 hours if the hit ratio (hit ratio = hits / (hits + misses)) drops below The frequency at which performance summaries are printed out can be adjusted using the /perf command line argument. Configure I/O Rate Points I/O Rate Points are PI Points that record 10-minute averages of the number of events per minute sent to the PI Server. Note that data collected by the I/O Rate Point is the same as the data that can be collected from the I/O Rate counter with the PI Performance Monitor Interface, except that the rate reported by the PI Performance Monitor Interface has units of events per second and the period over which the rate is averaged depends upon the scan rate of the Performance Monitor Interface. For example, the average will be taken over 10 minutes for a 10 minute scan class. The I/O Rate Point, however, has the advantage that it can be configured for interfaces on UNIX and VMS as well as Windows. Note that VMS and UNIX nodes use a separate iorate program to maintain a list of rate tags. Windows nodes do the calculation within the interface program. Thus, only one program can increment a Windows event counter. Use the following procedure to create an I/O Rate Point. On Windows, the following is can be done automatically from the PI Interface Configuration Utility. Create a PI Point with the following attributes: PointSource = L; PointType = Float32; Zero = 0; Span = 3000 (typically, but greater as needed); EngUnits = Events/Min. In the script file that starts the interface, use the /ec switch to assign an event counter between 1-34 or This counter must be unique within iorates.dat (below). For example, to assign an event counter of 5, use this line:...\interfaces\myint\myint /pa=x /ec=5 /id=1... Locate the iorates.dat file or, if it does not exist, create it. On Windows and UNIX, the iorates.dat file is located in the pihome\dat directory. PI Server System Management Guide Page 111

134 Chapter 5 - Managing Interfaces On VMS the iorates.dat file is located in the PISYSDAT directory. Create an entry in iorates.dat to associate the event counter number with the tag. For example, sychip01,5 would associate event counter '5' with a tag called sychip01. Performance Points for Scan Classes Performance Points for Scan Classes are PI Points that record the total number of seconds required for an interface scan data from a device and subsequently send the data to the PI Server. This number is updated after data is sent to the PI Server at the completion of each scan. The closer the scan time is to 0 seconds, the better the performance. The data has engineering units of seconds and is recorded to millisecond resolution if a PointType of type float16, float32, or float 64 is used for the Performance Point. Performance can be configured for interfaces on UNIX and VMS as well as Windows. The Windows Performance Counter that corresponds to a Performance Point is the Scan Time counter. Data that is collected from the Scan Time counter from the PI Performance Monitor Interface will have units of milliseconds. Performance points are an important tool for tuning scan classes, because if a scan takes too long, it can cause the next scan to be skipped, resulting in data loss. The scan classes may be tuned by changing the scan frequency, the scan offset, and the number of tags in the scan list. For more information on configuring scan classes and scan lists, consult the interface-specific documentation. Performance points are configured as follows. Set the extended descriptor (exdesc) to: or to: PERFORMANCE_POINT PERFORMANCE_POINT=interface_id where interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of scan classes. Set the PointSource attribute to correspond to the /ps flag on the startup command line of the interface. Set the PointType attribute to any of the floating-point point types that are supported by the PI Server Configure the PI Interface Status Utility The PI Interface Status Utility provides a convenient means to distinguish true flatlines in data from disruptions in data collection. That is, the utility provides a means of indicating to a user that data from a given interface is stale. Data becomes stale when no fresh data is sent Page 112

135 5.3 - Basic Interface Node Configuration from the interface to the PI Server. For example, stale data can occur under the following scenarios. The interface is running but the PI API node cannot send data to the PI Server. The interface is not running and a system digital state was not written to indicate that the interface has been shut down. This could happen if the interface crashes. One PI Interface Status tag is configured per monitored interface, each tag monitors a watchdog tag collecting data from the interface. If the watchdog tag s value on the PI server hasn t updated after a user specified amount of time, the PI Interface Status tag s status changes to a bad digital state status. If you decide to configure the PI Interface Status Utility, then the utility is always configured to run on the PI server Node. For more information see the PI Interface Status Utility documentation Configure Auto Point Synchronization Many interfaces, such as the PI OPC Interface, support Automatic Point Synchronization (APS). For example, PI Points on the PI Server can be automatically created based on the points in the OPC server using a configurable set of rules. You must consult your interface specific documentation to determine whether your interface supports APS. You can also consult the PI AutoPointSync User Manual. PI Server System Management Guide Page 113

136

137 Chapter 6. MANAGING SECURITY Typically, PI Server is used in production systems where secure, correct, and reliable operation is required. For this reason, a number of security mechanisms are available to protect against both willful and accidental tampering with the system. These include: Physical Security Network Security Operating System Security PI Server Security Firewall Control at the IP Address Level User Security User Name and Password Control for Individuals Groups Control for Separate Groups of Workers Database Security User, Group, and Access Rights to PI Point, PI User, and PI Digital State Databases. Point Security for Point Attributes and Point Data Trust-Login Security 6.1 Physical Security Once a user is logged in, access is granted until the user logs out. It is not unusual for the PI Server computer to be left unattended while a user is logged in. For this reason, physical access to the PI Server Home Node should be restricted. It is recommended that the PI Server computer be located in a lockable, temperature-controlled computer room with an uninterruptible power supply. Limiting the use of a single computer solely for data archiving can further enhance security and reliability. Thus, it is recommended for data collection to be distributed on one or more PI API or PINet Nodes. 6.2 Network Security Even if physical access to the PI Server computer is limited, access is available over the network. Network security is provided through several mechanisms. On TCP/IP, access to a PI Server System Management Guide Page 115

138 Chapter 6 - Managing Security given node is controlled via the host table, domain name server, or DHCP. See your networking documentation for details. The network router may also be configured to restrict traffic on specified subnets. Network setup and security is very important for satisfactory PI System operation. The details of this are broad, diverse, and beyond the scope of this manual. 6.3 Operating System Security The PI Server files are protected by the hosting operating system security. On all platforms, each executable, data file, and directory may independently be given read, write, and execute access on a per-user or per-group basis. The System Manager s account is called administrator on Windows systems and root on UNIX systems. Since the System Manager s account is central to a secure system, it is imperative that the account password be well chosen (to guard against password guessing), periodically changed, and known only to a small group of trusted managers. During installation, all the PI system files are created with the system s default security, and are owned by the installing user. This should be the System Manager. The System Manager may change the ownership and the access rights to these files. This might be done to assure that only selected users can have any access to the PI system. It is mandatory to keep full access to the System Manager and to make sure that the PI services have full access to the PI files. It is best to keep the file ownership as the System Manager. If tighter security is required, limit the access for group and world, and allow full access to the System Manager and to the Administrators group. 6.4 PI Server Security It is typical for a PI System Manager to implement restricted access to the Data Archive and the Point Database beyond what is provided by physical, network, and operating system security. In using PI Server security features, the System Manager is responsible for: Restricting access via the PI firewall Creating PI users accounts and groups Assigning users to groups Assigning an owner and a group to all databases and setting the access rights. Each database can have a different owner and a different group. The default owner and group is piadmin. The default access is o:rw g:r w:r. See the section on Database Security below. Note: Membership in the piadmin group does not automatically give special privileges. The piadmin user account does give unlimited access. Page 116

139 6.5 - Firewall Security Assigning owners and groups to points Setting the access permissions on each point, both for attributes and for data Assigning owners and groups to modules. Module level security is only accessible with the System Management Tools, which you can obtain from the OSIsoft support Web site. Maintaining the Trust Database for automated logins Running applications on the system console The piadmin user account has full privileges on all PI objects. Running any application from the PI home console grants that application the piadmin status. In high security environments, piconfig and pisetpass utilities can be forced to perform a login. This is done with the timeout parameter CheckUtilityLogin set to 1. The user is prompted to enter a PI username and password before being allowed to proceed when this feature is enabled Running applications remotely Most PI applications can run remotely and have the -remote set of flags for that purpose. Login as piadmin grants the user full access to all PI objects. Caution: Some operations are modifying local files and cannot be done remotely. Specifically this applies to modifications of the timeout and firewall tables. 6.5 Firewall Security The first level of PI access security is a firewall maintained by the pinetmgr subsystem. The firewall allows the PI System Manager to control access to the PI Data Archive at the IP address level. The pinetmgr process manages all connections to PI, including subsystem connections and TCP/IP applications. pinetmgr uses the PI Firewall Database to screen access based on the IP address. The database is a list of IP addresses and/or IP address masks. Each entry is associated with the ALLOW or DISALLOW keyword, and this specifies whether or not pinetmgr completes the connection request. piconfig is used to maintain the PI Firewall Database. Note: Requests from the local host (that is, the same computer on which pinetmgr is running on) are always allowed. PI Server System Management Guide Page 117

140 Chapter 6 - Managing Security Firewall Database The Firewall Database is a table with two fields. The first field is an IP address, IP address mask, or host name. The second field defines whether access for that address, mask, or host name is allowed. IP address mask syntax consists of a portion of an IP address and asterisks. An asterisk in an IP address field matches any number. Here are two examples: * New connection host names and IP addresses are checked against the Firewall Database in the following order. 1. If the connection originates from the local host, the connection is always accepted. 2. Firewall Database is searched for an exact match of IP address entry or host name entry. If an entry is found the search stops and the connection is treated according to that entry. 3. Firewall Database is searched for a wildcard match, for example, the connecting address of matches a Hostmask of *.*. A matching Disallow has precedence over an Allow. Here is an example: Host/Mask Value * ALLOW DISALLOW Only hosts within the subnet are allowed connections is not allowed to connect; even though it matches the first host mask. Modifying the Firewall Database Piconfig is used to modify the Firewall Database. PI will recognize modifications to the Firewall Database within 15 minutes, or upon restarting PI, whichever comes first. The Firewall Database can only be modified from a local piconfig session. List Attributes and Entries Example This piconfig example lists all entries: pi_gen,pifirewall hostmask,value hostmask="*" *.*.*.* ALLOW The listing shows the default firewall setting - all connections are allowed. Page 118

141 6.5 - Firewall Security Limit Connections Example The next example modifies the Firewall Database to only allow connections from the subnet pi_gen,pifirewall create,t hostmask,value Piconfig> *, ALLOW Disallow Specific Host Example Host names may also be used to allow or disallow specific host machines. The host name with domain name must be entered. For example to prevent connections from host bobcat on domain somewhere.com the following must be entered: pi_gen,pifirewall create hostmask,value Piconfig> bobcat.somewhere.com,disallow Rename an Entry Example The attribute NEWhostmask is used to rename an entry in the Firewall Database. Here is an example: pi_gen,pifirewall list hostmask,value hostmask=* *,ALLOW bobcat.somewhere.com,disallow edit hostmask,newhostmask Piconfig> bobcat.somewhere.com, tomcat.somewhere.com Connection attempts from tomcat will be disallowed. For example if apisnap run from that host, it would behave as follows: e:\pi\adm>apisnap tamarind:5450 PI API version Attempting connection to tamarind:5450 Error 2, connecting to tamarind:5450 The pipc.log on host tomcat would have the following entry: 11-Dec-02 16:19:03 D:\piapi\piapi32\apicomm.c> recv: Error: 10054, Unknown error A look at the PI Server message log, would have a message indicating the connection was not allowed: 0 pinetmgr 11-Dec-02 16:29:37 >> PInet Refused TCP/IP connection, hostname: tomcat.somewhere.com, PI Server System Management Guide Page 119

142 Chapter 6 - Managing Security Modify the Hostmask *.*.*.* Example If you wish to modify the hostmask *.*.*.*, you must use the following example. Do not use a wild card selection. pi_gen,pifirewall edit hostmask,value Piconfig> "*.*.*.*",DISALLOW To delete the global mask entry use the following: delete hostmask Piconfig> "*.*.*.*" Note: To disallow all network connection, make sure you have an entry with *.*.*.*,Disallow, and all other entries are either deleted or set to Disallow. Note: PIconfig loads the PIfirewall table in memory; all edits are to the in memory image. Changes are written to disk when the new table is loaded or piconfig is exited. 6.6 Database Security Database level security controls access to the various PI server databases such as PI Point and PI Module Database. PI Server installation sets the owners of these tables to piadmin. Therefore, only the piadmin account can initially change the settings. After installation, system administrators can alter the security settings to grant other users modification and access privileges. Following a brief description of all the security tokens in the DBsecurity table: PIDBSEC Only piadmin can change this token, which allows other users to view/change the DBsecurity table itself. The PIDBSEC token also controls programmatic access to the timeout table. Other users or groups may still be assigned modify privileges in the DBsecurity table but any changes to this token must be done by piadmin PIARCADMIN Controls access to archive management functions: Archive creation and registration. Archive shifts. To create new archives or change their attributes the user needs write access to this token. Archive backup operations require read access to this token. Page 120

143 6.6 - Database Security PIARCDATA Controls access to archive data that is not point specific. Access to archive events is controlled by individual point security. Such general data includes the list of archives (piartool -al) archive counters, archive activity grid and cache information (piartool -as, piartool -aag, etc.) PIartool -aw is also controlled by this token although it does access actual archive events PIBatch Controls the PIbatch database PICampaign Controls the PIcampaign database PIDS Controls the Digital States table. To create or edit sets or states the user needs write access to this token PIHeadingSets Controls the PIheadingsets database PIModules Controls the creation and modifications of modules in the MDB. Note that each module has its individual ownership and security specifications. This token controls access to the database as a whole PIPOINT Control the Point database. As with the MDB, there is individual point security specifications. This token also controls access to the Point Source table PITransferRecords Controls the creation and modification of transfer records in the MDB PIUSER This token controls several tables: PIusers, PIgroups, PIContext and PItrust Individual Subsystem Tokens Every PI subsystem has now a security token that controls access to that subsystem thread table and auditing. Initially, this token is owned by piadmin and is not visible in the Dbsecurity table. This setting can be modified by adding the appropriate token to the table. Note: See examples of managing the DBsecurity table in the PIconfig utility chapter PI Server System Management Guide Page 121

144 Chapter 6 - Managing Security 6.7 Point Security Security for points is assigned on two separate levels. Point attributes (zero, span, descriptor, etc.) have one access level and the point data values (Snapshot and Archive data) have another. Thus, you can have different owners and different access for point attributes than for point data Point Data Access When a point is created, the Archive and Snapshot data for the point are assigned a point data owner and a data group. The data are also assigned various combinations of read and write access for the data owner, group, and world Point Attribute Access When a point is created, the attributes of the point (such as zero, span, compression specifications, etc.) may be assigned to a different owner and different group than the point data. Note: Changing point ownership or security access is best done separately from other point editing operations. For example, change the span and the compression deviation first, and then change the security or the ownership. There is not any relationship necessarily between the point owner and the point group. Security Scenario for Users In a typical facility, a control engineer may be assigned to be the owner of the point attributes for the instruments that he or she is responsible for configuring. The point owner may be assigned ownership and read and write access for the data as well. On the other hand, the control room staff as a group, may be given read and write access to the data but be limited to read only access for the attributes. Interfaces usually need read/write access and use a trust login to obtain the privileges of a particular user. See Trust Login, page 125. System Manager Privileges System Manager privileges allow changing access permissions for any point, without regard to the point attribute owner (ptowner). The manager can override and change any setting, even if access is restricted. Note: The user piadmin is a special user. This account is the PI System super user. It has full access to all databases and database records regardless of security attribute settings. piadmin is the only user that has this level of privileges Access Algorithm Whenever a user logs in, the following algorithm is used to determine what access to a point is granted: Page 122

145 6.7 - Point Security 1. If the requester is piadmin, then grant full privileges. 2. If the requester is the owner, then grant the privileges assigned to the owner. 3. Otherwise if the requester is a member of the group, then grant the privileges assigned to the group. 4. If the requester is neither the owner nor a member of the group, then grant the privileges assigned to the world. Note: If a requester is a member of a given group, and group permission is more restrictive than world permission, then world access to the point is granted Assigning and Changing Ownership and Access Permissions Ownership and access permissions are assigned using the piconfig utility. The piconfig Utility on page 171 explains how to use this utility. The point owner or data owner can change the security attributes in the Point Database using piconfig. Changing the Point Attribute Owner Example In this piconfig example, open the table and list the point access ownership for a tag. Then change the owner for this point. * (Ls) pipoint * (Ls) tag, ptowner * (Ls) tag=sinusoid * (Ls) SINUSOID,piadmin * (Ls) edit * (Ed) tag, ptowner * (Ed) Piconfig> sinusoid, tom * (Ed) list * (Ls) tag, ptowner * (Ls) tag=sinusoid * (Ls) SINUSOID,tom Changing the PtGroup, DataOwner, and DataGroup attributes works similarly. Changing Point Attribute Access Permissions Example In this piconfig example, open the table, list the attribute access permissions, and then change them by adding group and world read permission: * (Ls) pipoint * (Ls) tag, ptaccess * (Ls) tag=sinusoid * (Ls) SINUSOID,o:rw g: w: * (Ls) edit * (Ed) tag, ptaccess PI Server System Management Guide Page 123

146 Chapter 6 - Managing Security * (Ed) Piconfig> sinusoid,o:rw g:r w:r * (Ed) list * (Ls) tag, ptaccess * (Ls) tag=sinusoid * (Ls) SINUSOID,o:rw g:r w:r Changing the Point Data Owner and Group Example To change a point owner and group, open the Point Database and list the DataOwner and DataGroup for the tag. It shows that the data owner is piadmin and the data group is piadmin. We want to change the owner to Operator1 and the group to the Operations Group, so that they can put in lab values. * (Ls) pipoint * (Ls) tag, dataowner, datagroup * (Ls) tag=sinusoid * (Ls) SINUSOID,piadmin,piadmin * (Ls) edit * (Ed) tag, dataowner, datagroup * (Ed) Piconfig> sinusoid, Operator1, OperationsGroup * (Ed) list * (Ls) tag=sinusoid * (Ls) SINUSOID,Operator1,OperationsGroup Changing Data Access Permissions Example To modify access permissions, open the Point Database and list the permissions for a tag. The listing below shows that the owner, group members, and world all have read and write access. * (Ls) pipoint * (Ls) tag, dataaccess * (Ls) tag=sinusoid * (Ls) SINUSOID,o:rw g:rw w:rw Then, for example, modify the permissions by removing world access completely. Now only the owner and group members can read and write data for this tag: * (Ls) edit * (Ed) tag, dataaccess * (Ed) Piconfig> sinusoid, o:rw g:rw w: * (Ed) list * (Ls) tag, dataaccess * (Ls) tag=sinusoid * (Ls) SINUSOID,o:rw g:rw w: How to Make All Points Accessible You can change all the access permissions on all points to world read/write access by executing the following piconfig commands: Page 124

147 6.8 - User ptaccess=o:rw g:rw dataaccess=o:rw g:rw tag="*" Security for Default Points in the PI Server PI is distributed with all default points owned by user piadmin, and assigned to group piadmin. Although they have the same name, the user and group have no special relationship to each other. The user piadmin is the PI System Manager, but the group piadmin has no special privileges. 6.8 User Security As mentioned earlier, the PI Server has its own user identification and password security. Client applications may obtain login credentials through a PITrust login, or by passing a user name and password. A PITrust assigns a user to the login session based on a set of credentials; this mechanism is discussed in the next section, Trust Login Security. To log in to the PI Server from one of the PI client applications, such as PI ProcessBook or PI DataLink, requires a PI user name and password or a valid PITrust. The user is also assigned to one or more groups of users. Note: The PI Server does support PI API based logins without supplying a user name/password or a trust. This is the default user access that assigns world rights to the connection. This feature may be disabled by adding the PITimeout table entry DefaultUserAccess and setting the value 0. A non-zero value or no entry allows default user access. If default user access is disabled no secure objects may be accessed regardless of security attribute settings. When a user accesses the PI Server, after the request passes the PI Firewall, the user ID and password are used to determine what access to grant. There are three types of user access: owner, group, and world. Owner access is typically readwrite privileges. Group access is often read-only. World access is by default, none. Two user accounts are included in the installation of PI Server, piadmin and pidemo. The piadmin user always has read/write access to all objects regardless of access settings. This is similar to a super user account in UNIX. The pidemo user has read-only access to all objects. Do not delete either account. You should establish passwords for both accounts. This does not affect the trust login process Group Database Access to data or to point attributes is normally granted to groups of users, such as instrument engineers or operators, rather than to individuals. The PI Group Database is where all PI Server System Management Guide Page 125

148 Chapter 6 - Managing Security PI groups are defined. Every user is a member of one or more groups. This determines their access to the various PI databases and their individual elements. Adding a New PI Group The piconfig utility is used to modify the PI Group Database. The table name is PIGROUP. The primary key is GROUP. The following attributes are defined: GROUP group name USERS users belonging to this group DESCRIPTION free text This piconfig example, opens the table and then lists all entries: * (Cr) pigroup * (Cr) list * (Ls) group, description,users,... * (Ls) group="*" * (Ls) piadmin,administration,piadmin piuser,user,pidemo ptmaintenance,, Next, a new group is added. In this example, the description attribute is used to specify the group s purpose. User is a read-only attribute. Note: To add users to groups, use the User Database, NOT the Group Database. * (Ls) create * (Cr) group, description * (Cr) Piconfig> Section1, Section1 crew chiefs and engineers *> Section1, Section1 crew chiefs and engineers * (Cr) list * (Ls) group,description * (Ls) group="*" * (Ls) piadmin,administration piuser,user ptmaintenance, Section1,Section1 crew chiefs and engineers User Database The PI User Database is where individual PI users are defined, and assigned to already existing groups. Passwords are also stored here. Users maintain their passwords using the pisetpass utility. The table name is PIUSER. The primary key is USER. Page 126

149 6.8 - User Security The following attributes are defined: USER user name DESCRIPTION free text GROUPS group(s) to which the user belongs CONTEXT <reserved for future use> Adding a New PI User The piconfig utility is used to modify the PI User Database. This piconfig example opens the table, and then lists all entries: $ piconfig * (Ls) piuser * (Ls) user, description, groups * (Ls) user="*" * (Ls) piadmin,pi Administration,piadmin pidemo,pi Demo,piuser The description attribute is used to specify such information as the user s full name, telephone extension, and address. To add a new user, specify each group to which the user should be added. The user may be added to one or more groups. The default password is the same as the user name. A different password can be assigned upon creation by appending /password to the user attribute. * (Ls) create * (Cr) user, description, groups,... * (Cr) Piconfig> tom/mypassword, [email protected], piadmin, piuser * (Cr) list * (Ls) user, description, groups,... * (Ls) user=tom * (Ls) tom, [email protected], piadmin,piuser Changing PI User Passwords PI users may change their passwords by using the pisetpass utility in the PI\adm directory. PI must be running for this utility to work. You must enter the current password in order to change the password. You can also set a password to a blank entry by using pisetpass, although this is not recommended. The manager can also specify the old password as "!" (exclamation mark) and new password as required. This bypasses old-password verification when the user running pisetpass as piadmin. PI Server System Management Guide Page 127

150 Chapter 6 - Managing Security 6.9 Trust Login Security When an application needs access to the PI Archive and does not have an explicit interactive login, you can configure an automatic Trust Login, using piconfig. This login grants access of an existing PI user as defined in the PI User Database, based on the current connection attributes such as the IP address, the machine name or the Operating System user name. Trust login work by comparing the connection credentials of the connecting application to the trust records in the Trust Database. Human intervention is not required at the time of connection. For example, interface processes must start, connect to PI Server, and achieve access rights with sufficient privileges to write data to the Data Archive. To permit this access, a trust record can be created in advance on the PI Server to allow the application to assume the privileges of a valid PI user. 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. It permits a unified login for PI API and PI- SDK applications that is consistent with Windows security. PI-SDK is limited to Windows clients. PI-SDK version 1.1 can use trust logins. Earlier versions of the PI-SDK have no trust login support. In the following sections, you will find: A discussion of connection credentials How to define trust records in the Trust Database Evaluating the match between trust records and connection credentials Examples Connection Credentials Trust records may be configured for three types of logins: PI API applications PI-SDK applications on Windows 98 PI-SDK applications on Windows The three types of connection credentials, which are determined by the operating system login of the connecting application, contain slightly different information. PI Server determines the connection credentials for PI API applications based on the IP address, the Host name, and a truncated application name. PI-SDK applications on Windows 98 assemble their own credentials, based on the IP address, the IPHost name, and a non-truncated application name. PI-SDK applications on Windows assemble their own credentials, including Windows Domain Membership, Domain User Name, IP address and/or host name, and Application Process Name. Page 128

151 6.9 - Trust Login Security The three types of logins are discussed more fully in the following sections. Trust records are discussed later, followed by examples. Connection Credentials for PI API Applications Connecting PI API applications that call piut_setprocname send a 4-character application name to the PI Server. The application name is referred to as a process name in the PI API User Guide. The PI Server uses reverse name lookup on the IP packet, to get the sender s address, and then looks up the host name. PI Server can determine the IP Address of the connecting machine through a Reverse Name Lookup. The name can come from a hosts file on the server machine, or, more commonly, from a Domain Name Server (DNS). The 4-character application name is determined by a call by the application to the PI API routine piut_setprocname. When PI Server accepts a connection, PI Server logs this name and adds a trailing E. Thus, PI Server can assemble a 3-part set of connection credentials: Application Process Name (4-characters + E) IP Address Host name of the connecting machine Once PI Server assembles a set of connection credentials, PI Server compares these to each trust record in the Trust Database. If a match is found, the connection is granted the same access as the PI User defined in the trust record. At connection, every PI API-based application attempts to receive a Trust Login authorization. If the application has a subsequent user/password login, this subsequent login overrides any trust authorization. Connection Credentials for PI SDK Applications on Windows 98 The PI-SDK assembles connection credentials for an application internally on the connecting client machine (Windows 98), including these attributes: Application process name. This is the executable file name. IP address IPHost name Run pidiag -host on the node where the application runs to view the connection credentials as retrieved from the local operating system. Domain and user name information cannot be obtained from Windows 98-based clients; the connection credentials sent from PI-SDK applications on those operating systems will omit those fields. Once a set of connection credentials reach the PI Server, the Server compares these to each trust record in the Trust Database. If a match is found, the connection is granted the same access as the PI user identified in the trust record. PI Server System Management Guide Page 129

152 Chapter 6 - Managing Security Connection Credentials for PI SDK Applications on Windows The PI-SDK assembles connection credentials for an application internally on the connecting client machine (Windows), including these attributes: Application process name. This is the executable file name. IP address IPHost name Windows Domain Membership OS User Name, as logged into the domain Run pidiag -host on the node where the application runs to view the connection credentials as retrieved from the local operating system. Once a set of connection credentials reach the PI Server, the Server compares these to each trust record in the Trust Database. If a match is found, the connection is granted the same access as the PI User identified in the trust record Defining Trust Records in the Trust Database The PI Trust Database is a table of trust records. Each record includes a unique name for the trust, a PI user name, and a combination of at least one of the following: Application Name, Domain name, IP address, Host, and Operating system user-name. Changes to the Trust Database take effect immediately. There is no need to restart any PI subsystem. For more information about the Trust Database, see PI Server Reference Guide, Chapter 2, PI Server Databases. The following table shows whether each field is required or optional and whether it may be used for each type of connection credential. Field in Trust Record Req or Opt. PI API PI SDK on Win98 PI SDK on WinNT or greater Trust name req AppName opt yes yes yes Domain opt no no yes IPAddr1 opt yes yes yes Netmask opt yes yes yes Host name opt yes yes yes OSUser opt no no yes PIUser req If IPAddr is used, Netmask must also be configured. Page 130

153 6.9 - Trust Login Security Before you configure records in the Trust Database, set up the entries in the User Database. For more information, see Adding a New PI User, page 127. When you establish a new trust record, if the PIUser you include does not already exist in the User Database, the trust record will be rejected. Note: Trust record with only Trust name and PIUser are not allowed. Always include at least one optional entry. PI Server does not allow two trust records that differ only in PIUser, because this would create ambiguous trust login results. Using Piconfig Piconfig is the only tool that can modify the Trust Database. The key value of the Trust Database is Trust. D:\PI\adm>piconfig * (Ls - ) pitrust * (Ls - PITRUST) 1 - Trust String D: C: 2 - NEWTrust String D: C: 3 - AppName String D: C: 4 - Domain String D: C: 5 - IPAddr String D: C: 6 - IPHost String D: C: 7 - Netmask String D: C: 8 - OSUser String D: C: 9 - PIUser String D: C: Suppose you wish to create a trust record that permits a PI-SDK application named piperfmon.exe to connect as a User called Perfmon. You could name the trust record perfmondefault. Use the following commands to create the record trust, appname, piuser perfmondefault, piperfmon.exe, perfmon Additional information about each field is given in the following sections. Trust The Trust field is required. It is a record name that must be unique within the Trust Table. Any alphanumeric combination is acceptable. AppName A blank value indicates the match is not required. Otherwise, a case-insensitive match is required. For a PI API application to match the AppName, the AppName must be specified as the 4- character application name plus an E at the end. PI Server System Management Guide Page 131

154 Chapter 6 - Managing Security For a PI-SDK application to match the AppName, the AppName must be specified as the filename of the application executable with file extension and without the directory path. Domain Windows Domain name may be used only for trust logins for PI-SDK client applications running on Windows operating systems. The domain must be the same for the PI Server and the connecting application. A blank value indicates the match is not required. Otherwise, a case-insensitive match is required. IPAddr and Netmask The IPAddr and Netmask fields are optional and may be used for either PI API or PI-SDK applications. This pair of fields allows matching exact machine IP Addresses or specific subnets. Setting both fields to indicates that a match is not required. If these fields are left blank, PI Server will store in both fields in the trust record. If you specify IPAddr, you must also explicitly provide a Netmask value. Failure to do so will generate an error. If you are requiring an exact match on an IP address, specify the Netmask as If you are specifying a Class C subnet, specify the Netmask as and the fourth field of the IPAddr as 0. Examples are given later in this chapter. Note: The relationship between IPAddr and Netmask in the Trust Database is the same as the relationship between Network Destination and Netmask in a TCP/IP routing table. The class C (24 bit) subnet is just an example any valid subnet and IPAddr is supported. If you use this mechanism to allow access to all addresses in a subnet, you must set the bits corresponding to your subnet to zero. IPHost IPHost (sometimes called Host name or machine) is an optional field that may be used for either PI API or PI-SDK connections. It refers to the name of the connecting machine. Trust lookups based on IPHost are case-insensitive. OSIsoft recommends that you verify the IPHost name as discussed below. For PI API connections, the IPHost name is retrieved by PI Server using the IP address of the connecting client. The lookup generally requires access to a Domain Name Server (DNS). If a DNS is not used, the client IPHost name must be defined in the hosts table of the PI Server. To check this name, ping the client machine from the PI Server. For example, the DNS might provide JoePC.osisoft.com. For PI-SDK connections, the IPHost name comes from the information sent by the client to the PI Server. This name is the short IPHost name. You can confirm this name by running pidiag -host on the client. For example, the name might be JoePC. Page 132

155 6.9 - Trust Login Security For PI-SDK connections, PI Server verifies domain membership of a client computer by checking with a domain controller. If this field contains a dollar sign ($), it represents any machine within the domain. In the example above, one trust record with an IPHost entry would not match both PI API and PI-SDK connection credentials. OSUser The OSUser (Operating system user) name field is used only for PI-SDK applications running within a Windows NT or Windows 2000 Domain. Leaving this field blank indicates a match is not required. Otherwise a case-insensitive match is required. Because Domain must be the same for both the PI Server and the connecting PI-SDK application, it is recommended that you include Domain whenever you want to include OSUser. If this field contains a dollar sign ($), it represents any domain user. If the PIUser field in the trust record is also $, then the OSUser name must match a name in the PIUser database. If this field contains a dollar sign ($), and the PIUser field contains a specific PIUser, then all domain users will be granted the access rights of that PI user. OSUser Names for Services on Windows Interfaces that run as automatic Windows Services have a default OSUser name on the host machine. Unless overridden, this name is LocalSystem, which is not a Domain Username. If you wish to include OSUser name as part of a trust login, you must change the default name for the interface on the host machine to something that is defined in the Domain user database. User Manager in the Administrative Tools does not list the default LocalSystem name. Instead, follow these steps to set a new OSUser Name. Windows NT: 1. Open Services in the Control Panel. 2. Select the interface service name and click Startup. 3. In the dialog that appears, select Log on as This Account. 4. Type in a new User Name and Password (twice) or select a User Name from the dropdown list. Click OK. Windows 2000/XP: 1. In the Control Panel, open Administrative Tools and then Services. 2. Select the interface service name and click Properties. 3. On the Properties page, select the Log On tab. 4. In the dialog that appears, select This Account. PI Server System Management Guide Page 133

156 Chapter 6 - Managing Security 5. Type in the Domain and a User Name and then a Password (twice) or select a User Name from the dropdown list. Click OK. In the example below, the Domain is OSI and the account User Name is piperfmon. The syntax is OSI\piperfmon. Figure 6-1. Establishing PI Performance Monitor as a Windows Service PIUser Required field. PIUser must be a valid user defined in the PI User Database (with one exception, described under OSUser). This field specifies the PI Server user whose privileges will be assigned to the incoming connection when the connection credentials match the specifications in the trust record. Although you can choose the piadmin account for PIUser, it is preferable to reserve the use of piadmin for installation and management of the PI System Evaluating the Match Between Trust Records and Connection Credentials When connection credentials are compared to the Trust Database, each trust record is considered. If only one record matches exactly, that record will be used to grant login. If more than one record contains matching fields, then the record that matches most closely will be used. If incoming PI API connection credentials do not match any trust record, the application is granted the default access rights, which is equivalent to having world access to any system object. Whether points can be accessed depends on the Point Security configured for each point. Page 134

157 6.9 - Trust Login Security If incoming PI-SDK connection credentials do not match any trust record, then the default user for that server as configured on the caller s machine is tried with a blank password. If that fails, the PI-SDK application is not connected. Scoring Criteria to Determine the Best Match When more than one trust record matches an incoming credential, the best match is determined by weighting the fields and calculating the total for each matching record. PI Server selects the trust record with the highest score. Weight Matching Field 163 application name 131 specific OS user 115 any Domain Machine ($) 107 any Domain user ($) 103 IP address 103 IPHost 101 Subnet 100 Domain match Other Applications on the PI Server Machine PI API or PI-SDK applications running on the same machine as the PI Server are automatically established with trust logins at the time PI Server is installed or upgraded. The PI System Manager may modify these login privileges in the trust table. Logins through a Node Already Using a Trust Login If an application using an explicit login connects to PI Server through a network node that is already using a trust login, the trust login connection is unaffected. A trust login and an explicit login are independent from each other unless they apply to the same application, in which instance, the explicit login overrides the trust login. Interaction with PI Firewall Security You can block connections from certain addresses through the PI Firewall mechanism. See PI Firewall Security, page 117, for more information. This takes precedence over trust, i.e. a connecting application must pass the firewall before trying to get a trust login. Protection of PI API Application Connections During Backups and Other Shutdowns Interfaces and the PI API BufServ rely on successful trust logins because they run as Services on Windows or as processes on UNIX. PI Server will not allow PI API connections while Trust Login services are unavailable. PI Server System Management Guide Page 135

158 Chapter 6 - Managing Security For example, whenever the Base Subsystem is shutdown for backups, existing connections are maintained, but no new PI API connections are accepted. Interfaces and PI API BufServ will attempt reconnections, typically every sixty seconds. Once the Base Subsystem is running again, new connections can occur New PI Server Installations PI System Managers who are directly logged into the server machine have unrestricted access to PI through management utilities as well as PI-SDK and PI API applications. The installation kit now generates four default entries for a new installation. These can be listed with piconfig: * (Ls - PITRUST) trust,appname,domain,ipaddr,iphost,netmask,osuser,piuser * (Ls - PITRUST) trust="*" * (Ls - PITRUST) The initial entries are two with IP address and two with IPhost name: The IP addresses are the TCP/IP standard local host address ( ) and the actual IP address of the server. The IPhost names are the TCP/IP standard name localhost and the actual IPhost name of the server, in this case bilbo. These trust-logins allow access for local applications by host name and by address. All local PI API applications are granted access. The PI System Manager may choose to delete or modify these trust records, although this is not recommended Trust changes on System Startup The four default trust records listed in PI Server installation section above are re-created or edited every time the system starts. This guarantees access to all applications running on the local machine even if the address changes as a result of a new network card, changes in network configuration or moving of the PI Server system to another machine. This behavior also takes care of cluster configuration, when the actual server might be running on a different machine after failure. To prevent this behavior, set the following PITIMEOUT parameter: RecreateServerTrust, Multiple Network Cards When applications run on machines with multiple network cards, it is unpredictable which credentials are sent to the server for the trust authorization. It is thus recommended to avoid such configurations, or create trust records for every IP address on the machine where the application runs. Page 136

159 6.9 - Trust Login Security Examples The PI Server compares incoming connection credentials with every Trust Login record. Each field in a trust record is compared to the corresponding credential field. Every field that is not blank in the Trust Record must exactly match the passed credentials. Otherwise, the authorization is not granted. When an authorization is refused for one trust record, the PI Server continues to search the other records until it has exhausted the possibilities. You can create explicit individual trust records for each interface or you can group them according to subnet, host machine, or username. A group of interfaces can share the same privileges, based on matching a name in the User Database. As explained previously, if IPAddr and Netmask fields are blank, they appear as Examples Restricted to Particular Client Applications or Remote Nodes If a trust record includes only a truncated application name, only a PI API client application may be authorized. It might be advisable to include an additional restriction on Host name and/or IP address at the same time. If a trust record includes only a full application executable file name, only a PI-SDK client application may be authorized. It might be advisable to include some additional restriction as well, based on one of the other optional fields. A remote PI API node or PINet node may be specified by Fixed IPAddress or by IPHost name. Example 1. Restricted to a Particular PI API Client Application The trust record shows only three entries: Trust record name AppName = rande PIUser name = IFGroupA. An AppName that is four characters and E indicates a PI API application. Rand is the truncated name for the Random Interface. The incoming credentials show: AppName = rande, which matches the trust record IPAddr and IPHost, which are blank in the trust record Therefore, authorization to use the privileges of IFGroupA would be granted to the connecting Random Interface. Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust APIIF1 AppName rande yes AppName rande PI Server System Management Guide Page 137

160 Chapter 6 - Managing Security Trust Record Domain Connection Credentials Domain IPAddr IPAddr Netmask IPHost IPHost Suzanne2 OSUser OSUser PIUser IFGroupA Example 2. Restricted to Particular PI SDK Client Applications The trust record shows only 3 entries: trust record name AppName = piperfmon.exe PIUser name = IFGroupB. The incoming credentials show: AppName = piperfmon.exe IPAddr = IPHost = Vaughan This application name includes the.exe extension, indicating a PI-SDK application. The application is running on Windows 98, because Domain and OSUser are blank. Therefore, because AppName is the only specification in the trust record, and the incoming credentials include a matching AppName, then authorization to use the privileges of IFTypeB would be granted to the connecting Performance Monitor Interface. Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust SDKIF1 AppName piperfmon.exe yes AppName piperfmon.exe Domain Domain IPAddr IPAddr Netmask IPHost IPHost Vaughan OSUser OSUser PIUser IFTypeB Page 138

161 6.9 - Trust Login Security Example 3. Specific PI API Application from a Specific Remote Node The following example trust (GTinterface) allows a specific PI API application (GTin) from a particular remote IPHost (GT55) and IP address ( ) the rights of a PI user Operator1. * (Ls - PITRUST) create * (Cr - PITRUST) trust,iphost,ipaddr,netmask,appname,piuser * (Cr - PITRUST) Piconfig> GTinterface,GT55, , ,GTinE,Operator1 Example 4. Any PI API Application from a Specific Remote Node with a Fixed IP Address The following example creates a trust record that would match any PI API application from a remote PI API node or VMS-based PINet remote data collection node with a fixed IP address. The trust record would allow the interface from a data source to write to the PI Server, just as the former Proxy Database did. Assume the entry in the User Database will be Trust,IPAddr,Netmask,PIUser Example 5. Any PI API Application from a Remote Node by Node (IPHost) Name The following example creates a trust record that would match any PI API application from a remote PI API server called Lychee.osisoft.com. This trust record could be used, for example, to allow an interface to a data source to write to the PI Server from a PI API remote data collection node or a VMS-based PINet remote data collection node. This is similar to the old Proxy Database, used before PI Server 3.3. Assume the user will be Trust, IPHost, PIUser Examples of PI SDK Client Applications on Windows The Windows operating systems permit more secure logins, using domain and User name. Example 6. Domains Match on Windows The following trust record grants the rights of IFTypeC for any PI-SDK application run on the Windows Domain OSI. In other words, only Domain is specified. This trust would not authorize any PI API application or any PI-SDK application on Windows 98. PI Server System Management Guide Page 139

162 Chapter 6 - Managing Security Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust NT/2000/XP AppName AppName piperfmon.exe Domain OSI yes Domain OSI IPAddr IPAddr Netmask IPHost IPHost Gerke OSUser OSUser Suzanne PIUser IFTypeC The set of credentials at the right is sent by a PI-SDK application on Windows. This example has Domain OSI and User Suzanne logged on to machine Gerke at IPaddress running an application called piperfmon.exe. Note: If you specify either a domain or OSUser in the trust record, the PI Server must be in the same domain as the connecting application. In this case, the credentials match the information in the trust record, because only Domain OSI was specified in the trust record. The application would be granted access to PI as the user IFTypeC. For greater restriction, you might also specify the application name and/or OSUser name or IP Addr. Example 7. Assigning Any OSUser on a Particular Domain to a PI User Database Entry of the Same Name Using $ For PI-SDK applications, PI Server allows you to assign any OSUser on a particular Domain to the PI User Database entry of the same name. Note: If you specify a domain or OSUser in the trust record, the PI Server must be in the same domain as the connecting application. Using this feature requires a Trust Record with OSUser set to $ and PIUser set to $. Other fields are optional. The operating system for the client application must be Windows. This trust would not authorize any PI API application or any PI-SDK application on Windows 98. Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust MatchUserName Page 140

163 6.9 - Trust Login Security Trust Record Connection Credentials AppName AppName piperfmon.exe Domain OSI yes Domain OSI IPAddr IPAddr Netmask IPHost IPHost Suzanne2 OSUser $ OSUser OSI\Perfmon PIUser $ In the example above, if the User Database contains a user named Perfmon, the trust will be granted. Whenever there is a record in the User Database that matches the entry in OSUser, the trust is granted. You could restrict the trust record further by specifying more fields, such as IPHost, subnet, or AppName. Example 8. Assigning Any Machine on a Particular Domain to a PI User Database Entry A dollar sign in the IPHost field of the trust record causes any machine on the same domain as the PI Server to be authorized with the same access as the OSI entry in the User Database. Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust Matchmachine AppName AppName piperfmon.exe Domain Domain OSI IPAddr IPAddr Netmask IPHost $ yes IPHost Suzanne2 OSUser OSUser Perfmon PIUser OSI PI Server System Management Guide Page 141

164 Chapter 6 - Managing Security Examples for Client Applications Using either PI API or PI SDK PI API credentials specify AppName truncated and PI-SDK credentials do not. If you want to build a trust record for both types of applications, do not specify AppName. Use IPHost or IPAddr. Using IPAddr and Netmask The IPAddr and Netmask combination allows more flexibility than an all-or-nothing match. The IP Address of the connecting machine is bitwise ANDed with the Netmask and then compared to the IPAddr field of the Trust Record. It is a match if the ANDed result matches the IPAddr field of the Trust Record. This allows granting Trust Logins based connecting machine subnets, similar to IP Routing algorithms. Remember that you can use additional fields in the trust record to further limit access. The following table gives some IPAddr/Netmask combinations and evaluation results: Row Trust IPAddr Trust Netmask Machine IPAddr Result of AND between Trust Netmask and Machine IPaddr Trust IPAddr and result of AND match? A Yes B Yes C No D Yes E No F Yes G No In Row A, the trust IPAddr and the Trust Netmask are blank. The ANDed result is also blank; these fields are ignored in the matching process. In Row B, when you combine Trust Netmask with Machine IPAddr, you get a 0 in the last field; this matches the Trust IPAddr. Use this when you want to authorize any PC on a subnet. See Example 8. In Row C, the third field does not match (168, 175). In Row D, the ANDed result of 240 and 178 is 176, and thus, matches the Trust IPAddr. In Row E, the ANDed result process does not match. This type of Netmask restricts matching to certain IP addresses on a network subnet. Row F and G illustrate the situation described in Example 9. Using IPAddr and Netmask to Specify a Particular Address. Example 9. Using IPAddr and Netmask to Specify a Particular Address You can specify a trust record with an explicit machine address, as shown below, and any connecting application at that machine will be granted a trust login. This example is shown Page 142

165 6.9 - Trust Login Security above in Row F. Similarly, the results of the credential IPAddr and the Netmask in Row G is not an exact match for the trust IPAddr and the trust is not authorized. Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust Matchmachine AppName AppName piperfmon.exe Domain Domain OS*I IPAddr yes IPAddr Netmask IPHost IPHost Suzanne2 OSUser OSUser Suzanne* PIUser OpsPC15 * only included for PI-SDK applications Example 10. Specifying a Subnet This example limits the login trust to a domain (OSI) and a specific Class C IP subnet: Trust Record Connection Credentials Field Name Field Value Match? Name Value Trust SubnetC1 AppName AppName piperfmon.exe Domain Domain OSI* IPAddr yes IPAddr Netmask IPHost IPHost Suzanne2 OSUser OSUser Suzanne* PIUser SubnetC1User * only included for PI-SDK applications This Trust Record grants the rights of SubnetC1User for any application run on any machine on the Windows Domain OSI as long as the machine is in the Class C subnet PI Server System Management Guide Page 143

166 Chapter 6 - Managing Security PI SDK Application on a Subnet The following example allows PI-SDK application with a name MG.exe running in domain plant1 and on any machine from the subnet with a name MGr and logged with a user named interface the access rights of PI user Mginter. * (Cr - PITRUST) trust,appname,domain,ipaddr,netmask, IPHost,osuser,piuser * (Cr - PITRUST) Piconfig> MGinterface, MG.exe, plant1, , , MGr0,INTERFACE, MGinter 6.10 Resolving Ambiguities Example 11. Resolving Ambiguities Closest Match for an IPAddr A connecting application is granted the trust login that matches it most closely. For example, in the following comparison chart, an application is running on host PIclient1 with IP address A trust record called Operator1 is defined for IPhost = PIclient1, IPaddr = , and PIUser = Operator1. Another trust record called Operator2 is defined for IPHost = PIclient1, IP address = , and PIUser = Operator2. Trust Records Connection Credentials Field Name Field Value Field Value Name Value Trust Operator1 Operator2 AppName AppName piperfmon.exe Domain Domain OSI IPAddr IPAddr Netmask IPHost PIclient1 PIclient1 IPHost PIclient1 OSUser OSUser perfmon PIUser Operator1 Operator2 Operator1 Trust Record matches the connection credentials exactly. Operator2 also matches, because the result of ANDing the Netmask and the Connection Credentials IPAddr gives , which matches the Operator2 Trust Record IPAddr. The application will be granted the rights of Operator1, not Operator2, because the combined IPAddr/Netmask results match the Operator1 record more closely. Page 144

167 Resolving Ambiguities Example 12. Resolving Ambiguities Scoring System In the event of multiple valid trust records, PI Server applies a scoring equation. In the example below, a set of credentials is compared to two trust records. Trust OSUsermatch has a blank in the IPHost field, HW6 in the OSUser field, and User6 in the PIUser field. Trust IPHostmatch has crabapple in the PIHost field, a blank in the OSUser field and User7 in the PIUser field. Trust Records Match? Connection Credentials Field Name Field Value Field Value Name Value Trust OSUsermatch IPHostmatch AppName AppName piperfmon.exe Domain Domain OSI IPAddr IPAddr Netmask IPHost Crabapple yes IPHost Crabapple OSUser HW6 yes OSUser HW6 PIUser User6 User7 The PI Server weighting factor for the OSUser field is higher than the weight of the IPHost field. Consequently, the connecting application would receive the trust login for User6. Example 13. Resolving Ambiguities Other Problems Sometimes ambiguities in trust records may be created inadvertently. For example, assume the following trust record AddedFirst exists, pointing to UserA in the User Database: Field Name Trust Field Value AddedFirst AppName Domain OSI IPAddr Netmask IPHost OSUser PIUser UserA PI Server System Management Guide Page 145

168 Chapter 6 - Managing Security Now suppose you add another trust record called NewNetmask and point to UserB like this: Field Name Trust Field Value NewNetmask AppName Domain OSI IPAddr Netmask IPHost OSUser PIUser UserB The PI Server would accept the NewNetmask Trust Record because the two NetMask fields are different. Notice that the IPAddr in both records has 0 in the last field. The first Netmask has a 24-bit Netmask, the second has a 28-bit Netmask. Unfortunately, any match with NewNetmask would also match with AddedFirst. There is no predictable rule as to which trust will be assigned if ambiguous Trust Records are created in the database. Page 146

169 Chapter 7. MOVING PI SERVERS PI Servers are designed for platform independence. All the databases and tables are stored in a format that allows you to move a Server to a different computer or a different location on the same computer. The programs and scripts themselves are platform-specific so a proper installation is needed for any host platform. This chapter provides the information necessary to move a Windows- or UNIX-based PI Server. To move a VMS-based PI Server, you must first migrate it to either Windows or UNIX. Refer to the OSIsoft support Web site for details on migrating VMS Servers. These instructions assume that the PI Server System that is being moved is release 3.2 or greater. If your PI System is an earlier release, upgrade it before continuing. 7.1 Preparation Before attempting to move a PI Server, ensure that the PI Server and all related processes have been stopped. Make a backup copy of the entire PI Server and all of the archive files (if they do not reside in the PI directory.) On UNIX hosts, back up the /etc/piparams.default file. On Windows hosts, back up the Registry. 7.2 Different Computer To move a PI Server onto a different computer, you install the PI Server software on the new computer and then copy the databases, tables, and archives over to the new PI Server. This section describes the steps for moving the PI Server and explains which files and directories you need to copy to the new Server. This section refers to the original PI Server as the source and to the new PI Server as the target. The pihome directory is the top-level PI directory (C:\PI\ for example). These instructions use the backslash (\) for path names, but the steps are the same for all platforms. Before starting the procedure below determine if there are any tags with a Snapshot value before the start time of the Primary Archive. Set the shutdown attribute to 0 for these tags. When the target PI system is first started, setting shutdown to 0 for these points will prevent errors because only the primary archive will be registered. To move the PI Server: 1. Perform a new installation on the target (new) host using the same release and build number as the source (original) host s PI Server. Select the default archive sizes PI Server System Management Guide Page 147

170 Chapter 7 - Moving PI Servers during the installation, because you delete them anyway, in one of the following steps. Ensure that the new PI Server is functional before you continue to the next step. 2. Identify the Primary Archive on the source PI Server using the administrative utility pidiag -ad or piartool -al or the Archive Manager plug-in in the PI System Management Tools (SMT). 3. Stop both the source and target PI Servers. 4. Copy the entire pihome/dat directory from the source PI Server to the pihome/dat directory of the target PI Server, excluding the following files: Pisubsys.cfg PISysID.dat (you can include PISysID.dat if you are moving the server to a computer with the same host name and IP address as the original server.) Archive files This overwrites most of the files in the target PI Server dat directory. 5. Copy the entire pihome/log directory from the source PI Server to the pihome/log directory of the target PI Server. 6. Copy the pipeschd.bat file from the pihome\bin directory of source PI Server to the pihome\bin directory of the target PI Server. 7. Delete the target PI Server s archives and copy the source PI Server s primary archive to the desired location on the target PI Server. 8. On the target PI Server, update the archive location file (piarstat.dat) by running the pidiag -ar utility. Specify the full path to the copied Primary Archive when prompted. 9. Restart the new PI Server and verify that it is working correctly. 10. Move and register the remaining archive files. This should be done while the new PI Server is running. 11. Move or install any platform or site specific interfaces or programs as needed. 12. Back up the new PI Server once it is stable. 7.3 Same Computer Moving the install location of a PI Server is nearly identical to moving from one computer to another. The procedures are identical except for the following steps: 1. Isolate your PI Server from the network. This will force buffering of data on the interface nodes. 2. Run piartool -qs monitor until the Event Queue is empty. 3. Run piartool -al redirecting the output to a text file. This is a record of all registered archives. Page 148

171 7.3 - Same Computer 4. Shut down your PI Server. 5. Save your dat directory, log directory and archives to a safe location. 6. Uninstall the PI Server. 7. Follow the instructions in the following sections; except, skip step 2 since this was already done in step 3 above. PI Server System Management Guide Page 149

172

173 Chapter 8. COPYING A PI SERVER If you want to create a second PI Server by moving an existing PI Server as described in Moving PI Servers on page 147, the server ID on the destination server must be deleted and recreated so that the second server has a unique ID. 8.1 Understanding the Server ID All PI Servers are identified by a ServerID. The Server ID is stored in the binary file PI\dat\PISysID.dat. The ID is used to uniquely identify a PI Server; basically, it augments the PI Server's host computer's name. For example, a PI Point may only be uniquely identified by including all four of these parameters: Server ID Computer Name (the computer name is the handle as set in the Known Servers table) Tag Name Point ID Originally the PI System ID was assigned at system installation with an algorithm the used the computer name to generate a 32-bit integer. This approach could create ambiguous IDs two unique computer names could generate the same ID. PI Servers with 32-bit IDs must continue to use these IDs otherwise client applications that reference the ID may not be able to resolve resources. PI Servers installed starting with version 3.3.?.? use GUIDs for the System ID. This ID is assigned at PI Server installation and is guaranteed to be unique. Note: The 32-bit ID is still generated on the PI Server for legacy purposes. For example, PI API based applications may only support the 32-bit ID. 8.2 Situations where Server ID must be Addressed The Server ID is only an issue when you move or copy the PI Server to another computer. There are three basic scenarios: 1. Moving to a new host computer and retiring the original computer as described in Moving PI Servers on page 147. In this case the Server ID file is copied to the new computer as part of the moving process. No other action is needed. PI Server System Management Guide Page 151

174 Chapter 8 - Copying a PI Server 2. Copying the PI Server to a new machine where the copy may be accessed simultaneously with the source PI Server. In this case, although the data may be nearly indentical, the two PI Servers must be assigned unique ID values. Therefore, the copied PI Server must have a Server ID different from the source PI Server. This is kept unique by not overwriting the Server ID file on the destination server; that is, keep the Server ID file that was created on initial PI Server installation on the destination server. In this scenario, the two servers are unique: ProcessBook displays that target the source PI Server will not resolve against the destination server. 3. Copying the PI Server to a new machine that will not be accessed simultaneously with the source PI Server. This scenario is used when it is desirable to access the destination PI Server with existing displays, etc., created against the source PI Server. Client applications that attempt to access both machines will have problems: the PI- SDK knows the server table will be ambiguous. Attempting to do this is not supported and will result in confusion. In summary: Copy the source PI Sever ID file to the destination PI server if the source PI Server is being retired. Leave the destination PI Server ID file in place if the source and destination PI Server may be accessed simultaneously. Note: The existence of two PI Servers with the same ID is problematic. This approach should only be used in special circumstances. Specifically, attempts to access both servers from the same client machine will result in confusing problems. Page 152

175 Chapter 9. MERGING TWO PI SERVERS The offline archive utilities can be used to merge two PI Server Systems. A merge is used when a PI Server System is to be retired and the data from the retired system is preserved in an existing system. The basic steps and an example merger follow. 9.1 Server Merging - Procedures Transfer Points Install all points from the retired system onto the destination system. Digital State Table and Digital Tags Make all changes to the digital state table before making any changes to the points. Review the retired system digital-state table. Use piconfig to extract any missing digital-sets and create them on the target system. If a set from the retired system already exists in the target system, make sure both have the same states. Digital points created on the target system are assigned a digital set by name. During archive conversion, only the offset is preserved, thus the data is interpreted according to the point s current digital-set. Point Editing / Creation Use piconfig to dump all required point attributes from all points to be merged to the destination system. Required point attributes are interface specific. If in doubt, dump all point attributes for all points, except the PointID and RecNo attributes. Remember that point attributes depend on the point class, therefore, not all points have the same attributes. All points do not have to be merged - just the points whose history is to be preserved. Tags names issues must be addressed. If a tag name is the same on both systems, for example, sinusoid, which is a standard simulation point, no special steps are required. If the tags are not the same a rename is required. Normally the conflicting retired tag is renamed; although either tag may be renamed. Required renames should be done before starting the merger. On the destination system, use piconfig and the retired system's point listing to create the points. PI Server System Management Guide Page 153

176 Chapter 9 - Merging Two PI Servers PI Batch Subsystem Considerations Special steps are necessary for systems running pibatch. Batches are stored in automatically created points. The points are in the format of piban, where N is an integer unique to the unit. These points must not be converted to the destination system. Batches must be moved independently of the points. The piconfig utility may be used to move the batches. First, use piconfig to dump all existing batches and unit configuration. Unit name conflicts between the two systems will require renaming the references to the conflicting units in the piconfig dumps. Use the PIBatch unit table listing to create the units on the destination system. The batches are created after the archives are converted. All pertinent unit configuration information must be listed. Details of these steps are shown below in the example merger. Create a Point ID Conversion Table on the Retired System Converting the retired archives to the destination system requires mapping the retired record numbers to the destination system record numbers. The mapping is established with a text file, which relates the retired system PointIDs, RecNos, and tags. The following piconfig script creates the input for the conversion tag=* Running this script with output redirected to a file is all that is required. This example assumes all tags are being merged. If all tags are not merged, edit the output file or use a tag selection of other than "tag=*". The ID conversion input file must only have entries of the format: pointid,recno,tag Any other entries, such as comments, are not allowed and will cause errors. Therefore, edit the file to remove any piconfig informational messages at the end of the file. Also, a new line must follow the last entry. If PIUnitBatches are being migrated, rename the UniqueID s of the old PIUnit to the UniqueID s of the destination PIUnit as described above. Cutover Interfaces At this time, interfaces feeding data to the retired system should be stopped. If appropriate, restart the interfaces pointing to the destination system. If the interfaces are restarted against the destination system, check interface output for errors--address any problems before proceeding. On the retired system run pishutev to put shutdown events into the Snapshot. This will force the Snapshot value into the Archive. Page 154

177 9.1 - Server Merging - Procedures Force a Shift on the Retired System Force a shift on the retired system. This puts a clean end time on the retired system, and makes management of the Archive merge easier. Run piartool -al to get a listing of all archives. Save this listing for reference when converting the archives. At this point the retired system is no longer needed. Shutdown the retired system. Move all retired archives to the destination system. For Unix systems this might mean using binary ftp. Create Binary ID Conversion Table on Destination System The text file created in the above step is the source for creating the ID conversion table. This table maps the tags from the old system into the new one. The piartool utility creates the ID conversion table; the syntax is: piartool -idci <full path to text file> -idco <full path to binary file to be created> This command is run on the destination system. Convert the Retired Archives The offline archive features of piarchss are used to convert the archives from the retired system. The syntax is: piarchss -id <id conversion binary file> -if <retired archive path> -of <converted archive path> There are a few things to consider when converting archives. If the retired system and destination system were running simultaneously, there will be overlapping archive dates. Overlapping archives must be combined using offline archive techniques. Also, by default, offline output archives are created as dynamic type. That is, they are not shiftable. The "-f" argument may be used to force output archives to a fixed size. Convert one archive and register it. If necessary, unregister any overlapping existing archives. Use piconfig or a client product to view data from this archive. Compare the data with the old system and assure correct conversion before proceeding with other archives. Proceed with the archive processing. This may be time consuming; especially if there are many overlapping archives. Register and view archives as they are completed. Add Batches from Retired Systems The text file from the PI Batch dump is now input via piconfig into the system. If all archives were merged, there should be an archive on line to receive the batch. If not all archives were migrated, batches for those dates will not be created. Details of this step are shown in the following example. PI Server System Management Guide Page 155

178 Chapter 9 - Merging Two PI Servers 9.2 Server Merge Procedure - Example The following example retires a small NT Intel PI System and merges it with an existing HPUX PI System. Both systems consist of example points provided with installation. The tags on the retired system were edited to create unique tags. Here is the archive list and point list of each system before starting the merge: Retired System BA:Active.1 BA:CONC.1Retired BA:LEVEL.1Retired BA:PHASE.1Retired BA:TEMP.1Retired batchid-1retired CDEP158Retired CDM158Retired CDT158Retired piba1 pipe:sine2retired pipe:sine2tretired pipe:sine3retired pipe:sine4retired pipe:sine5retired pipe:sineretired pitot1retired pitot2retired pitot3retired pitot4retired pitot5estretired pitot5rampretired pitot5retired pitot5runretired pitot6countretired pitot6timeneretired pitot6timeretired pitot_1retired pitot_avgretired pitot_maxretired pitot_minretired productid-1retired sin:h2retired sin:hourretired SINUSOIDRetired SINUSOIDURetired t_minretired t_state1retired Archive: D:\PI\dat\piarch.002 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.002 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Page 156

179 9.2 - Server Merge Procedure - Example Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 2025/2048 Start Time: 2-Mar-98 12:51:41 End Time: Current Time Backup Time: Never Archive: D:\PI\dat\piarch.003 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.003 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 2047/2048 Start Time: 2-Mar-98 12:50:27 End Time: 2-Mar-98 12:51:41 Backup Time: Never Archive: D:\PI\dat\piarch.001 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.001 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 1901/2048 Start Time: 25-Feb-98 14:16:40 End Time: 2-Mar-98 12:50:27 Backup Time: Never Destination System: BA:ACTIVE.1 BA:CONC.1 BA:LEVEL.1 BA:PHASE.1 BA:TEMP.1 batchid-1 CDEP158 CDM158 CDT158 piba2 pipe:sine pipe:sine2 pipe:sine2t pipe:sine3 pipe:sine4 pipe:sine5 pitot1 pitot2 pitot3 pitot4 pitot5 pitot5est pitot5ramp pitot5run pitot6count pitot6time PI Server System Management Guide Page 157

180 Chapter 9 - Merging Two PI Servers pitot6timene pitot_1 pitot_avg pitot_max pitot_min productid-1 sin:h2 sin:hour SINUSOID SINUSOIDU test1 test10 test11 test12 test13 test14 test15 test16 test17 test18 test19 test2 test20 test3 test4 test5 test6 test7 test8 test9 t_min t_state1 Archive: /opt/pi/dat/piarch.001 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 Version: 4 Path: /opt/pi/dat/piarch.001 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 59/512 Overflow: 2037/2048 Start Time: 2-Mar-98 12:21:11 End Time: Current Time Backup Time: Never Archive: /opt/pi/dat/piarch.002 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 Version: 4 Path: /opt/pi/dat/piarch.002 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 1/512 Overflow: 2047/2048 Start Time: Current Time End Time: Current Time Backup Time: Never Archive: /opt/pi/dat/piarch.003 Page 158

181 9.2 - Server Merge Procedure - Example PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 Version: 4 Path: /opt/pi/dat/piarch.003 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 1/512 Overflow: 2047/2048 Start Time: Current Time End Time: Current Time Backup Time: Never Point and PI Batch Configuration on Retired System Notice that the tag BA:Active.1 on the retired system conflicts with destination system. This tag must be renamed before proceeding. This tag is also used as the batch active tag for Reactor1. When adding the unit Reactor1 to the destination system, this change must be accounted for. Here's the dialog of the tag rename: D:\PI\adm>piconfig * (Ls - ) pipoint * (Ls - PIPOINT) edit * (Ed - PIPOINT) tag,newtag * (Ed - PIPOINT) PIconfig> ba:active.1,ba:active.1retired *> ba:active.1,ba:active.1retired Also, the tag piba1 exists on both systems. This is a PI Batch point and must not be migrated. In this example, the original piconfig files used to create the points on the retired system are used to create the points on the destination system. If original piconfig files do not exist for the retired system, use piconfig to dump appropriate data. The retired system has one PI batch unit that will be merged. The unit is a demo unit, but will be treated as a unique unit in this case; it will require some modification to prevent conflicts with the demo unit on the destination system. First step is to dump the unit configuration to a text file: * (Ls - ) pibaunit * (Ls - PIBAUNIT) 1 - UnitName (D) (C) 2 - NEWUnitName (D) (C) 3 - ActiveTag (D) (C) 4 - ActiveType (D) pulse (C) 5 - BIDExpr (D) (C) 6 - DataAccess (D) o:rw g:r w:r (C) 7 - DataGroup (D) piadmin (C) 8 - DataOwner (D) piadmin (C) 9 - Description (D) (C) 10 - EvalDelay (D) 0 (C) 11 - ProdExpr (D) (C) 12 - UnitAccess (D) o:rw g:r w:r (C) 13 - UnitGroup (D) piadmin (C) 14 - UnitOwner (D) piadmin (C) * (Ls - PIBAUNIT) unitname,activetag,bidexpr,description,prodexpr * (Ls - PIBAUNIT) PI Server System Management Guide Page 159

182 Chapter 9 - Merging Two PI Servers *piconfig Err> Wild-card specs. missing, default to '*'... Reactor1,ba:active.1,'batchid-1',Reactor 1,'productid-1' For this unit, several attributes are set to default values; only attributes unique to this unit are dumped. Since this unit's configuration conflicts with a unit on the destination system the attributes require editing before input. Here's the content of the input file after unitname,activetag,bidexpr,description,prodexpr Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'", "Retired Reactor 1","'productid-1Retired'" Create ID Conversion Text File The ID conversion text file is created on the retired system by running the following piconfig @exit D:\PI\adm>type retiredidconv.txt 9,9,ba:active.1Retired 8,8,BA:CONC.1Retired 7,7,BA:LEVEL.1Retired 10,10,BA:PHASE.1Retired 6,6,BA:TEMP.1Retired 11,11,batchid-1Retired 5,5,CDEP158Retired 4,4,CDM158Retired 3,3,CDT158Retired 13,13,piba1 34,34,pipe:sine2Retired 35,35,pipe:sine2tRetired 36,36,pipe:sine3Retired 37,37,pipe:sine4Retired 38,38,pipe:sine5Retired 33,33,pipe:sineRetired 18,18,pitot1Retired 19,19,pitot2Retired 20,20,pitot3Retired 21,21,pitot4Retired 25,25,pitot5estRetired 24,24,pitot5rampRetired 22,22,pitot5Retired 23,23,pitot5runRetired 29,29,pitot6countRetired 31,31,pitot6timeNERetired 30,30,pitot6timeRetired 32,32,pitot_1Retired Page 160

183 9.2 - Server Merge Procedure - Example 26,26,pitot_avgRetired 27,27,pitot_maxRetired 28,28,pitot_minRetired 12,12,productid-1Retired 16,16,sin:h2Retired 14,14,sin:hourRetired 1,1,SINUSOIDRetired 2,2,SINUSOIDURetired 15,15,t_minRetired 17,17,t_state1Retired The text file requires modification. The PI Batch tag, piba1, cannot be migrated and therefore, must be removed. Here are the contents after the edit: 9,9,ba:active.1Retired 8,8,BA:CONC.1Retired 7,7,BA:LEVEL.1Retired 10,10,BA:PHASE.1Retired 6,6,BA:TEMP.1Retired 11,11,batchid-1Retired 5,5,CDEP158Retired 4,4,CDM158Retired 3,3,CDT158Retired 34,34,pipe:sine2Retired 35,35,pipe:sine2tRetired 36,36,pipe:sine3Retired 37,37,pipe:sine4Retired 38,38,pipe:sine5Retired 33,33,pipe:sineRetired 18,18,pitot1Retired 19,19,pitot2Retired 20,20,pitot3Retired 21,21,pitot4Retired 25,25,pitot5estRetired 24,24,pitot5rampRetired 22,22,pitot5Retired 23,23,pitot5runRetired 29,29,pitot6countRetired 31,31,pitot6timeNERetired 30,30,pitot6timeRetired 32,32,pitot_1Retired 26,26,pitot_avgRetired 27,27,pitot_maxRetired 28,28,pitot_minRetired 12,12,productid-1Retired 16,16,sin:h2Retired 14,14,sin:hourRetired 1,1,SINUSOIDRetired 2,2,SINUSOIDURetired 15,15,t_minRetired 17,17,t_state1Retired PI Server System Management Guide Page 161

184 Chapter 9 - Merging Two PI Servers Dump the PI Batch Database As mentioned above, batches must be merged with piconfig scripts. Start by dumping all batches to be merged. To do this first dump all the units to a text file, then use this text file to dump all desired batches. In this example, all batches will be merged. Here is the script and procedure for dumping the @exit Edit the text file to include the start time and end time for each unit and add an exit command to the end. In this example, there is only one unit, and all the batches will be merged; therefore setting a very wide start and end time ensures that all batches are dumped. Here's the file after editing: D:\PI\adm>type unitlist.txt The script and procedure for dumping the batches follows: D:\PI\adm>type unitname,bid,prodid,starttime,stoptime unitname,searchstart,searchstop D:\PI\adm>piconfig input pibatchlist.dif input unitlist.txt > D:\PI\adm>type pibatchlist.txt *> Reactor1,*-1000d,* Reactor1,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20 Reactor1,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20 Reactor1,XYZ3,Green,3-Mar-98 12:24:23,12:44:00 * End Repeat... * (Ls - PIBATCH) PIconfig> PIconfig 1 Data lines 8 Command lines 0 Records in error... 3 Records Listed Pibatchlist.txt requires editing before input to the destination system. The unit name, Reactor1 must be changed to the migrated name Reactor1Retired. Also, the piconfig creation commands can be added to the top of the file. Here is the file after the unitname,bid,prodid,starttime,stoptime Reactor1Retired,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20 Reactor1Retired,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20 Page 162

185 9.3 - Shut Down the Retired System Reactor1Retired,XYZ3,Green,3-Mar-98 12:24:23,12:44: Shut Down the Retired System At this point we have piconfig text files of the point and batch databases and the ID conversion text file. This is required to reproduce the point and batch configuration on the destination system. Before shutting down the retired system, stop the interfaces and other data sources, write shutdown events to all the points, and force a shift. In this example, all interfaces are on the localhost rather than a remote node. On your system, make sure any API node and PINet node interfaces are shut down. Also shut down PI Totalizer, PI PE Scheduler, and PI Batch Subsystems. Before forcing the shift, make sure an empty archive is available for the shift. Here is the dialog from these steps: D:\PI\adm>pisrvsitestop D:\PI\adm>echo Stopping Site Specific PI System Services... Stopping Site Specific PI System Services... D:\PI\adm>..\interfaces\rmp_sk\rmp_sk -stop Stopping service rmp_sk rmp_sk Stopped Successfully. D:\PI\adm>..\interfaces\random\random -stop Stopping service random. random Stopped Successfully. D:\PI\adm>net stop pibatch The PI Batch Subsystem service is stopping... The PI Batch Subsystem service was stopped successfully. D:\PI\adm>net stop pitotal The PI Totalizer service is stopping... The PI Totalizer service was stopped successfully. D:\PI\adm>net stop pipeschd The PI Performance Equation Scheduler service is stopping.. The PI Performance Equation Scheduler service was stopped successfully. D:\PI\adm>..\bin\pishutev -verbose Shutdown input file: D:\PI\dat\shutdown.dat. Shutdown events will be written for tag mask * Point attributes: shutdown, 1 Shutdown Events at 3-Mar-98 11:04:09 sent for 37 Points Service Manager requested shutdown of pishutev D:\PI\adm>piartool -fs Attempting to force an archive shift... An archive shift has been initiated on the server. Completion time will vary from a few minutes to hours, depending on the machine and archive size. During this time the archive subsystem will be unavailable and the PI System should not be stopped until the shift is complete. PI Server System Management Guide Page 163

186 Chapter 9 - Merging Two PI Servers The status of the shift can be found in the message log using pigetmsg. The current primary archive is D:\PI\dat\piarch.002 and the target archive for shift is d:\pi\dat\piarch.004 The current primary archive has 2048 records and the target archive for shift has 2048 records. D:\PI\adm>pisrvstop At this point the retired system is no longer required. All the text files must be copied to the destination system. The archives to be merged must be copied to the destination system in binary mode. In this example, the following archives will be merged: Archive: D:\PI\dat\piarch.002 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.002 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 2025/2048 Start Time: 2-Mar-98 12:51:41 End Time: 3-Mar-98 11:15:03 Backup Time: Never Archive: D:\PI\dat\piarch.003 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.003 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 2047/2048 Start Time: 2-Mar-98 12:50:27 End Time: 2-Mar-98 12:51:41 Backup Time: Never Archive: D:\PI\dat\piarch.001 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: D:\PI\dat\piarch.001 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 39/512 Overflow: 1901/2048 Start Time: 25-Feb-98 14:16:40 End Time: 2-Mar-98 12:50:27 Backup Time: Never Add Retired Point Configuration to Destination System This is just a matter of inputting the scripts into piconfig. In this example, all tag configuration is in one file called retired.dif. The following command executes this script, only a portion of the output is shown: $ piconfig < retired.dif *> SINUSOIDRetired, 12 Hour Sine Wave,, float32, 0.0, 100.0, 50.0, 0, R, 2, 1, 0, *> SINUSOIDURetired, UTC 12 Hour Sine Wave,, float32, 0.0, 100.0, 50.0, 0, R, -2, 1, 0, *> CDT158Retired, Atmospheric Tower OH Vapor, DEG. C, float32, 50.0, 200.0, 140.0, 0, R,30, 1, 1, *> CDM158Retired, Light Naphtha End Point Control, STATE, digital,3.0, 4.0, 3.0, 1, R, 3, 1, 1, *> CDEP158Retired, Light Naphtha End Point,,int32,0.0, 400.0, 290.0, 0, R, 5, 1 Page 164

187 9.3 - Shut Down the Retired System Add PI Batch Unit Configuration to Destination System The example has unit configuration in the text file retiredunit.dif. Use piconfig to input this file: $ piconfig < retiredunit.dif *> Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'", Retired Reactor 1,"' productid-1retired'" PIconfig 1 Data lines 3 Command lines 0 Records in error... 1 Records Created Convert the Archives Converting the retired systems archive requires the binary ID conversion file. This is created from the ID conversion text file created on the retired system - retiredidconv.txt: $ piartool -idci /opt/pi/adm/retiredidconv.txt -idco /opt/pi/adm/retiredidconv.bin Creating new conversion table: /opt/pi/adm/retiredidconv.bin input lines processed 37 names in table The offline archive utility is used to convert the archives from the retired system. For this example, one archive will be converted and registered. Other archives are handled in a similar manner. Here is the dialog from the conversion: $../bin/piarchss -id /opt/pi/adm/retiredidconv.bin -if /opt/pi/dat/piarchretired.002 -of /opt/pi/dat/piarchconv.002 PIarchss offline archive utility Input file type: PI 3 Archive input file: piarchretired.002 Beginning first pass. Sorting input archive. Archive indicated start time: 2-Mar-98 12:51:41 Archive indicated end time: 3-Mar-98 11:09:30 Archive indicated recordcount: 2048 Processing record 1... Invalid ID Conversion on input Point ID 13. Record not processed. Primary record load completed. Records processed: 38 Records with data: 21 Empty records: 17 Records with errors: 0 Records out of time range: 0 Records with duplicate time range: 0 Overflow record load completed. Records processed: 157 Records with data: 155 Empty records: 0 Records with errors: 0 Records out of time range: 2 PI Server System Management Guide Page 165

188 Chapter 9 - Merging Two PI Servers Records with duplicate time range: 0 Begining Output pass. Output archive: piarchconv.002 Processing record 1... Invalid ID Conversion on input Point ID 13. Record not processed Loaded in 3( ) Seconds 7574 Event/Sec Archive Total seconds - ratio: Service Manager requested shutdown of piarchss Records for points not merged will not be processed. The above dialog shows a message indicating records for PointID 13 are not processed - this is the PI Batch point that was intentionally not merged. Note the times on the archive converted. The times overlap the primary archive on the destination system. This problem must be addressed before the converted archive can be registered. The solution is to force a shift, and combine the converted archive with the destination archive. After the shift, the destination system's archives are as follows: $ piartool -al Archive shift prediction: Shift Time: 18-Jan-38 19:14: Target Archive: /opt/pi/dat/piarch.002 Archive: /opt/pi/dat/piarch.003 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarch.003 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 98/512 Overflow: 2047/2048 Start Time: 3-Mar-98 16:32:27 End Time: Current Time Backup Time: Never Archive: /opt/pi/dat/piarch.001 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarch.001 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 98/512 Overflow: 1948/2048 Start Time: 2-Mar-98 12:21:11 End Time: 3-Mar-98 16:32:27 Backup Time: Never Archive: /opt/pi/dat/piarch.002 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarch.002 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 1/512 Overflow: 2047/2048 Start Time: Current Time End Time: Current Time Backup Time: Never The converted archive and piarch.001 must be combined. For this example the conversion will be made into a dynamic size. If converting into a fixed size archive, there must be Page 166

189 9.3 - Shut Down the Retired System enough space for all used records in both archives being combined. If in doubt use dynamic archives--they can always be moved into a fixed size archive later. In the following dialogs, the ID conversion file is not required: $../bin/piarchss -if /opt/pi/dat/piarch.001 -of /opt/pi/dat/piarchcomb.001 PIarchss offline archive utility Input file type: PI 3 Archive input file: /opt/pi/dat/piarch.001 Beginning first pass. Sorting input archive. Archive indicated start time: 2-Mar-98 12:21:11 Archive indicated end time: 3-Mar-98 16:32:27 Archive indicated recordcount: 2048 Processing record 1... Primary record load completed. Records processed: 97 Records with data: 86 Empty records: 11 Records with errors: 0 Records out of time range: 0 Records with duplicate time range: 0 Overflow record load completed. Records processed: 101 Records with data: 101 Empty records: 0 Records with errors: 0 Records out of time range: 0 Records with duplicate time range: 0 Begining Output pass. Output archive: /opt/pi/dat/piarchcomb.001 Processing record Loaded in 1( ) Seconds Event/Sec Archive Total seconds - ratio: Service Manager requested shutdown of piarchss Now combine the converted archive. $../bin/piarchss -if /opt/pi/dat/piarchconv.002 -of /opt/pi/dat/piarchcomb.001 PIarchss offline archive utility Input file type: PI 3 Archive input file: /opt/pi/dat/piarchconv.002 Beginning first pass. Sorting input archive. Archive indicated start time: 2-Mar-98 12:51:41 Archive indicated end time: 3-Mar-98 11:09:30 Archive indicated recordcount: 395 Processing record 1... Primary record load completed. Records processed: 97 Records with data: 26 Empty records: 71 Records with errors: 0 Records out of time range: 0 PI Server System Management Guide Page 167

190 Chapter 9 - Merging Two PI Servers Records with duplicate time range: 0 Processing record Overflow record load completed. Records processed: 139 Records with data: 139 Empty records: 0 Records with errors: 0 Records out of time range: 0 Records with duplicate time range: 0 Begining Output pass. Output archive: /opt/pi/dat/piarchcomb.001 Processing record Loaded in 20( ) Seconds 1093 Event/Sec Archive Total seconds - ratio: 4013 Service Manager requested shutdown of piarchss The combined archive is now ready for registration. Register it and have a look at some data from a merged point: $ piartool -ar /opt/pi/dat/piarchcomb.001 Attempting to register archive file: /opt/pi/dat/piarchcomb.001 Successfully registered archive file: /opt/pi/dat/piarchcomb.001 peach piadmin$ piartool -al Archive shift prediction: Shift Time: 18-Jan-38 19:14: Target Archive: /opt/pi/dat/piarch.002 Archive: /opt/pi/dat/piarch.003 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarch.003 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 98/512 Overflow: 2047/2048 Start Time: 3-Mar-98 16:32:27 End Time: Current Time Backup Time: Never Archive: /opt/pi/dat/piarchcomb.001 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarchcomb.001 State: 4 Type: 1 Write Flag: 1 Shift Flag: 0 Record Size: 1024 Count: 499 Offsets: Primary: 98/256 Overflow: 499/ Start Time: 2-Mar-98 12:21:11 End Time: 3-Mar-98 16:32:27 Backup Time: Never Archive: /opt/pi/dat/piarch.002 PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]: Version: 4 Path: /opt/pi/dat/piarch.002 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: 2048 Offsets: Primary: 1/512 Overflow: 2047/2048 Start Time: Current Time End Time: Current Time Backup Time: Never Page 168

191 9.3 - Shut Down the Retired System $ piconfig * (Ls - ) PIconfig> * (Ls - ) piarc.dif * (Ls - PIARC) PIconfig> sinusoidretired,2-mar-98,*, *> sinusoidretired,2-mar-98,*, ,GOOD,2-Mar-98 13:37: ,GOOD,2-Mar-98 14:39: ,GOOD,2-Mar-98 15:44: ,GOOD,2-Mar-98 16:57: ,GOOD,2-Mar-98 19:31: ,GOOD,2-Mar-98 20:31: ,GOOD,2-Mar-98 21:31: ,GOOD,2-Mar-98 22:40: ,GOOD,3-Mar-98 01:33: ,GOOD,3-Mar-98 02:38: ,GOOD,3-Mar-98 03:43: ,GOOD,3-Mar-98 04:57: ,GOOD,3-Mar-98 07:30: ,GOOD,3-Mar-98 08:39: ,GOOD,3-Mar-98 09:44: ,GOOD,3-Mar-98 10:57:56 Digital State,Shutdown,3-Mar-98 11:04:09 Digital State,Pt Created,3-Mar-98 14:29: ,GOOD,3-Mar-98 14:30: ,GOOD,3-Mar-98 15:30: ,GOOD,3-Mar-98 16:39: ,GOOD,3-Mar-98 16:48:56 End Repeat... Take a good look at several points before proceeding Merge the PI Batches Batches are stored in the Archive; therefore, all archives should be converted before processing the batch text files. Once again, piconfig is used to add the batches: $ piconfig * (Ls - ) pibatchlist.dif *>Reactor1Retired,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20 *>Reactor1Retired,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20 *>Reactor1Retired,XYZ3,Green,3-Mar-98 12:24:23,12:44:00 This completes the merger. PI Server System Management Guide Page 169

192

193 Chapter 10. THE PICONFIG UTILITY The piconfig utility maintains and configures PI Server databases such as the Point Database and the Digital State Table. The piconfig command line application runs on the PI Home node. You can work interactively with piconfig or you can supply text files that contain commands and data. Using piconfig, point information can be configured in a spreadsheet or database tool, exported to a text file, and then applied to the Point Database. The piconfig utility can also be used for troubleshooting. If you suspect that you have some tags that are not configured correctly, you can search for tags that match a certain list of attributes PI TagConfigurator & PI SMT Point Builder plug-in While piconfig is often used for building PI points, there are other utilities that can be obtained from OSIsoft to make this task easier: PI Tag Configurator, is an Excel spreadsheet add-in that can facilitate creating many new tags and modifying the attributes of existing tags in the Pipoint Table. The PI System Management Tools (PI SMT) includes a PI Point Builder Plug-in which is useful for editing or creating a small number of tags. PI SMT is available from the Download Center at the technical support web site, and documentation is included in the online Help file A Note to Pidiff Users The piconfig utility includes the features of the PIDIFF utility of OpenVMS PI Systems. It also includes many more features, such as the ability to edit tables other than the Point Database. Conversion information for upgrading from PI2 to PI3 may be found on the OSIsoft Web site. PI Server System Management Guide Page 171

194 Chapter 10 - The piconfig Utility 10.3 Key Concepts for Using Piconfig Starting and Stopping Piconfig The piconfig utility is a console application. To start, type piconfig at the command prompt. If you are on a UNIX system, be sure to type all lower-case characters, because the operating system is case-sensitive. $ piconfig In general, piconfig should be used only when PI is running. To end the piconfig session, use the exit command. The command character must precede every command. By default, the command character Data are on separate lines that are not preceded by the command character Interactive Session vs. Batch Method At startup, piconfig checks whether the input is coming from an interactive terminal session or from a piconfig script file. When run interactively, piconfig issues a prompt after each command. It is possible to turn prompting on and off by using the following no When turned on, the prompt indicates the piconfig mode and the current table name in parentheses. The table name in the prompt is set when you issue command: * (Ls - ) pipoint * (Ls - PIPOINT) Modes and tables are explained later in this chapter Selecting PI Tables Whether you are using an interactive session or a script file, the first step is to specify the PI table of interest. These are the PI tables that can be viewed and edited with piconfig: Table PI Tables Accessible Through piconfig Database Table Names Primary Key Points PIPOINT TAG Digital states PIDS SET Digital State Strings PISTATE STATE Users PIUSER USER Page 172

195 Key Concepts for Using Piconfig Database Table Names Primary Key User Groups PIGROUP GROUP Snapshot PISNAP or PISNAP2 TAG Archive PIARC TAG Batch Unit PIBAUNIT UNITNAME PI Batch PIBATCH UNITNAME Batch Alias PIBAALIAS ALIAS Trust Logins PITrust TRUST Firewall PI_GEN, pifirewall HOSTMASK Timeout Database PI_GEN, pitimeout NAME Attribute Sets PIATRSET SET Point Classes PIPTCLS CLASS Point Source PIPTSRC PTSRC PI Subsystem Information PISubsys,<subsystem> Not Applicable PI Subsystem Statistics PISubsysStats,<subsystem> Not Applicable PI Net Manager Statistics PINetMgrStats ID Database Security Dbsecurity DBName Subsystem Threads PIThread,<subsystem> ID The tables PI_Gen, PISubsys, PISubsysStats, PIThread and DBsecurity all require a second argument. This argument specifies the owner subsystem, or, for PI_Gen, the actual database file.?tbl Command to List Table Names The list of table names can be viewed using the?tbl command. Table Command to Select a Table Tables are selected using the table command. The currently selected table is indicated by the prompt. No table is selected until the first table command is issued. The table remains selected until the next table command. Status Commands The current setting of piconfig can be viewed using the status command. PI Server System Management Guide Page 173

196 Chapter 10 - The piconfig Utility Example of?tbl, Table, and Status Commands These commands are illustrated in the example below: * (Ls - ) 1 - PIPOINT 2 - PIDS 3 - PISTATE 4 - PIUSER 5 - PIGROUP 6 - PISNAP 7 - PIARC 8 - PIBAUNIT 9 - PIBATCH 10 - PIBAALIAS 11 - PITRUST 12 - PI_GEN 13 - PIATRSET 14 - PIPTCLS 15 - PISubsys 16 - PISubsysStats 17 - PINetMgrStats 18 - DBSecurity 19 - PITHREAD * (Ls - ) pipoint * (Ls - PIPOINT) ---- piconfig Status at 18-Mar-02 10:46: Mode: List Decimal digits displayed: -7 Characters: Command: <@> Delimiter: <,> Comment: <*> Quote: < > Struc. Type IN: <Delim.> OUT: <Delim.> Error count: 2 Max: 10 Current table: <PIPOINT> Cur. Prim.: <#####> Def. Prim: < > Nesting level : 0 Node: < ,piadmin> Table Attributes Once the table is specified, the attributes of that table can be displayed. In this example, PIPoint refers to the Point Database Table. The first column shows the attribute names and data types, the second column shows the default values, if any and the third column, the values of the last retrieved record. * (Ls - PIPOINT) 1 Tag String D:!#!#!# C: SINUSOID 2 NEWTag String D: C: 3 archiving BYTE D: 1 C: 1 4 changedate TimeSta D: 0 C: 21-Dec-02 01:03:0 5 changer String D: C: 6 compdev Float32 D: 2. C: 2. 7 Compdevpercent Float32 D: 2 C: 2. 8 compmax Uint16 D: C: compmin Uint16 D: 0 C: 0 Page 174

197 Key Concepts for Using Piconfig 10 compressing BYTE D: 1 C: 1 11 creationdate TimeSta D: 2. C: 17-Nov-02 18:39:5 12 creator String D: C: 13 DataAccess String D: o:rw g:r w:r C: o:rw g:rw w:rw 14 DataGroup String D: piadmin C: piadmin 15 DataOwner String D: piadmin C: piadmin 16 descriptor String D: C: 12 Hour Sine Wave 17 DigitalSet String D: system C: 18 displaydigits BYTE D: -5 C: engunits String D: C: 20 excdev Float32 D: 1. C: Excdevpercent Float32 D: 1 C: excmax Uint16 D: 600 C: excmin Uint16 D: 0 C: 0 24 exdesc String D: C: 25 PointID Uint32 D: 0 C: pointsource String D: Lab C: R 27 pointtype String D: Float32 C: Float32 28 PtAccess String D: o:rw g:r w:r C: o:rw g:rw w:rw 29 PtClassName String D: base C: classic 30 PtGroup String D: piadmin C: piadmin 31 PtOwner String D: piadmin C: piadmin 32 Recno Int32 D: 1 C: scan BYTE D: 1 C: 1 34 shutdown BYTE D: 1 C: 1 35 SourceTag String D: C: 36 span Float32 D: 100. C: step BYTE D: 0 C: 0 38 typicalvalue Float32 D: 50. C: zero Float32 D: 0. C: 0. Each of the table attributes can be viewed, set, or modified. Conceptually, each table in the piconfig utility has several columns, where the column headers are the attributes. Each row is a table record. For the PIpoint Table, each row corresponds to a particular tag Records Piconfig views its tables as a collection of records. A record is a collection of fields or attributes. One of these attributes is the primary key, which uniquely identifies the record within the current table. This data representation is done for convenience and standardization. It is not always an accurate image of the actual data. Consider the following entries in the Snapshot Table: CDM158 Auto 14-Jun-03 10:39:34 SINUSOID Jun-03 10:00:00 SINUSOIDU Jun-03 11:04:00 Attributes In this example, there is a record for each Snapshot, and each record contains three attributes. The attributes in this example are tag, value, and time. PI Server System Management Guide Page 175

198 Chapter 10 - The piconfig Utility Primary Key Every record contains one attribute that is defined as the primary key, which uniquely identifies the record. The primary key is the first attribute listed when using the?atr command. When using the select command to specify a record, the primary key must always be used. If it is not specified piconfig assumes * (all records). Other attributes may be selected in conjunction. For example, the primary key for the Pipoint Table is tag. When selecting the subset of tags with point source F, the primary key needs to be included as tag=*, pointsource=f Modifying the Primary Key Most table attributes can be modified in edit mode, using modify or istructure commands. The primary key is an exception. If you wish to change the primary key itself, you must provide the new key value using a special attribute: Use the newtag attribute for the Pipoint Table Use the newset attribute for the Pids Table For example, to rename the point sinusoid to mysinusoid, you would issue the commands: $ piconfig * (Ls - ) pipoint * (Ls - PIPOINT) edit * (Ed - PIPOINT) tag,newtag * (Ed - PIPOINT) piconfig> sinusoid,mysinusoid The attribute for the new primary key is always: new<primary-name> Note: Some tables do not support renaming of records, for example piarc and pisnap tables. Tag is the primary key of these tables. Since Tag is actually a point attribute, the rename must be down from the pipoint table. Other tables have similar relationships Piconfig Commands Once a table is selected, the next step is to use piconfig commands to retrieve and possibly change the data in the table. There are also piconfig commands that change the operational mode of piconfig. For example, you can use the modify command to change from list mode (read only) to create mode, delete mode, or edit mode. To see a list of piconfig commands, use the help command, as shown in the following example: * (Ls - PIPOINT) Page 176

199 Key Concepts for Using Piconfig *piconfig>? - This menu *piconfig> BYE - Exit piconfig *piconfig> CASE - Case sensitivity *piconfig> CD - Change working directory (for in/out files) *piconfig> CLEA - Clear selection and modifications specs *piconfig> COMM - Define comment character *piconfig> COMC - Set the command character *piconfig> DATA - Input data (redundant) *piconfig> DEFR - Primary key of default record *piconfig> DELI - Set delimiter character *piconfig> ECHO - Define echo: Data, Command, All, None *piconfig> ENDR - Mark end-of-record *piconfig> END-REPEAT - Mark end of data repetition *piconfig> ENDS - End of processing section *piconfig> ERROR - redirect error *piconfig> EXIT - Exit piconfig *piconfig> FLAG - Set table specific flags *piconfig> FLUS - Flush changes to table *piconfig> HELP - This page *piconfig> INPU - redirect input *piconfig> ISTR - Define input structure *piconfig> ISTY - Input structure type *piconfig> LINE - Increase input-line length *piconfig> LOGI - Connect to another PI host *piconfig> MAXE - Maximum errors allowed *piconfig> MODE - Mode: Create, Edit, List, Compare, Convert, Delete *piconfig> MODI - Modification specs *piconfig> OUTP - redirect output *piconfig> OSTY - Output structure type *piconfig> OSTR - Define output structure *piconfig> PROM - Prompt user for input *piconfig> PTCL - Default Point class *piconfig> QUIT - Exit piconfig *piconfig> QUOT - Set Quotation character *piconfig> RECS - Record separator Yes/No *piconfig> REFE - Reference by Name or Index *piconfig> SELE - Select (must include primary key specs.) *piconfig> SIGD - Set number of significant digits for real numbers *piconfig> STAT - Show current status: table, mode etc... *piconfig> STRU - Define structure (input/output depending on mode) *piconfig> STYP - structure type Delimited, Keyword, Fixed *piconfig> SYST - Execute any operating system command (dir, notepad...) *piconfig> STYP - structure type Delimited, Keyword, Fixed *piconfig> TABL - Set table (?TBL- to see all tables) *piconfig> TIMF - Number of decimal digits and Time zone name in timestamps * (Ls - PIPOINT) piconfig> PI Server System Management Guide Page 177

200 Chapter 10 - The piconfig Utility Example for Listing Point Information In this example, points are selected where the attribute tag starts with the letter S and have the point source R. R is the default point source for the random interface. All the tags that match these criteria will have their tag, point source, and point type displayed. $ piconfig * (Ls - ) pipoint * (Ls - PIPOINT) list * (Ls - PIPOINT) delimited * (Ls - PIPOINT) tag, pointsource, pointtype * (Ls - PIPOINT) tag=s*, pointsource=r * (Ls - PIPOINT) SINUSOID,R,Float32 SINUSOIDU,R,Float32 SQF100,R,Float32 SQF101,R,Float32 * (Ls - PIPOINT) piconfig> 0 Data lines 7 Command lines 0 Records in error 4 Records Listed The Pipoint Table is specified because we want to view the Point Database. The other commands are explained in the following paragraphs Mode Within piconfig, there are six possible working modes, as follows: (Ls) List mode (read only) Output formatted records from a table to screen or file (Cr) Create mode (add) Create new records in a table (Ed) Edit mode (modify) Modify or rename existing records (Dl) Delete mode Delete records from a table (Cv) Convert mode Convert input data from one format into another (Cm) Compare mode Compare file data to table data Create or Edit The character t (for true) may be specified with either create or edit mode. This combines the create and edit modes such that existing records are modified as specified while non-existent records are created as create, edit, t The specified mode persists until the next mode command is issued. Page 178

201 Key Concepts for Using Piconfig Check Only The character c (for check) may be specified with either create or edit create, edit, c Note: Check modifier is applicable only to the PIpoint Table In this mode points are validated and errors are reported but no changes are made to the point database. For all other tables this mode is identical with the normal edit or create mode. Check mode can also be specified for create, t, edit, t, c The specified mode persists until the next mode command is issued Structure Type The structure type (stype) indicates the format of the data structure used to specify input and output. The possible structure types are: Delimited Fixed Keyword In situations where the output structure type is different from the input structure type, the ostype and istype commands may be used instead of the stype command. The specified structure type persists until the next stype, ostype, or istype command. The default structure type is delimited format. Delimited Format In delimited format, one or more lines of comma-separated attributes describe the format of the data. One or more lines of comma-separated data values follow. These lines correspond to the attributes. For tag, pointsource,pointtype SINUSOID,R,FLOAT32 As shown above, the command is preceded by the command character (@) while the data are not. PI Server System Management Guide Page 179

202 Chapter 10 - The piconfig Utility Changing the Delimiter If you prefer, you may change the delimiter character to be any single (non-alphanumeric) character using the delimiter command. For example, to change the delimiter character to backslash ( \ ), issue the \ Note: The same delimiter character is used between piconfig attributes, between elements of a piconfig command and between both input and output data fields. Fixed Format In fixed format, we describe the data structure by one or more lines specifying the attribute, line number, starting position on the line (counting from 1), and field width. One or more lines of data values that correspond to the given format follows. For tag, 1, 1, pointsource, 1, 14, pointtype, 1, 19, 7 * * SINUSOID R FLOAT32 NEXTPOINT Lab FLOAT16 The lines starting with the asterisk (*) are comment lines and are ignored. Their only purpose is to improve readability. The format lines come first and are all grouped together. This defines a record. If there are more data lines than are specified in the record, piconfig interprets these as additional records of the same format. This example shows two input records. Fixed format is the same as used in the OpenVMS PI System PIDIFF utility. Changing the Comment Character If you prefer, you may configure the comment character to be something other than an asterisk. To do this, use the comment command (comm). Keyword Format In keyword format, every input line contains only two parts: the attribute and the value for that attribute, separated by the delimiter character. The default delimiter character is a comma (, ). The istructure command is not used with this format, as each line contains both data and its description. For example: tag, SINUSOID pointsource, R pointtype, FLOAT32 To select output attributes in keyword format, use the ostructure command. A single attribute is specified on each line, as shown below: Page 180

203 Key Concepts for Using pointtype To output all attributes for the current table, issue the * This works in both keyword and delimited formats. Note: The is meaningful only in list mode. A warning is issued if this command is executed in create, edit or delete mode. Structure Specifications Persistence Structure specifications for both input and output remain in effect until the table is changed. Before any data is processed, new structure specifications are added to previous specifications. After some data was processed, new structure specifications replace the previous ones. You can check which structure specification is in effect Select Command The select command is used to select the records of interest. Any combination of attributes may be used. In list mode only, the primary key specification defaults to * (all records). In edit or delete modes the primary key must be included in select specifications. A record must match all selection criteria to be selected. Select specifications remain in effect until the mode or table is changed. Until a command is processed, select specifications are added to previous specifications. After that, a new select specification replaces the previous ones. You can check the select specifications in effect at any time as Operators The following comparison operators are available: = equal <> not equal (!= also works) > greater than >= greater than or equal to < less than <= less than or equal to PI Server System Management Guide Page 181

204 Chapter 10 - The piconfig Utility These operators can be used for date, numeric or text fields. Text comparison is based on ASCII values Wildcards Wildcards, * and?, may be used in text fields. * matches all characters;? matches a single character The Ellipsis ( ) Construct for Repeating Attributes Structure specifications may contain table attributes followed by an ellipsis ( ). The ellipsis indicates that the last attribute may be repeated a variable number of times within a single record. If the ellipsis ( ) is on a separate line, it indicates that the last (previous) structure line may be repeated a variable number of times. In most cases, Delimited format is more suitable for repeatable attributes. In fixed format only complete lines can be repeated. A single field cannot be repeated on the same line in fixed format because its field length is fixed. The ellipsis construct can be used for both input and output. Example Using Ellipsis Construct List the states in the MODES state set using ellipsis. This means that multiple states will be listed in comma-separated format. * (Ls - PIDS) set,state,... * (Ls - PIDS) set=modes * (Ls - PIDS) MODES,Manual,Auto,Cascade,Program,Prog-Auto The ellipsis is useful where the same attribute can occur more then once in a single record. For example, a state set contains variable number of states. A point class contains a variable number of attributes and their defaults Endsection The endsection command triggers the processing of selected records. It is not always necessary to use an endsection command. An endsection is assumed when the end of file is reached or when a command follows lines of data. When an input structure is specified, every record is processed as data is entered. The following example demonstrates how processing occurs in both ways: d:\pi\adm>piconfig table pisnap * (Ls - PISNAP) piconfig> ostru tag,value,time *> ostru tag,value,time * (Ls - PISNAP) tag=sinusoid * (Ls - PISNAP) SINUSOID, ,20-Nov-02 16:25:30 * (Ls - PISNAP) tag * (Ls - PISNAP) piconfig> sinusoid *> sinusoid Page 182

205 Key Concepts for Using Piconfig sinusoid, ,20-nov-02 16:25: Exit Exit is the command that terminates the piconfig session. It is not necessary to use this command when running piconfig in batch mode because the end of file causes piconfig to execute the current commands and then exit. Quit and Bye has the same effect Batch Methods Preparing Input Files Entering commands by hand in interactive sessions can be prone to errors. It is often easier to enter the commands in a text file, save it, and then use that file as input to later piconfig sessions. This is particularly useful for maintaining the point database using a spreadsheet. See the example in the section, Adding Tags to the Point Database Using Excel. Comments can be added to the text file for better readability. For example, suppose you decided to list points with names starting in S and pointsource=r, including tagname, pointsource and pointtype. You could specify delimited output structure. To do all this, you could prepare and save an ASCII file named list.inp: ************* * list.inp * ************* * This piconfig script file lists the tagname, * pointsource, and * pointtype for all tags that start with "S" and * which have point source R tag, pointsource, tag=s*, Start piconfig and run this input file using the input command: $ piconfig * (Ls - ) list.inp The following output is generated: SINUSOID,Float32,R SINUSOIDU,Float32,R SQF100,Float32,R SQF101,Float32,R * (Ls - PIPOINT) piconfig> PI Server System Management Guide Page 183

206 Chapter 10 - The piconfig Utility Passing an Input File as a Parameter An alternative is to pass the input file as a parameter on the command line. The piconfig utility takes each pair of input parameters and treats the first as a command and the second as the command parameter: $ piconfig input list.inp SINUSOID,Float32,R SINUSOIDU,Float32,R SQF100,Float32,R SQF101,Float32,R * (Ls - PIPOINT) piconfig> Redirection of an Input File Another alternative is to use the standard UNIX or Windows I/O redirection from the command line: $ piconfig < list.inp SINUSOID,Float32,R SINUSOIDU,Float32,R SQF100,Float32,R SQF101,Float32,R piconfig 0 Data lines 6 Command lines 0 Records in error... 4 Records Listed Input files may contain all data, all commands, or mixed commands and data. Input files may be nested; that is, an input file can refer to other input files. Capturing Output and Errors in Files The piconfig utility output and errors are displayed by default on the computer screen. Use the output and error commands to redirect this output in a file. $ piconfig *>@output list.out *>@error errors.out By default piconfig echoes the input commands and input data in the file, as well as the output data. If you wish to see only the output data in the file, use the echo command with the data option: data Passing Commands as Parameters You can pass the commands on the piconfig command line. PIconfig takes each pair of input parameters and treats the first as a command and the second as the command parameter: $ piconfig input list.inp output list.out Page 184

207 Key Concepts for Using Piconfig Redirection of Output An alternative is to use standard UNIX or Windows I/O redirection from the command line: $ piconfig < list.inp > list.out Re-using an Output File as an Input File Redirecting the output to a file is very useful because you can reuse the output file as an input file with other piconfig commands. For example, suppose you want to create a tag that is similar to another tag that already exists on the PI Server. For example, the tagname and the hardware address are the only differences; the descriptor, zero, span, pointtype, pointsource, and engineering units are the same. You can accomplish this task by listing all of the point attributes of the existing tag to a file. Then the tagname and hardware address are modified using a text editor. Finally the file is used as input to piconfig to create the new tag Security on Piconfig Sessions Users of the piconfig utility can be required to login into the PI database by specifying a user name and a password. This option is turned on by setting the PItimeout parameter CheckUtilityLogin to 1. By default this option is off Remote Piconfig Sessions The piconfig utility running on one PI Server or PI-SDK node may connect a PI Server running on a different computer. There are two ways to do this. Using the Login Command If you already have a piconfig session in progress, you can switch to a different PI Server using the login command. The login command takes four parameters: 1. Remote PI 3 host name, or IP address 2. Remote PI Server user name 3. Remote PI password 4. Remote PI port ID (usually 5450) For figaro, piadmin, myadminpassword, 5450 Once the login command is issued, all subsequent commands are executed on the remote PI Server. Note: The PI_Gen tables are accessed only on the local machine. Even during a remote session. This means that modifying PI_Gen tables must be done locally. Attempting to modify these tables during a remote session will produce a warning message. PI Server System Management Guide Page 185

208 Chapter 10 - The piconfig Utility Invoking Piconfig for Remote Connection You can invoke the piconfig utility with the -remote command line option. After this option, specify the connection information using other command line switches. If you are passing any piconfig commands on the command line, enter them before the -remote option. For example: piconfig input piarc.dif -remote -node figaro -port username piadmin -password myadminpassword You may specify the parameters -node, -port, -username and -password in any order, after - remote Piconfig Commands and Tables This section contains details on piconfig commands and tables. Table Piconfig Commands Command Parameters Defaults Description? None None Lists all commands?atr None None Lists all attributes for current table?tbl None None Lists all tables known to piconfig Case Flag All (caseinsensitive ) Sets case-sensitivity-ignore mode. Flag may be: Data, Names, or All. This affects only tables accessed vie the PI_GEN table i.e. timeout and firewall. Cd Directory None Change directory for input/output files Clear None None Clears Modify and Select specifications Comchar Changes the command character to c Comment C * Changes the comment character to c Delimiter C, Changes the delimiter to c Echo Flag Data Specifies if input commands and data are echoed to the output file. Flag may be: Data, Commands, All, Verbose or None. End-repeat None None Marks end of repeated field Endrecord None None Terminates input of one data record. Required in keyword format. May be used in other formats to terminate input before all data fields were entered Endsection None None Marks the end of processing section Error File None Redirect error messages to file Page 186

209 Piconfig Commands and Tables Command Parameters Defaults Description Exit None None Exits piconfig. (Quit and Bye work the same way.) Help None None Lists all commands Input File None Redirects input from file. Istructure Structure None Specifies format of input data. Istype Flag D Selects input data format structure type: Fixed, Delimited, or Keyword. (F,D,K) Line N 1024 Input line buffer size Login PI 3 node, PI user name, password, port ID None Connect to a remote PI 3 home node using the given PI username, password, and TCP/IP port ID. Maxerr N 10 Sets the error tolerance. piconfig will exit when the number of errors reaches n. However, piconfig exits only when in non-interactive mode. A Maxerr value of -1 causes piconfig to exit upon the first error and display the line number of the input file. Mode Flag List Specifies mode of operation: Create, Edit, Delete, List, Compare, Convert, Create, and Edit mode can be modified to include both. Specify the mode flag as Edit,t or Create,t. For check only specify Edit,c or Create,c. Modify Modification None Defines field modifications. Ostructure Structure None Specifies format of output data. Only useful when in list mode. A warning is issued if this command is used in mode edit, create, or delete. Ostype Flag D Selects output data format structure type: Fixed, Delimited, or Keyword. (F,D,K) Output File None Redirect output to file. If <file> not specified, the output is directed back to standard output. Prompt Flag No Sets prompt mode: yes (for interactive sessions) or no (for batch sessions) Ptclassname Classname Base Specifies the point class: base or classic. Pipoint Table only. Quote C Must be or None Tells piconfig to enclose output fields with quote character c if they contain the delimiter character. Recsep Flag Yes Tells piconfig to separate multi-line output records with a comment line. PI Server System Management Guide Page 187

210 Chapter 10 - The piconfig Utility Command Parameters Defaults Description Select Selection Key=* Defines record selection criteria. Sigd N 5 Number of significant decimal digits in number display Status None None Report piconfig current configuration: table, mode, structure type, etc. Structure Structure None Specifies either input or output according to mode. Output in list and convert modes. Input in all other modes. STYP Structure Type Delimited Set structure type. Valid types are Delimited, Keyword, and Fixed. SYST System None Execute OS console command. For example Syst dir Table Table None Sets the PI table to Pipoint, Pids, etc. Timformat Dig,TZ 5,F Time format. Number of decimals on sub-second timestamps and whether or not to include timezone indication Point Database Table The table name is Pipoint. The primary key is TAG. Point Classes in the Point Database The Pipoint Table (Point Database) has several different point classes. The point class determines the attribute set for each point. The Base class attributes are included in all other point classes. Accessing Point Class Attributes To access the attributes of another point class, change the point class using the ptclassname command. For example, to change to the Classic point classic Optionally the ptclass can be specified at Pipoint Table load; the syntax pipoint,<ptclass> This example selects the Pipoint Table and classic pipoint,classic When listing classic point attributes of non-classic points, attributes unique to classic will appear to be blank. Page 188

211 Piconfig Commands and Tables Listing Attributes in the Classic Point Class Example To see which additional attributes are available using the Classic point class, select the Classic point class with the ptclass command and list the attributes using the?atr command. (Ls - ) pipoint (Ls - PIPOINT) (Ls - PIPOINT) classic (Ls - PIPOINT) Modifying an Attribute in the Point Database With the exception of point class and point type, the user-configurable point attributes in the Point Database may be modified using piconfig. The syntax <attribute>=<newvalue>,<attrib2>=<newvalue2>,... Example to Modify the Span Point Attribute In this example, the modify command is used to change the span for all tags starting with MyTag Example Using Operators for Modifying Point Attributes Values may be modified arithmetically by using the following operators: attribute += value attribute -= value attribute *= value attribute /= value This example changes all tags with a point source of X to have a zero that is 10 units less then its current value and increases the span to 110% of its current tag=*, zero-=10, Modify specifications remain in effect until a table is changed. New modify specifications are added to previous specifications until data is processed. After this, new specifications replace previous ones. Modifying a Nonexistent Attribute If you attempt to modify an attribute that a tag does not have (such as a Classic attribute for a point in the Base class), you will get an error message: PI Server System Management Guide Page 189

212 Chapter 10 - The piconfig Utility [-12001] Name Not Found in PInt] Adding Tags to the Point Database Using Excel The TagConfigurator is a utility that should be used to configure PI points using Microsoft Excel. It can be obtained from the OSIsoft Technical Support Web site at This section outlines a technique that can be used if you wish to develop a point configuration spreadsheet yourself. The spreadsheet should contain a row for each tag and a column for each attribute, such as tag, Pointsource, and pointtype. Save the spreadsheet as an ASCII file with comma-separated values. Precede any non-data lines in the file with an * comment character. That way piconfig will ignore them. Here s an example data file, taglist.dat, generated from a spreadsheet in Comma-Separated Variable format (CSV): RealTag1,Lab,float16 RealTag2,Lab,float16 Modify the following example structure file so that the attributes listed in the istructure line match the contents of the ASCII data file. Note that the tagname, as specified by the Tag attribute, is the only attribute that is required. Attributes that are not specified will be given default values. Use create mode to create new tags; use edit mode to modify existing tags. Use create, t or edit, t mode to create the tag if it does not exist and to modify it if it does exist. *Example piconfig input structure file *File name: example3.str * *Create or modify tags from input file taglist.dat create, tag, pointsource, * *List tags to verify creation or modification tag, pointsource, tag=*, Run piconfig using the structure file as input. piconfig < example3.str Page 190

213 Piconfig Commands and Tables PI Attribute Set Table The Attribute Set Table contains sets of attributes used to build point classes. An attribute defines a point attribute; it is comprised of a name, data type and default value. An attribute set contains a list of attributes. Attribute sets are the building blocks of point classes. Point classes are made up of a list of attribute sets. Note: Changing existing attribute sets except for changing default values, should be done with great care, in standalone mode. The table name is PIATRSET. It has the following attributes: Attribute SET ATTRIB DEFAULT TYPE Description name of attribute set Attribute name; a set has many of these Default value of the attribute Data type of the attribute. For example, String, Float32 Note: An attribute set has many of the Attrib, Default, Type triplet. The ellipsis ( ) following TYPE indicates those three may be repeated. The following piconfig session demonstrates listing the attribute sets on the PI Server: * (Ls - PIATRSET) piatrset * (Ls - PIATRSET) set * (Ls - PIATRSET) *PIConfig Err> Wild-card specs. missing, default to '*'. alarmparam base classic sqcalm_parameters totals * (Ls - PIATRSET) PIconfig> Now listing the entire classic then base attribute sets; note use of the ellipsis to repeat the output: * (Ls - PIATRSET) piatrset * (Ls - PIATRSET) attrib, default, type * (Ls - PIATRSET) * (Ls - PIATRSET) set * (Ls - PIATRSET) PIconfig> classic *> classic location1,0,int32 location2,0,int32 location3,0,int32 location4,0,int32 location5,0,int32 PI Server System Management Guide Page 191

214 Chapter 10 - The piconfig Utility filtercode,0,int16 squareroot,0,int16 totalcode,0,int16 convers,1.,float32 srcptid,0,int32 instrumenttag,,string userint1,0,int32 userint2,0,int32 userreal1,0.,float32 userreal2,0.,float32 * End Repeat... * (Ls - PIATRSET) PIconfig> base *> base descriptor,,string exdesc,,string typicalvalue,50.,float32 engunits,,string zero,0.,float32 span,100.,float32 pointtype,12,ubyte pointsource,lab,string scan,1,byte excmin,0,uint16 excmax,600,uint32 excdev,1.,float32 shutdown,1,byte archiving,1,byte compressing,1,byte step,0,byte compmin,0,uint16 compmax,28800,uint32 compdev,2.,float32 creationdate,31-dec-69 16:00:00,TimeStamp creator,0,uint16 changedate,31-dec-69 16:00:00,TimeStamp changer,0,uint16 displaydigits,-5,byte * End Repeat... Users familiar with classic PI Points will recognize all these attributes. These two attribute sets, Classic and Base, make up the classic point class Point Class Database The Point Class Database contains all the point classes defined on a PI Server. A point class defines the attributes of a PIPOINT. This approach allows points to have attributes specific to the point's role. For example, Totalizer points use a point class designed specifically for the Totalizer needs. Note: Editing existing Point Classes should be done with great care in standalone mode. Page 192

215 Piconfig Commands and Tables The table name is PIPTCLS. It has the following attributes: Attribute Class SET ATTRIB DEFAULT TYPE Description name of the class The attribute set where attribute in the class were defined. This attribute is only used in create mode. It is used to specify the attribute sets which comprise the point class. Attribute name; a class has many of these Default value of the attribute Data type of the attribute. For example, String, Float32 The following piconfig session lists the point classes on the server: * (Ls - PIPTCLS) class * (Ls - PIPTCLS) *PIConfig Err> Wild-card specs. missing, default to '*'. Alarm base classic SQC_Alarm Totalizer Now listing classic point class; this class is built from the classic and base attribute sets: * (Ls - PIPTCLS) piptcls * (Ls - PIPTCLS) list * (Ls - PIPTCLS) attrib,default,type * (Ls - PIPTCLS) * (Ls - PIPTCLS) class * (Ls - PIPTCLS) PIconfig> classic *> classic descriptor,,string exdesc,,string typicalvalue,50.,float32 engunits,,string zero,0.,float32 span,100.,float32 pointtype,12,ubyte pointsource,lab,string scan,1,byte excmin,0,uint16 excmax,600,uint32 excdev,1.,float32 shutdown,1,byte archiving,1,byte compressing,1,byte step,0,byte compmin,0,uint16 compmax,28800,uint32 PI Server System Management Guide Page 193

216 Chapter 10 - The piconfig Utility compdev,2.,float32 creationdate,31-dec-69 16:00:00,TimeStamp creator,0,uint16 changedate,31-dec-69 16:00:00,TimeStamp changer,0,uint16 displaydigits,-5,byte location1,0,int32 location2,0,int32 location3,0,int32 location4,0,int32 location5,0,int32 filtercode,0,int16 squareroot,0,int16 totalcode,0,int16 convers,1.,float32 srcptid,0,int32 instrumenttag,,string userint1,0,int32 userint2,0,int32 userreal1,0.,float32 userreal2,0.,float32 * End Repeat... * (Ls - PIPTCLS) PIconfig> Point Source Database The Point Class Database is actually a view into the point source index of the point database. It provides the ability to add a descriptor for each point source and to quickly view the number of points per point source. The table name is PIPTSRC It has the following attributes: Attribute Ptsrc Code Count Desc Description The point source character or string The internal code, used for point source update signup Number of points in this point source Free format descriptor The following piconfig session lists the point sources on the server: * (Ls - PIPTSRC) ptsrc,code,count,desc * (Ls - PIPTSRC) *PIconfig Err> Wild-card specs. missing, default to '*'. #,15,26, *,13,1, 1,7,5589, Page 194

217 Piconfig Commands and Tables C,4,22, G,9,18, L,3,15, Lab,5,4056, PIBatch-InternalUse-1,11,2, PICampaign-InternalUse-1,19,1, PITest,16,1, PIUnitBatch-InternalUse-1,8,109, R,1,9865, T,6,15,Totalizer Points U,12,2, Digital States Table The Digital State Table contains the digital state sets. A state set has a name and a list of states (digital state strings). The system is limited to sets with up to states in each set. The table name is PIDS. The primary key is SET. The following attributes are defined: Attribute SET SETNO STATE Description name of digital state set digital state set number (read only) digital state strings in the set The default set is called system and contains all the default system states found in a PI2.x Digital State Table. The System Digital State Set number, SetNo, is 0 (zero). Once created, a digital state set cannot be deleted. Listing all State Sets in the Digital State Table The next example shows how to list all state sets in the Digital State Table. The defaults are list mode and delimited format. In the example below, first we ask piconfig to list the attributes of the pids table. Then we ask to see all of the sets in the table; four are listed. $ piconfig (Ls - ) pids (Ls - PIDS) 1 - SET (D) Setxxx 2 - SETNO (D) STATE (D) Statexxx 4 - OLDCODE (D) NEWSET (D) (Ls - PIDS) set (Ls - PIDS) set=* (Ls - PIDS) SYSTEM BATCHACT PI Server System Management Guide Page 195

218 Chapter 10 - The piconfig Utility PHASES MODES Adding a Digital State Set To add a digital state set to the Digital State Table, use piconfig as follows: 1. Select the Digital State Table (Ls - PIDS) pids 2. Prepare to write to the table (Ls - PIDS) create 3. Specify an input data format of a digital state set name followed by any number of states in the set. Follow this with a data line. (Cr - PIDS) set, state,... (Cr - PIDS) piconfig> ValveStateSet, Open, Closed 4. Next, list the new state set in order to verify that it was properly created. Select only those sets that start with V. Use an endsection command to force processing: (Cr - PIDS) list (Ls - PIDS) set, state,... (Ls - PIDS) set=v* (Ls - PIDS) VALVESTATESET,Open,Closed (Ls - PIDS) piconfig> The endsection command is not needed when creating the state set because data lines are processed as they are entered. Adding a Digital State Set Using Multiple IStructure Lines This method uses multiple istructure command lines. 1. Select the Digital State Table (Ls - PIDS) pids 2. Prepare to write to the table (Ls - PIDS) create 3. Specify an input data format that consists of a digital state set name followed by any number of states in the set. (Cr - PIDS) set (Cr - PIDS) state (Cr - PIDS) The input lines are the set name followed by any number of states: ValveStateSet Open Closed Page 196

219 Piconfig Commands and Tables Subsequent lines are treated as input until the next piconfig command is issued. Modifying a Digital State Set If you want to modify an existing digital state set by adding a state, deleting a state, or renaming a state, you must specify all of the states in the state set. Individual states cannot be edited. For example, add another state to the ValveStateSet as follows: 1. Select the Digital State Table (Ls - PIDS) pids 2. Prepare to write to the table (Ls - PIDS) edit 3. Specify an input data format that consists of a digital state set name followed by any number of states in the set. (Ed - PIDS) set, state, The next line is pure input data (no commands) (Ed - PIDS) piconfig> ValveStateSet, Open, Closed, Stuck 5. Next, list the new state set in order to verify that it was properly created: (Ed - PIDS) list (Ls - PIDS) set, state, Select only those sets that start with V (Ls - PIDS) set=v* 7. Start processing (Ls - PIDS) VALVESTATESET,Open,Closed,Stuck (Ls - PIDS) piconfig> Note: For sets with more then a few states it is advisable to use an output file, edit the file, and then use it as input file. As mentioned above, the state must be added or edited as a whole. See the following explanation about editing the system set. Modifying the System state Set The System State Set is always set number 0. It cannot be deleted. Renaming it is allowed, yet not recommended. As with any other set, it must be edited in its entirety. The System State Set usually includes some blank states. To preserve these, make sure that blank state are enclosed in quotes, or use the oldcode attribute. The oldcode attribute can help keeping reference to state offsets within a set during editing. It has no other PI Server System Management Guide Page 197

220 Chapter 10 - The piconfig Utility system 0,?????????? 1, 2,?2 3, system?????????? ""?2 ""?4 Both examples show only the first 5 states in the system set, and in both cases states 1 and 3 are blank. Changing Capitalization of a Digital State String PI maintains a list of all digital state strings in use. This means that if a given digital state string is used in more than one digital state set, both sets refer to the same state string. System managers need the ability to edit the digital string in the event that an error is made when the string is first added to PI. The PIstate Table is used for this purpose. For example, to correct the digital state string error AUto to Auto, you would issue the following piconfig commands: (Ls - ) pistate (Ls - PISTATE) edit (Ed - PISTATE) state,newstate (Ed - PISTATE) piconfig> AUto,Auto AUto,Auto (Ed - PISTATE) piconfig> The only processing mode supported by the Pistate Table is edit, which means that you cannot use this table to create, delete or list digital state strings. To modify or list digital state sets or the strings that belong to them, use the Pids Table. You should not use the PIstate Table to substantially change the meaning of any digital state string. This would affect any digital state set that uses the state string. Changing the Digital State Set Name - Example In the digital state table, the primary key is SET, so the NEWSET attribute is used to change the value of the primary key: (Ls - ) pids (Ls - PIDS) list (Ls - PIDS) set (Ls - PIDS) set=* (Ls - PIDS) SYSTEM Page 198

221 Piconfig Commands and Tables BATCHACT PHASES MODES VALVESTATESET (Ls - PIDS) edit (Ed - PIDS) set,newset (Ed - PIDS) piconfig> ValveStateSet,NewValveStateSet (Ed - PIDS) list (Ls - PIDS) set (Ls - PIDS) set=* (Ls - PIDS) SYSTEM BATCHACT PHASES MODES NEWVALVESTATESET Creating a Digital Tag Example A digital tag is defined by specifying point type Digital in the Point Database. The digital state set will default to System. To specify a different state set, enter the digital state set name in the tag s DigitalSet attribute in the Point Database. In the example below, the tagname, the point type, and the digital state set are explicitly defined, while all the other point attributes use the defaults. 1. Select the Point Database Table. (Ls - ) pipoint 2. Prepare it for writing (Ls - PIPOINT) create 3. Specify the input data format (Cr - PIPOINT) tag, pointtype, digitalset *> istructure tag, pointtype, digitalset 4. Specify the data (Cr - PIPOINT) piconfig> ValveStateTag, Digital, ValveStateSet *> ValveStateTag, Digital, ValveStateSet 5. Next, list the new state set in order to verify that it was properly created: (Cr - PIPOINT) list (Ls - PIPOINT) tag, pointtype, digitalset 6. Select only those tags that start with V (Ls - PIPOINT) tag=v* 7. Now force processing (Ls - PIPOINT) ValveStateTag, Digital, ValveStateSet PI Server System Management Guide Page 199

222 Chapter 10 - The piconfig Utility Sending a Digital State to the Snapshot Database Next, send a digital state Value to the Snapshot to verify that the new tag you have created can retrieve the value. 1. Select the Snapshot Table (Ls - ) pisnap 2. Prepare for writing (Ls - PISNAP) edit 3. Specify the input data format: (Ed - PISNAP) tag, time, value 4. Specify the data. The timestamp is *, which indicates that the current time should be used. (Ed - PISNAP) piconfig> ValveStateTag, *, Open 5. Next, list the new state set in order to verify that it was properly created: (Ed - PISNAP) list (Ls - PISNAP) tag, time, value 6. Select only those tags that start with V: (Ls - PISNAP) tag=v* 7. Now start processing: (Ls - PISNAP) ValveStateTag, 26-SEP-03 15:45:32, Open Snapshot and Snapshot2 Tables The Snapshot and Snapshot2 tables provide access to the PI Snapshot, both for listing or editing. The table name is Pisnap. The primary key is TAG. The following attributes are defined: Table Snapshot and Snapshot2 Tables Attributes Attribute Description Comment TAG The tagname (Read only) PointID The point ID (Read only) Type The point type (float32 ) (Read only) Value TIME Event timestamp in the format DD-MMM-YY hh:mm:ss.ssss TimeNum Timestamp as a number in seconds past 01-Jan-70 (Read only) Page 200

223 Piconfig Commands and Tables Attribute Description Comment Status The value status (Read only) Flags (Q)uestionable (M)odifed (A)nnotated Only Q is read/write Annot Annotation To read Snapshot data, use list mode. To change the data, use edit mode. Other modes are not applicable. If a numerical Snapshot value is invalid, the PI Server shows the value as Digital State and the status attribute shows the digital state that describes the status. If a numerical value is valid, the actual value is shown and the status attribute shows the digital state GOOD. To change a digital point value, you can specify either the digital state name or the numeric offset (digital state number.) The file pisnap.dif is included with every system. It is a quick way to list Snapshot values. $ piconfig input pisnap.dif * (Ls - PISNAP) tag=c* * (Ls - PISNAP) CDEP158,2,GOOD,20-Nov-02 17:02:00 CDF144,Digital State,No Data,20-Nov-02 17:11:42 CDM158,Manual,GOOD,20-Nov-02 17:09:30 CDT158, ,GOOD,20-Nov-02 17:10:00 A second table named Pisnap2 is useful for debugging classic PI API applications. It uses the PI 2.x concepts rval and istat instead of Value and Status: Attribute RVAL ISTAT Description real values; or 0 for other point types Positive integer value for integers, status for invalid real values, or set and state number for digitals. In PI 2.x, istat for digital tags is the negative of the state number. In the Pisnap2 Table, istat contains a 32-bit number that represents both set and state. The set number is in the most significant 16 bits and the state number is in the least significant 16 bits. The system set number is 0. Be aware that some PI API functions truncate the most significant 16 bits. Refer to the PI Server Reference Guide, Appendix B, PI API Limitations, for more information. String values cannot be used in Pisnap2 Table. Adding Events to the Data Archive Using the Snapshot Table Events value/time pairs may be added to the PI Data Archive by using the Snapshot Table. The Snapshot contains the most recent event for each tag. If you add an event to a tag in the Snapshot Table, the previous event will be archived if it passes the compression tests. Events with timestamps earlier then the current Snapshot timestamp bypass the Snapshot PI Server System Management Guide Page 201

224 Chapter 10 - The piconfig Utility Table and are sent directly to the Archive. You can only view the most recent event in the Snapshot Table. The tagname, time stamp, and value must all be specified. The time can be in any of the valid PI time formats specified in the PI Server Reference Guide, Appendix A. Select the Snapshot table and prepare for editing. (Ls - ) pisnap (Ls - PISNAP) edit Specify the format of the input data. (Ed - PISNAP) tag, time, value The following lines are input data. RealTag, 13-Aug-03 10:00, 3.81 RealTag, 13-Aug-03 10:05, 2.45 IntTag, *, 5 DigTag, T+8h, CLOSED Adding Data Using Pisnap2 Table In the Pisnap2 Table, use the rval and istat attributes instead of the value attribute: In this example, a good and a bad value are added to PI: (Ls - ) pisnap2 * (Ls - PISNAP2) edit * (Ed - PISNAP2) tag,time,rval,istat * (Ed - PISNAP2) piconfig> sinusoid,*,50.0,0 > sinusoid,,50.0,0 * (Ed - PISNAP2) piconfig> sinusoid,*,0,-254 > sinusoid,*, 0,-254 Using the Pisnap2 Table to add values to integer and digital tags would require setting the istat attribute Archive Table The Archive Table provides access to the PI Data Archive. Events can be listed, added, modified, and deleted. The table name is Piarc. The primary key is TAG. The following attributes are defined: Table Archive Table Attributes Attribute Description Comment TAG the tagname (read only) PointID the point ID (read only) Type the point type (float32 ) (read only) Page 202

225 Piconfig Commands and Tables Attribute Description Comment Value TIME Event timestamp in the format DD-MMM-YY hh:mm:ss.ssss TimeNum Timestamp as a number in seconds past 01-Jan-70 (read only) Status the value status (read only) Flags (Q)uestionable (M)odifed (A)nnotated Only Q is read/write Annot NewValue Annotation New value for specific replacement These attributes are the same as the Pisnap attributes. In addition there are some auxiliary attributes that affect retrieval and editing: Attribute Count Mode Starttime Endtime Description Maximum number of events to retrieve in list mode Archive editing mode see below Start time for events retrieval End time for events retrieval Starttime and endtime can define both a forward and a backward search. Events can be added to the Snapshot using the Piarc Table. Events are placed in the Snapshot if they are more recent than the current Snapshot event; otherwise, they bypass compression and go straight to the Archive according to the archiving mode specified. When a new Snapshot event is stored, the previous Snapshot event is sent to the archive, compressed according to the compression specifications. List Mode Attribute for Piarc In list mode, the Piarc Table mode attribute can be one of the following: Attribute COMP EVEN Description Compressed events Interpolated events. The number of evenly spaced events returned between starttime and endtime is given by the Count parameter. Listing Archive Values The piconfig input file PI\adm\piarc.dif is provided with every PI Server. It is a quick way to view archive data from within piarc.dif PI Server System Management Guide Page 203

226 Chapter 10 - The piconfig Utility Next, enter data with the format: tagname, starttime, endtime, count For example, to view four hours of data for the tag sinusoid, with a maximum of 100 values, piarc.dif sinusoid, *-4h, *, The Piarc Table can be used also to view interpolated data by specifying the even mode. In this example, 5 evenly spaced values will be retrieved: * (Ls - PIARC) piarc * (Ls - PIARC) tag, starttime, endtime, count, mode * (Ls - PIARC) value,status,time * (Ls - PIARC) * (Ls - PIARC) piconfig> sinusoid,*,*-4h,5,even *> sinusoid,*,*-4h,5,even ,GOOD,20-Nov-02 17:52: ,GOOD,20-Nov-02 16:52:51 Digital State,Shutdown,20-Nov-02 15:52:51 Digital State,Shutdown,20-Nov-02 14:52:51 Digital State,Shutdown,20-Nov-02 13:52:51 * End Repeat... Edit Mode Attribute for PIArc Table In edit mode, the MODE attribute can be one of the following: Attribute noreplace append replace replacex replacesp remove appendx Description add unless event(s) exist at same time (PI 2.x) add event regardless of existing events add event, replace if event at same time Replace existing event (fail if no event at time) Replace a specified value when multiple values at the same time Remove existing event as append + no compression; that is, if this is the Snapshot, force into Archive Note: Do not confuse the Piarc Table mode attribute with the piconfig mode command. To delete archive events, use the Piarc Table mode attribute=remove in piconfig edit mode. Changing and Deleting Events in PIArc Table The following commands can be used to add, edit, and delete events. Page 204

227 Piconfig Commands and Tables Note: In remove mode, both value and time must exactly match the existing event. If the timestamp contains sub-seconds, it might be necessary to expand time resolution with the timf command in order to make an exact match. Similarly, the number of decimal digits might need to be increased for floating point values using the sigd tag, value, time, mode string1,some text,11:45, append realtag,12.5,10:44, replace inttag, 10, t, remove When adding a new archive event with the edit modes above, you must use: create,t The piconfig selection and modification may be used. For example one might create an input file (input.txt) with the following command tag, starttime, endtime, tag, value, labevents.txt labtag,t,y,100 then redirect this input file into piconfig in order to list some events to an output file called labevents.txt: * (Ls - PIARC) piconfig < input.txt Now one can change or delete all these events. For tag, value, status, value*= 1.1, labevents.txt This will increment all the previously selected events by 10%. To delete all events for a specified time range (last 7 days in this example) for a given tag you can place the script below in a file called tag, starttime, endtime, tag, tmpdelevents.dat PI Server System Management Guide Page 205

228 Chapter 10 - The piconfig Utility *@exit - uncomment this to exit and review before tag, Then invoke piconfig as follows: * (Ls - PIARC) piconfig input delevents.dif,mytag,t-7d,t Note, in order for the input file and it s parameters to be taken as one parameter, it s important to have no spaces between parameters, as show in the example. Also, note that this script will delete up to events, but it can be changed in the script. Changing Events when there are Multiple Events at the Same Time The following commands show how to modify a specific value out of several at the same time using replacesp mode. Note the use of NewValue attribute. The replace mode would cause the last value at the time to be replaced. * (Ed - PIARC) piarc.dif * (Ls - PIARC) PIconfig> rpflt1,*,y,100 *> rpflt1,*,y, ,GOOD,24-Jun-03 17:43: ,GOOD,24-Jun-03 01:00: ,GOOD,24-Jun-03 01:00:00 11.,GOOD,24-Jun-03 01:00:00 1.,GOOD,24-Jun-03 01:00:00 * End Repeat... * (Ls - PIARC) edit,t * (Ed - PIARC) tag,value,newvalue,time,mode * (Ed - PIARC) PIconfig> rpflt1,11,0.11,t+1h,replacesp *> rpflt1,11,0.11,t+1h, replacesp * (Ed - PIARC) piarc.dif * (Ls - PIARC) PIconfig> rpflt1,*,y,100 *> rpflt1,*,y, ,GOOD,24-Jun-03 17:43: ,GOOD,24-Jun-03 01:00: ,GOOD,24-Jun-03 01:00: ,GOOD,24-Jun-03 01:00:00 1.,GOOD,24-Jun-03 01:00:00 * End Repeat... Using the TimeFormat Command The TimeFormat command can be used to adjust the number of sub-second digits displayed in timestamps, and whether or not time zone information is displayed. The default number of sub-second digits to display is 5. No time zone information is normally displayed. This command affects the display of timestamps from the Snapshot and Archive only. Page 206

229 Piconfig Commands and Tables To set the number of sub-second digits to 4 and turn on time zone information display, you would enter the 4,t The time zone information displayed with every Snapshot and archive timestamp is the short label of time zone and current standard/daylight status. For example, in Pacific Standard Time, this label would be PST. You can check the labels for your time zone with the pidiag - tz command. If you issue the timeformat command with the number of sub-second digits only, time zone information display will be turned off. Using Sub-second Timestamps You can put events with sub-second timestamps in the Snapshot and Data Archive using the piconfig utility. The Time attribute has the format DD-MMM-YY hh:mm:ss.sssss The Timenum attribute is the equivalent floating point representation of the time in number of seconds past January 1, :00: The archive preserves the timestamp with accuracy of microseconds. Note: The default time accuracy of 5 digits might compromise a sub-second timestamp. Expand to 6 or 7 digits before editing or deleting such events. Using Annotations Since release 3.3, piconfig supports annotation to archive values, in both pisnap and piarc tables. We recommend using piconfig only for reading annotations. Annotations should be added using PI-SDK applications that are designed for that purpose PI Batch Unit Table The Batch Subsystem monitors batches that run on units in a manufacturing plant. This table contains configuration of the units. See Batch Subsystem in the PI Server Applications Guide for details on how to manage data in this table. The table name is Pibaunit. The primary key is Unitname. The following attributes are defined: Table PI Batch Unit Table Attributes Attribute UNITNAME NEWUnitName ActiveTag Definition Defines the UNIT name. UNITNAME is the primary index of the Pibaunit Table. Cannot include the \ character. Used to rename an existing unit. PI Tag which indicates batch activity on Unit. PI Server System Management Guide Page 207

230 Chapter 10 - The piconfig Utility Attribute ActiveType BIDEXPR DataAccess DataGroup DataOwner Description EvalDelay MergeConsecutive PRODEXPR UnitAccess UnitGroup UnitOwner Definition Interpretation of ActiveTag values. Pulse, the default, starts on batch on transition from 0 to 1 or greater. Step, starts a new batch on any value change. Defines an expression consisting of PI Tags and text to generate a BATCHID when a batch begins on a unit. The value of the evaluated expression cannot contain a \ character. Security attribute, which specifies access to batches created on the unit. Group membership of the batches created by the unit. Owner of batches created by the unit. Description of unit. Specifies delay, from batch start, before evaluating product and batch ID expressions. If non-zero, treats short batch stop and restarts as one contiguous batch. Defines an expression consisting of PI Tags and text. This expression is used to generate a PRODUCT name when the batch begins on a unit. The value of the evaluated expression cannot contain a \ character. Security attribute, which specifies access to the unit. Unit group membership. Unit owner PI Batch Alias Table Aliases are defined and maintained by the PI Batch Subsystem. An alias is used to define a PI tag that corresponds to an attribute (generally, the name of some measured quantity) of a process unit. The table is simple it consists of two columns an alias name and a PI tag name. The alias name has two components: a unit name and an attribute name. Alias syntax is: \\unit name\common name For example: \\Reactor1\temperature The unit name must be a defined PI Batch unit, that is, an entry for it must exist in the PIbaunit Table. The PI tag name must also be valid. See Batch Subsystem in the PI Server Applications Guide for details on how to manage data in this table. The table name is Pibaalias. The primary key is Alias. Page 208

231 Piconfig Commands and Tables Table PI Batch Alias Table Attributes Attribute Alias Tag NEWAlias Description Unit name and attribute. The syntax for alias names in this table is: \\unitname\attribute. PI tag corresponding to the attribute. Used to rename an existing alias PI Batch Table The Batch Subsystem records information about each batch in this table, whether the batches are in progress or terminated. See PI Server Applications Guide, Chapter 5, Batch Subsystem, for details on how to access data in this table. The table name is Pibatch. The primary key is Handle. It is rarely used in batch searches. The following attributes are defined: Table PI Batch Table Attributes Attribute UnitName Handle BID ProdID StartTime StartStatus StopTime StopStatus BIDsearch ProdIDsearch SearchStart SearchStop Count NEWUnitName Description Unit name to search Unique identifier for a single batch entry Batch ID Product ID Batch start time Status of batch start time Batch end time Status of batch end time Wild card search string for batch IDs Wild card search string for product IDs Time to search from Time to search to Maximum number of batches to retrieve Changing the unit on which a batch is run by altering attribute is not supported. Note: The PI Batch Subsystem refers to the older PI Server Batch support. The PI Module and PI Batch Database approach is replacing the PI Batch Subsystem. The PI SDK contains the best documentation of the Module and Batch Databases. PI Server System Management Guide Page 209

232 Chapter 10 - The piconfig Utility PI Subsystem Table The PI Subsystem Table shows subsystem-specific attributes and statistics. This read-only table is useful for troubleshooting. To load this table, the subsystem in question must be specified. The table name is Pisubsys. For example, to view attributes associated with pisnapss, enter the following command: pisubsys,pisnapss Note: This table has no real primary key since there is only one record. The set of attributes available on this table varies with the platform type. The table attributes are: Table Subsystem Table Attributes Attribute Description Operating System PISubsysName Subsystem Name All IDNumber Unique ID of Computer UNIX (Not all versions of UNIX support this attribute) Machine Hardware ID UNIX OSNodeName TCP/IP host name UNIX OSRelease Operating system release UNIX OSBuild Operating system build Windows OSSysName Operating system name All OSVersion Operating system version All PIStartupTime Subsystem startup time All PIVersion Subsystem version All Viewing PI Subsystem Information Here s an example listing attributes of the Subsystem Table. To list the record, use the ostructure command and specify pisubsysname as * (Ls - PISUBSYS) pisubsysname (Ls - PISUBSYS) osbuild, osversion (Ls - PISUBSYS) pistartuptime, piversion (Ls - PISUBSYS) pisubsysname=* (Ls - PISUBSYS) pisnapss Service Pack 6, May-03 17:08:20,PI The operating system attribute names may vary because they are operating system dependent. Page 210

233 Piconfig Commands and Tables PI Subsystem Statistics Table The PI Subsystem Statistics Table shows detailed subsystem statistics. This read-only table also requires subsystem specification. The table name is Pisubsysstats. For example, to view statistics for pisnapss enter the following command: pisubsysstats,pisnapss The table attributes are: Table PI Subsystem Statistics Table Attributes Attribute PISubsysName BytesRecv BytesSent MsgRecv MsgSent RecvErrors SendErrors StartTime Description Subsystem Name Number of bytes received since startup. Number of bytes sent since startup. Number of messages received since startup. Number of messages sent since startup. Number of receive errors since startup. Number of send errors since startup. Subsystem startup time. The bytes and messages received and sent refer to all inter-process communications. Viewing PI Subsystem Statistics The following example lists the statistics for pisnapss. There is no primary key so simply specify pisubsysname name as * (Ls - PISUBSYSSTATS) PIsubsysname (Ls - PISUBSYSSTATS) bytesrecv, bytessent (Ls - PISUBSYSSTATS) msgrecv, msgsent (Ls - PISUBSYSSTATS) recverrors, senderrors (Ls - PISUBSYSSTATS) starttime (Ls - PISUBSYSSTATS) pisubsysname=* (Ls - PISUBSYSSTATS) pisnapss 99626, ,432 0,0 4-Sep-02 17:08:19 Some SUBSYSSTATS tables also contain subsystem specific data. This data is usually presented for troubleshooting purposes. After setting a SUBSYSSTATS table always show the available attributes with command. PI Server System Management Guide Page 211

234 Chapter 10 - The piconfig Utility PINet Manager Statistics Table The PINet Manager Statistics Table displays information on active connections as well as some information specific to pinetmgr. This table is read-only. The attributes of this table are: Table PINet Manager Statistics Table Attributes Attribute ID BytesRecv BytesSent ConStatus ConTime ConType MsgSent Name NetType OSBuild OSSysName OSVersion PeerAddress PeerName PIVersion PIPath ProtocolVersion RecvErrors SendErrors Description Connection ID. This is the primary key. Bytes received by the connection. Bytes sent by the connection. Connection status. Time connection was established. Connection type PI API connection PI API or VMS PINet node Local connection PI SDK or PI Subsystem directly connected to pinetmgr Remote Router Connection from PINS to PI server Remote Resolver Connection to a PINS (other end of the above connection) Messages sent by connection. Connection name. Connection network type WIN32 named pipes, UNIX, or TCP/IP Operating system build. Operating system name. Operating system version. IP Address of connecting machine. Host name of connecting machine. Version of PI Network Manager. PI Server root directory on the server. This item is the same for all connections. PI Protocol version of connecting application. Number of receive errors on the connection. Number of send errors on the connection. The table name is Pinetmgrstats. The Connection ID is assigned based on order of connection. Since connection names are not required to be unique, the ID is the primary key. Page 212

235 Piconfig Commands and Tables Viewing PI Connection Information Specifying the ID as pinetmgr accesses statistics associated with pinetmgr. Specifying ID as * will list all connection statistics and pinetmgr statistics. ID, Name, and ProtocolVersion are the only attributes that apply to pinetmgr. ConTime refers to startup time of pinetmgr. The following example lists all attributes of all current connections: * (Ls - PINETMGRSTATS) ID, BytesRecv, BytesSent, ConStatus * (Ls - PINETMGRSTATS) contime, contype, msgsent, name * (Ls - PINETMGRSTATS) nettype, peeraddress, peername * (Ls - PINETMGRSTATS) protocolversion,recverrors,senderrors * (Ls - PINETMGRSTATS) id=* * (Ls - PINETMGRSTATS) 6,24,132447,[0] Success 4-Sep-02 17:08:05,Local connection,759,pimsgss WIN32 Named pipe,, 3.1,0,0 * ,24, ,[0] Success 4-Sep-02 17:08:12,Local connection, ,piupdmgr WIN32 Named pipe,, 3.1,0,0 * ,24, ,[0] Success 4-Sep-02 17:08:19,Local connection,64851,pisnapss WIN32 Named pipe,, 3.1,0,0 * ,24, ,[0] Success 4-Sep-02 17:08:27,Local connection,24266,piarchss WIN32 Named pipe,, 3.1,0,0 * ,24,102724,[0] Success 4-Sep-02 17:08:34,Local connection,1072,pibasess WIN32 Named pipe,, 3.1,0,0 * ,24,372707,[0] Success 4-Sep-02 17:09:13,Local connection,2059,pipeschd WIN32 Named pipe,, 3.1,0,0 * ,24,60055,[0] Success 4-Sep-02 17:08:49,Local connection,672,pisqlss WIN32 Named pipe,, 3.1,0,0 * ,24, ,[0] Success PI Server System Management Guide Page 213

236 Chapter 10 - The piconfig Utility 4-Sep-02 17:08:57,Local connection,198466,pitotal WIN32 Named pipe,, 3.1,0,0 * ,24,154881,[0] Success 4-Sep-02 17:09:04,Local connection,2828,pibatch WIN32 Named pipe,, 3.1,0,0 * ,20, ,[0] Success 4-Sep-02 17:09:12,Local connection, ,pipee WIN32 Named pipe, ,localhost 1.8,0,0 * ,20,33340,[0] Success 4-Sep-02 17:43:44,Local connection,2715,rmpse WIN32 Named pipe, ,localhost 1.8,0,0 * ,20,50446,[0] Success 4-Sep-02 17:43:45,Local connection,3349,rande WIN32 Named pipe, ,localhost 1.8,0,0 * ,24,38287,[0] Success 5-Sep-02 15:01:35,Local connection,6,piconfig WIN32 Named pipe,, 3.1,0,0 * PINetMgr,,,,,,PINetMgr,, 3.1,, * PI Users Table This table defines PI users and records their assignment to groups. For details, see PI System Management and PI Server Databases in the PI Server Reference Guide The table name is Piuser. The primary key is User. The table attributes are: Table PI Users Table Attributes Attribute User Description Groups Context Description User name User description List of groups to which the user belongs Reserved for future use Page 214

237 Piconfig Commands and Tables Attribute NEWUser Description Used to rename an existing user The description attribute is used to specify any type of user information, such as address or title. The user may be added to multiple groups. Note: Users are assigned to groups using the Piuser table. Attempting to change the group membership of users via the pigroup table has no affect PI Group Table This table defines groups to which PI users may be assigned. It is discussed in PI Server Reference Guide Chapter 3, PI Server Databases. The table name is Pigroup. The primary key is GROUP. The table attributes are as follows. Table PI Group Table Attributes Attribute Group Description Users NEWGroup Description Group name User description List of users belonging to the group Used to rename an existing group PI Thread Table Table PI Thread Table Attributes Attribute ID Action ActValue Calls Handle PoolName Priority State Description Operating system thread ID Edit only see table below Edit only value for the action performed Number of calls served by the thread Subsystem handle Every thread belongs to a thread-pool. We are mainly interested in the RPC thread pool, which serves client calls to a subsystem. The thread priority The thread state generally Wait or InUse PI Server System Management Guide Page 215

238 Chapter 10 - The piconfig Utility Table PI Thread Table Actions Action Description Action Value Priority Change thread priority 1 to increase -1 to decrease Suspend Resume Terminate Temporary suspensions of thread execution Resume a thread previously suspended End this thread * (Ls - ) pithread,piarchss * (Ls - PITHREAD) id,calls,handle,poolname,priority,state * (Ls - PITHREAD) 1500,7,212,RPC,0,Wait 1596,9,216,RPC,0,Wait 1504,11,220,RPC,0,Wait 1116,18,224,RPC,0,InUse 2124,9,228,RPC,0,Wait 3664,8,232,RPC,0,Wait 2592,9,236,RPC,0,Wait 3812,7,240,RPC,0,Wait 1216,0,816,EVQ,0,Wait 2488,0,820,EVQ,0,Wait 2736,0,824,EVQ,0,Wait 3140,0,828,EVQ,0,Wait 3012,0,832,EVQ,0,Wait 2356,0,840,Shift,0,Wait 3336,655015,0,Main,, 3888,166401,248,Message,, 3016,190,260,Read,, Note: The PIThread table is primarily a monitoring tool. We recommend using it only with in-depth understanding of threads. Specifically, avoid using it for any modification or thread creation PI Database Security Table Database level security controls the access rights of users and groups to the various system databases; for example, create a point. Earlier releases required user piadmin to edit a database. Database security is accessed through the Dbsecurity Table. This is a general database security table its structure applies to all databases. The record structure looks like this: Table PI Database Security Table Attributes Attribute DBName Description Database name Page 216

239 Piconfig Commands and Tables Attribute Access Group Owner Description Security attribute, which specifies access to the table Group name PI user name declared to be the owner of the table. Defaults to Piadmin. The following examples shows how to access and modify the DBsecurity table. C:\pi\adm>PIconfig table dbsecurity * (Ls - DBSECURITY) dbname, owner,group,access * (Ls - DBSECURITY) *PIconfig Err> Wild-card specs. missing, default to '*'. PIARCADMIN,PIadmin,PIadmin,o:rw g:r w:r PIARCDATA,PIadmin,PIadmin,o:rw g:r w:r PIBatch,PIadmin,PIadmin,o:rw g:r w:r PICampaign,PIadmin,PIadmin,o:rw g:r w:r PIDBSEC,PIadmin,PIadmin,o:rw g:r w:r PIDS,PIadmin,PIadmin,o:rw g:r w:r PIHeadingSets,PIadmin,PIadmin,o:rw g:r w:r PIModules,PIadmin,PIadmin,o:rw g:r w:r PIPOINT,PIadmin,PIadmin,o:rw g:r w:r pisnapss,piadmin,piadmin,o:rw g:r w:r PITransferRecords,PIadmin,PIadmin,o:rw g:r w:r PIUSER,PIadmin,PIadmin,o:rw g:r w:r * (Ls - DBSECURITY) ed,t * (Ed - DBSECURITY) dbname, owner,group,access Modify the access to archive data and allow the operator group * (Ed - DBSECURITY) PIconfig> PIARCDATA,PIadmin,operators,o:rw g:rw w: *> PIARCDATA,PIadmin,operators,o:rw g:rw w: Modify the access to base subsystem auditing and thread table * (Ed - DBSECURITY) PIconfig> pibasess,piadmin,operators,o:rw g:rw w:r *> pibasess,piadmin,operators,o:rw g:rw w:r Modify the access to Update Manager thread table (no auditing in Update Manager) * (Ed - DBSECURITY) PIconfig> piupdmgr,piadmin,operators,o:rw g:rw w:r *> piupdmgr,piadmin,operators,o:rw g:rw w:r * (Ed - DBSECURITY) list * (Ls - DBSECURITY) *PIconfig Err> Wild-card specs. missing, default to '*'. PIARCADMIN,PIadmin,PIadmin,o:rw g:r w:r PIARCDATA,PIadmin,operators,o:rw g:rw w: pibasess,piadmin,operators,o:rw g:rw w:r PIBatch,PIadmin,PIadmin,o:rw g:r w:r PICampaign,PIadmin,PIadmin,o:rw g:r w:r PIDBSEC,PIadmin,PIadmin,o:rw g:r w:r PIDS,PIadmin,PIadmin,o:rw g:r w:r PIHeadingSets,PIadmin,PIadmin,o:rw g:r w:r PIModules,PIadmin,PIadmin,o:rw g:r w:r PI Server System Management Guide Page 217

240 Chapter 10 - The piconfig Utility PIPOINT,PIadmin,PIadmin,o:rw g:r w:r pisnapss,piadmin,piadmin,o:rw g:r w:r PITransferRecords,PIadmin,PIadmin,o:rw g:r w:r piupdmgr,piadmin,operators,o:rw g:rw w:r PIUSER,PIadmin,PIadmin,o:rw g:r w:r * (Ls - DBSECURITY) PIconfig> Refer to the chapter Managing Security for a detailed discussion of database security and this table PI Trust Database This table is used to allow a client application to connect to the PI Server as a specific PI user without requiring that the client application explicitly log in. This is required for unattended client applications such as interfaces. The client and PI Server obtain the client s credentials from the operating system, domain controller, and network software. These include any of the following: domain name, IP host name, IP address, and username. Select this table using the PITRUST The primary key is TRUST. The table attributes are: Table Trust Table Attributes Attribute Trust Domain IPAddr Description A name for this trust relationship The domain name for the client machine IP address of client machine NetMask Network address mask in the format ( ) IPHost OSUser AppName PIUser Name of client machine User name under which the client is running Application name Associated PI user Any field specified as NULL string ( ), is ignored when incoming connection are matched against the table. Domain, IPHost, AppName, and OSUser must be specified exactly or not at all. IPAddr and NetMask must be specified together. If you provide a value for one, you must also provide the other. PIUser must always be specified as either a currently existing PI user in the User Database or as a dollar sign ($). The dollar sign must be paired with a $ in either OSUser or IPHost. If the trust matches incoming credentials and there is no PIUser Page 218

241 Piconfig Commands and Tables with the same name, an error occurs at run-time. This method of specification matches any user or any machine that passes the domain controller validation of their login credentials PI General Table Interface piconfig has a General Table interface, which includes the Timeout, Firewall, and Trust databases. Select the table using the PI_GEN,tablename Note: Piconfig cannot access remotely the General Tables, only on the local machine. However, the SMT tools have remote access. PI Timeout Database This table contains the PI Server timing parameters as well as many other configurable parameters. Adjustment of these parameters should be done by the PI Server Administrator. Select this table using the PI_GEN, pitimeout The primary key is NAME. The table attributes are: Table PI Timeout Table Attributes Attribute Name Value NEWName Description Timing attribute name Timing value as a string Used to rename an existing name The PI Timeout database cannot be modified remotely. PI Firewall Database This table is used by the System Manager to control general access to the PI Server by network address. Select this table using the PI_GEN, pifirewall The primary key is HOSTMASK. The table attributes are: Table PI Firewall Table Attributes Attribute HostMask Value Description The name or IP address of a client computer ALLOW or DISALLOW PI Server System Management Guide Page 219

242 Chapter 10 - The piconfig Utility Attribute NEWHostMask Description Used to rename an existing HostMask The PI Firewall Database cannot be modified remotely. PI Proxy Database As of release 3.3, the Proxy Database is no longer in use. During upgrade, its contents are converted to PI Trust Database records Helpful Hints Abbreviations All piconfig commands can be abbreviated to four characters Case-sensitivity In UNIX systems, program and file names are case-sensitive. This includes HP-UX, Digital UNIX, Solaris, and AIX. Windows program and file names are case preserving, but not case-sensitive. The piconfig commands, attribute names and table names are not case-sensitive, but the data are case-sensitive. The case-sensitivity on PIGEN tables may be changed for both of these parameters by using the case command Command Input Files The piconfig commands and data can be placed in any number of files and executed using the input command. If the input file contains many lines, all of which have the same command, the following construct may In this construct, the command specified will be prepended to every line in the command file. This is useful, for example, when a file with input structure lines have been generated from another program, such as PIDIFF, or when the same complex structure is used for both input and output Input Line Length By default, piconfig reads from its input up to 1024 characters. This is sufficient in almost all cases. If the input contains lines longer than 1024, reset the input buffer using the line command, for 4000 Page 220

243 Helpful Hints Using Quoted Strings There are two main reasons to use quotes (single or double) with piconfig data: The data contains an embedded delimiter character that will confuse correct parsing either on input or on output that will be used in the future by piconfig itself or by other applications (Microsoft Excel, for example). The specific table requires certain data to be enclosed in quotes (single or double) for its own further processing. Examples include the pibatch tables and the Performance Equations expressions configured in the extended-descriptor of a point. Piconfig attempts to parse incoming data into fields using the delimited character. If a field starts with a quote (either single or double) piconfig ignores any delimiter until a matching quote is found. When an already quoted string must contain embedded quotes, there are two options: Enclose strings containing double quotes in single quotes and vice versa Escape the embedded quotes with a backslash ( \ ) Note: A field containing the delimiter character must be quoted. A field that starts with a quote should be quoted using the other type of quote. A field that starts with one type of quote and contains the other type as well should be quoted, and the embedded quotes must be escaped.? For example, a field containing: unit,function should be specified as "unit,function" Or 'unit,function' The expression 'sinusoid' > 'tag33' should be specified as "'sinusoid' > 'tag33'" Or ('sinusoid' > 'tag33') The expression 'sinusoid' + "t-1d" + "ABC" Should be specified as "'sinusoid' + \"t-1d\" + \"ABC\"" PI Server System Management Guide Page 221

244 Chapter 10 - The piconfig Utility When the output from piconfig is used in another session or by another program such as Excel, make sure that fields containing the delimiter character are quoted (on output). Using the quote command does this: ' Sending Values as Strings Piconfig sends all table values as strings. When sent to the Snapshot (Archive values go via the Snapshot), it is interpreted in the following way: For a string tag: Use the incoming string without change. For a digital tag: Look for a state in the tag s state-set. Look for a state in the System digital-set. Interpret the string as a numeric offset and check if within range of the tag s set. For all other tag types: Look for a state in the System digital-set. Convert the string to a value of the tag s type Boolean Values When a field in any table is a Boolean flag, for example the Step flag in the pipoint table, the input data can be specified as: 1 / 0 Yes / No True / False Piconfig always sends the data to the table as a string as explained above. The table owner, in this example the Base Subsystem, will interpret the incoming string as a Boolean value 1 / 0. This can cause some confusion in the digital-states table when states are defines as the strings 1, 2, 3, We recommend that you configure digital states like this: One, Two, or State1, State2, Similarly, if you want to define the states true, false, make a set with false in the 1st position followed by true to correspond to 0 and 1. Alternatively, modify these names: Strue S-false. Page 222

245 Helpful Hints Configuration Persistence Table specifications remain in effect until the next table command. Mode specifications remain in effect until the next mode command. For all structure formats, the structure specifications remain in effect until a table is changed. New structure specifications are added to previous specifications until they are used to process data. After this, new specifications overwrite previous ones. Select, and modify specifications behave similarly. These two commands are also cleared on mode and table changes Command Line Parameters The piconfig commands may be specified as command line parameters when invoking piconfig. Each pair of parameters is assumed to be a command. These commands will be executed before the first prompt is issued. Some examples are: $ piconfig comchar? $ piconfig table pipoint stype fixed $ piconfig help Changing Special Characters The special characters in piconfig can be customized to be any single, visible character that is not a number or a letter. These special characters include: command character (ComChar) comment character (comment) delimiter character (delimiter) quote character (quote) Specifying a quote character causes any field containing the delimiter character (comma by default), to be enclosed with the specified quote character. Use this option any time the output is being re-used for input, for example when the extended descriptor contains commas and you want to create a comma-separated file. In this example, the comment character is changed: $ piconfig *piconfig> * This is a comment. *piconfig> * Change the comment character to! *piconfig>! Now we have a new comment character. *piconfig>!change back to the original comment character. * *piconfig> * Now we have our original comment character. Similarly, you can change the delimiter used in delimited format to be a different character than comma (,). To display the currently assigned characters, mode, and table, use the status command piconfig Status ---- PI Server System Management Guide Page 223

246 Chapter 10 - The piconfig Utility Mode: List Characters: Command: <@> Delimiter: <,> Comment:<*> Quot:<> Struc. Type IN: <Delim.> OUT: <Delim.> Error count: 3 Max: 10 Curent table: <PIPOINT> Cur. Prim.: <> Def. Prim: < > Nesting level : 0 Node: < ,piadmin> Convert Mode Example The following is a simple example of converting fixed format data into delimited format. This can be helpful in PI2 to PI3 conversions. Convert mode can be used to reorder fields in a record or to apply modifications to data. e:\pi\adm>type fixed.dat * Tag tag e:\pi\adm>piconfig mode convert * (Cv - ) fixed * (Cv - ) delim * (Cv - ) tag,1,1,10 * (Cv - ) zero,1,10,5 * (Cv - ) span,1,20,5 * (Cv - ) zero,span,tag * (Cv - ) none * (Cv - ) fixed.dat 0, 200,Tag1-5, 655,tag Converting Point Database Information from PI2 to PI Server To transfer information from a PI OpenVMS Point Database to a PI Server Point Database, see the OSIsoft support Web site for more information Hexadecimal and Octal Numbers By default, piconfig uses decimal notation (base 10). To specify numbers in octal, precede them with 0. To specify numbers in hexadecimal, precede them with 0x. For example, the numbers 10, 012, and 0xA specify the same number. A few PI 2.x pidiff attributes are not used in piconfig. See the OSIsoft support Web site for more information. Page 224

247 Chapter 11. PI TROUBLESHOOTING AND REPAIR Data passes through many steps on the way into and out of the Archive. The main strategy to apply when troubleshooting is to determine which parts of the data path are malfunctioning, and also, which parts are functioning correctly. The first step is to isolate the problem to a single computer, either client or server, or to the network. Follow the steps in the Troubleshooting Checklist to isolate the problem area. A table of error messages is available in Appendix A: PI Messages on page 281. The second step is to isolate the problem further to a particular client program or PI subsystem. See Verifying PI Processes on page 228, and PI System Data Files on page 235, for help with this. The third step is to determine the exact cause of the problem. This will lead to a good understanding of what is needed to fix the problem, repair the damage, and prevent a recurrence. If needed, go to the Repairs section to repair data files such as Archives or Point Database. After working through the Troubleshooting Checklist, you may still not have resolved your problem. In this case, you will want to call OSIsoft Technical Support for some help. The technical support engineer will ask for some key information and also may ask to dial into your system in order to do some hands on troubleshooting Troubleshooting Checklist Determine which computers exhibit the problem: 1. Determine which computers exhibit the problem: Client computer(s) Server computer(s) Interface computer(s) The best test is to run the questionable system against a known good system. If all computers exhibit the problem, it is more likely a network problem. If all clients exhibit the problem, it indicates a server problem. 2. Is PI the only program having trouble? If other programs on the same computer are giving trouble, this indicates a hardware or networking problem. Telnet is a good program to try to run. If Telnet works correctly, the network is not likely to be the problem. PI Server System Management Guide Page 225

248 Chapter 11 - PI Troubleshooting and Repair 3. If there is a client problem, check security. Log in as the user piadmin. Check the setup.log and pipc.log files in the c:\pipc\dat directory. Also check the server central log file using the pigetmsg utility. A table of error messages is available in Appendix A: PI Messages on page 281. If a trend in PI ProcessBook flatlines, see the section on p If there is a server problem, verify that all PI processes are running. On Windows, type net start at the command prompt to list all processes running as Services. On UNIX, use the piverify.sh utility. PI Systems may take several minutes to start; loading the Point Database, Snapshot and Archives takes most of the time. Utilities, such as piartool and piconfig, are not fully operational until startup has completed. 5. Even if the process is listed as running, it may be in a state where it is not communicating with pinetmgr. Verify that each PI process is communicating properly by using the utilities listed in the Verifying PI Processes section below. 6. Try to get the exact error message. Error numbers may be translated to text using: pidiag -e <errno> There is a list of error messages in Appendix A: PI Messages on page Note the time of the problem and which subsystems have stopped running. Inspect the message log using the pigetmsg utility, and the individual process log files. See Appendix A: PI Messages on page On Windows, try running with pistart.bat, rather than as Services. There may be additional status messages displayed in the command windows that may be helpful. 9. On HP-UX, verify SHLIB_PATH environment variable is defined correctly. It should point to the directory /opt/pi/lib. 10. On Solaris, verify LD_LIBRARY_PATH environment variable is defined correctly. It should point to the directory /opt/pi/lib. 11. If a subsystem crashes, there may be additional information that would be useful to our developers. Dr. Watson is the default just-in-time debugger for Windows systems. To install Dr. Watson as default debugger, run the following command: drwtsn32.exe -i Dr. Watson process traps unhandled process exceptions, also known as process crashes. Dr. Watson captures the process state on crash and writes details to drwtsn32.log. Optionally the entire process image is written to user.dmp. The location of these files, as well as other Dr. Watson behavior, is configurable. Running drwtsn32.exe interactively starts the configuration dialog. Recommended settings are as follows: Log File Path: Default location is recommended. Page 226

249 Troubleshooting Checklist Crash Dump: Default name is recommended. Note this file may be over written; after a process crash copy this file to a safe location. Number of Instructions: 25 Number of errors to save: 25 Crash Dump Type: Full Dump Symbol Table: Select Dump All Thread Contexts: Select Append to Existing Log File: Select Visual Notification: Do not select. Servers typically run unattended; therefore, there is no user to see the notification. Sound Notification: Do not select. Create Crash Dump File: Select On UNIX systems, look for a file called core in the PI\bin or PI\adm directories. This is a binary file. These files are useful only if they were created while running a debug version of PI. Debug versions are not shipped by default. OSIsoft Technical Support will arrange for a download of a debug build of PI if necessary. 12. If you have a pinetmgr problem, use: netstat -a to determine if there is any other process talking on port If so, this indicates that at one time pinetmgr was communicating successfully. You may need to use piconfig to adjust the timing parameters in the PITimeout Table. Refer to the section called Tuning the PI System later in this chapter. 13. If you have an Archive or Snapshot problem, use the piartool -as and piartool -ss utilities to gather more information about the data flow. 14. Next, try retrieving a Snapshot three different ways; the combined results of all three tests helps pinpoint the source of the problem: apisnap from a remote node (uses API + network) apisnap from the home node (uses API) piconfig < pisnap.dif from the home node (uses internal communication) To determine if the Archive has been corrupted, use piartool -aw. 15. If this is an Update Manager problem, use the pilistupd utility to see which processes are signed up for events. 16. Determine if the problem is with all points on all interfaces or just a few points on some interfaces. 17. Each PI System is distributed with a standard set of points including SINUSOID, CDEP158, and CDM158. Each PI System is distributed with the Random and RampSoak Simulators. 18. If this is an interface problem on a remote node, check security. There must be an entry in the PI Trust Table for that node or specifically for that interface. Also check PI Server System Management Guide Page 227

250 Chapter 11 - PI Troubleshooting and Repair the Firewall database. Check the individual interface log files as well as the central log file using the pigetmsg utility. See Appendix A: PI Messages on page 281. If an API interface is not able to connect, be sure that the PI Base Subsystem, PI Archive Subsystem, and PI Snapshot Subsystem are running. 19. If an installation or upgrade problem, check the log file: UNIX - /tmp/piinstall.log Windows PIPC\dat\SetupPIServer.log and PIPC\dat\PIServerMaster.log. See the Getting Started manual for more information. 20. Check ownership and execute permissions on files that are giving trouble. Try running as Root (UNIX) or Administrator (Windows). If the trouble goes away when you run as the System Administrator, then you have a permission problem. 21. Read the PI release notes to determine if this is a known problem. Another source of information is the OSIsoft Technical Support Web site, http//techsupport.osisoft.com, which has technical notes posted. If you haven t solved the problem after working through this checklist, you will need to phone or OSIsoft Technical Support Verifying PI Processes When PI is running, all of the PI processes should be running. When PI is stopped, all of the PI processes should be stopped. The exception is pishutev, which only runs briefly at PI startup. Even if a process is listed as running, it may be in a state where it is not communicating with pinetmgr. You can verify that each PI process is communicating properly by using the utilities outlined in this subsection Verifying PI Processes on Windows Systems On Windows systems, you can list all processes that are started as Services by typing at the command prompt: net start PI processes or interfaces that are running interactively will each have a separate command window that is labeled with the process name Verifying PI Processes on UNIX Systems On UNIX systems, there is a utility called piverify.sh, which reports on the running status of all of the PI processes, including the interfaces that are shipped with PI. Change to the adm subdirectory and type: piverify.sh Page 228

251 Verifying PI Processes Communication with PINet Manager The PInet Manager process is the communication router for PI. All client processes communicate with PI Subsystems via pinetmgr. All of the PI processes in PI Server communicate with each other via pinetmgr. None of the PI utilities will work if pinetmgr is not running properly. The TCP/IP port for communicating with PI defaults to This is a change from PI OpenVMS systems, which default to port 545. The change is important because it allows PI to run without superuser privileges and thus provides a foundation for a more secure system. You should not need to change the TCP/IP default port. The only reason for doing so would be to resolve a port number conflict with other software. Contact OSIsoft Technical Support if you are affected by this problem Pimsgss All PI processes send messages to the PI Message Subsystem process, which writes messages to the PI Message Log. A simple way to test pimsgss is to run the pigetmsg utility. If pimsgss is not working correctly, you will see the following: D:\PI\adm>pigetmsg Message ID [A], (0-n) (A)ll (T)ail (F)lush (Q)uit (?): Message Source [*], (?): Start time in PI format [*-15m], s(k)ip (?): End time in PI format [*], s(k)ip (?): Maximum count [], (0-n) (?): Text mask [*], (?): Display count [], (0-n) (?): [-10733] PINET: RPC Resolver is Off-Line. At PI System startup, there is a short time when pimsgss is not yet running. During this time, and at any other time when pimsgss is not functioning, PI Systems running on Windows will direct messages to the system event log. You can read this messages using the Event Viewer application in the Administrative Tools group. When the pimsgss starts, it will merge messages from the Windows Event Log into the PI Server Message Log. The behavior on UNIX differs from the above. PI Systems running on UNIX will send messages to the individual subsystem ASCII message logs in the PI/log directory when the pimsgss is not available. These are: Pinetmgr.log Pibasess.log Piarchss.log Pibackup.log Pisnapss.log Piupdmgr.log Random.log PI Server System Management Guide Page 229

252 Chapter 11 - PI Troubleshooting and Repair Rmp_Sk.log Pipeschd.log Pibatch.log Pishutev.log PIsqlss.log Pitotal.log Pialarm.log PI Update Manager The Update Manager process provides event notification services. For example, ProcessBook trends subscribe to Snapshot event updates to keep trends current; interfaces subscribe to point database changes such as addition of new points. A simple way to test piupdmgr is to run the pilistupd utility. If piupdmgr is not working correctly, you will see the following: C:\PI\adm>pilistupd pilistupd -h for help [-10727] PINET: RPC is Non-Existent Producer Consumer Qual. Flags Pending status: [-12150] not registered in updmgr PI Base Subsystem The PI Base Subsystem process manages the Point and User Databases. It performs all security authorization. A simple way to test pibasess is to run the pisnap and piconfig utilities. If pibasess is not working correctly, you will see the following: $ pisnap.sh PI API version Attempting connection to localhost:5450 Error -994, connecting to localhost:5450 $ piconfig * (Ls - ) pipoint *PIConfig Err> Table initialization error (PIPOINT *@table pipoint *[-10733] PINET: RPC Resolver is Off-Line Snapshot Subsystem The Snapshot Subsystem manages the Snapshot and the Event Queue. It handles compression and sends events to the Archive. A simple way to test pisnapss is to run the piartool -ss and pisnap utilities. If pisnapss is not working correctly, you will see the following: Page 230

253 Verifying PI Processes $ piartool -ss Getsnaptablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line $ pisnap.sh PI API version Attempting connection to localhost:5450 Enter tagname: sinusoid Error: pisn_getsnapshotsx Error: piar_getarcvaluex Error: piar_getarcvaluesx 100 Tag = SINUSOID Point Number = 1 Type = Real Hour Sine Wave! Snapshot value Value = ERROR ERROR Status = ERROR Latest archive value Value = ERROR ERROR Status = ERROR Archive Subsystem The Archive Subsystem, piarchss, manages the archives. It stores new events received from the Snapshot Subsystem and responds to requests for Archive access. These might be requests for compressed, interpolated or calculated data. The Archive Subsystem handles archive shifts. A simple way to test piarchss is to run the piartool -al, piartool -as and pisnap utilities. If piarchss is not working correctly, you will see the following: $ piartool -al Getarchivefilelist Failed: [-10733] PINET: RPC Resolver is Off-Line $ piartool -as Getarcmemtablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line $ pisnap.sh PI API version Attempting connection to localhost:5450 Enter tagname: sinusoid Error: piar_getarcvaluex 0 Error: piar_getarcvaluesx 100 Tag = SINUSOID Point Number = 1 Type = Real Hour Sine Wave! Snapshot value Value = ERROR ERROR Status = ERROR Latest archive value Value = ERROR ERROR Status = ERROR Archive events are queued when piarchss is not operating correctly. The Event Queue count is visible from B and piartool -qs Pishutev This PI Subsystem inserts shutdown events into the PI Archive. Although it runs on PI start, the shutdown events are time stamped with the previous shutdown time. PIShutev exits after PI Server System Management Guide Page 231

254 Chapter 11 - PI Troubleshooting and Repair completion; therefore, this process will not be present on systems that have been running for a while Random Interface The Random simulator provides simulated data for default PI points, such as sinusoid. On Windows systems, Random is installed and started as a service; pisrvsitestart.bat starts the service. On UNIX systems it is started by random.sh, which is called from pisitestart.sh, which in turn is called from pistart.sh. See the OSIsoft Web site for current interface documentation RampSoak Interface The batch ramp-soak simulator, rmp_sk, creates batch-like data. On Windows systems rmp_sk is installed and started as a service; pisrvsitestart.bat starts the service. On UNIX systems, it is started by rmp_sk.sh, which is called from pisitestart.sh, which in turn is called from pistart.sh. See the OSIsoft Web site for current interface documentation Running PI Processes Independently Under normal operation, all of the PI processes are started up together using the pisrvstart script, and are stopped together using the pisrvstop script. It is sometimes useful in troubleshooting to run a subset of the PI processes. On Windows, pisrvstart.bat starts each subsystem interactively in its own command window. There are inter-process dependencies with the PI System. All PI Subsystems rely on pinetmgr. The PI Update Manager provides key services; therefore most subsystems require it to be running. Also, the Archive Subsystem requires the Snapshot Subsystem for normal startup. In general, for troubleshooting, the following subsystems should be started in the order listed: pinetmgr pimsgss piupdmgr pibasess pisnapss piarchss Stopping a Windows Process To stop and start processes on Windows, use the Services dialog in the Control Panel. You can also do this from a command prompt using the net stop command. For example, to stop the PI Message Subsystem, issue the command: net stop pimsgss Stopping a UNIX Process The pistop_ss.sh and pistart_ss.sh are used to stop and start subsystems on UNIX. The following example shows how piarchss is stopped and restarted. Page 232

255 UNIX Process Quotas pistop_ss.sh piarchss pistart_ss.sh piarchss Alternatively, the kill -2 command can be used to stop any PI process. The following example shows how piarchss is stopped and restarted. $ cd /export/pi/adm $ ps -upiadmin PID TTY TIME COMMAND 9313? 0:00 bufserv 834 ttyp4 2:16 random 9335? 0:00 iorates 794 ttyp4 0:22 pibasess 1507 ttys1 0:00 ps 760 ttyp4 10:31 PIsnapss 9330? 0:00 ioshmsrv ttyp4 0:00 ksh 726 ttyp4 0:05 pimsgss 777 ttyp4 4:03 piarchss 9320? 0:01 mqsrv 9325? 0:00 mqmgr 836 ttyp4 0:00 rmp_sk 743 ttyp4 0:09 piupdmgr 709 ttyp4 870:48 pinetmgr 838 ttyp4 0:02 pipeschd 1492 ttys1 0:00 ksh $ kill $../bin/piarchss & [1] 1508 $ 11.3 UNIX Process Quotas Some UNIX systems set process quotas unsuitable for servers. These quotas are used to keep rogue applications, such as student projects, from monopolizing system resources such as memory. In general, for systems dedicated as a server, most limits can be set to maximum. Two key UNIX parameters should be reviewed. Maximum data segment. This is the maximum private virtual memory size of a process. The PI Archive and Base Subsystems are memory-intensive. The value of this parameter should be set to 2 gigabytes, the maximum for 32-bit computers. Max files/descriptors. This number is the maximum number of file handles or descriptors a process may open; including TCP/IP connections. This value should be set well above the maximum number of PI Server connections expected. If your system has a large process count, you may see errors recorded in the PI Message Log that report conditions such as no more processes and no more file handles. This can be caused by a maximum process count limit that is too low. The quota may seem sufficient, but UNIX often uses spawned processes for operations such as logging in, listing files, network communications, or just leaving Window sessions open and idle. PI Server System Management Guide Page 233

256 Chapter 11 - PI Troubleshooting and Repair Here are some observed behaviors that may be caused by insufficient process count: Archive shift not completing PI Archive Subsystem fails to resume normal operations after a shift Subsystems lose connection with the PI Network Manager Interfaces and clients lose connection with PI UNIX commands return the error can t fork, out of process quota As a general rule of thumb, you can assume that PI might need as many as 70 processes at once. Changing this quota varies with the UNIX platform. In all cases, you must log in as root to do any system configuration IBM AIX Run the smit utility. Select System Environments, then Change/Show Characteristics of Operating System. Change the variable Maximum number of processes per user Compaq Tru64 If you are using dxwindows, click on the Application Manager icon on the front panel, double-click on System_Admin, double-click on Monitoring Tuning, and double-click on Kernel Tuner. Select the proc subsystem, and examine the max-proc-per-user attribute. If not using dxwindows, the utility: # sysconfig -q proc will give a list of current settings. Of these, examine: max-proc-per-user = 64 max-threads-per-user = 256 task-max = 277 thread-max = 552 To change a value, you will have to create a stanza file. For more information about stanza files, issue the UNIX command man stanza. This file might look something like this: proc: max-proc-per-user=70 Before you apply any stanza file, always copy your current /etc/sysconfigdb file so that you can back out your changes if you need to. To apply the changes to the system, use the command # sysconfigdb -m -f yourfile.name proc where yourfile.name is the name of the file you created. You will have to reboot the system before this change will take effect. Page 234

257 PI Server Data Files HP-UX Run the sam utility. Select Kernel Configuration, then Configurable Parameters find maxuprc (maximum number of user processes) and nproc (maximum number of processes). If you change either value, you will need to create a new kernel (sam will ask you about this when you try to exit), and the new parameters will not take effect until you reboot Sun Solaris Run the sysdef utility. It will give a long list of current parameters. Somewhere in the middle is: * * Tunable Parameters * maximum memory allowed in buffer cache (bufhwm) 986 maximum number of processes (v.v_proc) 99 maximum global priority in sys class (MAXCLSYSPRI) 981 maximum processes per user id (v.v_maxup) 30 auto update time limit in seconds (NAUTOUP) 25 page stealing low water mark (GPGSLO) 5 fsflush run rate (FSFLUSHR) 25 minimum resident memory for avoiding deadlock (MINARMEM) 25 minimum swapable memory for avoiding deadlock (MINASMEM) * To change the max number of processes, you can only change maxusers and add memory. By default, maxusers is set to Maxusers = number of megabytes of memory - 2 Maxusers can be changed by modifying the /etc/system file. To set maxusers to 70, for example, the entry would be set maxusers = 70 The quotas max_nprocs and maxuprc are dependent on maxusers. The relationship is: max_nprocs (maximum number of processes system-wide): 10 + (16 * maxusers) maxuprc (maximum number of processes per user): max_nprocs PI Server Data Files The PI Server data files are located in the PI\dat directory. Archives are likely to be elsewhere. PI Server System Management Guide Page 235

258 Chapter 11 - PI Troubleshooting and Repair Pidiag -fb Internally, most PI Server data files have the same low-level structure and are referred to as PIFileBase-type files. The most notable exceptions are PI archive files. However, the annotation files that correspond to the PI archive files are of type PIFileBase. The pidiag -fb utility dumps the PIFileBase-type files and can be used to check PIFileBase-type files for correctness. Pass it the complete pathname of the PIFileBase-type file as a parameter. For example: pidiag -fb c:\pi\dat\pidignam.dat If it returns an error, you can either try to fix it with the following command: pidiag -fbf c:\pi\dat\pidignam.dat Note that PI must not be running when you attempt to repair a file. It is enough in most cases to shutdown the owning subsystem Note: In some cases pidiag -fbf will report the following: Error reading input record # nn [-10466] No Record Available for Passed recno This is normal for records between the actual last record and the maximum allocated record. The warning disappears if the utility is run a second time. Piarcmem.dat This binary file is the Snapshot Database used by pisnapss. It contains the most recent values that have been sent to PI the Snapshot value for each point when PI is shut down. Pisnapss periodically writes the latest Snapshot values to this file. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piarstat.dat This binary file keeps track of registered archives. It is required by piarchss. If you are having trouble with archive file registration, do not delete this file. Instead, see How to Repair the Archive Registry in this chapter. Pidignam.dat This binary file stores each unique digital state name. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Pidigst.dat This binary file stores the digital sets; it references names stored in the above file. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Page 236

259 PI Server Data Files Pimapevq.dat PimaNNNN.dat These are the memory-mapped Event Queues. Most systems use the default single file pimapevq.dat. Certain situations require multiple Event Queues; in this case the files take the naming convention of pimannnn.dat where NNNN is an integer. The memory mapped Event Queue serves two purposes. First, it used for moving events from the Snapshot Subsystem to the Archive Subsystem. PISnapss places events which pass compression into this queue. PIArchss takes these events and writes them to the Archive. Second, this file provides storage of events when the Archive Subsystem cannot process events such as during archive shifts or when the archive process is shutdown. This file, as the name implies is a memory-mapped file. Memory mapped files allow for high speed in-memory access with the security of being safely backed up to disk. Pilastsnap.dat This binary file stores the timestamp of the last completed Snapshot flush to disk. On PI System startup, this timestamp is assumed to be the shutdown time and is used as the timestamp for shutdown events. On orderly shutdown, this file will contain the true shutdown time. On a system crash such as a power failure the Snapshot may be as old as the Snapshot flush cycle time period. The Snapshot flush cycle is controlled by the SnapFlushCycle timeout parameter, which is 15 minutes by default. Pimsgtxt.dat This binary file stores formatted message strings used by the pigetmsg utility. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Pipoints.dat This binary file stores the Point database. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piptalia.dat This binary file contains alias information. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piptattr.dat This binary file stores the point attributes. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piptclss.dat This binary file stores the point classes. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. PI Server System Management Guide Page 237

260 Chapter 11 - PI Troubleshooting and Repair Piptunit.dat This binary file stores the units. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piusr.dat This file stores the user database. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piusrctx.dat This file stores the context database. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Piusrgrp.dat This file stores the group database. This is a pifilebase-type database so its validity can be checked and restored using pidiag -fb and pidiag -fbf. Shutdown.dat This text file contains directives that tell the PI Shutdown Interface which points should receive shutdown events Identifying the Update Manager Issues: the pilistupd utility The pilistupd utility shows the size of the queues of events maintained by the Update Manager. The utility requires that PI be running. Note: Windows-based PI Server exposes Update Manager Counters as Windows Performance Counters. These counters may be viewed with the Windows Performance Monitor and stored as PI points using the OSI Performance Monitor Interface. This subject is covered in detail later in this chapter. From a command prompt at the PI\adm directory, execute the utility pilistupd. This will show a simple, although sometimes large, table summarizing the current state of update signups. The table has five columns: Producer: This is the source of update notifications. Currently there are five producers. PI Snapshot Subsystem is a producer of Snapshot events. PI Base Subsystem is a producer of Point Database and Module Database changes. The Archive Subsystem is a producer of archive changes. The Batch Subsystem is a producer of Batch Database changes. Consumer: Application currently signed up as a consumer of specified producer. For PI API applications, the consumer name is usually the first 4 letters of the login name of the user running the application. These names are not unique so the PI Update Manager assigned ID is appended to the name. PI API applications also have the PI Network Manager ID appended. These integers are appended to help find specific Page 238

261 Identifying the Update Manager Issues: the pilistupd utility consumers. For the PI-SDK, the consumer name is the complete application name with a colon and a PI-SDK supplied identifier followed by a pipe character and a PI Update Manager assigned ID. Qual: This is the qualifier. The qualifier is a producer-specific integer. For example, Snapshots update stores the requested point ID in the qualifier. Flags: A producer-specific field. Pending: Number of events available for the consumer to retrieve. The value goes up and down as events come in and the consumer pulls them out. Values that increase continuously might indicate that the consumer is not working properly or disconnected. Note: The Pending number shows a maximum of 4096 events, even if more events are in the queue. The Update Manager might limit individual consumers from accumulating too many pending events. This is a display limitation and does imply data loss. Command line Switches for pilistupd pilistupd has the following command line switches: -v Show version -h Help -c consumer Select a specific consumer -p producer Select producer -m min Show only events with pending >= min -t Show only the total number pending for this selection (specific cons./prod.) -d piupdmgr dump to pi\adm\updmgr.dmp -r C <S> Repeat C times every S sec. -g A list of registered producers/consumers -sp Sort output by producers Example 1. Point Updates Only For example, the following command limits output to the Producer ptupdates: e:\pi\adm>pilistupd -p ptupdates Producer Consumer Qual. Flags Pending ptupdates Pibatch ptupdates Pitotal ptupdates PipeE ptupdates RandE ptupdates RmpSE PI Server System Management Guide Page 239

262 Chapter 11 - PI Troubleshooting and Repair In the results, the first entry is PI Batch Subsystem registered as a consumer of Point Database changes. The integer 1 indicates this is the first consumer to register with the PI Update Manager. The second registered consumer is the Totalizer Subsystem. The third entry is a PI API-based application, probably Performance Equation Scheduler. PI API applications always have a four-character name with E appended. The two subsequent integers, separated by the pipe ( ), are the PI Network Manager assigned connection ID and the PI Update Manager assigned ID. The connection ID is useful in tracking down errant client applications; for example a ProcessBook display that is not checking for updates. The PI Network Manager Statistics table can be used to lookup the machine associated with an ID. Entries 4 and 5 are also PI API-based applications, probably the Random and RampSoak interfaces, which are installed by default on the PI Server node. Random interface generates sinusoid points. A trend of sinusoid can indicate whether the Server is providing updates to the client normally. Example 2. Running pilistupd with PI ProcessBook Display Open The next table was generated by running pilistupd with an open PI ProcessBook display, trending 5 points. e:\pi\adm>pilistupd Producer Consumer Qual. Flags Pending ptupdates Pibatch ptupdates Pitotal ptupdates PipeE ptupdates RandE Ptupdates RmpSE snapshots PiadE snapshots PiadE snapshots PiadE snapshots PiadE snapshots PiadE The last 5 lines of results are all the same display consumer piade The consumer name indicates an application logged in under piadmin account and it s a PI API application the first 4 characters of piadmin with an E appended. This consumer has a PI Net Manager ID of 33 and a PI Update Manager ID of 9. The qualifier attribute shows the point IDs being trended. There are three pending events, two for point ID 29761, and one for point ID 1. Example 3. Determining Whether Client Updates are Occurring Running pilistupd several times should reveal changes in the pending numbers. This can be done easily by using command line switches. The -m option, requests a minimum pending value of 1. The -r requests that the command be run 100 times. In the example below, the command is issued and then results appear for 4 runs before the command is stopped with Ctrl C. For three of the runs, none of the producers have any pending updates, as indicated by the No Matching entries output. Page 240

263 Repairs e:\pi\adm>pilistupd -p snapshots -m 1 -r 100 No Matching entries No Matching entries Producer Consumer Qual. Flags Pending snapshots piade snapshots piade snapshots piade snapshots piade snapshots piade No Matching entries ^C In a normal system, you would anticipate that the pending number would reach 1 occasionally as the pilistupd command was run before the consumer retrieved the update. If the pending number never increases above 0, it may be that data is not arriving from the source. If the pending number increases continually and does not shrink, the consumer is probably not retrieving the updates Repairs Occasionally a PI data file may become corrupt due to a power outage or some other unusual circumstance. There are utilities available to rebuild corrupted Archives, the Archive registry, and the Point Database Recovering Data from Corrupted Archives Archive files have a header and a record structure. Data is put in the records, but there is also auxiliary information that indexes the records and chains the records together for fast data access. If, for example, the Archive cache flushing is interrupted by a power outage, the index records might be left in an inconsistent state. When Archive file corruption occurs and the file becomes unreadable, it is desirable to recover as much data as possible from that file. The Offline Archive Utility can be used to recover the data and rebuild the Archive header and the record indexing and chaining information. For more information about the theory behind the Offline Archive Utility, see PI System Management. Recovering a Corrupted Non-primary Archive To recover the data from a corrupted Non-primary archive, launch the Offline Archive Utility, specifying the corrupted archive as the input file and a non-existing file as the output file. By default, the start time and end time of the input archive will be used as the start time and end time of the output archive that is created. The data in a non-primary Archive may be recovered while PI is still archiving data. The Offline Archive Tool will unregister the archive during the recovery operation. Here is an example command to recover a non-primary archive: $../bin/piarchss -if /export/pi/dat/piarch.001 -of piarch1.fix -f 0 PI Server System Management Guide Page 241

264 Chapter 11 - PI Troubleshooting and Repair...First pass......sorting input archive......output pass Loaded in 2( ) Seconds 338 Event/Sec. 739 Archive Total seconds - ratio: 369 In this example, piarch1.fix does not exist prior to the operation It is created as a fixed Archive the same size as the input Archive because the -f 0 parameter was specified. After it is created, it may be registered using the piartool -ar utility, and then data events may be added to the Archive in the usual way. If the input file were registered prior to the operation, it would be unregistered during the operation. When the operation is complete, it may be registered again using the piartool -ar utility. Recovering a Corrupted Primary Archive If the corrupted archive is the Primary Archive, then PI cannot archive data during the recovery process. Further, the Primary Archive cannot be unregistered. Thus to recover the Primary Archive, prior to recovery one has to either stop the Archive Subsystem or force a shift so that the archive is no longer the Primary Archive. To force a shift, use the piartool -fs utility. To recover the Primary Archive: 1. Stop the Archive Subsystem. 2. Launch the Offline Archive Utility specifying the parameters: Output archive is fixed size (-f 0) End time left open (-oet Primary) After recovery: 1. Remove the old Primary Archive (rename it) 2. Rename the output file to the same path and filename of the original Primary Archive. 3. Restart the Archive Subsystem Note: Every archive has a parallel annotation file, with an extension.ann. In PI , the annotation file will be identified incorrectly after renaming its associated archive file. Since renaming is necessary in this case, unregister the renamed file after initial registration, and re-register it. Example of Recovering a Primary Archive Here is an example of recovering a Primary Archive. In this example, the Failed to unregister input archive message may be ignored. It occurs because the Archive Subsystem was stopped prior to recovery. $../bin/piarchss -if /export/pi/dat/piarch.005 -of piarch.005.fix -f 0 -oet 0 Page 242

265 Repairs...First pass......sorting input archive... Failed to unregister input archive: [-10733] PINET: RPC Resolver is Off-Line Archive utility not running - or archive not registered Continue processing......output pass Loaded in 2( ) Seconds 542 Event/Sec Archive Total seconds - ratio: 519 In this example, piarch.005.fix does not exist prior to the operation. It is created as a fixed archive the same size as the input archive because the -f 0 parameter was specified. The end time of the output archive is left open because the -et 0 parameter was specified Restoring a Complete Server from Backup The following procedure guides you through restoration of a complete PI Server from backup and the original installation disk. This is suitable for cases of disk crashes or disasters of similar magnitude. If the problem is clearly only with the data, start from step This procedure assumes the operating system was reinstalled and has no knowledge of previous installation. 2. Disconnect the PI Server from the network. This is an important step. Interfaces buffer data when the PI Server is not available. This data is safely stored and managed by the PI Buffer Server bufserv. Bufserv attempts, once a minute, to reconnect to the PI Server; immediately on reconnection all data is written to the PI Server. In the recovery process the PI Server starts before full recovery; if the buffered nodes are not isolated, data from these nodes are lost. 3. Reinstall PI. The same version of PI should be installed. Data file formats may change between versions; it is important to install the same version that ran at time of last backup. 4. Start PI, and then stop PI after proper startup is observed. This accomplishes the "run once" functions performed after an installation. 5. Verify that PI is not running before proceeding to the next step. 6. With the exception of pisubsys.cfg, restore (using Windows Explorer or the copy command) the files that were backed up from the original PI\dat\ directory to the new PI\dat\ directory. 7. Restore all the message log files ("pimsg_xxxxxxx.dat") to the PI\log directory. 8. Restore (using Windows Explorer or the copy command) the archives that you have backed up to tape (or to a different drive) to the proper directory (by default PI\dat). 9. Restore (using Windows Explorer or the copy command) any of the batch files from the PI\adm directory that had been customized to start and stop PI (such as pisrvsitestart.bat etc.). PI Server System Management Guide Page 243

266 Chapter 11 - PI Troubleshooting and Repair 10. If you are uncertain which of your backed up archives was the Primary Archive (archive 0) at the time you last made a backup, use pidiag -ahd and examine the archive dates. The primary should have the latest start date and no end date: e:\pi\adm>pidiag -ahd..\dat\piarch001.dat 11. You will need to do the following steps to reconstruct your Archive Manager data file. After step 9 above make sure no PI process is running, and then execute the following command from the PI\adm directory: pidiag -ar 12. This utility will prompt you for the path and filename of the archive that you want to assign as the Primary Archive. Enter the name (including the full path) of the Primary Archive (archive 0) before the crash. 13. If the backup was performed using PI Version or greater, then skip this step because the snapshot is backed up as of and there is no need to rename the piarcmem.dat file. Otherwise, if the backup was performed with a version of PI prior to , rename the PI\dat\piarcmem.dat to PI\dat\piarcmem.dat.old. 14. If the backup was performed using PI Version or greater, then skip this step. Otherwise, execute the Base Subsystem found in PI\bin to re-create the snapshot file: pibasess -snapfix 15. Restart PI. 16. You will have to manually register all of the other archives that you want mounted. pidiag -ar only registers the specified primary archive. Register the other archives in their new locations: piartool -ar <path_and_archive_file_name> 17. Use piartool -al and the client tools (PI ProcessBook and PI DataLink) to verify that all the data has been recovered. If the data is intact, you are done. Run the clients locally, since the PI Server should be isolated from the network. It is very important to confirm correct PI Server recovery before exposing the PI System to buffered data. Failing to do so may cause data loss. 18. Connect the PI Server to the network. Verify the PI Server is reachable from clients on the network. Monitor all buffered interface nodes Restoring Archives From Backup To restore an archive from backup: 1. Copy the archive file to disk. 2. Unregister any archives whose dates overlap the archive to be restored. For details, see Unregistering an Archive on page Use piartool -ar <path> to register the restored archive. 4. Use piartool -al to list the registered archives and their dates. The archive just registered should be displayed. Page 244

267 Repairs Note: The PI Server will not allow registering archives with overlapping dates. If you find overlapping dates, you can use pidiag -ahd to check the exact start and end times Restoring Subsystem Databases From Backup Many databases are interconnected. For example, the Point Database must be synchronized with the Snapshot and Primary Archive. Generally, if one database must be restored from backup, all databases must be restored from backup, as well as the primary archive. Partial backup restoration should be done under the advice of PI Technical Support. To restore a database, shut down the PI System. Do another backup to a safe location. Replace the existing database files and the Primary Archive from the most recent backup. Restart the PI System Correcting Archive Event Timestamps Offline archive processing may be used to transform event time stamps. This feature applies a time offset to all events in an archive. The offsets, specified by a data file, define the offset as a function of time. Time transformation processing is typically used to fix an archive with incorrect times. For example, a system with incorrect time setting or time zone setting will have all archive event timestamps offset. Time transformation processing adds an equal but opposite offset to correct this error. Using Time Transformation Processing Offline archive processing with time transformation differs little from standard offline archive processing. All arguments, such as input file and output file, must be specified. Additional arguments specify time transformation behavior. The additional arguments are: -tfix <time conversion file> [-tfixend <time> -oeendtime <time>] The argument -tfix followed by full file specification is required. The arguments -tfixend and -oeendtime are optional. The first option, -tfixend, followed by a timestamp specifies the time to perform no transformations. All events with timestamps greater than or equal to this time will not be transformed. This option is used when only a portion of the archive has incorrect event timestamps. For example, if a PI System was run for a period with incorrect system clock setting, then the clock was set correctly and run for some period before applying a time transformation fix. The second option, -oeendtime, followed by a timestamp specifies a timestamp to set as the archive end time when conversion is complete. The archive end time is set to the passed value if all events are older than this time; otherwise, the end time is set to the time of the oldest archive event. PI Server System Management Guide Page 245

268 Chapter 11 - PI Troubleshooting and Repair Time Conversion File Format The time conversion file is an ASCII file containing a list of timestamp/offset pairs. The timestamp and offset are separated with a comma. Lines beginning with "#", and empty lines are ignored. White spaces are ignored The timestamp may be a local time string in PI Time format; either an absolute time in the format "dd-mmm-yy hh:mm:ss" or a relative time, such as "*-300d" or *. Only one timestamp format can be used in a given file. The first format encountered is assumed for all timestamps. The offset is the number of seconds to add to the event timestamps. Sub-second precision of the time shift is not supported. The offset is applied to all events with timestamps greater than or equal to specified timestamp but less than next timestamp in the conversion file. Here are some examples: The following example uses UTC seconds time format. The timestamp "0", is January 1, 1970, and is well into the 21st century. The offset is a positive one hour. Therefore this data file will simply move all events ahead by one hour. # Example 1, Moves entire archive ahead by 1 hour 0, ,3600 Example 2 is similar to example 1, but uses local time stamps to specify a suitably large time range to cover all events. The offset is This data file will move all events back by one hour. # Example 2, Also moves entire archive back by 1 hour 01-Jan-70 00:00:00, Jan-30 00:00:00,-3600 Example 3 applies a missed daylight savings time conversion for the Northern Hemisphere summer of The first timestamp is sufficiently in the past to cover all events up to the daylight savings transition; no offset is applied up to, but not including 06-Apr-03 02:00:00. From 06-Apr-03 02:00:00 up to, but not including, 26-Oct-03 02:00:00 one hour is added to all events. No offset is applied from 26-Oct-03 02:00:00 to current time. # Example 3, Applies a missed dst conversion to an # archive that covers summer of Jan-97 00:00:00,0 06-Apr-97 02:00:00, Oct-97 02:00:00,0 31-Dec-97 23:59:59, Repairing the Archive Registry This archive registry information is stored in a binary file called piarstat.dat. If this file is corrupted, it can be rebuilt using the pidiag utility. To do this: 1. Copy piarstat.dat to a temporary location. Do not overwrite the original rename it in case you need it later. 2. Stop PI. Page 246

269 Repairs 3. Run pidiag -ad and collect the dump of piarstat.dat, verifying the output. 4. If the results of the dump look good, attempt the automated recovery. Otherwise, use the interactive one. 5. Restart PI. 6. Check the message log to see if all archives are loaded. If the interactive version is used, only the Primary Archive will be loaded. 7. Register any remaining archives. If the interactive version was used, all other archives will need to be registered. Options for Running Pidiag There are three ways to run the recovery tool: -ad -ar -ara Dumps the current piarstat.dat file. This is used to review the data in the file. Provides an interactive recovery utility for renaming the old piarstat.dat to piarstat.old and generating a new one with a single entry - the Primary Archive - provided by the user. Provides an automated recovery utility that renames the old piarstat.dat to piarstat.old and generates a new one with all of the entries found in the original file. Any errors will cause the automated version to abort, and the user should resort to the interactive version How to Repair the Snapshot There are two types of possible damage to the Snapshot from which PI can recover: Snapshot times in the future. Accidentally moving the PI Server system time into the future can cause this; at a minimum all points collected locally will be in the future. Snapshot events are replaced when a newer value is received; therefore these events remain in the Snapshot until actual time catches up. Events earlier than Snapshot time bypass compression. Bypassing compression can put a large load on your PI Server. Damaged or corrupted Snapshot file, piarcmem.dat. Corruption may be caused by disk or power failures. This section describes techniques for repairing the Snapshot in both of these situations. Recovering from Future Times in the Snapshot The fix option is invoked by stopping pisnapss on a running PI System. Re-start pisnapss from a command prompt, passing the -f command line argument. This must be done interactively; not as a Windows service: Pisnapss -f PIsnapss on startup will look for all Snapshots more than 20 minutes in the future. These future Snapshots will be overwritten with a NULL value. PIsnapss reports to the message log the number of future events detected. No fix-up messages are written if no future Snapshots were detected. New incoming data will immediately overwrite the NULL Snapshot, even if the incoming value is out-of-order. If an out-of-order value is received when the Snapshot is NULL, values in the archive later than the Snapshot will not be visible to client applications. PI Server System Management Guide Page 247

270 Chapter 11 - PI Troubleshooting and Repair Typically, this is not a problem because values are written in time order, but it is something to consider when running pisnapss.exe with the -f option. PIsnapss will continue to run normally after the fix-up. Control-C the interactive pisnapss process and restart it as a service. Note: Snapshots fixed by this procedure will remain set to NULL until a new snapshot event is fixed. If a point does not receive events regularly the NULL snapshot may cause problems with applications expecting normal values. A Snapshot can always be written manually if needed. ANY new event that is received for a point with a null snapshot will be absorbed into the Snapshot, even if that event is an out of order event. If an out of order event is received, then any data that was in the archive after the out of order Snapshot value will not be visible. Rebuilding the Snapshot File If the PI System is unable to start because the Snapshot file, piarcmem.dat, cannot be loaded, it will be necessary to generate a new Snapshot file. Note: This procedure builds a new snapshot file with Shutdown events in it. The Snapshot will be updated as the PI System receives new data. If you follow this procedure when your snapshot file is normal, you will lose data. You should use this command only when directed by OSIsoft Technical Support. To do this, shut down pibasess, piarchss, and pisnapss. Rename the file PI\dat\piarcmem.dat to another name. At a command prompt, change your current directory to PI\bin and issue the command: pibasess -snapfix The PI Base Subsystem will write a message to the screen indicating that Snapshot recovery mode has been specified and that recovery is in progress. When recovery is complete, pibasess will write a final message to the screen and exit. You may then restart the PI System. This Snapshot recovery command can be run with the entire PI System shut down. Removing Future Time Snapshots The piconfig utility can be used to remove all or selected Snapshot events. When the Snapshot event is removed, the Snapshot Subsystem attempts to retrieve the latest archived event from the Archive and replace the Snapshot event with it. That event is removed from the Archive. If there are no events for the point in the Archive, the Snapshot is deleted and remains uninitialized until a new Snapshot event is sent. The following piconfig script shows how to do that: piconfig table pisnap * (Ls - PISNAP) tag=*,time>"*+10m" * (Ls - PISNAP) tag,value,time Page 248

271 Repairs * (Ls - PISNAP) 8 * (Ls - PISNAP) deletesnap.dat * (Ls - PISNAP) piarc * (Ls - PIARC) ed,t * (Ed - PIARC) mode=remove * (Ed - PIARC) tag,value,time * (Ed - PIARC) v * (Ed - PIARC) deletesnap.dat The first part extracts all the events that are later than 10 minutes past the current time into a file. The second part (using the PIARC table) removes all these events from the Snapshot. The last archive event for each tag replaces then Snapshot. Any combination of conditions can be used to select the events to be deleted, for example all tags of a specific interface. 8 command ensures that rounding errors do not cause events to not be found Recovering from Accidental Change to System Time The PI Server handles automatically all changes to system time. Thus our recommendation is to never manually change the system time. On Windows, always use the automatic DST option. However, occasionally such changes are required, and unfortunately, from time to time this change leads to human errors. For example instead of moving the clock to 2 AM it is moved to 2 PM. Time synchronization software, designed to keep computer clocks accurate without error-prone human intervention, have also been implicated in moving system clocks erroneously. As a result, the events are recorded in the future. Usually this is discovered after many of these events were already stored in the Archive. To recover from such situation: 1. Stop the PI System. 2. Correct the system time and the time on all connected nodes. 3. Isolate the PI Server from interface nodes. The best technique is to disconnect the server from the network. While fixing the PI Server, it is best to allow the data to buffer until the system is verified up and running normally. 4. Rename the Event Queue file, pimapevq.dat for later processing. The Event Queue may contain many future events. Rename the following files located in the dat directory: pilastsnap.dat pilasttot_t.dat pilastalarm.dat 5. Create an empty archive file using piarcreate utility. 6. Run pidiag -ar and register only the new empty archive. There are two options for fixing the Snapshot: PI Server System Management Guide Page 249

272 Chapter 11 - PI Troubleshooting and Repair 1. If the erroneous future data can be discarded, start the Snapshot Subsystem with -f flag as explained above. 2. Otherwise, keep the current file, and after the system startup, delete or edit individual values using piconfig, as explained above. 3. Start the PI Server in base mode. This starts just the minimum required subsystems pinetmgr, pimsgss, piupdmgr, pisnapss, piarchss, and pibasess: pisrvstart -base 4. Register all the old archive files but the previous primary (which contains future data) pidiag -ahd can be used to examine unregistered archive file header. 5. Create a new primary archive using piartool -ac. 6. Specify a start-time before any events that might be coming in. Specify the end-time as *. This instructs the Archive Subsystem to register the new archive as primary. The start time specified must account for all buffered data. If in doubt set the start time well before the time the problem was first encountered. Offline archive processing can merge this data with existing archives if necessary. 7. Verify that the PI System is running correctly. Reconnect the Server to the network. 8. Reprocess the old Primary Archive using the offline tool to either filter out the future data, or correct its time by the required difference. 9. Reprocess the Event Queue into an archive file and correct timestamps as required. 10. Optionally combine these two archive (old primary and result of Event Queue). 11. Register the corrected archive file How to Repair the Point Database To perform a consistency check of the Point Database and fix any reported errors, run pibasess with the fix option. This also synchronizes the Snapshot and Archive databases with the Point Database, since they contain references to the point database. The fix option is invoked by stopping pibasess on a running PI System and restarting it with -f command line argument. This must be done interactively; you cannot pass command line arguments when starting pibasess as a Windows Service. The consistency check adds messages to the PI Message Log. Additional information may also be presented in the command window. Once the consistency check is complete, the subsystem continues normal operation. It does not need to be restarted without the -f parameter. However, if you are running PI as Windows Services, you will need to shut down pibasess in order to restart it as a service before logging off How to Repair the Module Database A module database consistency/fix-up is performed by running the PI Base Subsystem from the command line as follows: pibasess -mdbfix Page 250

273 Tuning the PI Server The following is performed: Table and index entry count size checks are performed. The entry counts should be the same. Modules that have a record size of zero are removed. These modules would be unrecoverable. Parent and children references to non-existent modules are removed. This utility may modify the Module Database. Therefore it is important to have a safe backup Tuning the PI Server Most PI Servers require no tuning and work well with default settings. In some instances, you may need to make adjustments through the Timeout Database, discussed below Communications Layer of the PI Server A fundamental part of the PI Server architecture is the communications layer. Each PI subsystem or process communicates with the other subsystems using Remote Procedure Calls (RPCs). The pinetmgr process manages the RPCs, and is thus involved in every communication between PI processes. For example, if the Snapshot Subsystem (pisnapss) sends an event to the Archive Subsystem (piarchss) for storage, the communication flows from pisnapss to pinetmgr to piarchss. If the Archive Subsystem writes a message to the System Message Log, the communication flows from piarchss to pinetmgr to pimsgss. Thus the pinetmgr process can be viewed as the hub of the wheel, where each spoke connects to a different subsystem. All communication is asynchronous. ("non-blocking" on UNIX). Windows PI Servers use advanced, Windows-specific, multithreaded I/O. UNIX Inter-Process Communication PI Subsystem inter-process communication, by default, uses UNIX Sockets protocol. UNIX sockets is a simpler, thus faster, protocol than TCP/IP. Generally this works fine. Heavily loaded systems, especially heavy file system activity, may encounter excessive errors. If the errors shown in the following table occur regularly, switch to TCP/IP as explained below. Error Description 11 Resource temporarily unavailable PINET: Incomplete Message PINET: Corrupted Message PINET: Message verification failure. PI Server System Management Guide Page 251

274 Chapter 11 - PI Troubleshooting and Repair CP/IP for Subsystem Inter-process Communication The PI System can be configured to use TCP/IP for inter-process communication. The text file pisubsys.cfg, located in the /dat directory, defines the desired inter-process communication protocol. By default this file looks as the following: # # File: pisubsys.cfg # Created /03/95 # Generic_local /opt/pi/dat/piv3.rdz The last line specifies the UNIX Sockets rendezvous file. To use TCP/IP, make the changes as shown below: # # File: pisubsys.cfg # Created /03/95 # # Generic_local /opt/pi/dat/piv3.rdz Generic_local localhost:5451 The previous UNIX Sockets rendezvous file entry is commented out and replaced with a TCP/IP specification of localhost on port The port number can be any unused port greater than 1024; it cannot be the default listener port of should be used unless it conflicts with another application. This example also assumes the host localhost is defined in the /etc/hosts file. The PI System must be stopped and restarted for these changes to take effect. Note: This technique if only used for advanced troubleshooting. This should only be done under the advice of OSI Technical Support Resolving Excessive CPU Usage by Utilities The utilities piconfig, pigetmsg, pilistupd and piartool may use excessive CPU. You can fix this problem by increasing the time-out values for these. This results in more emphasis being given to listening for messages and during this listening period (select) the CPU is not used and is available to other tasks. Increase the values as follows: pi_gen, pitimeout edit name, value piconfig> piartool, 100 piconfig> piconfig,1000 piconfig> pigetmsg,1000 piconfig> pilistupd,1000 On some UNIX platforms, pinetmgr may report an error 11 or 35. This message would typically be viewed with pigetmsg or in log/pinetmgr.log. This error is due to insufficient resources available to complete the transfer of a large message. The fix is to increase the default time-out and the number of retries pinetmgr uses for message transfer. Read and Page 252

275 Tuning the PI Server write time-outs default to 50,000 microseconds, read and write retries default to 250. We recommend increasing the time-outs in increments of approximately 25% until the errors disappear. If the errors persist when the timeout values are over 150,000 microseconds, call OSI Technical Support. To increase the time-outs: pi_gen, pitimeout edit name, value piconfig> readtimeout,62500 piconfig> writetimeout,62500 piconfig> readretry,350 piconfig> writeretry,350 Note: PI Server installation sets all timeout values to well-tested initial values. Changes to these values should be done under the advice of OSI Technical Support. Very short timeout values may cause specific utilities to spin faster and thus use more CPU. Before making changes based on CPU consumption, isolate the CPU to the offending processes. Use available tools to analyze each process. For example, if pisnapss is in a high CPU state, run piartool -ss and look at Snapshot read and write rates because excessive rates may be the true source of CPU load Identifying Abusive Usage If the PI Server uses most of the CPU one needs to identify more specifically the cause. In some cases it is wrong sizing, i.e., the configuration is too large for the available hardware, such as CPU, memory or disk. The introduction of threading in release 3.4 solves many performance issues; however, very large archive queries can still affect performance. The total number and size of queries can be monitored with piartool -as. If the number of read access and number of events retrieved seem excessive, use the activity grid as follows. Also, the pinetmgrstats table in Piconfig can help identify network connections with the highest traffic. This is explained in The piconfig Utility on page 171 of this guide. Activity Grid The Archive Subsystem provides a tool for monitoring the rate of read-access to the Archive. This tool creates, over a finite time period, a grid of activity. The grid indicates which users and points account for the most activity. This monitoring requires significant computing resources and therefore is normally turned off. Start the activity grid to identify the users that present the greatest load on the system and the points that are being queried most often. Once the load on the system is identified, it is best to turn off the activity grid. To start the activity grid: Piartool -aag start PI Server System Management Guide Page 253

276 Chapter 11 - PI Troubleshooting and Repair To stop it, and remove all its memory Piartool -aag stop To temporarily stop the accounting yet allow querying of the current statistics Piartool -aag pause Each query requests the number of events retrieved or the number of retrieval calls made. These can be arranged by points or by users. A yearly average might go through thousands of events for a specified point, yet counts as a single call. The following gets the number of events retrieved by point. This is since the activity grid was started. d:\pi\adm>piartool -aag point event Name - Count - ID SINUSOID 35-1 CDT CDM The following gets the number of event-retrieval calls, arranged by user. d:\pi\adm>piartool -aag user access Name Count ID pidemo Solving Other Problems Failed Backups For tips on troubleshooting backups, see Troubleshooting Backups in the chapter Backing up the PI Server Slow Reverse Name Lookup The PI Network Manager looks up the host name of all computers connecting with PI API. The name lookup is used to identify the connecting computer for trust login and firewall access. A Reverse Name Lookup requests the Domain Name Server (DNS) to translate an IP address to host name. This request must complete in a reasonable amount of time for PI to function correctly. Network systems with malfunctioning Reverse Name Lookup will experience slow connections or failure to connect to PI. Often the symptoms may be isolated to a subnet or computers connecting from outside the LAN. The standard TCP/IP utility, nslookup, can be used to check Reverse Name Lookup. If nslookup reports a delay when resolving an IP address to name, the network has DNS problems that should be addressed. Resolving this problem is a system network configuration task and beyond the scope of this document. If the problem cannot be resolved in a timely manner, the Reverse Name Lookup can be disabled. First, add an entry reversenamelookupflag to the PI Timeout Table. Set the value of this to zero to disable the lookup. Setting the value to a non-zero entry or removing the reversenamelookup flag entry enables the lookup. Page 254

277 Solving Other Problems Here is an example piconfig session which disables Reverse Name Lookup. pi_gen, pitimeout create,t name, value piconfig> reversenamelookupflag,0 If Reverse Name Lookup is disabled, trust login access by name would not work. You can modify the trust record to use other credential information. Another way to speed up Reverse Name Lookup is to create a local host file on the PI Server Slow Domain Controller Access Trust logins from PI-SDK-based applications require access to the Windows Domain controller or Active Directory. The lookup is required to authenticate client login credentials. Slow access to these services will adversely affect the system. The utility pidiag -host performs the same validation carried out by pibasess. Run this utility from a command line on the server to get a measure of the access time and reliability. Disabling the authentication feature defeats an important part of single user signon of PI Client applications. Rather than disabling it, it is best to insure reliable access to the Domain Controller or Active Directory. If necessary, the timeout parameter WindowsAuthentication may be used to disable this feature. A value of zero disables the authentication. Removing this timeout parameter or giving it a value of other than zero enables this feature. The PI Base Subsystem must be restarted for this change to take affect. The utility pidiag -host performs the same validation carried out by pibasess. Run this utility from a command line on the server to get a measure of the access time and reliability Flatline in a PI ProcessBook Trend If a PI ProcessBook trend flatlines, you may have a problem with PI ProcessBook, with the PI Server, with network performance/connectivity/configuration, or with the data source. Here are some possible diagnostic steps to take: 1. Determine whether only one tag is affected or several are affected. Check another trend in the ProcessBook to see if the problem is limited to only some points. If the problem involves multiple points, go to step 2. If the problem involves only one point, go to step Try retrieving the data from the PI Archive by closing and reopening the trend window. If the trends appear normal, the problem may be in the update signup. Go to step 3. If the trends still show no data, go to step If no tags are producing trends, run pilistupd on the PI Server to see if the flatline is due to the PI ProcessBook program not being signed up for updates. See PIlistupd Utility in the System Management chapter. 4. View the pending numbers in the results. Pending numbers represent the number of events queued and not yet retrieved by the client such as PI ProcessBook. If data is not arriving from the data source, the pending number remains at zero. If the client PI PI Server System Management Guide Page 255

278 Chapter 11 - PI Troubleshooting and Repair ProcessBook is not retrieving the updates, the pending number continually grows and does not shrink. This indicates whether the problem is with the PI Server or with the client application. 5. If the pending updates are growing, try restarting the PI System. If this does not fix the problem, contact OSIsoft Technical Support for additional assistance. If the pending updates remain zero, go to step If all the points are signed up for updates, and refreshing the data from the archive still yields a flatline trend, the problem could be in the archive, in the data source, or in communications to the data source. 7. To determine if the Server is working, create a trend for a point with data generated on the Server, such as sinusoid, which is generated by the Random Interface on the Server. 8. If the trend for sinusoid appears correctly, it means that the archive is working and communication between Server and client is working. Then go to step If the trend for sinusoid does not appear correctly, go to step Verify that the archive program is working (piartool -as, piartool -al) 11. Try inserting data into a test point (using piconfig or PI DataLink) and try trending this point. If this is successful, go to step 6. If not, contact OSIsoft Technical Support for additional assistance. 12. If all these tests are successful, the data source for the flatlined points may not be working. Examine the Source-point attribute of the point to find out which interface is feeding data for the point in question. 13. Check the PINetstats Table (See Chapter 1, PI System Management) to verify that the interface program is running and connected to the Server. 14. Verify that the interface program is communicating with the external data source (DCS system, RDB system, etc.). The documentation for the specific interface should explain how to do this. 15. If the data source is running successfully, go to step Security may be preventing the process at some point. Examine the interface log files and the PI Server log files (pigetmsg). Verify that both the data source interface and PI ProcessBook have the correct access to the system. Examine all messages about trusts granted or refused. 17. If the points in question have some access restrictions, there must be established trust logins. The interface must have access as a PI user with WRITE access to the points. PI ProcessBook must have read access to all these points. If none of the above steps have resolved the problem, contact OSIsoft Technical Support for additional assistance. Page 256

279 COM Connectors 11.9 COM Connectors Occasionally, errors are observed when OSI client applications fail to obtain process data. If the errors are related to a foreign data historian, the applications generally receive error codes in the range to , instead of returning data. As usual, you can use the pidiag -e utility to translate these errors to text. The source of the error can be the Redirector or the specific COM Connector in use. Errors may be logged in either the Windows Event Log or the PI Message Log. In general, the distinction is this: The Redirector logs information about its own activities to the Windows Event Application Log. This includes startup, shutdown and loading of COM Connectors. The PI Subsystems record errors in foreign system point lookup and data retrieval in the PI System Message Log. This section gives some guidelines for troubleshooting data retrieval problems from COM Connectors. As new techniques become available, they will be posted on the OSI Technical Support COM Connector page, available at Redirector Troubleshooting This subsection describes techniques for confirming the correct operation of the Redirector. When troubleshooting a COM Connector problem, you should always begin with this subsection. Confirming Redirector Installation The Redirector is not installed separately; it is installed as part of the PI Server. To confirm that the Redirector was installed correctly, check the PI Server installation log file piudsinst.log in the root of your system disk. Look for two lines reading: Registering PI UDS Redirector. Creating EventLog registry key for piudsrdr You can use the Windows utility dcomcnfg to confirm installation and check the Redirector's properties. Invoking dcomcnfg displays this dialog box: PI Server System Management Guide Page 257

280 Chapter 11 - PI Troubleshooting and Repair Figure Distributed COM Configuration Properties Once you have confirmed from this dialog that OSI PI Server Redirector is installed, continue with the troubleshooting tips below until the problem is solved. When you are able to clear the problem, you must restart the Redirector. This is done by shutting down the Base, Snapshot, and Archive Subsystems and restarting them. There is no method to restart the Redirector alone. The Redirector is not launched if there is no COM Connector (a.k.a. mapped) points configured on the system. Check for Mapped Points in the Archive Mapped points should be correctly defined in the PI Point Database. A mapped point is one that has the three identifying point attributes: ctr_progid, ctr_strmap and ctr_lmap. Check using piconfig: tag, ctr_progid, ctr_strmap, Point class "classicctr" can be created using the piconfig file classicctr.dif provided with the PI Server installation kit. You may create your own point classes for PI Server mapped Page 258

281 COM Connectors points. The point class may be of any name as long as it contains the above three point attributes. Check for the PI Redirector Process If the PI Server mapped points are defined, a process called piudsrdr.exe should be running. Check for this in the Windows Task Manager, Processes tab: Figure Windows Task Manager Processes 1.) Check the PI Message Log If the Redirector is not running, check the PI Message Log using the pigetmsg utility. Check for any messages related to the Redirector or a COM Connector. If this message appears: 0 pipoints 23-Jun-03 16:07:25 >> Error getting UDS Point interface. [ ] Invalid pointer it means that the Redirector is not installed correctly. Attempt to reinstall by opening a command window, setting your default directory to the PI\bin directory and issuing the command: piudsrdr /RegServer A Windows message will be displayed in an alert box if the registration fails. Issuing this command if the Redirector is already correctly installed is harmless. PI Server System Management Guide Page 259

282 Chapter 11 - PI Troubleshooting and Repair 2.) Check the Windows Event Log Run the Windows Event Viewer and select the Application log. The PI Redirector may write a message if it is able to start but not able to keep running. The Redirector will also fail to start if the Windows Event Log is full. Choose Clear All Events from the Log menu to clear the Application log. To prevent this from recurring, you may wish to change the event log settings. To do this, start the Application Log Properties dialog box. The default settings are shown in Figure Application Log Properties. Figure Application Log Properties Note: This screenshot is from Windows 2000; the Windows Server Properties dialog box is similar. The default settings can become a problem if your system generates a log file of 512Mb of messages within 7 days. You can avoid this problem by specifying a larger event log or by choosing the Overwrite events as needed radio button. Page 260

283 COM Connectors 3.) Run the Redirector Dump Script Every COM Connector implements a method for obtaining information on its mapped points. A script for requesting this information can be obtained from OSIsoft Technical Support Web site at In order for this script to work correctly, identity of the Redirector should be set to This user (a domain user with administrative privileges) in dcomcnfg. If the identity is set to The launching user, any logged in user who runs the script is likely to launch another instance of the Redirector. Such an instance of Redirector will not share information with the one launched by PI Base which contains the mapped point information. If a change is made to the identity setting, restart the Redirector by restarting Base, Snapshot, and Archive. Also, if the identity of the Redirector is set to a specific user, you should make sure that all out-of-process COM Connectors can be launched and accessed by this user COM Connector Troubleshooting If a COM Connector is successfully loaded by the Redirector, a message like this will be written to the Windows Event Log: Figure COM Connector Loading shows the result of the Redirector loading a simulator COM Connector. Figure COM Connector Loading PI Server System Management Guide Page 261

284 Chapter 11 - PI Troubleshooting and Repair If the COM Connector cannot be loaded, a message to this effect will be logged. Troubleshooting steps depend on how the COM Connector is implemented. COM Connectors are of two different types: in-process or out-of-process. The manual for the specific COM Connector you are using will tell you the Connector type. In-Process COM Connector An in-process COM Connector is implemented as a DLL. When the PI Base Subsystem loads a point that references the COM Connector, this DLL is loaded into the process space of the Redirector. You will not see a separate process running. Check the Windows Event Log. If the COM Connector is not registered, the message will say this. In this case, attempt to re-register the COM Connector by opening a Windows command window, setting your default directory to the location of the COM Connector DLL and running the regsvr32 utility. If the COM Connector DLL were named myconn.dll, you would issue the command: regsvr32 myconn.dll An alert box will be displayed if the COM object implemented by the DLL cannot be registered. A common cause of inability to register is DLLs upon which the COM object DLL depend are not installed. The missing DLLs may be those provided by the foreign data historian vendor. Note: In-process COM objects are not visible to the dcomcnfg utility. One way of seeing the DLLs loaded by the Redirector is to use the ListDLLs utility available from the SysInternals Web site Out-of-Process COM Connector This type of COM Connector will appear as a separate process in the Windows Task Manager window. You should also check the COM object properties using dcomcnfg. The Properties and Identity should match those of the Redirector, unless the COM Connector s manual says otherwise. If the COM Connector does not appear in the dcomcnfg list, it has not been successfully registered. Attempt to re-register the COM Connector by opening a Windows command window, setting your default directory to the location of the COM Connector executable and running it with the /RegServer switch. If the COM Connector executable were named myconn.exe, you would issue the command: myconn.exe /RegServer An alert box will be displayed if dependent DLLs are missing. Other errors are not displayed. Page 262

285 Chapter 12. FINDING AND FIXING PROBLEMS: THE PIDIAG UTILITY The pidiag utility is a collection of tools for diagnostics, information, and simple repairs. It is designed to help the PI System Manager and OSI Software technical support in gathering information about a PI System, troubleshooting and solving some common problems. The following sections explain in detail the various tools included in pidiag. To invoke pidiag: pidiag -xxx where xxx identifies one tool. Depending on the specific tool, some additional parameters might follow. The optional parameters are summarized in the following table and described in this section, unless otherwise noted in the table. Option -ad -adg <version> 'path' -ahd 'path' -ar -ara -archk 'path' [complete] -cid [ < ServerID > < APIServerID> ] [-install] [-upgrade] -crash -dapi [hostname] -did Description Dump archive manager data file. Downgrade archive file(s) to a specific version Dump the archive file header. Recover archive manager data file. Auto recover archive manager data file. Described in this chapter. Archive integrity check utility. Create Server ID file optionally passing Server ID and PI API ID. The PI API ID must be an integer. Server ID may be a GUID or an integer. - upgrade option creates Server ID file for a system upgrade. Server ID and PI API ID are set to integer based on host name. -install option creates Server ID file for a new installation. Server ID is set to a UID. The PI API ID is set to integer based on host name. Simulate a process crash. Create and display PI API Server ID based on supplied host name. Machine host name is used if host name is not supplied. Dump Server ID file. -e code Translate error code. PI Server System Management Guide Page 263

286 Chapter 12 - Finding and Fixing Problems: the pidiag Utility Option -fb 'path' -fbc 'path' -fbf 'path' < outpath > -gpc 'name' -host -machine Description Dump file base data file. Compact a file base data file. Recover (fix) file base data file index, optionally copying into a new file. Gets performance counter path. Display host information as used for Trust-Login. Machine and compile information. -n number Format and display number as various types. -qd [HeaderOnly RecNo=n PointId=<id>] 'path' -qs 'path' -rgs [-?] [-u] 'path' {ReplaceableParameter ="Value"} Dump header or all/filtered events from Event Queue file. Get offline queue file statistics. Register or unregister COM component by running.rgs script in 'path'. -t time {U} Convert timestamp to string. -tz {time} {TZ} [ -check -dump [-brief] -full ] -tz [ -if path -ifrule [path] ] [-of path] -udf 'path' -upc 'name' -uuid [count] Show timezone information. Special DST settings. Resets the piadmin (userid #1) password to blank. Uninstalls performance counters for named subsystem. Create and display "count" UIDs. 1 UID is created if "count" is not supplied. -v Version information. -w msec Wait for passed milliseconds. -xa <path> [ -st <start> -et <end> [-uid <unique id>] [-xh <schema url>] ] Export audit records. This option is documented in Auditing the PI Server. The pidiag utility resides in the PI\adm subdirectory. Page 264

287 General Information Tools that operate on files, such as compact and repair options should never be used with open files. This means in general, that they should be used only when the system is down. If in doubt, consult OSI technical support before using such tools. It is also advisable to make a backup copy of the data file before compressing or repairing. The following can be used to display a short help page with all the options. pidiag -h pidiag -? 12.1 General Information Version Information pidiag -v Displays the version of pidiag utility itself. In general this is the same version for all PI utilities and subsystems. D:\PI\adm>pidiag -v Version: PI Program: pidiag PI Path: D:\PI Error Code Translation To display text for a given error number, run: pidiag -e errorcode Positive numbers are operating system error codes, depending on the platform where the PI Server is running. Negative numbers are PI errors. C:\PI\adm>pidiag -e 2 [2] The system cannot find the file specified. C:\PI\adm>pidiag -e [-11002] Record Header Data Mismatch 12.2 Time Utilities Time Translations pidiag -t time <U> This provides translation between time string formats and internal formats: If time starts with 0 (zero) an integer format (seconds since 1-jan-70) is translated to string representation. pidiag assumes local time, unless the 3rd argument is U or UTC in which case the argument is taken to be universal time (GMT). If the first character is not 0, the time argument is treated as time string, absolute or relative, and translated into an integer value. Both local time and UTC integer values are displayed. PI Server System Management Guide Page 265

288 Chapter 12 - Finding and Fixing Problems: the pidiag Utility Note: On UNIX systems, you generally cannot specify an asterisk ( * ) by itself to mean current time unless you enclose it in double quotes. A single asterisk is interpreted by the shell as a wildcard search character. String to Integer Format C:\PI\adm>pidiag -t 1-sep 1-Sep-02 00:00:00 PDT - Local: UTC: C:\PI\adm>pidiag -t t+1h 21-Oct-02 01:00:00 PDT - Local: UTC: C:\PI\adm>pidiag -t "*" 21-Oct-02 20:00:10 PDT - Local: UTC: Integer Format to String C:\PI\adm>pidiag -t Oct-02 20:00:10 PDT - Local: UTC: C:\PI\adm>pidiag -t U 21-Oct-02 20:00:10 PDT - Local: UTC: Time Zone To show time zone information, run: pidiag -tz {time} {TZ} {-check -dump} Running pidiag -tz with no additional arguments shows The setting for the TZ environment variable The standard time zone name and the daylight time zone name in effect The general rules for DST transitions. The TZ environment variable should typically not be set. A StartYear, EndYear, Month, Week, Day, Time, and Offset define the daylight and standard time transition rules. C:\PI\adm>pidiag -tz TZ environment variable: <not set> Standard Time Name: Pacific Standard Time (PST) Daylight Time Name: Pacific Daylight Time (PDT) StartYear, EndYear, Month, Week, Day, Time, Offset 1970, 2038, 4, 1, 1, 7200, , 2038, 10, 5, 1, 7200, 0 The transitions rules are defined as follows. StartYear is the first year that the rule is in effect EndYear is the last year that the rule is in effect Month is the month (1-12) that the rule is applied. Week is the week (1-5) that the rule is applied. If week is 5 and there are only 4 weeks in the month, then 5 designates the last week in the month. If week is -1, then week is to be ignored and day becomes absolute. Page 266

289 Time Utilities If week is greater than 0, then day is the relative day (1-7) that the rule is applied. A day of 1 represents Sunday, a day of 2 represents Monday, and so on. For example, a week of 1 and a day of 1 means the first Sunday in April. If week is -1, then day is an absolute day (1-31). Time is the time in seconds after midnight that the rule is applied. Offset is the time in seconds to subtract from standard time to get the local time. For example, daylight saving time is in effect, is subtracted from standard time. Running pidiag -tz with the {time} argument will display the corresponding local and UTC times in seconds and whether the passed time is in standard or daylight saving time. If the time string is ambiguous, it is marked with an asterisk (*). Time strings are ambiguous if they specify a time in the last hour of daylight savings time before the beginning of standard time. In the northern hemisphere, this occurs in the fall. In the southern hemisphere, this occurs in the spring. C:\PI\adm>pidiag -tz "25-Oct-02 01:30:00" TZ environment variable: <not set> Standard Time Name: Pacific Standard Time (PST) Daylight Time Name: Pacific Daylight Time (PDT) StartYear, EndYear, Month, Week, Day, Time, Offset 1970, 2038, 4, 1, 1, 7200, , 2038, 10, 5, 1, 7200, 0 Passed Time: 25-Oct-02 01:30:00 PDT Local: UTC: If your time zone does not observe daylight savings time, the utility will indicate this. C:\PI\adm> pidiag -tz TZ environment variable: <not set> Standard Time Name: US Mountain Standard Time (UMST) Daylight Savings Time: <not observed> The -dump option dumps the whole time zone table. This includes fall/spring changes in every year. The dump is in comma-separated variable (CSV) format and can be loaded directly into a spreadsheet, providing all time-change information for the local time zone. The -dump option can be combined with -brief. The output with this option includes the year and spring and fall time changes, each marked with D or S to denote daylight or standard time. The -check option generates no output at all, unless the time zone settings on your system are invalid. The utility is used this way in the installation script on UNIX systems. Daylight Savings Time Changes PI uses an internally constructed table to determine when changes between Standard Time and Daylight Savings Time occur. On Windows, this table is built using the single time change rule available from the operating system. UNIX systems tend to store more yearspecific rules, but there are still issues for time zones in which the change rule is different from year to year. PI Server System Management Guide Page 267

290 Chapter 12 - Finding and Fixing Problems: the pidiag Utility PI now supports the loading of a time zone information table from a binary file called PI\dat\localhost.tz. If this file is present and valid, it is loaded and used for all time translations. The table can be constructed as follows: pidiag -tz -dump -brief > myzone.txt The record of the resulting text file contains year, spring time change, and fall time change. Edit the file to reflect the actual change times for your time zone. The file need not contain a record for every supported year; years that are not specified use the operating system generated rule. To install the new file, issue the command: pidiag -tz -if myzone.txt -of test.tz You can check the validity of test.tz by using pidiag to read it again, using the -if command. pidiag assumes that any file ending in.tz is a binary file; all others are assumed to be text. The -if command can be combined with any other. For example, to test the date 31-oct-02 01:30 using the new table, issue the command: pidiag -tz "31-oct-02 01:30" -if test.tz To dump the contents of a binary file to text, issue the command: pidiag -tz -if test.tz -dump > test.txt If the new timezone information table correctly represents the time transitions, copy the binary file to PI\dat\localhost.tz and restart PI. Doing this does not affect the timestamps of data already stored by PI, since these timestamps are stored as UTC. It affects only the translation of these stored times to local times. The timezone information now stores additional information such as the names of the applications that created or modified it, and the first time the table was put into service. This in-service time will be set on first system startup only if it was loaded from PI\dat\localhost.tz. To see this additional information, issue the command: pidiag -tz -full Different Time Zone If the TZ parameter is specified (in addition to time parameter), the transitions are shown as they would appear if that TZ environment variable were in effect. Note that the TZ argument follows the time/year argument, so you must provide a time string or year to use this feature. The specified time zone can be different from the local time zone. C:\PI\adm>pidiag -tz "*" GMT0BST TZ environment variable: GMT0BST Standard Time Name: GMT (GMT) Daylight Time Name: BST (BST) StartYear, EndYear, Month, Week, Day, Time, Offset 1970, 2037, 4, 1, 1, 7200, , 2037, 10, 5, 1, 7200, 0 Passed Time: 8-Oct-03 20:27:04 BST Local: UTC: Note: On UNIX systems, this feature can be used to determine whether or not the operating system recognizes your passed TZ string as valid. Displayed transition Page 268

291 File-base Utilities times, however, tend to reflect your system s current time zone settings. Changing a UNIX system s time zone settings requires platform-specific techniques. You should reboot your UNIX system after changing its time zone settings File-base Utilities Most of the PI System internal databases are stored as index files with specific internal organization. We call this structure file-base. The following tools are provided for diagnostics and repair of such database files. More information is available in PI Server Data Files in the chapter PI Troubleshooting and Repair. Caution: Do not use Compact or Recover tools on open files while the system is running! Dump File-base Data File pidiag -fb <path> This lists the inner structure of a file-base index. OSI technical support can determine from this information if any errors occur in the structure of the file: C:\PI\adm>pidiag -fb c:\pi\dat\pidigst.dat PIfilebaseheader:: File Name: C:\PI\dat\pidigst.dat Major Version: 2 Minor Version: 0 Directory Location: 1024 Directory Size: 512 Record Count: 4 Last Recno: 0 Maximum Recno: 64 User Block Size: 512 Data Location: 1536 Data Size: 2724 PIsecureobject[@(#)pisecobj.cxx /30/96]:: User ID: 1 Group ID: 1 Access: [113] [o:rw g:rw:r] Index Dump: Record, Offset, Size: 0, 2994, 1266 Record, Offset, Size: 1, 2839, 29 Record, Offset, Size: 2, 2887, 51 Record, Offset, Size: 3, 2956, Compact a File-base Data File pidiag -fbc <path> Following excessive add and delete operations, a file-base file might grow and contain some holes. This tool is provided to rebuild the file and compress the holes, thus saving some disk space. This occurs automatically for message files and the point database. PI Server System Management Guide Page 269

292 Chapter 12 - Finding and Fixing Problems: the pidiag Utility Recover File-base Data File Index pidiag -fbf <path> <outpath> The internal directory of a file-base database can be rebuilt from the data itself. This is needed in cases of index corruption. The optional outpath parameter instructs the utility to write the recovered output to a new file. In some cases a more complete recovery is possible that way Archive Management The commands in this section assist with archive file management Dump the Archive Manager Data File The Archive Manager data file contains the list of archive files currently known to the PI Server. The contents of the file can be dumped using the command: pidiag -ad When the Archive Subsystem is running, use the following command: piartool -al to provide this information. The file PI\dat\piarstat.dat contains information on all registered archives. C:\PI\adm>pidiag -ad Archive manager data file version is 1 Archive primary archive code is 1 Archive manager data file dump follows: PInt [$Workfile: pinttmpl.cxx $ $Revision: 13 $]:: Table contains 3 entries, with 3 total slots allocated. Extend size is 2 slots and the next icode is C:\PI\dat\piarch C:\PI\dat\piarch C:\PI\dat\piarch.003 Alphabetical index: C:\PI\dat\piarch.001 C:\PI\dat\piarch.002 C:\PI\dat\piarch.003 PIobject: End of Dump The -ad option may be used, for example, in a procedure to repair the archive registry. See How to Repair the Archive Registry in the chapter PI Troubleshooting and Repair Automatic Recovery of the Archive Manager Data File The command: pidiag -ara Page 270

293 Archive Management attempts an automatic recovery of the archive manager data file PI\dat\piarstat.dat. Caution: Use only when the PI Server is shut down! This option creates a new archive manager data file using the data in the existing data file. It can be used if the index in the current file is corrupted Manual Recovery of the Archive Manager Data File The command: pidiag -ar recovers the archive manager data file. Caution: Use only when the PI Server is shut down! This option creates a new archive manager data file. It prompts the user for the full path of the Primary Archive file. Upon restarting PI, this file will be the only archive registered. This option is useful when moving a PI Server to another machine, or when running the same point configuration with different sets of archives. If the archive manager file is corrupted, try first the -ara option. If that does not help, use -ar option. More information on using the -ar and -ara options is provided in How to Repair the Archive Registry in the chapter PI Troubleshooting and Repair. Note: The command pidiag -ara can be also used to downgrade the format of the archive registry from to earlier versions of the PI Archive Information about Unregistered Archives It is frequently necessary to obtain information about Archive files that are not currently registered. To do this, use the command: for example: pidiag -ahd <path> pidiag -ahd d:\pi\dat\piarch.001 The output is similar to the output from piartool -al for a single Archive file: E:\PI\Adm>pidiag -ahd e:\pi\dat\piarch.001 PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 47 $]:: Version: 6 Path: e:\pi\dat\piarch.001 State: 3 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: Offsets: Primary: 8192/8192 Overflow: 28591/32768 Start Time: 4-Apr-03 18:19:41 End Time: 4-Apr-03 19:53:41 Backup Time: Never Annotations: 1/65535 End of Dump PI Server System Management Guide Page 271

294 Chapter 12 - Finding and Fixing Problems: the pidiag Utility For examples on using the -ahd option, see Restoring a Complete Server from Backup, Restoring Archive Files from Backup, or Recovering from Unintended Change to System Time in the chapter PI Troubleshooting and Repair. Note: This command can only be used if the archive file is not registered, or if the PI Server is down. If you use it with a registered Archive file, pidiag will return an access error Verify the Integrity of Archive Files Command syntax: pidiag -archk 'path' [complete] The -archk command can be used to perform integrity checks or extract statistics from archive files that are not registered. Below is an example report after running the command on an archive file: Analyzing archive: D:\PI\dat\piarch recno: 1 id: 1 indices: 1 records: 5 events: 636 fr: 89.4% recno: 2 id: 2 indices: 1 records: 5 events: 631 fr: 88.6% recno: 3 id: 3 indices: 2 records: 278 events: fr: 99.5% recno: 4 id: 4 indices: 7 records: 866 events: fr: 99.6% recno: 5 id: 5 indices: 1 records: 23 events: 3202 fr: 97.3% recno: 6 id: 6 indices: 1 records: 31 events: 4355 fr: 96.6% recno: 7 id: 7 indices: 1 records: 39 events: 5534 fr: 98.4% recno: 8 id: 8 indices: 1 records: 27 events: 3981 fr: 98.7% recno: 9 id: 9 indices: 1 records: 6 events: 1340 fr: 89.7% recno: 10 id: 10 indices: 1 records: 19 events: 4646 fr: 98.3% recno: 11 id: 17 indices: 6 records: 1092 events: fr: 48.0% recno: 12 id: 18 indices: 0 records: 1 events: 69 fr: 48.4% recno: 13 id: 14 indices: 0 records: 1 events: 1 fr: 0.8% recno: 14 id: 15 indices: 0 records: 1 events: 1 fr: 0.8% recno: 15 id: 16 indices: 0 records: 1 events: 1 fr: 0.8% recno: 16 id: 19 indices: 0 records: 1 events: 0 fr: 0.0% recno: 17 id: 24 indices: 0 records: 1 events: 0 fr: 0.0% recno: 18 id: 0 indices: 0 records: 1 events: 0 fr: 0.0% recno: 19 id: 0 indices: 0 records: 1 events: 0 fr: 0.0% errors detected 23 total index records 2399 total data records total events events per record total annotations The above listing include for every point (sorted by record number or recno ), the number of index records ( indices ), the number of data records, the count of events in all records and the average fill ratio ( fr ). Points receiving events in order and no edits or remove events will typically have a fill ratio close to 100%. Note: Since the last record in a chain is rarely full, the fill ratio is almost never going to be exactly at 100%. Page 272

295 Archive Management Looking at archive statistics and in order to maintain best performance, points should not have more than one or two index records on average. If this is not the case for many points, compression parameters should be reviewed for these points or the archive files should be made smaller. In the above example, points 4 and 17 (recnos 4 and 11 respectively) clearly have an excessive number of index records. The archive check command will detect and report any errors in the archive file. Errors are summarized at the end of the report but when running the command, they are sent to the standard error (stderr) stream. As a result, when redirecting the output to a file, the following syntax should be used so that errors are inserted into the output file report.txt: pidiag -archk "archive_file" > report.txt 2>&1 Alternatively, the following construct can be used to redirect the output to two different files: pidiag -archk "archive_file" 1> report.txt 2> errors.txt The archive errors or corruptions could be the result of failures (crash, unexpected termination, power failure, etc) or software bugs. In the case this happens, the offline archive utility can be used to reprocess the corrupted archive file, recover the data and fix all issues. For more information, see Using the Offline Archive Utility (piarchss) on page 40. The -archk command can also be run with the optional argument complete, in order to extract detailed information about the archive file structure. This extra information is similar to what is provided by the archive walk command (see piartool -aw). It notably includes point types and statistics (start time, event count, fill ratio) for every index or data record and for each point in the archive file. The archive header information (see pidiag -ahd above) is also included at the beginning of the report. Here is an example of the detailed mode: D:\PI\adm>pidiag -archk D:\PI\dat\piarch.001 complete Analyzing archive: D:\PI\dat\piarch PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Version: 7 Path: D:\PI\dat\piarch.001 State: 3 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: 1.7 Offsets: Primary: 20/65536 Overflow: / Annotations: 10826/65535 Annotation File Size: Start Time: 19-Oct-05 12:39:10 End Time: Current Time Backup Time: Never Last Modified: 19-Dec-05 18:09:15 recno: 1, id: 1, events: 636, annotations: 0, fr: 89.4% - (Float32) index array size: 1 0: idxrec id: 1, record pointers: 5, total events: 636 record array size: 5 0: record id: , start: 19-Oct-05 12:39:10, events: 142, fr: 99.4% 1: record id: , start: 30-Oct-05 15:33:27, events: 142, fr: 99.7% 2: record id: , start: 12-Nov-05 09:29:36, events: 142, fr: 99.9% 3: record id: , start: 22-Nov-05 04:44:08, events: 142, fr: 99.9% 4: record id: , start: 15-Dec-05 13:31:42, events: 68, fr: 47.9% [...] PI Server System Management Guide Page 273

296 Chapter 12 - Finding and Fixing Problems: the pidiag Utility Downgrade Archive File to Older Versions Command syntax: pidiag -adg <version> 'path' The -adg command offers the ability to downgrade archive files, so they can be mounted by older versions of the PI Archive. Archive file versions are displayed in the archive header information (see previous section about pidiag -ahd). The following table shows the archive file versions of the most recently released PI Servers: PI Server Version(s) Archive Version / Note: PIdiag -adg accepts wildcard characters in the path argument (example: D:\PI\dat\piarch.* ). This allows performing easy downgrade of many archive files in a single command. Example, converting an archive file from PI to : D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005 PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Path: D:\PI\dat\piarch.005 State: 4 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: 0.0 Offsets: Primary: 17/65536 Overflow: / Annotations: 1/65535 Annotation File Size: 2064 Start Time: 1-Jan-04 00:00:00 End Time: 1-Jan-05 00:00:00 Backup Time: Never Last Modified: 15-Nov-05 18:37:37 Conversion command: D:\PI\adm>pidiag -adg 6 D:\PI\dat\piarch.005 Processing: D:\PI\dat\piarch [0] Success D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005 PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]:: Path: D:\PI\dat\piarch.005 State: 3 Type: 0 Write Flag: 1 Shift Flag: 1 Record Size: 1024 Count: Add Rate/Hour: 0.0 Offsets: Primary: 17/65536 Overflow: / Annotations: 1/65535 Annotation File Size: 2064 Start Time: 1-Jan-04 00:00:00 End Time: 1-Jan-05 00:00:00 Backup Time: Never End of Dump Page 274

297 Server ID Utilities 12.5 Server ID Utilities As of PI 3.3 SR1, the Server ID of the PI Server is stored in the PI\dat\PISysID.dat file. The first time that any PI-SDK application connects to a PI Server from a given node, the PI-SDK caches this server ID in the client s local Registry. On subsequent connections, PI-SDK applications compare the cached Server ID to the actual Server ID of the PI Server during the Server.Open call to make sure that a connection is being made to the same PI Server. Although the PISysID.dat file did not exist before PI 3.3 SR1, the PI Server still returned a Server ID to PI-SDK applications. The PI Server used a hashing algorithm to determine the Server ID, which took the name of the machine as input and generated a number as output. This number was not a globally unique identifier (GUID), which meant that the hashing algorithm could generate the same numeric identifier from two different machine names. If PI 3.3 SR1 or greater is installed as a new system, the Server ID is generated as a GUID and stored in the PISysID.dat file. If PI 3.3 SR1 or greater is installed as an upgrade from a system that is less than 3.3 SR1, then the Server ID is generated using the old hashing algorithm and stored in the in the PISysID.dat file. There are three pidiag options, -dapi, -cid, and -did, that can be used to troubleshoot or to generate a PISysID.dat file. The -dapi option echoes a Server ID to the standard output using the old hashing algorithm. The usage is: pidiag -dapi [hostname] If hostname is not passed, then the host name of the machine is used in the hashing algorithm. Here is some example output from the -dapi option. pidiag -dapi MyServer Host: MyServer API Server ID: 6239 The -cid option generates a new PISysID.dat file. The usage is: -cid [ < ServerID > < APIServerID> ] install] [-upgrade] The optional APIServerID that can be passed on the command line is not used by any application. If the optional ServerID is passed on the command line, simply pass the same identifier for the APIServerID. The -install option causes the Server ID to be generated as a GUID. The -upgrade option causes the Server ID to be generated using the old hashing algorithm. The -did option dumps the contents of the PISysID.dat file. pidiag -did Dumping file E:\PI\dat\PISysID.dat 1. MajorVersion: 3 2. MinorVersion: 3 3. MajorBuild: MinorBuild: ServerID: 1eb5cdbe a5-900d ee43ea 6. APIServerID: A new PISysID.dat file would need to be generated in the following scenario: Suppose that you have a pre-sr1, PI 3.3 Server that you want to move to a different node. The new machine will be given the same name as the old machine after the migration is complete. PI Server System Management Guide Page 275

298 Chapter 12 - Finding and Fixing Problems: the pidiag Utility Install PI 3.3 SR1 on the new node and copy the archive files from the old PI 3.3 system to the new node. A PISysID.dat file on the new 3.3 SR1 Server will be generated with a GUID as the Server ID because the 3.3 SR1 install was not an upgrade. It would be desirable to create a PISysID.dat file with a Server ID that was generated with the old hashing algorithm so that old PI-SDK applications will not complain when they are connecting to the new server. This new file can be generated as follows. pidiag -dapi MyServer Host: MyServer API Server ID: 6239 pidiag -cid Alternatively, if the name of the new Server has already been changed to MyServer, the new file can be generated as follows. pidiag -cid -upgrade 12.6 Performance Counter Utilities (Windows Only) Get Performance Counter Path The -gpc option of pidiag can be used to help configure performance counter tags for use with the PI Performance Monitor interface. From a command prompt, type the command pidiag -gpc to bring up the Get Counter Path Dialog. Select counters from the dialog and click the Add button. Clicking the Add button causes the full path of the performance counter to be echoed to the command prompt. The format of the path is the same format used by the PI Performance Monitor Interface. Once all desired counters have been echoed to the command prompt, the output can be used in conjunction with the PI TagConfigurator Excel Add-In for building PI Performance Monitor Tags Uninstall Performance Counters The -upc option of pidiag uninstalls performance counters for the specified subsystem for debugging purposes. For example pidiag -upc pinetmgr removes the Registry key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\pinetmgr\Performance and all of its values. Stopping and starting pinetmgr as a service, re-installs the performance counters Get Performance Counter Values The -gmmf option of pidiag can be useful to check the definition or get the current values of PI performance counters. These performance counters are exposed by all PI Subsystems and are available through the standard Windows Performance Counter API. The PI Perf-Mon Page 276

299 Performance Counter Utilities (Windows Only) Interface (the Basic version is included with the PI Server distribution) can easily be set up to historize the value of these performance counters in the PI Archive, as well as the OSprovided ones. The following table shows the list of Performance Counter object names for the main PI Subsystems: Subsystem Main Counters Session Statistics Subsystem Statistics PI Network Manager pinetmgr_counters N/A N/A PI Message Subsystem pimsgss_counters PISession:pimsgss PISubsys:pismsgss PI License Manager pilicmgr_counters PISession:pilicmgr PISubsys:pilicmgr PI Update Manager piupdmgr_counters PISession:piupdmgr PISubsys:piupdmgr PI Base Subsystem pibasess_counters PISession:pibasess PISubsys:pibasess PI Snapshot Subsystem pisnapss_counters PISession:pisnapss PISubsys:pisnapss PI Archive Subsystem piarchss_counters PISession:piarchss PISubsys:piarchss Important Notes These object names are case sensitive. PIdiag will return a system error 2 when mistyped. These objects are all defined in the global namespace of Windows. As a result, their names must always be prefixed by the string Global\ (case-sensitive). Example: C:\PI\adm>pidiag -gmmf Global\pibasess_Counters Performance counters for MMF Global\pibasess_Counters Point Count: Connector Point Count: 0 Point Create or Edit/sec: 0 Digital State Translations/sec: 165 Wild Card Searches/sec: 200 Point Accesses/sec: Module Count: 20 Heading Set Count: 0 Heading Count: 0 Module Database Record Count: 24 Module Create or Edit/sec: 0 Heading Set Create or Edit/sec: 0 Heading Create or Edit/sec: 0 Module Database Create or Edit/sec: 0 Module Accesses/sec: 94 Heading Set Accesses/sec: 0 Heading Accesses/sec: 0 Module Database Accesses/sec: 94 PI Server System Management Guide Page 277

300 Chapter 12 - Finding and Fixing Problems: the pidiag Utility 12.7 Miscellaneous Wait for Passed Milliseconds The command to wait for passed milliseconds is: pidiag -w msec This is used in several PI command procedures Testing Crash Dump Capability of an OS The command to crash the pidiag utility by accessing a non-existent element of an array is: pidiag -crash This is used to test the crash dump capability of a particular operating system: Dr. Watson on Windows and core on UNIX. PIdiag, when run with the -crash argument purposely raises an operating system exception; in other words, it purposely crashes. This is used to test the installed just-in-time debugger. Windows Only Dr. Watson is the default just-in-time Windows debugger. Debuggers, including Dr. Watson, rely on debug symbols to translate code addresses to line numbers and meaningful text. The PI System installs these symbols in %SystemRoot%\Symbols\exe directory where SystemRoot is typically C:\Windows. The system environment variable, _NT_SYMBOLS_PATH, must include this full path. On a crash, if this path is not included in _NT_SYMBOLS_PATH the crash symbols will not be correctly interpreted Reset Password to Blank The command to reset the piadmin (userid #1) password to blank is: pidiag -udf <path> This is useful when the piadmin password is lost. Following this operation, the piadmin password can be set to any given string using the pisetpass utility. For example, e:\pi\adm>pidiag -udf e:\pi\dat\ The administrative password has been successfully reset. The administrative account is piadmin. Note: The PI Base Subsystem must be shut down for this command to succeed. Also notice the path argument requires a trailing \ or / character Display Network Definitions The command to display the network definitions of a computer is: pidiag -host This option may be used on nodes running client applications and interfaces, to help the definition of trust login records. For example: Page 278

301 Miscellaneous d:\pi\adm>pidiag -host Domain <OSI> Machine <bilbo> User <Bagins> IP Addr < > Primary Domain Controller: <\\MASTERDC> This option also tests the availability of the Domain Controller. This call should complete is a fraction of a second; if it hangs or takes more than a few seconds to return it indicates the Domain Controller access may not be fast or consistent. Failure to have prompt access to the Domain Controller will result in poor PI System performance Register a COM Component pidiag -rgs This registers a COM component by running the input registration script. The script should have all the necessary registry information to launch and access the component. This utility is useful if the COM component is to run remotely from a client node and the client node does not have all the necessary.dll's in order to instantiate it locally, which is required in order for the component to self-register. The component should be provided with the script. pidiag -rgs [-?] [-u] FILENAME.RGS [Replaceable Parameter="Value"] Arguments in square brackets [ ] are optional. -? Displays this help dialog -u Performs unregistration Replaceable Parameter - Anything in the RGS file surrounded by % is a replaceable parameter. For example: %MODULE%. Value - You must provide a value for replaceable parameters. For example, to register an RGS file that contains %MODULE% in the script as below: HKCR { NoRemove CLSID { ForceRemove {8FC8B7BC-0C07-11D4-84C4-00C04F6102DF} = s 'UDSSim4 Class' { ProgID = s 'Demo4.UDSSim4.1' VersionIndependentProgID = s 'Demo4.UDSSim4' ForceRemove 'Programmable' LocalServer32 = s '%MODULE%' val AppID = s '{8FC8B7B0-0C07-11D4-84C4-00C04F6102DF}' PI Server System Management Guide Page 279

302 Chapter 12 - Finding and Fixing Problems: the pidiag Utility 'TypeLib' = s '{8FC8B7AF-0C07-11D4-84C4-00C04F6102DF}' } } } pidiag -rgs MYOBJECT.RGS MODULE= "c:\program Files\MyProgram\myobject.exe" GUID Generation The -uuid options of pidiag can be used to generate globally unique identifiers, known as GUIDs. pidiag -uuid 43157bae e-b0f6-a3c1581fe86a Machine-specific Programming Information The -machine option of pidiag can be used to print out machine-specific information that may be useful for programmers. On Windows machines, this option also provides details about the processor architecture of the local machine. The number of processors (both physical and logical) is shown, as well as information on the presence of Intel Hyper- Threading Technology. pidiag -machine CPU Architecture: INTEL Physical/Logical Processors: 1/2 Hyper-Threading Status: 1 (enabled) System appears to be little endian. PI System built as little endian. long integers are 4 bytes. TCHARs are 1 byte. Pointers are 4 bytes. Enumerations are 4 bytes. int8s are 1 byte. uint8s are 1 byte. int16s are 2 bytes. uint16s are 2 bytes. int32s are 4 bytes. uint32s are 4 bytes. int64s are 8 bytes. uint64s are 8 bytes. float32s are 4 bytes. float64s are 8 bytes. Page 280

303 APPENDIX A: PI MESSAGES This chapter discusses the messages that PI writes to its message logs during normal operation. Messages are written to the message log by the PI Message Subsystem. Use the pigetmsg utility in the PI\adm directory to retrieve messages. Normal Startup Messages The following messages are typical when the PI System is started: 0 pinetmgr 27-Oct-05 16:23:12 >> WorkingSet Parameters changed, Current settings: , 1984MB, Previous settings: , MB 0 pinetmgr 27-Oct-05 16:23:12 >> Local listener opened 0 pinetmgr 27-Oct-05 16:23:12 >> Starting main control loop. 0 pimsgss 27-Oct-05 16:23:14 >> PI Message subsystem starting 0 pimsgss 27-Oct-05 16:23:14 >> Starting PI process pimsgss. 0 pinetmgr 27-Oct-05 16:23:14 >> Connection accepted: Process name: pimsgss(3852) ID: 0 0 pimsgss 27-Oct-05 16:23:14 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pinetmgr 27-Oct-05 16:23:15 >> Servertablelist received from: pimsgss(3852). 3 entries: PImsg 1 pimsgss_subsysquery 1 pimsgss_dbsecurity 1 0 pinetmgr 27-Oct-05 16:23:15 >> Connection accepted: Process name: pilicmgr(3228) ID: 1 0 pilicmgr 27-Oct-05 16:23:15 >> Starting PI process pilicmgr. 0 pinetmgr 27-Oct-05 16:23:16 >> Servertablelist received from: pilicmgr(3228). 3 entries: pilicmgr 1 pilicmgr_subsysquery 1 pilicmgr_dbsecurity 1 0 pinetmgr 27-Oct-05 16:23:17 >> Connection accepted: Process name: piartool(2568) ID: 2 0 pilicmgr 27-Oct-05 16:23:17 >> PI subsystem pilicmgr is now running, version: PI pilicmgr 27-Oct-05 16:23:17 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB PI Server System Management Guide Page 281

304 Page pilicmgr 27-Oct-05 16:23:17 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:23:20 >> Connection accepted: Process name: piartool(3772) ID: 3 0 pinetmgr 27-Oct-05 16:23:23 >> Connection accepted: Process name: piartool(2560) ID: 4 0 pinetmgr 27-Oct-05 16:23:25 >> Connection accepted: Process name: piupdmgr(3184) ID: 5 0 piupdmgr 27-Oct-05 16:23:25 >> Starting PI process piupdmgr. 0 pinetmgr 27-Oct-05 16:23:26 >> Connection accepted: Process name: piartool(2588) ID: 6 0 pinetmgr 27-Oct-05 16:23:26 >> Servertablelist received from: piupdmgr(3184). 4 entries: piupdmgr 1 piupdmgr 2 piupdmgr_subsysquery 1 piupdmgr_dbsecurity 1 0 piupdmgr 27-Oct-05 16:23:27 >> PI subsystem piupdmgr is now running, version: PI piupdmgr 27-Oct-05 16:23:27 >> WorkingSet Parameters changed, Current settings: , 1984MB, Previous settings: , MB 0 piupdmgr 27-Oct-05 16:23:27 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:23:29 >> Connection accepted: Process name: pibasess(2732) ID: 7 0 pinetmgr 27-Oct-05 16:23:29 >> Connection accepted: Process name: piartool(3124) ID: 8 0 pibasess 27-Oct-05 16:23:29 >> Starting PI process pibasess. 0 pinetmgr 27-Oct-05 16:23:30 >> Servertablelist received from: pibasess(2732). 6 entries: piptss 1 piusss 1 piptsdk 1 PIModuleDbSDK 1 pibasess_subsysquery 1 pibasess_dbsecurity 1 0 pibasess 27-Oct-05 16:23:31 >> PI subsystem pibasess is now running, version: PI pibasess 27-Oct-05 16:23:31 >> WorkingSet Parameters changed, Current settings: , 1984MB, Previous settings: , MB 0 pibasess 27-Oct-05 16:23:31 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:23:32 >> Connection accepted: Process name: pisnapss(3720) ID: 9 0 pisnapss 27-Oct-05 16:23:32 >> Starting PI process pisnapss. 0 pievqwriter 27-Oct-05 16:23:33 >> Primary Queue successfully initialized (64MB/1024KB) 0 pinetmgr 27-Oct-05 16:23:33 >> Connection accepted: Process name: piartool(2728) ID: 10 0 pinetmgr 27-Oct-05 16:23:34 >> Servertablelist received from: pisnapss(3720). 3 entries: pisnapss 1 pisnapss_subsysquery 1 pisnapss_dbsecurity 1 0 pisnapmgr 27-Oct-05 16:23:34

305 >> Snapshot records loaded, count: 13, found: 13, status: [0] Success 0 pisnapmgr 27-Oct-05 16:23:34 >> PIsnapmgr::loadsnaptables: loaded: C:\PI\dat\piarcmem.dat, status: [0] Success 0 pisnapss 27-Oct-05 16:23:35 >> PI subsystem pisnapss is now running, version: PI pisnapss 27-Oct-05 16:23:35 >> WorkingSet Parameters changed, Current settings: , 1984MB, Previous settings: , MB 0 pisnapss 27-Oct-05 16:23:35 >> Digital State table synchronized with Base Subsystem 0 pisnapss 27-Oct-05 16:23:35 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:23:35 >> Deleting connection: piartool(2568), Shutdown request received from piartool(2568) (8), ID: 2 0 Connection Statistics 27-Oct-05 16:23:35 >> ID: 2; Duration: 0.03 min.; kbytes sent: 4.90; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:35 >> Deleting connection: piartool(3772), Shutdown request received from piartool(3772) (8), ID: 3 0 Connection Statistics 27-Oct-05 16:23:35 >> ID: 3; Duration: 0.03 min.; kbytes sent: 4.90; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:36 >> Connection accepted: Process name: piarchss(356) ID: 11 0 pinetmgr 27-Oct-05 16:23:36 >> Connection accepted: Process name: piartool(2720) ID: 12 0 piarchss 27-Oct-05 16:23:36 >> Starting PI process piarchss. 0 pievqreader 27-Oct-05 16:23:37 >> Primary Queue successfully loaded (0 events) 0 piarcmgr 27-Oct-05 16:23:37 >> Primary archive file C:\PI\dat\piarch.001 loaded. 0 piarcmgr 27-Oct-05 16:23:37 >> Archive file C:\PI\dat\piarch.002 loaded. 0 piarcmgr 27-Oct-05 16:23:37 >> Archive file C:\PI\dat\piarch.003 loaded. 0 piarcmgr 27-Oct-05 16:23:37 >> Cache Manager: cache pool set to 2048 records, maximum unflushed events per point is pinetmgr 27-Oct-05 16:23:37 >> Servertablelist received from: piarchss(356). 5 entries: piarss 1 piarss2 1 piarbatch 1 piarchss_subsysquery 1 piarchss_dbsecurity 1 0 piarchss 27-Oct-05 16:23:38 >> PI subsystem piarchss is now running, version: PI piarchss 27-Oct-05 16:23:38 >> WorkingSet Parameters changed, Current settings: , 1984MB, Previous settings: , MB 0 piarchss 27-Oct-05 16:23:38 PI Server System Management Guide Page 283

306 Page 284 >> Digital State table synchronized with Base Subsystem 0 piarchss 27-Oct-05 16:23:38 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:23:39 >> Connection accepted: Process name: piartool(3544) ID: 13 0 pinetmgr 27-Oct-05 16:23:42 >> Connection accepted: Process name: piartool(3920) ID: 14 0 pinetmgr 27-Oct-05 16:23:44 >> Connection accepted: Process name: piartool(1984) ID: 15 0 pinetmgr 27-Oct-05 16:23:47 >> Deleting connection: piartool(2728), Shutdown request received from piartool(2728) (8), ID: 10 0 Connection Statistics 27-Oct-05 16:23:47 >> ID: 10; Duration: 0.03 min.; kbytes sent: 23.77; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:47 >> Deleting connection: piartool(2560), Shutdown request received from piartool(2560) (8), ID: 4 0 Connection Statistics 27-Oct-05 16:23:47 >> ID: 4; Duration: 0.05 min.; kbytes sent: 4.76; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:47 >> Deleting connection: piartool(2588), Shutdown request received from piartool(2588) (8), ID: 6 0 Connection Statistics 27-Oct-05 16:23:47 >> ID: 6; Duration: 0.03 min.; kbytes sent: 4.76; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:47 >> Deleting connection: piartool(3124), Shutdown request received from piartool(3124) (8), ID: 8 0 Connection Statistics 27-Oct-05 16:23:47 >> ID: 8; Duration: 0.03 min.; kbytes sent: 8.30; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:47 >> WorkingSet Parameters: MB, 1984MB. 0 pinetmgr 27-Oct-05 16:23:47 >> Connection accepted: Process name: piartool(3724) ID: 16 0 pinetmgr 27-Oct-05 16:23:50 >> Connection accepted: Process name: piartool(3052) ID: 17 0 pinetmgr 27-Oct-05 16:23:53 >> Connection accepted: Process name: piartool(3684) ID: 18 0 pinetmgr 27-Oct-05 16:23:56 >> Connection accepted: Process name: piartool(2184) ID: 19 0 pinetmgr 27-Oct-05 16:23:58 >> Deleting connection: piartool(1984), Shutdown request received from piartool(1984) (8), ID: 15 0 Connection Statistics 27-Oct-05 16:23:58 >> ID: 15; Duration: 0.05 min.; kbytes sent: 35.21; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:58

307 >> Deleting connection: piartool(3920), Shutdown request received from piartool(3920) (8), ID: 14 0 Connection Statistics 27-Oct-05 16:23:58 >> ID: 14; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv: 0.54; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:58 >> Deleting connection: piartool(3544), Shutdown request received from piartool(3544) (8), ID: 13 0 Connection Statistics 27-Oct-05 16:23:58 >> ID: 13; Duration: 0.03 min.; kbytes sent: 35.21; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:58 >> Deleting connection: piartool(2720), Shutdown request received from piartool(2720) (8), ID: 12 0 Connection Statistics 27-Oct-05 16:23:58 >> ID: 12; Duration: 0.03 min.; kbytes sent: 26.59; kbytes recv: 0.54; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:23:58 >> Connection accepted: Process name: pishutev(2540) ID: 20 0 pishutev 27-Oct-05 16:23:58 >> Starting PI process pishutev. 0 pishutev 27-Oct-05 16:24:00 >> PI subsystem pishutev is now running, version: PI pishutev 27-Oct-05 16:24:00 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pishutev 27-Oct-05 16:24:00 >> Shutdown input file: C:\PI\dat\shutdown.dat. 0 pishutev 27-Oct-05 16:24:00 >> Shutdown events will be written for tag mask * Point attributes: shutdown, 1 0 pinetmgr 27-Oct-05 16:24:01 >> Connection accepted: Process name: piartool(3780) ID: 21 0 pinetmgr 27-Oct-05 16:24:03 >> Connection accepted: Process name: pisqlss(3388) ID: 22 0 pisqlss 27-Oct-05 16:24:03 >> Starting PI process pisqlss. 0 pinetmgr 27-Oct-05 16:24:05 >> Servertablelist received from: pisqlss(3388). 3 entries: pisqlss 1 pisqlss_subsysquery 1 pisqlss_dbsecurity 1 0 pinetmgr 27-Oct-05 16:24:05 >> Connection accepted: Process name: piartool(2748) ID: 23 0 pisqlss 27-Oct-05 16:24:06 >> PI subsystem pisqlss is now running, version: PI pisqlss 27-Oct-05 16:24:06 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pisqlss 27-Oct-05 16:24:06 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:24:08 PI Server System Management Guide Page 285

308 Page 286 >> Connection accepted: Process name: pibackup(3496) ID: 24 0 pibackup 27-Oct-05 16:24:08 >> Starting PI process pibackup. 0 pinetmgr 27-Oct-05 16:24:09 >> Deleting connection: piartool(2184), Shutdown request received from piartool(2184) (8), ID: 19 0 Connection Statistics 27-Oct-05 16:24:09 >> ID: 19; Duration: 0.05 min.; kbytes sent: 35.21; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:09 >> Deleting connection: piartool(3684), Shutdown request received from piartool(3684) (8), ID: 18 0 Connection Statistics 27-Oct-05 16:24:09 >> ID: 18; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:09 >> Deleting connection: piartool(3052), Shutdown request received from piartool(3052) (8), ID: 17 0 Connection Statistics 27-Oct-05 16:24:09 >> ID: 17; Duration: 0.03 min.; kbytes sent: 35.21; kbytes recv: 0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:09 >> Deleting connection: piartool(3724), Shutdown request received from piartool(3724) (8), ID: 16 0 Connection Statistics 27-Oct-05 16:24:09 >> ID: 16; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv: 0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:10 >> Servertablelist received from: pibackup(3496). 3 entries: pibackup 1 pibackup_subsysquery 1 pibackup_dbsecurity 1 0 pinetmgr 27-Oct-05 16:24:10 >> Connection accepted: Process name: piartool(3256) ID: 25 0 pibackup 27-Oct-05 16:24:11 >> PI subsystem pibackup is now running, version: PI pibackup 27-Oct-05 16:24:11 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pibackup 27-Oct-05 16:24:11 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:24:12 >> TCP/IP (IPV4) connection listener opened on port: pinetmgr 27-Oct-05 16:24:13 >> Connection accepted: Process name: pitotal(1804) ID: 26 0 pitotal 27-Oct-05 16:24:13 >> Starting PI process pitotal. 0 pinetmgr 27-Oct-05 16:24:15 >> Connection accepted: Process name: piartool(1152) ID: 27 0 pinetmgr 27-Oct-05 16:24:18 >> Connection accepted: Process name: pialarm(3300) ID: 28 0 pialarm 27-Oct-05 16:24:18 >> Starting PI process pialarm.

309 0 pinetmgr 27-Oct-05 16:24:20 >> Deleting connection: piartool(2748), Shutdown request received from piartool(2748) (8), ID: 23 0 Connection Statistics 27-Oct-05 16:24:20 >> ID: 23; Duration: 0.05 min.; kbytes sent: 38.44; kbytes recv: 0.54; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:20 >> Servertablelist received from: pialarm(3300). 3 entries: pialarm 1 pialarm_subsysquery 1 pialarm_dbsecurity 1 0 pinetmgr 27-Oct-05 16:24:20 >> Deleting connection: piartool(3780), Shutdown request received from piartool(3780) (8), ID: 21 0 Connection Statistics 27-Oct-05 16:24:20 >> ID: 21; Duration: 0.05 min.; kbytes sent: 35.06; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:20 >> Connection accepted: Process name: piartool(2592) ID: 29 0 pialarm 27-Oct-05 16:24:21 >> PI subsystem pialarm is now running, version: PI pialarm 27-Oct-05 16:24:21 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pialarm 27-Oct-05 16:24:21 >> Initializing alarms. 0 pialarm 27-Oct-05 16:24:21 >> Registered to update manager as a consumer 0 pialarm 27-Oct-05 16:24:21 >> Registered for point updates. 0 pialarm 27-Oct-05 16:24:21 >> Initialize group tags (pointsource G ) 0 pialarm 27-Oct-05 16:24:21 >> 0 alarm group tags. 0 alarm groups. 0 pialarm 27-Oct-05 16:24:21 >> Restarting from save file C:\PI\dat\pilastalarm.dat 0 pialarm 27-Oct-05 16:24:21 >> 0 alarm tags. 0 pialarm 27-Oct-05 16:24:21 >> Initialize SQC alarm tags (pointsource Q ) 0 pialarm 27-Oct-05 16:24:21 >> 0 sqc alarm tags. 0 pialarm 27-Oct-05 16:24:21 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:24:23 >> PInet accepted TCP/IP connection, cnxn ID 30 Hostname: samson.osisoft.com, : pinetmgr 27-Oct-05 16:24:23 >> New Pinet 1 connection: PipeE Protocol: pinetmgr 27-Oct-05 16:24:23 >> New Pinet 1 connection: PipeE Successful Trust-Relation login: samson.osisoft.com PipeE piadmin. 0 pinetmgr 27-Oct-05 16:24:23 PI Server System Management Guide Page 287

310 Page 288 >> Connection accepted: Process name: PIPESCHD(2076) ID: 31 0 pinetmgr 27-Oct-05 16:24:25 >> Servertablelist received from: pitotal(1804). 3 entries: pitotal 1 pitotal_subsysquery 1 pitotal_dbsecurity 1 0 pinetmgr 27-Oct-05 16:24:25 >> Connection accepted: Process name: piartool(2628) ID: 32 0 pitotal 27-Oct-05 16:24:26 >> PI subsystem pitotal is now running, version: PI pitotal 27-Oct-05 16:24:26 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pitotal 27-Oct-05 16:24:26 >> Registered to update manager as a consumer 0 pitotal 27-Oct-05 16:24:26 >> Registered for point updates. 0 pitotal 27-Oct-05 16:24:26 >> Restarting from save file C:\PI\dat\pilasttot_T.dat 0 pitotal 27-Oct-05 16:24:26 >> Startup complete - 0 active points. 0 pitotal 27-Oct-05 16:24:26 >> Rpcservertablelist successfully registered to pinetmgr. 0 pinetmgr 27-Oct-05 16:24:27 >> Successful login ID: 30. Address: Host: samson.osisoft.com. Name: PipeE. User: piadmin. Trust:!Proxy_127! 0 pinetmgr 27-Oct-05 16:24:28 >> Connection accepted: Process name: pibatch(2708) ID: 33 0 pibatch 27-Oct-05 16:24:28 >> Starting PI process pibatch. 0 pinetmgr 27-Oct-05 16:24:30 >> Servertablelist received from: pibatch(2708). 3 entries: pibatch 1 pibatch_subsysquery 1 pibatch_dbsecurity 1 0 pinetmgr 27-Oct-05 16:24:30 >> Connection accepted: Process name: piartool(2504) ID: 34 0 pibatch 27-Oct-05 16:24:31 >> PI subsystem pibatch is now running, version: PI pibatch 27-Oct-05 16:24:31 >> WorkingSet Parameters changed, Current settings: , 10MB, Previous settings: , MB 0 pibatch 27-Oct-05 16:24:31 >> Starting pibatch 0 pibatch 27-Oct-05 16:24:31 >> Registered to update manager as a consumer 0 pibatch 27-Oct-05 16:24:31 >> Registered for point updates. 0 pibatch 27-Oct-05 16:24:31 >> Batch databases loaded 0 pibatch 27-Oct-05 16:24:31 >> Rpcservertablelist successfully registered to pinetmgr. 0 pibackup 27-Oct-05 16:24:31 >> Successfully registered subsystem pibatch, version pinetmgr 27-Oct-05 16:24:32

311 >> Deleting connection: piartool(1152), Shutdown request received from piartool(1152) (8), ID: 27 0 Connection Statistics 27-Oct-05 16:24:32 >> ID: 27; Duration: 0.03 min.; kbytes sent: 39.83; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:32 >> Deleting connection: piartool(3256), Shutdown request received from piartool(3256) (8), ID: 25 0 Connection Statistics 27-Oct-05 16:24:32 >> ID: 25; Duration: 0.03 min.; kbytes sent: 39.83; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:38 >> Connection accepted: Process name: piartool(3348) ID: 35 0 pinetmgr 27-Oct-05 16:24:40 >> Connection accepted: Process name: piartool(1240) ID: 36 0 piafserver.exe 27-Oct-05 16:24:43 >> Loading SubSystems from 'C:\Program Files\PIPC\PIAF\SubSystems': 0 pinetmgr 27-Oct-05 16:24:43 >> Connection accepted: Process name: piafserver.exe(3140) ID: 37 0 pinetmgr 27-Oct-05 16:24:44 >> Deleting connection: piartool(2504), Shutdown request received from piartool(2504) (8), ID: 34 0 Connection Statistics 27-Oct-05 16:24:44 >> ID: 34; Duration: 0.03 min.; kbytes sent: 46.71; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:44 >> Deleting connection: piartool(2592), Shutdown request received from piartool(2592) (8), ID: 29 0 Connection Statistics 27-Oct-05 16:24:44 >> ID: 29; Duration: 0.03 min.; kbytes sent: 41.19; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:44 >> Deleting connection: piartool(2628), Shutdown request received from piartool(2628) (8), ID: 32 0 Connection Statistics 27-Oct-05 16:24:44 >> ID: 32; Duration: 0.03 min.; kbytes sent: 42.55; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:52 >> PInet accepted TCP/IP connection, cnxn ID 38 Hostname: samson.osisoft.com, : pinetmgr 27-Oct-05 16:24:52 >> New Pinet 1 connection: RmpSE Protocol: pinetmgr 27-Oct-05 16:24:52 >> New Pinet 1 connection: RmpSE Successful Trust-Relation login: samson.osisoft.com RmpSE piadmin. 0 pinetmgr 27-Oct-05 16:24:52 >> PInet accepted TCP/IP connection, cnxn ID 39 Hostname: samson.osisoft.com, : pinetmgr 27-Oct-05 16:24:52 >> New Pinet 1 connection: RandE Protocol: pinetmgr 27-Oct-05 16:24:52 PI Server System Management Guide Page 289

312 >> New Pinet 1 connection: RandE Successful Trust-Relation login: samson.osisoft.com RandE piadmin. 0 pinetmgr 27-Oct-05 16:24:55 >> Deleting connection: piartool(1240), Shutdown request received from piartool(1240) (8), ID: 36 0 Connection Statistics 27-Oct-05 16:24:55 >> ID: 36; Duration: 0.03 min.; kbytes sent: 46.71; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:55 >> Deleting connection: piartool(3348), Shutdown request received from piartool(3348) (8), ID: 35 0 Connection Statistics 27-Oct-05 16:24:55 >> ID: 35; Duration: 0.05 min.; kbytes sent: 46.64; kbytes recv: 0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host: 0 pinetmgr 27-Oct-05 16:24:57 >> Successful login ID: 38. Address: Host: samson.osisoft.com. Name: RmpSE. User: piadmin. Trust:!Proxy_127! 0 pinetmgr 27-Oct-05 16:24:57 >> Successful login ID: 39. Address: Host: samson.osisoft.com. Name: RandE. User: piadmin. Trust:!Proxy_127! 0 pishutev 27-Oct-05 16:24:58 >> Shutdown of PI subsystem pishutev in progress. 0 pishutev 27-Oct-05 16:25:00 >> Shutdown Events at 27-Oct-05 16:21:46 sent for 10 Points 0 pishutev 27-Oct-05 16:25:00 >> Shutdown of PI subsystem pishutev complete. 0 pibackup 27-Oct-05 16:25:08 >> Successfully registered subsystem pisnapss, version pibackup 27-Oct-05 16:25:08 >> Successfully registered subsystem piarchss, version pibackup 27-Oct-05 16:25:08 >> Successfully registered subsystem pimsgss, version pibackup 27-Oct-05 16:25:09 >> Successfully registered subsystem pilicmgr, version pibackup 27-Oct-05 16:25:09 >> Successfully registered subsystem pibasess, version pinetmgr 27-Oct-05 16:25:19 >> Deleting connection: pishutev(2540), Shutdown request received from pishutev(2540) (8), ID: 20 0 Connection Statistics 27-Oct-05 16:25:19 >> ID: 20; Duration: 1.07 min.; kbytes sent: 38.39; kbytes recv: 15.06; app: pishutev; user: ; osuser: ; trust: ; ip address: ; ip host: Client Connection Messages The pinetmgr utility writes messages to the PI System message log that track communications between PI clients and the PI Server. The following message from pinetmgr indicates that a client is attempting to connect to PI Server. Note that a connection ID (cnxn ID) is assigned. 0 pinetmgr 27-Oct-05 17:23:14 Page 290

313 >> PInet accepted TCP/IP connection, cnxn ID 44 Hostname: samson.osisoft.int, :1209 PI API-based clients will have a message similar to the following. The client publishes its name and protocol. The name is a five-character string. The first four letters give the application name or login name; the fifth character is always E. In this example, the client name is snape: 0 pinetmgr 27-Oct-05 17:23:14 >> New Pinet 1 connection: snape Protocol: PI Server then attempts to use the credentials of the incoming connection to locate a record in the PItrust database. If a match is found, the following message is written: 0 pinetmgr 27-Oct-05 17:23:14 >> New Pinet 1 connection: snape Successful Trust-Relation login: samson.osisoft.int snape piadmin. If a match is not found, the message is: 0 pinetmgr 27-Oct-05 17:28:14 >> New Pinet 1 connection: snape No Trust established for: figaro.osisoft.com snape using default login. A default login means that the connection is a member of the world as defined by the security string associated with PI Server internals such as the point database and archived data. See Chapter 1, System Management, for a description of the PI Server security model. PI-SDK-based applications have a similar set of connection establishment messages. There are two differences. First, the published application name is more detailed. It contains the full executable name plus the process ID. Second, the trust login information is not published. Here is a set of messages showing the About PI-SDK application connecting: 0 pinetmgr 27-Oct-05 19:04:44 >> PInet accepted TCP/IP connection, cnxn ID 49 Hostname: caleb.osisoft.com, : pinetmgr 27-Oct-05 19:04:44 >> Connection accepted: Process name: AboutPI SDK.exe(5632):remote(5632) ID: 49 0 pibasess 27-Oct-05 19:04:45 >> Trust <pi3build> Granted to: OSI\ADMINISTRATOR caleb AboutPI SDK.exe (108 ms) 0 pinetmgr 27-Oct-05 19:04:46 >> Successful login ID: 49. Address: Host: caleb.osisoft.com. Name: AboutPI SDK.exe(5632):remote. User: piadmin. Trust: caleb Subsystem Connection Messages The pinetmgr utility writes messages to the PI System message log that track communications between utilities and the subsystems. New connections requested by one of the PI subsystems are assigned a connection ID: 0 pinetmgr 27-Oct-05 16:23:25 PI Server System Management Guide Page 291

314 >> Connection accepted: Process name: piupdmgr(3184) ID: 5 The subsystem begins its own initialization. On Windows, part of this process involves updating the subsystem s own working set size limits: 0 piupdmgr 27-Oct-05 16:23:25 >> Starting PI process piupdmgr. 0 piupdmgr 27-Oct-05 16:23:27 >> PI subsystem piupdmgr is now running, version: PI The above messages may be following by subsystem-specific initialization messages. When initialization is complete, the subsystem tells pinetmgr which Remote Procedure Calls (RPCs) it supports. This is indicated in the following message: 0 pinetmgr 27-Oct-05 16:23:26 >> Servertablelist received from: piupdmgr(3184). 4 entries: piupdmgr 1 piupdmgr 2 piupdmgr_subsysquery 1 piupdmgr_dbsecurity 1 When pinetmgr receives notification of new RPCs, it updates the master list, and then sends the updated list to all PI subsystems. When a subsystem receives this updated master RPC list, it writes the following message. At this point, the subsystem is ready to process remote procedure calls: 0 piupdmgr 27-Oct-05 16:23:27 >> Rpcservertablelist successfully registered to pinetmgr. If pinetmgr is unable to send the updated list to the new subsystem, it writes a message as follows: 0 pinetmgr 27-Oct-05 16:32:22 >> Error sending client table(2) to: piupdmgr A successfully connected subsystem may write messages indicating its initialization progress. In general, there is no message written when initialization is complete and the subsystem is ready to process RPC calls. Disconnect Messages The following messages indicate normal disconnects. The error number (in square brackets) is given along with its translation. 0 pinetmgr 27-Oct-05 16:25:19 >> Deleting connection: pishutev(2540), Shutdown request received from pishutev(2540) (8), ID: 20 0 pinetmgr 27-Oct-05 16:44:21 >> Deleting connection: RandE, [-10721] PINET: Client Aborted Connection. (4), ID: 39 samson.osisoft.com :1106 The following messages indicate abnormal disconnects. The error number (in square brackets) is given along with its translation. 0 pinetmgr 27-Oct-05 19:26:31 >> Deleting connection: snape, GetQueuedCompletionStatus error: Network name deleted [64] The specified network name is no longer available. Connection: snape (14, 64), ID: 51 samson.osisoft.com :1835 Page 292

315 The following message indicates that an RPC was not completed within the timeout specified. The requestor passes the timeout when it places the call with pinetmgr. This timeout is not configurable. 0 pinetmgr 19-Feb-97 17:19:26 [-10722] PINET: Timeout on PI RPC or System Call RPC Resolver Messages Every few minutes, the pinetmgr sends a healthcheck message to each of the PI subsystems. If one doesn t respond within a given amount of time, pinetmgr will report the following message and the subsystem (RPC resolver) is marked off-line. >> Deleting connection: pisnapss, Subsystem Healthcheck failed. If an RPC is made to a subsystem that is marked off-line, the following message is generated. [-10733] PINET: RPC Resolver is Off-Line The following message indicates that the first part of a message was retrieved. This contains the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout occurred. >> Deleting connection: pisnapss, Connection lost(1), [-10731] PINET: incomplete message Piupdmgr The pinetmgr utility keeps track of processes that have signed up for updates. It is possible for a signed-up process to go away without properly unsigning up. If pinetmgr detects this case, it will remove the dead process from its table and report the following message: 0 piupdmgr 19-Feb-97 17:31:15 >> Consumer <UNKNE 8> timed out! removed... Error Codes System error messages usually contain error codes. Error codes are reported in square brackets. Negative numbers indicate PI System errors. Positive numbers indicate operating system errors. Pidiag Use the pidiag utility to interpret error codes. Do not type the square brackets: pidiag -e errorcode This will display the associated error message. For example: pidiag -e [-10722] PINET: Timeout on PI RPC or System Call PIdiag will also translate operating system error codes, which are always positive numbers. Note that the error code translation takes place on the operating system running pidiag. For example, on Windows, you could issue the command: PI Server System Management Guide Page 293

316 pidiag -e 2 [2] The system cannot find the file specified. Avoid reading error codes from the PI Server message log on one operating system and translating them with pidiag -e on another. PI Error Message Codes System error messages usually contain error codes. Error codes are reported in square brackets. Negative numbers indicate PI System errors. Positive numbers indicate operating system errors. Table A-1. Error Codes 1-99, With Messages Code Code Identifier Message 0 PI_NORMAL Success -1 PI_ERROR Generic Error or PI 2.x Point Out of Range or Not Defined -2 PI_ATT_BLANKTAG Blank tag -3 PI_ATT_PTDBFULL Point data base full -4 PI_ATT_MEMDBFULL Memory data base full -5 PI_ATT_TAGNOTFOUND Tag not found -6 PI_ATT_BADCHARTAG Illegal Characters in Tag -7 PI_ATT_TAGEXISTS Tag already exists -8 PI_ATT_BADTIME Time is After Current Time and Date or Time is <0-9 PI_ATT_BADINTVALUE Illegal Status Value or Integer Value -10 PI_ATT_OTHERPROC Cannot Create Tag Because Other Procedure is Creating Tag -11 PI_ATT_BADDIGCODERANGE Digital Code is Out of Range -12 PI_ATT_NODSSTRING Digital state string not found -13 PI_ATT_BADDSCODERANGE Digital State Code Out of Range For This Tag -15 PI_ATT_NOSOURCETAG Source tag not found -19 PI_ATT_PTATTZERO Point Attribute Zero Error or Disk Error for Point Database -20 PI_ATT_BADZEROSPAN Bad Zero or Span For Integer Point -21 PI_ATT_NEGSPAN Span not greater than zero -22 PI_ATT_BADTYPVALUE Typical Value Not Between Zero and Top of Range Page 294

317 Code Code Identifier Message -23 PI_ATT_BADDSCODE Illegal digital state code -24 PI_ATT_BADNUMDS Bad Number of Digital States -25 PI_ATT_BADPTTYPE Illegal point type -26 PI_ATT_BADPTSOURCE Illegal point source -27 PI_ATT_BADENGUNIT Illegal engineering unit code -28 PI_ATT_BADLOC1 Bad Location Parameter 1 (Range Depends on Point Source) -29 PI_ATT_BADLOC2 Bad Location Parameter 2 (Range Depends on Point Source) -30 PI_ATT_BADLOC3 Bad Location Parameter 3 (Range Depends on Point Source) -31 PI_ATT_BADLOC4 Bad Location Parameter 4 (Range Depends on Point Source) -32 PI_ATT_BADLOC5 Bad Location Parameter 5 (Range Depends on Point Source) -33 PI_ATT_BADTOTPTTYPE Point Type of Totalized Point is Not Real -34 PI_ATT_BADRATEPT Rate Point Type Must Be Real or Integer -35 PI_ATT_BADRESCODE Illegal resolution code -36 PI_ATT_BADARCHONOFF Illegal archiving on/off value -37 PI_ATT_BADCOMPONOFF Illegal compressing on/off value -38 PI_ATT_BADCOMPDEV Illegal compression deviation specification -39 PI_ATT_BADCOMPMINTIME Illegal compression minimum time specification -40 PI_ATT_BADCOMPMAXTIME Illegal compression maximum time specification -41 PI_ATT_BADEXCDEV Illegal exception deviation specification -42 PI_ATT_BADEXCMINTIME Illegal exception minimum time specification -43 PI_ATT_BADEXCMAXTIME Illegal exception maximum time specification -44 PI_ATT_BADFILTCODE Illegal filter code -45 PI_ATT_BADTOTCODE Illegal totalization code -46 PI_ATT_BADTOTCONV Illegal totalization conversion factor -49 PI_ATT_BADSQRTCODE Illegal square root code -50 PI_ATT_BADSCANONOFF Illegal scan on/off value PI Server System Management Guide Page 295

318 Code Code Identifier Message -51 PI_ATT_RESCODECONST Cannot change resolution code -52 PI_ATT_BADTIMEFORMAT Illegal time/date string format -53 PI_ATT_POINTNOTTOTAL Point is Not a Total -54 PI_ATT_TOTDBFULL Totalization data base full -55 PI_ATT_PTNOTINTOTDB Point Not Defined in Totalization Data Base -56 PI_ATT_SINGLEQUOTE Tagname Should Be in Single Quotes, not Double Quotes -57 PI_ATT_MISSINGTAG Filter or Trigger Tag Does Not Exist -58 PI_ATT_EXTDESCSYNTAX Syntax Error in Extended Descriptor -59 PI_ATT_BADEXTDESCKEYWD Unrecognized Keyword in Extended Descriptor -60 PI_ATT_NOPIDAVAIL No more pid slots for retrieving point update lists -61 PI_ATT_NOTAGCHANGE No More Tags Created, Edited, or Deleted -62 PI_ATT_NOPTUPDATE Not signed up for point updates -63 PI_ATT_BADDISPDIG Display Digits <-20 or >10-64 PI_ATT_BADCLAMPCODE Illegal Clamping Code (<0 or >3) -65 PI_ATT_BADSCHEDCODE Illegal Scheduling Code (<0 or >2) -66 PI_ATT_NONATSCHED Natural Scheduling is Not Allowed For Post- Processed Tags -67 PI_ATT_BADGROUPPSIZE Illegal group size for moving average (<2) -68 PI_ATT_BADPERIOD Illegal period -69 PI_ATT_BADOFFSET Illegal Offset (<0 or >86399) -70 PI_EVM_BADNUMPOINTS Illegal Number of Points (<1) -71 PI_EVM_BADPOINTNUM Point Number Out of Range -72 PI_EVM_NOMOREEXCEPT No more room for programs requesting exceptions -73 PI_EVM_TOOMANYPTS No room for this many points for this list -74 PI_EVM_NOMOREPTS No room for more points -75 PI_EVM_NOPTSESTAB No points established -76 PI_EVM_PTSNOTDISESTAB Some points not disestablished -78 PI_EVM_TIMEOUT Timed out Page 296

319 Code Code Identifier Message -79 PI_EVM_BADTIMEOUT Bad timeout value Table A 2. Error Codes , With Messages Code Code Identifier Message -101 PI_ARCH_DATENOTONLINE Date not on-line -102 PI_ARCH_RECORDNOTFOUND Record not found (empty) -103 PI_ARCH_NODATA No Data For This Point at This Time -105 PI_ARCH_BADSTARTENDTIME End Time Not After Start Time, or Start Time <0-106 PI_ARCH_NOGOODDATA No Good Data For This Point at This Time -107 PI_ARCH_NEGSQUAREROOT Cannot Calculate Square Root of Negative Number -108 PI_ARCH_BADEDITTIME Time is Before the Editing Time Limit -109 PI_ARCH_VALUEEXISTS Value at This Time Already Exists -110 PI_ARCH_SLOWARCHIVE Archive program not keeping up with events -111 PI_ARCH_30SECRULE Event Not Processed by Archive Program Within 30 Seconds -112 PI_ARCH_ARCH1OFFLINE Point not created because archive one not on-line -113 PI_ARCH_TOOFEWVALUES Number of Values Argument to Archive Retrieval Routine is Bad Table A 3. Error Codes , With Messages Code Code Identifier Message -201 PI_PE_CORRUPTFILE Performance Equation file corrupted -202 PI_PE_CANTDELETEPETAG Cannot delete tag that is used in PE -203 PI_PE_CANTDELETETOTTAG Cannot delete tag that is used in totalization -204 PI_PE_CANTDELETESQCTAG Cannot delete tag that is used in SQC calc -251 PI_SQL_MEMERR SQL: memory allocation error -252 PI_SQL_SYNERR SQL: syntax error -253 PI_SQL_INVSTMT SQL: invalid statement -254 PI_SQL_INTERR SQL: severe internal error -255 PI_SQL_NOSUPPORT SQL: unsupported statement -256 PI_SQL_TIMERR SQL: invalid time PI Server System Management Guide Page 297

320 Code Code Identifier Message -257 PI_SQL_TAGERR SQL: tag not found -258 PI_SQL_TYPERR SQL: invalid data type -259 PI_SQL_CALCERR SQL: calculation error -260 PI_SQL_INVWHERE SQL: invalid WHERE clause -261 PI_SQL_COLERR SQL: column count error -262 PI_SQL_NOSELECT SQL: statement is not a SELECT -263 PI_SQL_SYSTEMERR SQL: system error occurred -264 PI_SQL_TIMESTEPERR SQL: TIMESTEP error -265 PI_SQL_NOQUERY SQL: no query found in string -266 PI_SQL_USERABORT SQL: use aborted execution -267 PI_SQL_INVARG SQL: invalid function argument -268 PI_SQL_NOTSAFE SQL: execution too expensive -269 PI_SQL_INVTABLE SQL: invalid table name -270 PI_SQL_INVALIAS SQL: invalid table alias name -271 PI_SQL_BADINI SQL: invalid INI file entries -272 PI_SQL_TRUNC SQL: returned string truncated -273 PI_SQL_TIMEOUT SQL: query timed out -274 PI_SQL_NOPARAM SQL: run-time parameter missing -275 PI_SQL_BUSY SQL: handle is busy with another operation -280 PI_GRID_MEMERR Pigrid: memory allocation error -281 PI_GRID_RANGERR Pigrid: column index out of range -282 PI_GRID_NOCOLTYPE Pigrid: column not defined -283 PI_GRID_NOCOLSIZE Pigrid: data size not set -284 PI_GRID_INVDTYPE Pigrid: invalid data type -285 PI_GRID_INVDSIZE Pigrid: invalid data size Table A 4. Error Codes , With Messages Code Code Identifier Message -501 PI_SQC_BADCHARTTYPE Sqc: illegal chart type Page 298

321 Code Code Identifier Message -502 PI_SQC_BADALARMGROUP Sqc: illegal alarm group number -503 PI_SQC_CALCDBFULL Sqc: calculation data base full -504 PI_SQC_BADSAMPLESIZE Sqc: Illegal Sample Size (<0 or >32767) -505 PI_SQC_BADSAMPLEPERIOD Sqc: illegal sample period -506 PI_SQC_BADCALCPERIOD Sqc: calculation period less than sample period -507 PI_SQC_BADPERIODSTART Sqc: illegal start period time -508 PI_SQC_BADIGNORESAMP Sqc: Illegal Number of Samples to Ignore After Trigger -509 PI_SQC_BADMOVAVGWT Sqc: illegal geometric moving average weight -510 PI_SQC_CUSUMKNEG Sqc: CUSUM k Less Than Zero -511 PI_SQC_CUSUMHNEG Sqc: CUSUM h Less Than Zero -512 PI_SQC_BADINITCUSUM Sqc: Illegal Initial CUSUM (<0 or >h) -513 PI_SQC_BADTESTGROUP Sqc: Illegal Test Group Number (<1 or >256) -515 PI_SQC_CALCMISSING Sqc: calculation not found -516 PI_SQC_RAWTAGMISSING Sqc: raw data tag for SQC calculation not found -517 PI_SQC_TRIGTAGMISSING Sqc: Trigger Tag for SQC Calculation Not Found -518 PI_SQC_CHARTTAGDEFD Sqc: Chart Tag Already Defined in SQC Database -519 PI_SQC_CHARTEQUALSRAW Sqc: Chart Tag is the Same as the Raw Tag -520 PI_SQC_INPUTFILEMISSING Sqc: input file does not exist -521 PI_SQC_BADINPUTFILEFMT Sqc: Input File is Not Properly Formatted -522 PI_SQC_BADRANGEVALUE Sqc: Value is Out of Range -523 PI_SQC_BADRANGEALARM Sqc: Alarm Number is Out of Range -524 PI_SQC_CANTWRITEFILE Sqc: cannot open file for writing -525 PI_SQC_COMMENTMISSING Sqc: Comment Not Found in Comment File -526 PI_SQC_INVARRAYINDEX Sqc: Array Index is Out of Valid Range -527 PI_SQC_CTLLIMTAGMISSING Sqc: Control Limit Tag is Not in SQC Structure -528 PI_SQC_CTLLIMNOTINFILE Sqc: Control Limits Not Found in Control Limit File PI Server System Management Guide Page 299

322 Table A 5. Error Codes , With Messages Code Code Identifier Message -801 PI_EP_BADCONST Expression parser: illegal constant -802 PI_EP_BADNUM Expression parser: illegal number -803 PI_EP_TOOMANYTAGS Expression parser: too many constants/tags -804 PI_EP_TOOCOMPLEX Expression parser: expression too complex -805 PI_EP_BADKEYWORD Expression parser: illegal keyword -806 PI_EP_BADCHAR Expression parser: illegal character -807 PI_EP_TOOMANYUNARIES Expression parser: too many unary operators -808 PI_EP_BADBOOLEANS Expression Parser: Illegal Combination of Boolean Operators -809 PI_EP_UNBALPARENS Expression parser: unbalanced parentheses -810 PI_EP_TOOMANYRTPARENS Expression parser: too many right parentheses -811 PI_EP_NOPARENS Expression Parser: Nothing in Parentheses -812 PI_EP_BADIF Expression parser: illegal if-then-else structure -813 PI_EP_CMDSTACKOVERFLOW Expression parser: command stack overflow -814 PI_EP_NULLEQUATION Expression Parser: Null Equation for Expression -815 PI_EP_REDSTACKOVERFLOW Expression Parser: Reduction Stack Overflow for Expression -816 PI_EP_BADTOKEN Expression parser: illegal token -817 PI_EP_SYNTAX Expression parser: syntax error -818 PI_EP_CALCSTACKOVERFLOW Expression parser: calculation stack overflow -819 PI_EP_DISKERR Expression parser: disk error reading constant files -820 PI_EP_CALCOVERFLOW Expression parser: calculation overflow -821 PI_EP_DIVZERO Expression Parser: Division by Zero -822 PI_EP_BADARGUMENT Expression parser: illegal function argument -823 PI_EP_BADEXPONENT Expression Parser: Non-integer exponent -824 PI_EP_BADCONSTANT Expression parser: undefined constant Table A 6. Error Codes , With Messages Code Code Identifier Message Page 300

323 Code Code Identifier Message -900 PI_EE_BADTAG Expression evaluation: illegal tag -912 PI_EE_BADIF Expression evaluation: illegal if-then-else structure -914 PI_EE_NULLEQUATION Expression Evaluation: Null Equation for Expression -916 PI_EE_BADTOKEN Expression evaluation: illegal token -917 PI_EE_SYNTAX Expression evaluation: syntax error -918 PI_EE_CALCSTACKOVERFLOW Expression evaluation: calculation stack overflow -920 PI_EE_CALCOVERFLOW Expression evaluation: calculation overflow -921 PI_EE_DIVZERO Expression Evaluation: Division by Zero -922 PI_EE_BADARGUMENT Expression evaluation: illegal function argument -923 PI_EE_BADEXPONENT Expression Evaluation: Non-integer exponent -925 PI_EE_BADVALUE Expression evaluation: illogical current value -981 PI_NET2_BADTABLEID Table ID Specified is Not Supported -982 PI_NET2_BADTABLECODE Specified Table Code is Not Supported -983 PI_NET2_BADTRANSMODE Requested Transaction Mode is Not Supported -991 PI_NET2_BADFUNCCODE PINet Function Code is Not Valid -992 PI_NET2_BADLENGTH Specified Length is Not Consistent -993 PI_NET2_BADCOUNT Specified Count is Not Valid -994 PI_NET2_BADPINETVER Incompatible PINet version -995 PI_NET2_BADMSGSEQ Bad PINet message sequence -996 PI_NET2_MSGTOOBIG Message Too Big for PINet -998 PI_NET2_MEMALLOCERR Memory allocation error -999 PI_NET2_LOGINREQD Request not permitted without login Table A 7. Error Codes , With Messages Code Code Identifier Message PI_NET2_BADGRID Grid not implemented PI_NET2_NODEFHOST Default host not found PI_NET2_NOBATSUBSYS No Batch Subsystem on PI2 server PI Server System Management Guide Page 301

324 Table A 8. Error Codes , With Messages Code Code Identifier Message PI_ERR_MALLOC Failed memory allocation PI_ERR_NEW Failed new operation PI_ERR_ACTIVATE Unable to Activate Object PI_ERR_PASSIVATE Unable to Passivate Object PI_ERR_IMPOSS Internal error (impossible) PI_ERR_UNDERRANGE Subscript under range PI_ERR_OVERRANGE Subscript over range PI_ERR_BADPOINTER Bad or Null Pointer PI_ERR_UNSUPPORTED Unsupported or Unimplemented Call PI_SHUTDOWN PI system shutting down PI_ERR_TIMEOUT PI system timed out PI_ERR_ACCESSLOCK Target Object in Use or Locked PI_XS_NOREAD No read access secure object PI_XS_NOWRITE No write access secure object PI_XS_BADSTRING Badly formed access string PI_XS_BADUGVER Version Mismatch in Usergroup Activate PI_XS_BADUSERVER Version Mismatch in User Activate PI_XS_CTXIDINUSE User Context ID in Use PI_XS_GROUPINUSE Group ID in Use PI_XS_NOACCESS No access secure object PI_XS_BADUSERSTR Invalid security user/owner string PI_XS_BADGRPSTR Invalid security group string PI_XS_BADDBNAME Invalid security database name PI_XS_MISMATCH security or trust relation mismatch PI_XS_TRUSTUNSUP Trust relation not supported on server PI_XS_NOTRUST No trust relation for this request PI_XS_SIMILARTRUST Trust records must differ more than name and Piuser Page 302

325 Code Code Identifier Message PI_XS_IPANDMASK Must specify both IP address and Net Mask PI_XS_NONULLTRUST Trust definition must include more than name and Piuser PI_XS_NOPIADMIN User must be piadmin for this operation PI_XS_DBSECNOTINIT DB Security not initialized PI_XS_NULLSECOBJ Unable to retrieve secure object PI_FB_BADCREATEFILE Create new file failed PI_FB_BADOPENFILE Open existing file failed PI_FB_BADFILECLOSE Close file failed PI_FB_BADFILEREMOVE Delete file failed PI_FB_BADFILETRUNCATE Truncate file failed PI_FB_INVALIDFILE Fstat Failed PI_FB_BADFILELOCK Fcntl Failed to Get Lock PI_FB_BADFILEUNLOCK Fcntl Failed to Free Lock PI_FB_BADHEADER Illegal file header parameters PI_FB_FILEOPEN File open PI_FB_FILECLOSED File closed PI_FB_BADFILEREAD Read from file failed PI_FB_BADFILEWRITE Write to file failed PI_FB_BADRECNOVALUE Recno Greater Than Directory Size PI_FB_RECNOINUSE Recno In Use PI_FB_RECNONOTFOUND No Record Available for Passed recno PI_FB_BADRECLEN Reclen Greater Than Maximum Allowed Size PI_FB_TIMETOGROWDIR Getting New recno, Directory is Full PI_FB_BADBUFFERSIZE Passed Buffer Too Small to Hold Record PI_FB_BADFILESEEK Lseek Failed PI_FB_BADFILEHEADER Fatally corrupted file header PI_FB_DIRTYHEADER Dirty header PI_FB_INVUSERBLOCK Invalid user block size PI Server System Management Guide Page 303

326 Code Code Identifier Message PI_FB_BADVERSION Version mismatch PI_FB_CNTMISMATCH Record count mismatch between header and index PI_FB_LOWDISKSPACE low disk space, file size cannot be increased PI_FB_PATHNOTDIRECTORY The path is valid, but the path is not a directory PI_FB_NULLPATHSTRING Cannot extract file and path from null string PI_PD_TAGEXISTS Tag Already Exists in Table PI_PD_INVTAG Invalid Characters in Tag PI_PD_BADCHAIN Broken Context Chain in Table PI_PD_INVPTID Ptid is Not a Valid Point PI_PD_CTXEXISTS Tag Already Exists for Context PI_PD_NOTAG Tag Does Not Exist in Table PI_PD_ENDSEARCH End of Table Reached PI_PD_BADASVER Bad ptattributeset Version PI_PD_BADPTCLVER Bad ptclass Version PI_PD_BADPOINTVER Bad point version PI_PD_POINTINUSE Point Already Has a ptclass PI_PD_PTCLASSINUSE Point class already defined PI_PD_CLASSESINUSE Ptclasses Already Defined PI_PD_BADPTCLASSREV Point class revision mismatch PI_PD_NOPTCLASS Point class not defined PI_PD_NOMOREPTS No More Points in Search PI_PD_VALIDFAIL Point validation failed PI_PD_AMBIGUOUS Point ID does not match Tag or Tag rename to same name PI_PD_NOMATCHINGPOINTS No points found in search PI_PD_BADATTRIBUTE Point does not contain specified attribute PI_PD_NOEDIT Attempt to edit or set internally set point attribute Page 304

327 Code Code Identifier Message PI_PD_INVALIDATT Attempt to create attribute set with invalid attribute name PI_PD_INVALIDNAME Invalid name for point class or attribute set PI_PD_NOBASEATT Base attribute set not included in point class definition PI_PD_NODELBASEATT Attribute set delete not allowed PI_PD_ATTSETINUSE Attribute set is in use PI_PD_MISSINGREQATTRIBUTES Required attribute missing in the attribute set PI_PD_BASEATTNAME Attribute name being used by base attribute set PI_PD_BUILTINATTNAME Attribute name being used by built-in PI_PD_BADPTTYPECHANGE Unsupported point type change PI_PD_RESERVEDNAME Name reserved for internal use PI_PD_INVALIDBASEATTNAME Invalid attribute name for base attribute set PI_PD_NOATTSETRENAME Rename not allowed for this attribute set PI_PD_CLASSINUSE Point class is in use PI_PD_BADPTCLASSESREV PIptclasses revision mismatch PI_PD_NOEDITBASECLASS Base point class edit/delete not allowed PI_PD_INVALIDATTTYPE Unsupported attribute type PI_PD_NOEDITBASEATT Base attribute set edit not allowed except for default change PI_PD_MISSINGREQATTRIBUTESE TS Required attribute set missing in the point class PI_PD_NODELSET Delete not allowed for this attribute set PI_PD_NODELCLASS Delete not allowed for this point class PI_PD_NOPTCLSRENAME Rename not allowed for this point class PI_PD_ATRTYPECHANGEINPREDE FORINUSEATRSET PI_PD_ATTRIBDELINPREDEFORIN USEATTRIBSET PI_PD_ATTRIBSETDELINPREDEFO RINUSEPTCLASS Attribute type change in this attribute set not allowed Attribute delete in this attribute set not allowed Attribute set delete in this point class not allowed PI Server System Management Guide Page 305

328 Code Code Identifier Message PI_PD_STANDALONEMODEREQUI RED This operation requires StandAlone mode PI_UD_INVALIDGRPUSRNM Invalid Group or User Name PI_UD_INVGRPSLFREF Invalid Group self reference PI_UD_INVGRPLAYER Super Group cannot be member Super Group PI_DS_NAMEEXISTS State Already Exists in Table PI_DS_SETNOTFOUND Set not found PI_DS_STATENOTFOUND State not found PI_DS_ILLEGALSETDEFINITION Illegal set definition: no states defined PI_DS_CANTDELETESYSSET Cannot delete system state-set PI_DS_TOOMANYSETS Maximum number of Sets Exceeded PI_DS_TOOMANYSTATES Maximum number of States Exceeded PI_DS_SETMISMATCH Digital set number mismatch during type coercion PI_DS_NEGATIVEOFFSET Negative state number in digital type coercion PI_NET_ABORT PINet: client aborted connection PI_NET_TIMEOUT PINet: Timeout on PI RPC or System Call PI_NET_NOCONNECTION PINet: no connection PI_NET_QUEOVERFLOW PINet: queue overflow PI_NET_SYNCHRONOUS PINet: synchronous PI_NET_ASYNCHRONOUS PINet: asynchronous PI_NET_RPC_NONEXISTENT PINet: RPC is Non-Existent PI_NET_SEND_ERROR PINet: send error PI_NET_RECV_ERROR PINet: receive error PI_NET_NO_MESSAGE PINet: no message PI_NET_INCOMPLETE_MESSAGE PINet: incomplete message PI_NET_CORRUPTED_MESSAGE PINet: corrupted message PI_NET_RPCRESOLVEROFFLINE PINet: RPC Resolver is Off-Line PI_NET_BROKENCONNECTION PINet: broken connection Page 306

329 Code Code Identifier Message PI_NET_TRANSACTIONLISTFULL PINet: session manager transaction list full PI_NET_ILLEGALRPCID PINet: RPC Table ID or Entry ID set to illegal value of PI_NET_PENDING PINet: Asynchronous connection to pinetmgr is Pending PI_NET_DISABLED PINet: connection disabled PI_NET_INVALIDRPCSERVERTABL ELIST PINet: Invalid or Null RPC Server Table List PI_NET_INVALIDHOST PINet: invalid host PI_NET_RPCRESOLVERNOTAVAIL ABLE PINet: RPC Resolver chooses to not service request PI_NET_CONNECTIONLISTFULL PINet: Connection list full PI_NET_RPCRESOLVERTMPOFFLI NE PINet: RPC Resolver temporarily Off-Line PI_NET_TRANSLATORINUSE PINet: PI API client attempted two or more simultaneous calls PI_NET_MESSAGEVERIFICATIONF AILURE PINet: Message verification failure PI_NET_MESSAGETOOLARGE PINet: Attempt to send or receive message larger than maximum allowable PI_NET_TRANSLATORVERIFICATI ONFAILURE PINet: PIAPI translator verification failure PI_NET_NOROUTEENTRY PINet: No routing entry exists for RPC PI_NET_NORPCCODE PINet: No RPC entry for table/function code PI_NET_NORPCNAME PINet: No RPC entry for table/function name PI_NET_NORPCCALLBACK PINet: No callback function for RPC entry PI_NET_EXCESSIVEZEROBYTERE ADS PINet: Connection broken by peer PI_NET_INVALIDSESSIONID PINET: Invalid session ID PI_NET_RPCTABLEGENMISMATCH PINET: RPC Table Generation mismatch PI_NET_COMPLETIONPORTERRO R PI_NEWERSERVERVERSIONREQU IRED PINET: Completion Port Error PINET: Newer server version required PI Server System Management Guide Page 307

330 Code Code Identifier Message PI_NOREMOTECONNECTION PINET: No remote connection PI_NET_FAILEDREMOTECONNECT ION PINET: Failed remote connection PI_NET_NO_BYTES recv() returned zero bytes PI_NET_EXCESSIVEREADRETRIES Read retry limit exceeded PI_NET_FORCEDDISCONNECT Connection deleted by request of administrator PI_NET_MAXCONNIDLETIME Maximum Connection Idle time reached: Connection Closed PI_NET_INVALIDPINETMGRCONTR OLMODE Invalid PINetMgr Control Mode PI_NET_NOTLOCALSESSION Access only allowed by local PI Server connection PI_NET_USERCANCELEDCONNEC TION ser canceled session login PI_NET_TRANSACTIONABORTED PINET: Transaction aborted by local session thread PI_NET_CONCURMSGABOVELIMIT Client exceeded maximum concurrent queries in RPC thread pool Table A 9. Error Codes , With Messages Code Code Identifier Message PI_AR_RCHDVMM Record header version mismatch PI_AR_RCHDDMM Record header data mismatch PI_AR_RCHDSMM Record header size mismatch PI_AR_RCHDBADPTRECID Record header bad (0) point record ID PI_AR_RCHDBADRECID Record header bad (0) record ID PI_AR_RCHDBADSIZE Record header bad set size byte count PI_AR_RCHDOVERWRITE Record header stream overwrite PI_AR_RCBADDATATYPE Attempted to Add Event With Invalid Data Type PI_AR_RCOBJTOOBIG Event Contents Are Too Big to Fit in Any Record PI_AR_NOTTYPEDIG Record not type=digital PI_AR_NOTTYPEFLOAT2 Record not type=float2 zero/span do not apply. Page 308

331 Code Code Identifier Message PI_AR_INVRECCNT Invalid record count for creating archive PI_AR_INVRECSIZE Invalid record size for creating archive PI_AR_BADSTREAMATT Failed to Attach Archive File to Stream PI_AR_ARCFILEVMM Archive file version mismatch PI_AR_ARCFILERAB Archive File in Unrecognized State PI_AR_CRPTTIME Corrupt Time Values in Archive Header PI_AR_CRPTPTRS Corrupt Overflow or Primary Record Pointers PI_AR_ARCNOTMNTD Archive file not mounted PI_AR_INVPTCNT Point Count Out of Range PI_AR_CRPTCACHEREC Cache record corrupt PI_AR_PTRECIDBND Invalid Value for Requested ptrecid PI_AR_BOUNDS Archive record full PI_AR_BADCACHELOAD Cache->loadrecord Failed PI_AR_BADGETTARREC Arcmgr::gettargetrecord Failed PI_AR_BADOVERFLOW Arcfile::overflowrecord Failed PI_AR_BADARLOADREC Arcfile::loadrecord Failed PI_AR_DUPARCFAIL Requested to Load Archive File Already Loaded PI_AR_BADSETINDEX An Index Record Does Not Have an Index PI_AR_BADINDEXSRC Set Index Did Not Receive an Index Record PI_AR_EMPTYRECORD No Events in Record PI_AR_NOEVENTAFTER No Events After Passed Eventide PI_AR_NOEVENTBEFORE No Events Before Passed Eventid PI_AR_BADPTRECID Invalid ptrecid Passed PI_AR_STOREOPEN Underlying Storage is Open PI_AR_BADARCRECORD Invalid archive record pointer passed PI_AR_BADARCFILE Invalid archive file pointer passed PI_AR_NOARCHIVEBEFORE No archive before passed archive PI_AR_NOARCHIVEAFTER No archive after passed archive. PI Server System Management Guide Page 309

332 Code Code Identifier Message PI_AR_NORECORDBEFORE No record before passed record PI_AR_NORECORDAFTER No record after passed record PI_AR_RECNOTINCACHE Target Record Not in Cache PI_AR_DATENOTONLINE No archive online for target time PI_AR_EVENTOUTOFORDER Attempting to Add an Event Before Last Event PI_AR_INDEXRECMISMATCH Add event index mismatch PI_AR_DATEINFUTURE Target Date in Future PI_AR_INVMAXCOUNT Invalid maximum count PI_AR_INVINTERVAL Invalid intervals for archive call PI_AR_INVTIMES Invalid times for archive call PI_AR_INVRECTYPE Invalid record type PI_AR_COUNTTOOSMALL Count not large enough for interval PI_AR_SNAPMISMATCH Count mismatch loading snapshot PI_AR_ARCHIVEFULL No More Available Records in This Archive PI_AR_INVALIDSTATE Invalid Archive State For Mounting or Dismounting PI_AR_INVSTIME Invalid start time PI_AR_INVETIME Invalid end time PI_AR_NOTENOUGHVALS Not enough good values for calculation PI_AR_INVSUMMARYCODE Invalid code for summary function PI_AR_NOGOODDATA No good data for this time PI_AR_CALCFAILED Calculation Failed (e.g. Division by Zero) PI_AR_INVMODEADD Invalid mode for archive add event PI_AR_INVMODEEDIT Invalid mode for archive edit event PI_AR_INVMODEDEL Invalid mode for archive delete event PI_AR_RCHDRMM Mismatch in record header record ID PI_AR_RCHDPMM Mismatch in record header chain pointer PI_AR_EMPTYDRECORD Empty data archive record PI_AR_EMPTYIRECORD Empty index archive record. Page 310

333 Code Code Identifier Message PI_AR_BADPRIMARY Failed to get primary archive PI_AR_CREATEFLAG Archive creation flag already set PI_AR_NOARCHMOUNT No archives mounted PI_AR_NOSHIFTARC No archive qualified for shift PI_AR_REMNER No events in record for removal PI_AR_REMENF Target event for removal not found in record PI_AR_REPNER No events in record to replace PI_AR_REPENF Target event for replacement not found in record PI_AR_NAVBEFORE Target time before archive start time PI_AR_NAVAFTER Target time after archive end time PI_AR_NOTWRITEABLE Target archive is not writeable PI_AR_NOTSHIFTABLE Target archive is not shiftable PI_AR_DUPPRIMARY Attempted to register two primary archives PI_AR_OVERLAP Attempted to register overlapping archives PI_AR_RECLOCKFAIL Attempted to lock a locked archive record PI_AR_RECUNLOCKFAIL Attempted to unlock an unlocked archive record PI_AR_EMPTYFILE Attempting operation on an empty archive file PI_AR_TOOMANYEVENTS Event collection exceeded maximum allowed PI_AR_NOANNOTATION Annotation not found in archive PI_AR_ANNOTMISMATCH Annotation mismatch (archive) PI_AR_ANNOTEXIST Annotation already exist in archive PI_AR_SHIFTINPROG: Archive Shift already in progress PI_AR_BCKUPINPROG: Archive Backup already in progress PI_AR_BCKMODEMISMTCH: Backup End must follow Start and vice versa PI_AR_BADDIGDATA: Cannot convert to a Digital State PI_AR_SAMETIMEREC: Start time equal end time in archive record PI_AR_SAMETIMEARG: Start time equal end time argument in archive call PI_AR_SCALLFILTER: All data events are filtered in summary calculation. PI Server System Management Guide Page 311

334 Code Code Identifier Message PI_AR_SCNOEVENT: No events found within the time range of summary calculation PI_AR_SCOOSCALL: Out of sequence calls in summary calculation PI_AR_SCOOSEVENT: Out of sequence data events in summary calculation PI_AR_NULLLOADREC: Invalid record pointer for loading PI_AR_PTLOCKFAIL: Failed to lock archive-cache point PI_AR_NAVUNEXPECTED: Unexpected error navigating the archive PI_AR_ARCITERINVALID: Archive event iterator not properly initialized PI_AR_INVSAMPMODE: Invalid sample mode PI_AR_INVSAMPTIMES: Error with sample time array specification PI_AR_INVTIMECONST: Error with summary calculation time array PI_AR_INVNUMINTERVALS: Error with the summary calculation numinterval array PI_AR_SCNINVCB: Invalid CalculationBasis PI_AR_SCNINVTYPE: Invalid Summary CalcType PI_AR_SCNINVTIMES: Error with time constraint array in Sumnav object PI_AR_SCNINVFILTER: Error with the filter constraint array in Sumnav object PI_AR_SCNOOSRESCALL: Calling getresult before done in sumnav object PI_AR_SCNBADRE Internal error with result in sumnav object PI_AR_SCNINVARG: Invalid parameter in sumnav object PI_AR_SCNINTERPERR: Error interpolating data in sumnav object PI_AR_SCNOOSCALL: Out of sequence call in sumnav object PI_AR_SCNOOSEVENT: Out of sequence data event in sumnav object PI_AR_RCOVERFLOW: Point query exceeded maximum cache record count PI_AR_NONNUMERICSUM: Non-numeric tag in summary calculation PI_AR_LOWDISKSPACE: Low disk space, file cannot be created PI_AR_ANNGUIDMISMATCH: Annotation file ID is not matching archive file PI_AR_NODOWNGRADE: Archive file downgrade to requested version not Page 312

335 Code Code Identifier Message supported PI_AR_TOOMANYREQEVENT S: Number of requested events exceeded the maximum allowed PI_AR_NOTARCHIVING: Archive subsystem not in archiving state PI_AR_NEEDARCSIZE: Missing size information for new archive file creation PI_AR_RCEXCEEDSLIMIT Point has more cache records than maximum configured PI_AR_CACHEUSECOUNT Cache record found with invalid reference count on clean operation PI_AR_RECEIVEDNEWSNAP New snapshot event received while pending delete PI_AR_SHIFTIMMINENT Archive Shift predicted withing backup lead time PI_AR_FLUSHQLIMIT Reached maximum write cache events in lock contention PI_AR_FLUSHEVTIMEOUT Timeout waiting for point flush operation PI_AR_PRIMARYREADONLY Primary archive is Read-only. Archiving and archive shifts disabled PI_AR_INVMODEADDCACHE Invalid mode for adding event to cache PI_3PHUNAVAIL PI Server is not installed properly or is not running PI_RDR_HISTTIMEDVALUEFAI L PI_ RDR _HISTTIMEDVALUESFAIL PI_ RDR _SNAPTIMEDVALUEFAIL PI Redirector could not get archived value from foreign system PI Redirector could not get archived data from foreign system PI Redirector could not get snapshot value from foreign system PI_ RDR _SNAPISLOCALFAIL PI Redirector could not determine whether to cache snapshot values from foreign system PI_ RDR _SNAPSSIGNUP PI Redirector could not signup for updates with foreign system PI_ RDR _SNAPSUPDATESFAIL PI_ RDR _SNAPPUTTIMEDVALUEFAIL PI_ RDR _ADDCONNECTORFAIL PI Redirector could not get updates from foreign system. PI Redirector could not write snapshots to foreign system. PI Redirector could not load connector or set PI Server system name. PI Server System Management Guide Page 313

336 Code Code Identifier Message PI_ RDR _ARCSUMMARYFAIL PI Redirector could not get arcsummary/summaries directly from foreign system PI_V_NOANNOTATION Annotation not found in Pivalue PI_V_ANNOTMISMATCH Annotation mismatch PI_V_ANNOTEXIST Annotation already exist PI_V_ANNOTTOOLONG Annotation exceeds size limit PI_V_INVALID_VARIANT_TYP E Invalid variant type code PI_V_MISMATCH PIvalue mismatch PI_V_NOTATIME Variant type is not a time PI_V_NOTAUID Variant type is not a UID PI_OFFL_BADOPENFILE Error opening offline file PI_OFFL_BADRECNO Bad record number for offline input PI_OFFL_BADIDCONV Bad Id conversion table PI_OFFL_BADFILEREAD Failed to read input file (PI2) PI_OFFL_NOTINIDCONV Point ID not found in ID conversion table PI_OFFL_PTIDMM Point ID mismatch in offline loading PI_OFFL_NOTARGETREC Cannot post events, no target record PI_OFFL_INVTIMES Invalid Times For Offline loading PI_OFFL_BADARCTYPE Invalid archive type for processing PI_OFFL_NOEVENTS No events from input file were added to output archive Table A 10. Error Codes , With Messages Code Code Identifier Message PI_TABLEFROZEN Pint is Frozen from Changes PI_TABLENONAME Name Not Found in pint PI_TABLENOCODE Code Not Found in pint PI_TABLEDUPNAME Name Already in Use in pint PI_TABLEDUPCODE Code Already in Use in pint PI_TABLEINVNAME Invalid Name for Use in pint Page 314

337 Code Code Identifier Message PI_TABLEINVSLOT Invalid Slot for Use in pint PI_TABLEINUSE Table already contains entries PI_TABLELOADMIS Count Mismatch on Load PI_TABLEFILEUSE Underlying File Store in Use PI_TABLEMAXENTRIESEXCEEDED Attempt to activate or create table larger than allowed PI_TABLENOIDENTIFIER Identifier not found in PInttemplate PI_TABLEINVIDENTIFIER Identifier in PInttemplate is not valid PI_TABLENORECORDDEFINITION Record definition of generic table is empty PI_ARG_N OOWNLIST Arglist is Not Owned PI_ARG_OWNLIST Arglist is Owned PI_ARG_FROZEN Operation is Invalid on a Frozen List PI_ARG_BADMERGE Failed merge PI_GRID_BADSETCOLINF Pigrid: setcolinfo Failed PI_GRID_BADSETNUMROW Pigrid: setnumrows Failed PI_GRID_BADVERSION Pigrid: Version Mismatch in Activate PI_GRID_BADSETNUMCOL Pigrid: setnumcols Failed PI_UPD_NOTREG Not registered in updmgr PI_UPD_NOCONS Consumer not registered in updmgr PI_UPD_NOPROD Producer not registered in updmgr PI_UPD_MISMATCH Id mismatch PILIC_NOLICFILE no license file PILIC_ERROPENFILE error open license file PILIC_BADKEY invalid license key PILIC_INVSPECS invalid license specs PILIC_NOSUCHLIC no such license PILIC_NOTREGISTERED user not registered PILIC_LICEXCEDED usage exceeded licensed amount PILIC_LICEXPIRED license expired PI Server System Management Guide Page 315

338 Code Code Identifier Message PILIC_BADUSERKEY user mismatch PILIC_MISMATCH amount or another mismatch PILIC_NOLICFILE10 license error PILIC_SERVIDFILEEXISTS Server ID file creation failure; file already exists PILIC_SDKCONNECTIONS Maximum licensed SDK Application connections exceeded. Connection refused PILIC_APICONNECTIONS Maximum licensed API Application connections exceeded. Connection refused PILIC_POINTCOUNT Maximum licensed Point Count exceeded PILIC_MODULECOUNT Maximum licensed Module Count exceeded PILIC_POINTMODULECOUNT Maximum licensed aggregate Point/Module Count exceeded PILIC_BDB Not licensed to use Batch Database PILIC_MDB Not licensed to use Module Database PILIC_COMCONNECTORS Not licensed to use COM Connector-mapped points PILIC_SERVERAPP Not licensed to use this server or UDS application PILIC_CLIENTAPP Not licensed to use this client application PILIC_MAXHISTORY Not licensed to access Archive for passed dates PILIC_ERRGETMAC Error getting Machine info PILIC_NOLICMGR License Manager not accesible PILIC_NOKNOWNAPPS Did not receive Known Application data PILIC_OLDLICFILE License file too old to parse PILIC_INTERFACE Not licensed to use this interface PILIC_MIDDLEWARE Not licensed to use this middle-ware application PILIC_NONCCPOINTCOUNT Maximum licensed non-com Connector Point Count exceeded PI_BA_DUPACTIVETAG Batch active tag is already being used by another unit Page 316

339 Code Code Identifier Message PI_BA_BADSIZE Number of arguments in PIarray is incorrect PI_BA_BADACTIVETAGTYPE Batch Active Tag Type is not STEP or PULSE PI_BA_UNITARCHIVETAGMISSING Invalid unit identifier PI_BA_WAIT Wait for in use object PI_BA_BADSYNTAXBATCHID Batch ID expression Syntax Error PI_BA_BADSYNTAXPRODUCTID Product ID expression Syntax Error PI_BA_BADPTBATCHID Invalid tag in Batch ID expression PI_BA_BADPTPRODUCTID Invalid tag in Product ID expression PI_BA_UNSUPPORTEDACTIVETAG TYPE Batch active tag is not integer, real, or digital PI_BA_NOBATCHINEVENT PIevent does not contain a batch record (PIblob len 0 ) PI_BA_PIBANEXISTS Could not create a unique archive tag name for unit PI_BA_STARTTIMESTATUSINVALID Status of start time for a batch is invalid PI_BA_STOPTIMESTATUSINVALID Status of stop time for a batch is invalid PI_BA_BATCHEND This is an end of batch event PI_BA_BATCHSTART This is a start of batch event PI_BA_TIMENOTFOUND Time was outside boundaries of PIbaIndex Directory PI_BA_INVALIDINDEX Index for PIbaIndex Directory is invalid PI_BA_INVALIDTIMESPAN Time span within search contains no indexes PI_BA_NO_UNITS_MATCHED Unit mask matches none of the current units PI_BA_NO_END_EVENT_EXISTS No end event exists for this batch handle PI_BA_BATCHOREVENT_EXISTS Attempt to archive batch over existing batch PI_BA_INVALIDPIBLOB Archived batch record invalid PI_BA_CANTDELETE Attempt to delete an active batch or batch with null end timestamp PI_BA_NOBATCHES No matching batches were found PI_BA_INVALIDHANDLE Invalid or missing batch handle. Batch edit requires specifying a valid batch handle. PI Server System Management Guide Page 317

340 Code Code Identifier Message PI_BA_DUPACTIVETAG Batch active tag is already being used by another unit PI_PE_ERROR Performance equation error PI_PE_PARSEERROR Performance equation parsing error PI_PE_DIVIDEBYZERO Performance equation divide by zero error PI_PE_OVERFLOW Performance equation overflow error PI_PE_LEX_FILE_NOT_FOUND Performance Equation: File PExxx.llr not found in DAT directory PI_PE_RULE_FILE_NOT_FOUND Performance Equation: File PExxx.dfa not found in DAT directory PI_PE_RESOURCES_NOT_FOUND Performance Equation: File pisystem.res not found in DAT directory PI_PE_INVALID_CONNECTION Performance Equation: Invalid Connection PI_PE_BAD_TREE_AT_GENCODE Performance Equation: Bad parse tree during code generation PI_PE_BAD_TREE_AT_TYPECHEC K PI_PE_FUNC_WRONG_NUMBER_O F_ARGS Performance Equation: Bad parse tree during type check Performance Equation: Function has wrong number of arguments PI_PE_FUNC_NEEDS_ONE_ARG Performance Equation: Function needs at least one argument PI_PE_FUNC_TO_MANY_ARGS Performance Equation: Function has too many arguments PI_PE_FUNC_ARG1_NOT_DIGITAL Performance Equation: First argument for function is not digital PI_PE_FUNC_ARG1_NOT_TIME Performance Equation: First argument for function is not a time PI_PE_FUNC_BAD_ARG_TYPES Performance Equation: Function has bad argument data type PI_PE_FUNC_NEEDS_MORE_ARG S Performance Equation: Wrong number of arguments for function PI_PE_FUNC_ARG1_INVALID Performance Equation: Invalid first argument PI_PE_FUNC_ARG2_INVALID Performance Equation: Invalid second argument PI_PE_FUNC_ARG3_INVALID Performance Equation: Invalid third argument Page 318

341 Code Code Identifier Message PI_PE_FUNC_ARG4_INVALID Performance Equation: Invalid fourth argument PI_PE_FUNC_ARGS_NOT_SAME_T YPE PI_PE_FUNC_ARGS_NOT_NUMBE RS Performance Equation: All arguments must have same data type Performance Equation: All function arguments must be numbers or evaluate to numbers PI_PE_TOO_MANY_ARGS Performance Equation: Function has too many arguments PI_PE_ADD_CONNECT_FAILED Performance Equation: Connection failed PI_PE_TOO_MANY_CONNECTS Performance Equation: Too many connections PI_PE_PCT_GOOD_TOO_SMALL Performance Equation: Percent good is below requested threshold Table A 11. Error Codes , With Messages Code Code Identifier Message PI_MSG_BADQUERY Bad query for messages in GetMessages PI_MSG_BADMAXCOUNT The query for messages contains an invalid total number of messages parameter in GetMessages PI_MSG_BADSTARTTIME The query for messages contains an invalid PI format start time in GetMessages PI_MSG_BADENDTIME The query for messages contains an invalid PI format end time in GetMessages PI_MSG_BADMESSAGEID The query for messages contains an invalid Message ID in GetMessages PI_MSG_BADUSER The query for messages contains an invalid program name in GetMessages PI_MSG_BADSEARCHSTRING The query for messages contains an invalid message search string in GetMessages PI_MSG_BADOPTION1 The query for messages must have end time and/or total message count in GetMessages PI_MSG_BADOPTION2 The query for messages must have start time and/or total message count in GetMessages PI_MSG_BADOPTION3 The query for messages must have start time and/or end time in GetMessages PI_MSG_NAMEMISMATCH The query for messages contains an invalid name in the query name table in GetMessages PI Server System Management Guide Page 319

342 Code Code Identifier Message PI_MSG_BADFILE The PI Message file can not be read. It may be corrupt PI_AUD_FNF Cannot find audit file PI_AUD_CREFAIL Cannot create audit file PI_AUD_BCKUPINPROG Audit disabled during backup PI_AUD_WRITEERR Failed to write audit record PI_NTLOG_NOHANDLE No Application Event Log Handle PI_NTLOG_NOUPDATE Unable to get updates from App Log PI_NTLOG_NOSENDTOPI Unable to send event log messages to PI PI_NTLOG_BADGETREGVAL Unable to get values for pimsgss service registry key PI_NTLOG_NOREGKEY Unable to get registry key for service pimsgss PI_CTR_BADPERFINFO PIPerfInfo struct is bad PI_CTR_BADGETPERFREG Unable to get Perflib registration info PI_CTR_BADSETPERFREG Unable to set Perflib registration info PI_CTR_BADGETPIREG Unable to get PI performance registration info PI_CTR_BADSETPIREG Unable to set PI performance registration info PI_CTR_BADPERFLIBNUM Perflib Last Counter larger than Last Help PI_CTR_ODDPERFLIB Perflib Last Counter is odd number or Last Help is even number PI_CTR_BADPERFLIBSET Perflib Last Help is greater than Last Counter by more than one PI_BADCOUNTERNAMELENG TH he performance counter name is larger than 32 characters, counters will not be installed PI_TST_NOTFOUND Test not found in DB PI_TST_DBERROR Cannot record results in test DB PI_TST_MAILERROR Cannot test results PI_TST_NOPISYS Test requires running PI system PI_TST_INVATR Invalid test attribute PI_TST_FAILED Test failed Page 320

343 Table A 12. Error Codes , With Messages Code Code Identifier Message PI_ISTREAMFAIL Istream::get Failed PI_OSTREAMFAIL Ostream:: Failed PI_BADOFFSET Generic Out-of-Bounds Error (pistring, piarray) PI_NOTFOUND Element Not Found (piarray) PI_OVERFLOW Number Too Big For pivalue PI_NOTANUMBER Pivalue Type is Not Numeric PI_INFINITY Pivalue Divide by Zero PI_NOTAFLOAT Pivalue Type or pistring is Not Float PI_NOTANINTEGER Pivalue Type or pistring is Not Integer PI_BADFLOATFORMAT Number of Digits or Decimals Out of Range PI_NOTASTRING Pivalue Type is Not a String PI_WRONGVALTYPE Pivalue Type is Not Allowed For This Call PI_NOTABLOB Pivalue Type is Not a Blob PI_NOTAVALUETYPE Value Type is Not a Valid pivalue Type PI_INVALIDPATH Invalid path specified PI_BADTARGET Context sensitive bad target error PI_BADINITIALIZE Context sensitive initialization failure PI_BADVERSION Generic bad version failure PI_DUPLICATE Generic duplicate name PI_BADEVENTMODE Invalid or Unsupported pievent Mode PI_MAXLENGTHEXCEEDED Attempt to activate or create a pistring or piblob larger than max allowable PI_LOGMESSAGESTHROTTLED Excessive messages to PImsgss, log messages temporarily terminated PI_INVALIDBOOKMARK Invalid or corrupt book mark PI_INVALID Generic invalid call or argument PI_MISMATCH Generic mismatch PI_NOTADIG PIvalue type is not digital PI Server System Management Guide Page 321

344 Code Code Identifier Message PI_PATHNOTFOUND Requested path not found PI_BCKUPINPROG Cannot perform operation during backup PI_INVALIDTZCONFIG TimeZone configuration is invalid PI_MAXARRLENGTHEXCEEDED Attempt to activate or create a PIarray larger than max allowable PI_UNABLETORETRIEVEUNIXERRNO A call on UNIX fails but errno is zero PI_BADARGUMENTCONVERSION No suitable conversion from a variant to RPC argument PI_INVALIDTIMESTAMP PIvalue cannot represent PIstring as a valid timestamp PI_ENVVAR_EXISTS System environment variable already exists PI_MAXQUEUELIMIT Non-expandable PIfifo reached maximum capacity PI_EMPTYQUEUE Attempt to extract data from empty PIfifo Table A 13. Error Codes , With Messages Code Code Identifier Message PI_INVALIDEFFECTIVEDATE Object not found for passed effective date PI_MODULENOTFOUND Module does not exist PI_INVALIDMODULEVERSION Invalid or missing module version PI_DUPLICATEEFFECTIVEDATE Value with passed effective date already exists PI_LASTMODULEVALUE Cannot remove last module value. Use module remove PI_ROOTMODULE Attempt to remove or edit a Built in module element PI_MODULEHIERARCHYBREAK Attempt to delete or remove a module that breaks existing hierarchy PI_UNEXPECTEDMODULEDBERROR Unexpected PI Module Database error PI_MODULEVALUEEXISTS Effective date already exists for attempt add or move of a module value PI_INVALIDPARENT Invalid parent specified for the operation PI_DUPLICATEHIERARCHY Attempt to create or edit object with Page 322

345 Code Code Identifier Message duplicate hierarchical level PI_INVALIDHIERARCHY Attempt to create or edit object with invalided hierarchical level PI_NOPARENTREFERENCE Module does not have parent reference to specified module PI_NOCHILDREFERENCE Module does not have child reference to specified module PI_INVALIDQUERYDATE Invalid or unspecified query date PI_INVALIDUID Invalid or unspecified uid PI_INVALIDMODE Invalid or unspecified module value access mode PI_MODULEVALUENOTFOUND Module Value for passed effective date not found PI_INVALIDHEADING Specified heading does not exist or is member of different heading set PI_INVALIDTIMERANGE Invalid or unspecified time range for batch database search PI_NOMATCHINGMODULES No matching PIModules for call PI_NOMATCHINGBDBRECORDS No Matching Batch Database records PI_MDBNOTSUPPORTED Attempted operation not supported by the specified database PI_MDBCIRCULARREFERENCE Attempt to insert a PIModule that would cause a circular reference PI_MDBNOMATCHINGVALUES No module values within the passed time range PI_MDBLASTVALUE Attempt to remove the last module value PI_BDBCROSSREFERENCE Attempt to remove a Batch Database Record which contains a cross reference to another record PI_BDBBSSNOTSUPPORTED Batch Database does not support this action with Batch Subsystem Batch PI_INVALIDBDBTIME Invalid start or end time for Batch Database Record PI_BDBMAXRECORDSEXCEEDED Batch database search exceeded maximum allowed records PI_THREADPOOLDISABLED Subsystem does not support thread pool or PI Server System Management Guide Page 323

346 Code Code Identifier Message thread pool is disabled PI_THREADSUSPENDED Thread is in suspended state PI_INVALIDTHREADID Passed thread ID is invalid PI_THREADTIMEOUT Time out waiting for semaphore or lock PI_THREADABANDONED Thread or handle has been abandoned PI_THREADUNLOCK Attempt to release exclusive lock from thread that did not acquire the lock PI_THREADESCALATE Attempt to Escalate lock without prior nonexclusive lock PI_THREADEXCLUSIVE Thread already has exclusive lock PI_IOCOMPLETED Asynchronous IO has completed PI_THREADNOTSUPPORTED Thread control function not supported PI_UKNOWNLOCKERROR Unknown system error attempting to get lock PI_SHAREDLOCKTIMEOUT Timeout attempting to get non-excluseive lock PI_UNBALANCEDLOCKRETURN Lock return count greater than get count PI_EXCLUSIVELOCKTIMEOUT Timeout attempting to get excluseive lock PI_THREADPOOLOVERRANGE Attempt to create too many threads PI_ARCHK_OVFREVCHAIN Invalid backwards chaining of overflow record PI_ARCHK_IDXREVCHAIN Invalid backwards chaining of index record PI_ARCHK_RECIDXNOTFOUND Overflow record not found in index records PI_ARCHK_MULTIPLEIDXREF Index entry referenced by multiple overflow records PI_ARCHK_OOOIDXREC Out-of-order overflow record in index record PI_ARCHK_OOOEVENT Out-of-order event found in overflow record PI_ARCHK_INVANNHANDLE Event marked as annotated with no annotation handle PI_ARCHK_INVANNOTATION Annotation record not found for annotated event PI_ARCHK_DUPANNHANDLE Annotation record referenced by multiple Page 324

347 Code Code Identifier Message events PI_ARCHK_IDXTIMEMISMATCH Index not matching overflow record start time PI_ARCHK_EVBEFORESTART Event before archive start time PI_ARCHK_EVAFTEREND Event after archive end time PI_ARCHK_IDXACTIVATION Unexpected error reading index record PI_ARCHK_IDXSTARTERROR Index start time doesn't match archive start time PI_ARCHK_1STRECNOTHEAD First overflow record has a previous record PI_ARCHK_PTTYPEMISMATCH Point type not matching primary record PI_ARCHK_INVALIDIDXTYPE Unexpected data type for index record PI_ARCHK_INVALIDARCNUM Invalid archive file number PI_ARCHK_OVFCIRCHAIN Circular chaining of overflow record PI_ARCHK_IDXCIRCHAIN Circular chaining of index record PI_ARCHK_TOOMANYERRORS Too many errors, filtering non-fatal errors PI_MMQ_SYNC_CREATE Creation of Piarchss synchronization object failed PI_MMQ_SYNC_OPEN Opening of Pisnapss synchronization object failed PI_MMQ_SYNC_WRITETIMEOUT Timeout waiting for write access to Event Queue PI_MMQ_SYNC_WRITEFAILED Wait for queue write returned a WAIT_FAILED status PI_MMQ_SYNC_UNEXPECTED Unexpected error waiting for Event Queue access PI_MMQ_SYNC_READTIMEOUT Timeout waiting for read access to Event Queue PI_MMQ_SYNC_READFAILED Wait for queue read returned a WAIT_FAILED status PI_MMQ_INVALID_FILESIZE Invalid queue file size (requires inimum 2 data pages) PI_MMQ_FILEPATH_TOOLONG File path and name exceed 260 characters (MAX_PATH) PI_MMQ_PHYSFILE_CREATE Error while creating queue file PI Server System Management Guide Page 325

348 Code Code Identifier Message (pimapevq.dat) PI_MMQ_MAPFILE_CREATE Error while creating mapped file of Event Queue PI_MMQ_MAPFILE_OPEN Error while opening mapped file of Event Queue PI_MMQ_MAPFILE_MAPVIEW Error while mapping a page view of the queue file PI_MMQ_MAPFILE_INIT Event queue not initialized before read or write access PI_MMQ_MAPFILE_UNMAPVIEW Error while unmapping a page view of the queue file PI_MMQ_MAPFILE_FULL Event queue file is entirely full PI_MMQ_FILESIZE_MISMATCH Configured file size doesn t match existing file PI_MMQ_PAGESIZE_MISMATCH Configured page size doesn t match existing file PI_MMQ_FORWARD_VERSION Existing queue file is from a later version PI_MMQ_INVALID_READPAGE Invalid read page index in existing queue file PI_MMQ_INVALID_WRITEPAGE Invalid write page index in existing queue file PI_MMQ_INVALID_FREEPAGES Inconsistent number of available pages in existing queue file PI_MMQ_WRITEPAGE_FULL Write failedtarget write page is full PI_MMQ_STREAMINIT_ERROR Error while creating i/o stream object PI_MMQ_ACTIVATION_FAILED Read error while activating event from queue PI_MMQ_UNRECOGNIZABLE_FILE File format is not a valid memory-mapped Event Queue file PI_MMQ_MAPFILE_FLUSHVIEW Error while flushing to disk a view of the queue file PI_MMQ_EMPTY_READPAGE Attempt to read data from an empty page PI_MMQ_BAD_FILENAME Invalid overflow file name template PI_MMQ_BAD_EXTENSION Missing extension in overflow file name template Page 326

349 Code Code Identifier Message PI_MMQ_BAD_DATA_OFFSET Invalid data member offset within PImapfilepage PI_MMQ_EVCOUNT_MISMATCH Event count mismatch with empty data pages PI_SUBSYSINFO_INVALID_ARGUMEN TS PI_SUBSYSINFO_INVALID_PROCESSI D Invalid arguments for Sub-system Information RPC Invalid process ID Sub-system Information RPC PI_BCKFILE_FILENAME_NULL Cannot add file to the list of backed up files because the file name is null PI_BCKFILE_REMOVE_ERROR_FILEN OTFOUND PI_BCKFILE_ADD_ERROR_DUPLICAT EFILENAME PI_BCKFILE_DUPLICATE_BACKEDUP _FILE_LIST PI_BACKUP_BACKUPSUBSYS_NOT_I NITIALIZED Cannot remove file from list of backed up files because the file name was not found in the list Cannot add file to the list of backed up files because the file is already in the list Only one backup file list object can be created Backup manager is not initialized PI_BACKUP_VSS_UNSUPPORTED Unsupported operating system for Volume Shadow Copy Services PI_BACKUP_INVALID_COMPONENT_ NAME PI_VSSEVENT_FREEZE_IN_PROGRE SS PI_VSSEVENT_FREEZE_NOT_IN_PR OGRESS PI_BCKEVENT_FREEZE_TIMEOUT_W AITING_FOR_THAW_EVENT PI_VSSEVENT_FREEZE_TIMEOUT_D URING_FREEZE_EVENT PI_VSSEVENT_IDENTIFY_COMPONE NT_MISMATCH PI_BCKEVENT_SUBSYSTEM_NOT_P ARTICIPATING PI_BCKEVENT_RPCRESOLVEROFFLI NE Invalid component name VSS Freeze already in progress Expected VSS Freeze to be in progress, but freeze was not in progress VSS Freeze timed out waiting for VSS thaw event VSS Freeze timed out before VSS freeze event could complete VSS Identify failure. Two VSS components have the same name but different component properties Subsystem does not participate in backups. The backup event was ignored RPC Resolver offline for a subsystem to which the backup subystem is communicating. Find error in PI Server System Management Guide Page 327

350 Code Code Identifier Message message log to identify problematic RPC PI_BCKEVENT_IN_PROGRESS Backup event in progress PI_BCKSTATE_INVALID_STATE_TRA NSITION Invalid state transition for backup PI_BCKSTATE_BACKUP_ABORTED Backup was aborted PI_BCKSTATE_BACKUP_SHUTDOWN _NOCOMPLETE PI_BCKSTATE_BACKUP_IN_PROGRE SS Backup shutdown without completing Backup in progress PI_BCKRPC_NO_RESPONSE Expected VSS Async callback function was not called within timeout period PI_BCKRPC_CALLBACK_UNEXPECTE D PI_BCKRPC_INVALID_BACKUP_COM MAND PI_VSSAPI_ADDCOMPONENT_FAILE D PI_VSSAPI_ADDDATABASEFILE_FAIL ED PI_VSSAPI_BACKUPTYPE_UNKNOW N PI_VSSAPI_BACKUPTYPE_LOG_UNS UPPORTED PI_VSSAPI_BACKUPTYPE_OTHER_U NSUPPORTED Unexpected VSS Async callback. Callback function was called but was not expected Invalid backup command VSS API call AddComponent failed VSS API call AddDatabaseFiles failed Unknown backup type Backup type of LOG is unsupported Backup type of OTHER is unsupported PI_BCKLOCK_GETLOCK_TIMEOUT GetLock timeout for master backup lock PI_BCKLOCK_GETEXCLUSIVELOCK_ TIMEOUT PI_BCKLOCK_RETURNEXCLUSIVELO CK PI_BCKLOCK_RETURNEXCLUSIVELO CK_NOTLOCKED PI_BCKLOCK_GETLOCK_NONVSSBA CKUP GetExclusiveLock timeout for master backup lock ReturnExclusiveLock failed for master backup lock ReturnExclusiveLock for master lock failed because master lock was not locked GetLock failed for master backup lock because a non-vss backup is in progress Page 328

351 Table A 14. Error Codes , With Messages Code Code Identifier Message PI_UNX_SEMRANGE Semaphore count out-of-range PI_UNX_ARRSEM Semaphore belongs to array PI_UNX_EVNONAME No name for shared event PI_UNX_EVNOINIT Event not initialized PI_UNX_BADEVSEM Named semaphore init failed Table A 15. Error Codes , With Messages Code Code Identifier Message PI_WARNING Generic warning PI_PD_IGNORE Attribute ignored PI_PD_OPERATIONFAILED One or more point SDK operations failed PI_BCKSTATE_NOTREADY_FORFRE EZE Warning - not ready for freeze yet PI_NODATA Generic Nothing Found warning PI_TMPUNAVAIL Generic temporary unavailable - try later PI_RELOADED Generic reload warning PI_UPD_OVERFLOW Update queue overflow, some events missing PI_ALREADYLOCKED Request locking an already locked PI_CTR_NOINSTALL Perflib registry is bad, will not install counters PI_CTR_DONOTINSTALLCOUNTERS Performance counters chosen not to be installed PILIC_GRACELICEXP License expired or exceeded grace period PI_AR_DUPTIMESTAMPS Last event in collection has same timestamp as next event PI_AR_REMGENEVENT Attempt to remove or replace a generated event PI_AR_ANNFILERENAMED Annotation file not matching archive ID, successfully renamed PI_AR_INVCOMPEVENT Event for removal not found in snapshot record, passed to archive PI Server System Management Guide Page 329

352 Code Code Identifier Message PI_AR_NOTINBACKUPSTATE No archive file in backup state PI_RDR_PARTIALSUCCESS One or more Redirector operations failed PI_RDR_SUMMARYNOTSUPPORTED PI COM Connector does not support this summary. Summary will be performed on host. Page 330

353 APPENDIX B: PI PERFORMANCE COUNTERS PI Server has a number of performance counter statistics that can to be viewed using Microsoft s Performance Monitor utility (System Monitor in Windows 2000). The following tables list the statistics that may be viewed. PI Base Subsystem Statistics Attribute Point Count Connector Point Count Point Create or Edit/sec Digital State Translations/sec Wild Card Searches/sec Point Accesses/sec Module Count Heading Set Count Heading Count Module Database Record Count Module Create or Edit/sec Heading Set Create or Edit/sec Heading Create or Edit/sec Module Database Create or Edit/sec Description Total number of defined points. This number includes the Connector Point Count. Count of defined points that are mapped points. These are points that interact with points on a foreign data historian using a COM Connector. Rate at which points are created or edited. Rate at which digital state strings are translated to offsets. Rate of wild card point searches. This counter represents the rate at which new searches are started, not the number of points found. Rate at which point information is accessed, not including point edits. This will include translations of tag to point id. The total number of modules in the module database. The total number of heading sets in the module database. The total number of headings in the module database. The total number of records in the module database. Rate at which modules are created or edited. Rate at which heading sets are created or edited. Rate at which headings are created or edited. Rate at which MDB records are created or edited. PI Server System Management Guide Page 331

354 Attribute Module Accesses/sec Heading Set Accesses/sec Heading Accesses/sec Module Database Accesses/sec Description Rate at which module information is accessed, not including module edits. Rate at which heading set information is accessed, not including module edits. Rate at which heading information is accessed, not including module edits. Rate at which module database information is accessed, not including module edits. PI Archive Subsystem Statistics Attribute Archived Events/sec Out of Order Events/sec Events Cascade/sec Events Read/sec Read Operations/sec Primary Archive Number Cache Record Count Cache Records Created/sec Cache Records Deleted/sec Record Disk Reads/sec Record Disk Writes/sec Cache Record Disk Reads/sec Cache Record Memory Reads/sec Overflow Index Record/sec Overflow Data Record/sec Cache Clean Operations/sec Cache Flush Description Rate of successful event addition to the archive. Out of order events posted in the archive. Rate of Out-of-Order events causing record shifts. Rate of archive events read. Rate of archive read calls. Each call can return multiple events. The rate of event retrieval is Events Read/sec. Internal index number of archive current assigned to primary position. Archive cache records in memory. Rate at which archive cache records are created. Rate at which archive cache records are deleted. Rate of archive disk reads (includes Cache Record Disk Reads/sec). Rate of archive disk writes. Rate of archive cache disk reads. Rate of archive cache memory hits. Rate at which index archive records are created. Rate at which data archive records are created. Rate at which archive cache records are removed from memory. Rate at which points are flushed to disk. Page 332

355 Attribute Operations/sec Time to Archive Shift Connector Read Operations/sec Connector Events Read/sec Connector Summaries/sec Connector Events Read Exec Time Connector Event Read Exec Time Connector Summaries Exec Time Point Flushes Last Cycle Unflushed Points Archive Cycles/Sec Total Unflushed Events Configured Cache Record Pool Current Cache Record Pool Config. Max Unflushed Events/pt Current Max Unflushed Events/pt Primary Archive % Used Event Queue Chunk Size Flush Queue Size Write Contentions/sec Write Contention Points GetSnapshot Calls/sec Description Number of seconds until the archive is projected to shift. This time is not calculated if the archive is less than 20% full. Rate of calls to read events for mapped points through COM Connectors. This rate is NOT included in the Read Operations/sec counter. Rate of events read for mapped points through COM Connectors. This rate is NOT included in the Events Read/sec counter. Rate of summaries for mapped points through COM Connectors. This rate is NOT included in the Events Read/sec counter. Time elapsed in milliseconds for one Events Read for a COM Connector point. Time elapsed in milliseconds for one Event Read for a COM Connector point. Time elapsed in milliseconds for one summaries call for a COM Connector point. Number of points flushed to disk during last cycle. Busy points might get flushed several times per cycle. Number of points that have at least one unflushed event. Number of Subsystem cycles per second. Total number of unflushed events. Maximum number of cache records in the read-only pool. Current maximum number of cache records, this may be lower that the configured value due to low memory resources. Maximum number of unflushed events per point. Current maximum number of unflushed events per point, this may be lower that the configured value due to low memory resources. Percent of used records in Primary Archive File. Number of events read per Event Queue read operation. Number of pending flush operations in memory queue. Rate of write lock contentions (EVQ threads). Number of points in write contention last cycle. Rate of internal calls to the Snapshot Subsystem. PI Server System Management Guide Page 333

356 Attribute ArcEvent Calls/sec CompEvents Calls/sec InterpEvents Calls/sec PlotEvents Calls/sec Summary Calls/sec PICampaigns Created/sec PIBatches Created/sec PIUnitBatches Created/sec PITransferRecords Created/sec PICampaigns Edited/sec PIBatches Edited/sec PIUnitBatches Edited/sec PITransferRecords Edited/sec PICampaigns Read /sec PIBatches Read /sec PIUnitBatches Read /sec PITransferRecords Read/sec PICampaigns Deleted /sec PIBatches Deleted /sec PIUnitBatches Deleted /sec PITransferRecords Deleted /sec Description Rate of single archive event calls. Rate of compressed events calls. Rate of interpolated events calls. Rate of plotted (trended) event calls Rate of summary/filter expression calls. Rate of PI Campaign creation. Rate of PI Batch creation. Rate of PI Unit Batch creation. Rate of PI Transfer Record creation. Rate of PI Campaign edits Rate of PI Batch edits Rate of PI Unit Batch edits Rate of PI Transfer Record edits. Rate of PI Campaign access. Rate of PI Batch access. Rate of PI Unit Batch access. Rate of PI Transfer Record access. Rate of PI Campaign deletion. Rate of PI Batch deletion. Rate of PI Unit Batch deletion. Rate of PI Transfer Record deletion. PI Snapshot Subsystem Statistics Attribute Snapshots/sec Out Of Order Snapshots/sec Description Rate at which events are sent to the snapshot. Rate at which out-of-order events are sent to the snapshot. Page 334

357 Attribute Queued Events/sec GetSnapshots/sec GetSnapshot Calls/sec GetSnapshots Calls/sec Remove Snapshots/sec Digital State Translations/sec Connector Snapshots/sec Connector GetSnapshots/sec Connector Updates/sec Connector Snapshot Put Elapsed Time Connector Snapshot Read Elapsed Time Connector Updates Elapsed Time Events in Primary Queue Number of Overflow Queues Events in Overflow Queues Estimated Remaining Capacity Event Queue Total Pages Event Queue Used Pages Event Queue Page Shifts/sec Description Rate at which events are sent to the Event Queue. Rate at which events are read from the snapshot. Rate of individual snapshot value calls. Rate of multiple snapshot values calls. Rate of snapshot values being deleted. Rate of digital strings translated into offsets. Rate at which events are sent to mapped points through COM Connectors. This rate is NOT included in the Snapshots/sec counter. Rate at which events are read from mapped points through COM Connectors. This rate is NOT included in the GetSnapshots/sec counter. Update events received from COM Connectors. This rate is NOT included in the Connector GetSnapshots/sec counter. Time elapsed in milliseconds for Snapshot Put for COM Connector a point. Time elapsed in milliseconds for Snapshot Read for a COM Connector point. Time elapsed in milliseconds for Updates for COM Connector points. Number of events in the primary queue file. Number of overflow queue files (0 if only the primary queue is active). Total of events in the overflow queue files. Estimated maximum number of events with current queue file. Number of data pages in primary queue file. Number of full data pages in primary queue file. Rate of data page shifts in primary queue file. Primary Event Queue Id Identification number of primary queue (0 to 65,535). PI Server System Management Guide Page 335

358 PI Message Subsystem Statistics Attribute Sent Messages/sec Retrieved Messages/sec Inserted Messages/sec Description The number of messages sent to PI Message Subsystem per second. The number of messages retrieved by the PI Message Subsystem per second. The number of messages that were inserted into the PI Message Subsystem from the Application Event Log per second. PI SQL Subsystem Statistics Attribute Callbacks/sec ArcValueCompCalls/sec ArcValueCompEvents/sec WildcardSearches/sec WildcardPoints/sec ArcValueCalls/sec SnapshotCalls/sec WHERE Clause Evaluations/sec ArcValueTimedCalls/sec ArcValueTimedEvents/sec SummaryArcValueCalls/se c Dot Variable Evaluations/sec Next Point With Source Calls/sec Description Rate of calls to PI-SQL execution callback routine. Rate of RPC calls made to the PI Archive Subsystem for compressed events. Rate at which compressed data events are returned by the PI Archive Subsystem. Rate at which new wildcard searches are initiated in the PI Point Database. Rate at which points are returned when performing wildcard searches of the PI Point Database. Rate of RPC calls made to the PI Archive Subsystem to obtain a single archived value. Rate of RPC calls made to the PI Snapshot Subsystem to obtain a single snapshot value. Rate of full evaluations of the WHERE clause of a SELECT statement. Rate of RPC calls made to the PI Archive Subsystem for interpolated or timed events. Rate at which interpolated or timed data events are returned by the PI Archive Subsystem. Rate of RPC calls made to the PI Archive Subsystem for summarized values (i.e. average, total, standard deviation, etc.). Rate of "dot" variable evaluations made within the PI SQL Library. A dot variable in SQL is a table alias and column name, such as "picomp.tag. This rate is a measure of PI SQL Subsystem processing not related to obtaining data from other subsystems. Rate at which points are returned by the PI Base Subsystem in searches for points with a specific PointSource attribute. Page 336

359 Attribute PostCalls/sec PostEvents/sec Handles Description Rate of RPC calls made to the PI Snapshot Subsystem to post events from execution of SQL INSERT or UPDATE statements. Rate at which data events are posted to the PI Snapshot Subsystem from execution of SQL INSERT or UPDATE statements. Number of PI SQL handles currently allocated in the PI SQL Subsystem. This is an indication of how many clients are actively processing SQL statements. PI Totalizer Subsystem Statistics Attribute Total Point Count Source Tag Values/sec EventExpr/sec FilterExpr/sec Filter Changes/sec Period End/sec Updates/sec Update status Description The total number of active PI Totalizer Subsystem points. Rate of Totalizer input events. Rate of EventExpr evaluations. Rate of FilterExpr evaluations Rate of Filter state changes Rate of Totalization period completions Rate of snapshot values to Totalizer points The status of the PI Update Manager as perceived by the PI Totalizer. If non-zero, this is the absolute value of the most recently received error code. If zero, all is well. PI Network Manager Statistics Attribute Connections Messages Sent/sec Messages Received/sec Bytes Sent/sec Bytes Received/sec Overflow/sec Receive Errors Description The number of connections to the PI Network Manager. Applies to _Total only. The number of messages sent to the PI Network Manager. The number of messages received by the PI Network Manager. The number of bytes sent to the PI Network Manager. The number of bytes received by the PI Network Manager. The number of times an overflow message is required by the PI Network Manager. The number of times an error occurs during a receive of a message to the PI Network Manager. PI Server System Management Guide Page 337

360 Attribute Send Errors PI API Connections PI SDK Connections Licensing Failures Licensing Warnings Description The number of times an error occurs during a send of a message to the PI Network Manager. The number of PI API applications connected. The number of PI SDK applications connected. The number of times an application was rejected due to licensing concerns The number of times an application was warned of licensing concerns PI Performance Equations Statistics Attribute AlarmFuncCalls/sec ArcFindCalls/sec ArcSummaryCalls/sec ArcValueCalls/sec FailedEvaluations/sec NumberOfPEs SnapshotCalls/sec SnapshotEvents/sec SteamFuncCalls/sec TotalEvaluations/sec Description Rate of calls made to alarm functions. Rate of calls made to the PI Archive Subsystem for finding values. Rate of calls made to the PI Archive Subsystem for summarized values. Rate of calls made to the PI Archive Subsystem for compressed events. Rate of PE evaluations that return the digital state Calc Failed. Number of Performance Equations. Rate of calls made to the PI Snapshot Subsystem to obtain snapshot event(s). Rate of snapshot event retrieval. Rate of calls made to steam functions. Rate of PE evaluations. PI Session Statistics Attribute Messages Sent/sec Messages Received/sec Bytes Sent/sec Bytes Received/sec Receive Errors Send Errors Description The number of messages sent by the PI session. The number of messages received by the PI session. The number of bytes sent by the PI session. The number of bytes received by the PI session. The number of times an error occurs during a receive a message by the PI session. The number of times an error occurs during a send of a message by the PI session. Page 338

361 PI Subsystem Statistics Attribute Message Queue Length Pending Transactions Actual Pending Transactions Message Pickup Time Message Execution Time Message Complete Time Callback Execution Time Transaction Completed/sec Transaction Cancelled/sec Transaction Avg Time Transaction Max Time Lock Acquisitions/sec Lock Timeouts/sec Lock Contentions/sec RPC Threads Total RPC Threads Active File Open File Close File Read/Sec File Write/Sec File Delete/Sec File Create File Compress File Grow Description Number of incoming messages in queue. Number of pending transactions. Only for internal debugging purpose. You should use it only under the suggestion of OSI Technical Support. Latency of incoming messages (time in message queue). Execution time of incoming message (RPC). Total message handling time (including results sending). Execution time of transaction callback. Number of transactions completed per second. Number of transactions cancelled per second. Average execution time of outgoing transactions. Maximum execution time of outgoing transactions. Number of successful lock acquisitions per second Number of lock timeouts (failed locks) per second. Number of lock conflicts (threads waiting for the same lock). Total number of RPC worker threads (query processing). Number of RPC worker threads processing a query. Number of time File base Open called. Number of time File base Close called. Rate of File base Read. Rate of File base Write. Rate of File base Delete. Number of time File base Create called. Number of time File base Compress operations. Number of time File Directory grow operations. PI Server System Management Guide Page 339

362 PI Update Manager Statistics Attribute Pending events New events/sec Lost events/sec Update signups New registration/sec Consumer count Max pending events Get Events calls/sec Description Total Events pending in the PI Update Manager database. Events sent to the PI Update Manager. Events lost due to the PI Update Manager database being full. Queued signups in the PI Update Manager. Consumer and Producer registration rate. Total number of registered consumers. Maximum pending events reached in the PI Update Manager database. Total consumers Getevent calls rate. PI Update Consumer Statistics Attribute Pending events New events/sec Lost events/sec Update sign-ups Get Events calls/sec Description Total Events pending for this consumer. Event rate for this consumer. Events lost due to the PI Update Manager database being full. Queued sign-ups for this consumer. Getevent calls rate. PI Update Producer Statistics Attribute Pending events New events/sec Update calls/sec Update sign-ups Description Total Events pending for this producer. Event rate for this producer. Rate of incoming update calls Queued sign-ups for this producer. PI Server LocalHost Statistics The piperfmon.dif file contains examples of some basic performance counters useful in monitoring PI Server. These points contain performance information about the PI Server as well as the machine that runs it. The performance counters for the machine are useful in determining resource problems of the machine that runs PI Server. The performance counters for the PI Server are useful in determining how well the PI Server is performing. Page 340

363 Table B 16. PI Performance Counters Tag PERF.LOCALHOST.Logical Disk(_Total).Free Megabytes PERF.LOCALHOST.Memory.% Committed Bytes In Use PERF.LOCALHOST.Memory.Page Faults/sec PERF.LOCALHOST.Process or(0).% Processor Time PERF.LOCALHOST.TCP.Se gments Retransmitted/sec PERF.LOCALHOST.TCP.Se gments Sent/sec PERF.LOCALHOST.Process (piarchss).% Processor Time PERF.LOCALHOST.Process (pibasess).% Processor Time PERF.LOCALHOST.Process (pinetmgr).% Processor Time PERF.LOCALHOST.Process (pisnapss).% Processor Time Explain Text Free Megabytes displays the unallocated space on the disk drive in megabytes. One megabyte = 1,048,576 bytes. % Committed Bytes In Use is the ratio of Memory: Committed Bytes to Memory: Commit Limit. (Committed memory is physical memory in use for which space has been reserved in the paging file should it need to be written to disk. The commit limit is determined by the size of the paging file. If the paging file is enlarged, the commit limit increases, and the ratio is reduced). This counter displays the current percentage value only; it is not an average. Page Faults/sec is the overall rate that faulted pages are handled by the processor. It is measured in numbers of pages faulted per second. A page fault occurs when a process requires code or data that is not in its working set (its space in physical memory). This counter includes both hard faults (those that require disk access) and soft faults (where the faulted page is found elsewhere in physical memory). Most processors can handle large numbers of soft faults without consequence. However, hard faults can cause significant delays. This counter displays the difference between the values observed in the last two samples, divided by the duration of the sample interval. % Processor Time is the percentage of time that the processor is executing a non-idle thread. This counter was designed as a primary indicator of processor activity. It is calculated by measuring the time that the processor spends executing the thread of the Idle process in each sample interval, and subtracting that value from 100%. (Each processor has an Idle thread, which consumes cycles when no other threads are ready to run). It can be viewed as the percentage of the sample interval spent doing useful work. This counter displays the average percentage of busy time observed during the sample interval. It is calculated by monitoring the time the service was inactive, and then subtracting that value from 100%. Segments Retransmitted/sec is the rate at which segments are retransmitted, that is, segments transmitted containing one or more previously transmitted bytes. Segments Sent/sec is the rate at which segments are sent, including those on current connections, but excluding those containing only retransmitted bytes. % Processor Time is the percentage of elapsed time that all of the threads of this process used the processor to execute instructions. An instruction is the basic unit of execution in a computer, a thread is the object that executes instructions, and a process is the object created when a program is run. Code executed to handle some hardware interrupts and trap conditions are included in this count. On Multi-processor machines the maximum value of the counter is 100 % times the number of processors. PI Server System Management Guide Page 341

364 Tag PERF.LOCALHOST.PI Archive.Read Events operations/sec PERF.LOCALHOST.PI Archive.Cache Record Disk Reads/sec PERF.LOCALHOST.PI Archive.Cache Record Memory Reads/sec PERF.LOCALHOST.PI Base Subsystem.Point Count PERF.LOCALHOST.PI Network Manager(_Total).Connection s PERF.LOCALHOST.PI Network Manager(_Total).Messages Sent/sec PERF.LOCALHOST.PI Network Manager(piarchss).Message s Sent/sec PERF.LOCALHOST.PI Network Manager(pibasess).Message s Sent/sec PERF.LOCALHOST.PI Network Manager(pisnapss).Message s Sent/sec PERF.LOCALHOST.PI Snapshot.OutOfOrderSnapsh ots/sec PERF.LOCALHOST.PI Snapshot.Queued Events/sec PERF.LOCALHOST.PI Snapshot.Snapshots/sec PERF.LOCALHOST.PI Update-Manager.Pending events PERF.LOCALHOST.CALCU LATED.PI Compression Ratio Explain Text Rate of archive events read. Archive cache disk reads. Archive cache memory hits. Total number of defined points. This number includes the Connector Point Count. The number of connections to the PI Network Manager. This counter only applies to instance _Total. The number of messages sent to the PI Network Manager. Out of order events sent to the snapshot. Events sent to Event Queue. Events sent to the snapshot. Total Events pending in the PI Update Manager database. PI Compression Ratio is a performance equation that calculates amount of data that is compressed. Page 342

365 Tag PERF.LOCALHOST.CALCU LATED.PI Archive.Cache Hit Rate Explain Text PI Archive.Cache Hit Rate is a performance equation that measures the rate at which data is accessed from memory as opposed to disk. PI Server System Management Guide Page 343

366

367 TECHNICAL SUPPORT AND RESOURCES Technical Support Options OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a week. You can read complete information about technical support options, and access all of the following resources at the OSIsoft Technical Support Web site: OSIsoft provides the following support options and resources. Help Desk and Telephone Support Telephone support is available 24 hours a day, 7 days a week. Please note that in some cases you may need to leave a message, and you will receive a call back within one hour. Call the Technical Support Center at (01) FAX Technical Support at (01) Support support is available 24 hours a day, 7 days a week. Send technical support inquiries, including the problem description and message logs, to: [email protected]. Technical Support will respond to your inquiry within 24 hours. Personalized Online Technical Support The Online Call Center allows you to create a support call, which will be responded to in 24 hours. It also allows you to review information from your previous support calls. Click My Support > My Calls. My Support also allows you to review My Products, My Download History, and SRP Terms, which covers Service Reliance Program (SRP) service agreements. 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 in 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). PI Server System Management Guide Page 345

368 System Manager Resources include tools and instructions that help you manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving Time configuration, PI Server security, PI System sizing and configuration, PI Trusts for Interface Nodes, and more. Remote Server Access Technical support engineers can remotely access your PI Server to provide diagnostics, hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us > Remote Access Options in the Technical Support Web site. On-site Technical Support OSIsoft provides on-site service according to SRP service level agreements. To see current SRP status, go to My Support > SRP Terms in the Technical Support Web site. 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 message log(s) at that time Find Version and Build Numbers To find version and build numbers for each PI System subsystem (which vary depending on installed upgrades, updates or patches) use either of the following methods: If you have PI System Management Tools (PI SMT) installed, select Start > Programs > PI System > PI System Management Tools. In PI SMT, select the server name, then under System Management Plug-Ins, open Operation > PI Version. The PI Version tree lists all versions. If you do not have PI SMT installed, open a command prompt, change to the pi\adm directory, and enter piversion -v. To see individual version numbers for each subsystem, change to the pi\bin directory and type the subsystem name followed by the option -v (for example, piarchss.exe -v). View Computer Platform Information To view platform specifications: In Windows, right-click on My Computer and choose Properties. For more detailed information, select Start > Run, and enter msinfo32.exe In UNIX, enter uname -a Page 346

369 INDEX OF TOPICS? command, 186?atr command, 186?tbl command, 186 piconfig, 173 Abbreviations, 220 Access Permissions algorithm, 122 Changing, 123 read-write, 122 Active Directory Slow access to, 255 Activity grid, 253 Adding a digital state Set, 196 Alias Table Batch, 208 Annot, 201 Annotations, 207 API about, 96 on VMS, 95 API buffering. See buffering API Nodes, 96 application programming interface, 96 AppName field, 131 APS utility, 113 architecture distributed data collection, 94 Archive Archived Events counter, 28 Archiving Flag, 29 Cache, 28 combining files, 59 contents of, 27 Corrupted, 243 dividing, 60 dynamic, 36 file recovery, 270 Files, 34 Fixed, 36 full, 36 initializing, 57 Listing values, 203 Management, 33 data file, 270 Memory Cache, 28 Performance daily monitoring, 27 Primary Archive, 46 Number, 29 Registering, 46 Reorganizing files, 59 Repairing the Registry, 246 Restore, 244 Sequence Number, 47 Shift Enable Flag, 58 Prediction, 29 Archive Manager Data File recovery, 270 archive record size, 34 archive registry, 56 Archive Subsystem PI Server System Management Guide Page 347

370 performance counters, 332 Archive Subsystem Troubleshooting, 231 archive walk, 49 archives archive registry, 56 annotation files, 52 anticipating overflow, 51 archive shift, 33 archive shifts, 57 archive walk, 49 backfilling without compression, 54, 55 command-line tools, 37 creating, 52 creating new primary, 55 deleting, 56 editing data in, 51 failing to register, 55 fixed and dynamic, 33, 35 for previously collected data, 54 forcing archive shifts, 58 gaps, 34 ID conversion file, 43 index records, 35 list record details, 49 maximum size, 53 minimum and maximum size, 52 moving, 56 moving to another server, 43 naming, 52 offline utility, 41 piarchss parameters, 41 piarchss utility, 41 piartool utility, 37 precentage records used, 47 predicting shifts, 47 processing, 41 records, 34 registering, 56 registering, 33 shift p rediction, 57 size considerations, 53 sizing, 53 slow access, 35 space needs, 51 specifying maximum size, 54 specifying number of points, 53 time limit on modifying, 52 unregistering, 56 Archives About, 33 ArchiveX, 202 ASCII file using in piconfig, 183 Attribute Point Location4, 104 PointSource, 103 Attribute Set Table, 191 Attributes Access Permissions changing, 123 Displaying, 174 For subsystems, 210 Istructure, 190 Llisting for table, 186 Modifying in Point Database, 189 Wrong Class, 189 Set Point Database, 188 Time, 207 Timenum, 207 Automatic Point Synchronization, 113 Automatic Startup Compaq Tru64 UNIX Systems, 11 HP-UX 10 Systems, 9 HP-UX 9 Systems, 15 IBM AIX Systems, 13 Page 348

371 PI Server, 6 Solaris UNIX Systems, 7 Windows Services, 6 backfilling archives creating new primary archive, 55 without compression, 54, 55 backfilling data, 54 Backups Automating, 66 PI Server, 63 Recommendations, 66 Base Subsystem, 230 performance counters, 331 Batch Alias Table, 208 Batch method piconfig, 172 Batch mode, 183 Batch Subsystem Batch Unit Table, 207 Batch Tables, 209 BATCHEXPR, 208 BID Batch Subsystem, 209, 214, 215 BIDsearch Batch Subsystem, 209 Boolean values, 222 buffer, 95 buffering about, 95 maximum size of buffer, 95 recommendations, 95 Buffering PI API, 96 bufserv file buffer size, 95 Bye command, 183 BytesRecv, 211, 212 BytesSent, 211, 212 C language, API, 96 Case command, 220 Case-preserving, 220 Case-sensitive, 220 Digital State Set, 198 flag, 186 UNIX operating system, 172 Cd command, 186 Character special, Changing, 223 t for true, 178, 179 Classic Point Attributes, 189 Classicctr, 258 Clear command, 186 Client Applications Connection Messages, 290 Security, 125 clock setting on interface nodes, 101 clock, system, 23 codes, error operating system, 21 COM component register, 279 COM Connector in-process, 262 out-of-process, 262 troubleshooting, 257, 261 Web site, 257 Combining Archives, 59 ComChar, 186, 223 Comma Separated Format, 179, 190 Command?tbl, 173 All in piconfig, 186 Bye, 183 Case, 220 character, 186, 223 piconfig, 172 Comm, 180 Endsection, 182 Error, 184 PI Server System Management Guide Page 349

372 help, 176 Iistructure, 196 input, 220 Llisting all, 186 Ostructure, 180 Output, 184 piconfig commands, 176 Quit, 183 Select, 176, 181 Status piconfig, 173 Table, 173 Command Line Arguments, 223 Command Specification Persistence, 223 Comment, 186 Character, 186, 190, 223 Changing, 180 Command, 180 Lines, 180 Communication layer, 251 Routing function of PINet Manager, 229 COMP mode, Piarc Table, 203 Compaq Tru64 process count, 234 Compare mode, 178 compression backfilling archives without, 54, 55 for backfilling archives, 54 out of order events, 23 ratio, 24 Compression Specifications, 24 compression tuning, 24 Computer platform Information, 346 Connection Credentials, 128 evaluating matches for, 134 firewall, 135 Connections connection credentials, 128 Display info on, 212 ID, 291 Messages Clients, 290 Subsystems, 291 slow, 254 ConStatus, 212 Consumer pilistupd utility, 238 ConTime, 212 ConType, 212 conversion files, ID, 43 Convert mode, 178, 224 Corrupted Archives, 243 non-primary, 241 Primary, 242 Count Batch Subsystem, 209 PIARC Table, 203 piartool -al, 47 counter events, 23 events in queue, 24 events in queue counter, 24 events sent to queue counter, 24 number of overflow queues, 25 out of order events, 23 out-of-order events, 23 remaining queue capacity, 25 snapshot events read, 24 total overflow events, 25 Counter Archive Memory Cache counters, 28 Archived Events, 28 Events Read, 28 Page 350

373 number of archive read requests, 28 out-of-order event archive, 28 Overflow Data Record, 30 Overflow Index Record, 30 PI Server Performance, 340 counter, point, 23 counters performance, 331 CPU Excessive usage of, 253 CPU usage by utilities, 252 Create Mode, 178 creating archives for old data, 54 creating new primary archives, 55 CSV format, 190 ctr_lmap, 258 ctr_progid, 258 ctr_strmap, 258 data time limit on modifying, 52 Data File repairs, 241 Recovering from corrupted archives, 241 Data Archive Adding values, 201 data buffering about, 95 data flow buffering, 95 snapshot, 22 Database Firewall, 219 Point, 57, 189 Timeout, 219 Trust, 218 Database Security, 173 Database Security Table, 216 Dates overlapping, 245 Daylight Savings Time and interface nodes, 101 customizing changes, 267 list of changes, 267 Dbsecurity, 173 DbsecurityTable, 216 Dcomcnfg, 257, 262 Default Digital State Set, 195 default values pigetmsg parameters, 19 Delete Mode, 178 deleting archives, 56 deleting connection error message, 22 Delimited Structure type, 179 Delimiter, 186 Character, 180, 187, 223 Command, 180 Format, 179, 223 Digital State, 5, 172 Table, 195 Digital State Set adding, 196 capitalization, 198 Changing the Name, 198 default, 195 limits, 195 modifying, 197 Digital State Table merging systems, 153 Digital State Value Sending to the Snapshot database, 200 Digital tag Creating, 199 DigitalSet, 199 Directory PI Server System Management Guide Page 351

374 PIHOME directory on NT, 101 Disconnect Messages, 292 distributed data collection, 94 Documentation conventions, v for interfaces, vi Domain Name Server, 129 trust logins, 132 Domain Controller Slow access to, 255 Dr. Watson, 278 DST and interface nodes, 101 Dump capability crash pidiag, 278 dxwindows, 234 Dynamic archive, 36 dynamic archives, 33, 35 Echo, 186 Edit Mode, 178 Edit Mode Attribute, 204 editing archives, 51 Ellipsis construct, 182 End of file, 183 EndRecord, 186 End-Repeat, 186 Endsection, 186 Command, 182 Endtime, 203 error messages interpreting, 21 Error code number translating to message text, 265 Command, 184 messages, 281 interpreting, 281 Negative or Positive, 293, 294 error messages about, 21 deleting connection, 22 interpreting, 21 operating system, 21 rpc resolver, 22 subsystem health check failed, 22 EVEN interpolated events, Piarc, 203 event definition of, 23 in the event queue, 24 out of order, 23 overflow events, 25 remaining primary queue capacity, 25 sent to the Event Queue, 24 Event Log configuring, 260 event queue events in, 24 events sent to, 24 monitoring, 25 number of overflow queues, 25 remaining capacity, 25 total overflow events, 25 Event Queue recovery, 61 Troubleshooting, 230 Event Timestamps correcting, 245 events time limit on modifying, 52 events counter, 23 events in queue counter, 24 events read counter, 24 events sent to queue counter, 24 Excel Adding tags to Point Database, 190 Exit, 183, 187 Page 352

375 Failed to unregister input archive message, 242 file buffer, 95, See also buffering maximum size, 95 File corruption, 241 File handles, 233 File-base Utility, 269 compact, 269 index, 269 Firewall, 219 Database, 219 Modifying, 118 Security, 117 troubleshooting, 228 Fixed Format, 180 structure Structure type, 179 Fixed Archive, 36 fixed archives, 33, 35 Flag Shift-enable, 57 Flags, 201 Flatline in a trend troubleshooting, 255 Force processing, 196 Format Delimiter, 179, 182, 223 Fixed, 180 Keyword, 180, 186 full, archive, 33 gaps archives, 34 General Table Interface Timeout, Firewall, Proxy, 219 Group assigning users to, 126 Database, 125 table for, 215 Handle Batch Subsystem, 209, 214, 215, 219 Help Command, 176 lists all commands, 187 Hexadecimal notation, 224 Hostmask, 173, 219 Modify, 120 HP-UX process count, 235 I/O Redirection, 184, 185 IBM AIX process count, 234 ID PINetMgr, 212 ID Conversion File, piarchss, 43 index record, 35 Initialization archive, 57 Input Command, 183, 220 redirect, 187 to piconfig, batch files, 183 Installation Redirector, 257 Integer Format to String, 266 Interactive session piconfig, 172 interface nodes setting clock, 101 Interface Nodes definition of, 94 Interface Status Utility, 113 interfaces and PI API, 96 APS utility, 113 definition of, 94 Interface Status Utility, 113 setting system clock, 101 Interfaces downloading documentation for, vi internal counters piartool-qs, 25 PI Server System Management Guide Page 353

376 Inter-process communication TCP/IP, 252 UNIX Sockets, 251 IP Address, 117 IPAddr trust logins, 132 IPHost trust logins, 132 Istat Attributes, 202 Istructure, 180, 187, 190 Command, 196 Istype, 179 Key primary, 176 Keyword, 180 Delimiter, changing, 180 Structure type, 179 Limit digital state sets, 195 limits, time, 52 List, 187 Mode, 178 primary key default, 181 LocalHost Statistics, 340 Location4, 104 Performance point, 112 Login, 187 explicit over trust, 135 Trust, 128 login, remote pigetmsg, 20 Manager. See PI Server System Manager Mapped points, 258 Max_nprocs, 235 Maxerr, 187 Maximum data segment, 233 file handles/descriptors, 233 maximum archive size, 52, 53 maxpoints, 53 maxsize, 54 MaxUpdateQueue, 31 Maxuprc, 235 Maxusers, 235 message log, 18 Message Log, 2, 3, 229 message logs message subsystem offline, 20 pigetmsg, 18 remote login, 20 rpc resolver error, 22 searching messages, 19 viewing on other servers, 20 viewing with pigetmsg, 18 Message Subsystem performance counters, 336 message subsystem offline viewing messages, 20 Messages Client Connection, 290 Disconnects, 292 Interpreting, 281 Normal Startup, 281 RPC Resolver, 293 Subsystem, 229 Subsystem Connection, 291 Method batch or interactive, piconfig, 172 Millisecond timestamps, 207 minimum archive size, 52 Mode, 187 Edit, 178 Piarc Table, 203 piconfig, 176, 178 Specifications, persistence, 223 t option, 178 Modify, 187 Command, 189 Specifications, 189 Page 354

377 Module Database Repairing, 250 moving archives, 56 XE "conversion files, ID" to another server, 43 Moving PI Servers, 147 MsgRecv, 211 MsgSent, 211, 212 Name Connection name, 212 naming archives, 52 Netmask trust logins, 132 NetType, 212 Network definitions, display the, 278 Router, 116 Security, 116 Network Manager performance counters, 337 NEWhostmask, 119 Newset keyword, 176 Newtag keyword, 176 NEWUnitName, 207 nodes, 94 NT Interface installation PIHOME directory, 101 Octal notation, 224 offline archive utility, 37, 40, 41 list of parameters, 41 Offline Archive Utility ID Conversion File, 43 time conversion file, 44 Time Filtering, 43 offline mode pimsgss, 20 offline, message subsystem, 20 OpenVMS and PI API, 95 Operating System Error Codes, 293, 294 Security, 116 Operators Modify Point Attributes, 189 piconfig, 181 OSBuild, 210 OSIsoft Universal Interface. See UNIINT OSSysName, 210 Ostructure, 187 Command, 180 Ostype, 179, 187 OSUser trust logins, 133 OSVersion, 210 Out of order event counter archive, 28 out of order events compression, 23 out of order events counter, 23 Output, 187 Command, 184 overflow events, 25 Overflow Offsets piartool -al, 47 overflow queues, 25 overflow XE "primary record" record, 34 Overlapping dates, 245 Owner point attribute, 123 Parameter Passing an input file, 184 Passing as Output, 184 Timing, 219 Password, 126 blank, 127 changing, 127 default, 127 reset piadmin, 278 Path piartool -al, 47 PI Server System Management Guide Page 355

378 PeerAddress, 212 PeerName, 212 Pending Number pilistupd utility, 239 Performance Counter PI Server, 340 performance counters Archive Subsystem, 332 Base Subsystem, 331 Message Subsystem, 336 Network Manager, 337, 338 PEs, 338 Snapshot Subsystem, 334 SQL Subsystem, 336 TotalizerSubsystem, 337 performance equations performance counters, 338 Performance Equations Subsystem performance counters, 338 performance problems out of order events, 23 Permissions Attributes, changing, 123 PEs performance counters, 338 PI API about, 96 Buffering, 96 impact on system set number, 201 on VMS, 95 PI API buffering. See buffering PI Attribute Set Table, 191 PI Base Subsystem Troubleshooting, 230 PI Batch Alias Table, 208 PI Batch Table, 209 PI Connections, 213 PI DataLink Data access, 125 PI Message Log, 229 Subsystem, 229 PI ProcessBook Data access, 125 PI Processes, 229 Running independently, 232 Sign up for updates, 293 Status, 228 Stopping interactively, 4 PI Proxy Database, 220 PI Server Automatic Startup, 6 Backups, 63 data files, 235 Error Codes, 293, 294 Message Log, 290, 291 moving PI Systems, 147 performance counters, 340 performance monitoring, 27 restore from backup, 243 Security, 116 Starting, 1, 281 Windows, 2 Winpdows, 2 Stopping, 1, 3 System Manager, 116 Security responsibilities, 116 Timing parameters, 219 tuning, 251 PI Server System Manager, 116 PI session performance counters, 338 PI Session Statistics, 338, 339 PI Subsystem, 211 Table, 211 PI Subsystem Table, 210 PI System merging two systems, 153 PI tables how to select, 172 Page 356

379 PI TagConfigurator, 171 PI Thread Table, 215 PI_GEN, 173, 219 Piadmin, 117, 124, 125 reset password, 278 Piarc, 173 Edit mode attribute, 204 Piarc Table, 202 piarchss, 37, 40 offline archive utility, 41 Piarchss, 231 piarchss -id, 43 piarchss offline utility list of parameters, 41 Piarcmem.dat, 236 piarcreate, 37, 52 Piarcreate, 52 piarstat.dat, 56 Piarstat.dat, 236 piartool, 37 -aw, 49 creating archives with, 52 deleting archives, 56 moving archives, 56 -qs, 25 registering archives, 56 unregistering archives, 56 Piartool, 52 -al, 46 results from, 47 -as, 27 piartool -ac, 52 piartool -acd, 52 piartool -ar, 56 piartool -au, 56 piartool -ooo, 23 piartool -ss events counter, 23 events in queue counter, 24 events read counter, 24 events sent to queue counter, 24 number of overflow queues, 25 out of order events counter, 23 point counter, 23 remaining capacity, 25 total overflow events, 25 piartool -ss, 22 PIATRSET, 173 Pibaalias, 173, 208 Pibasess, 230 Pibatch, 209 PIBatch considerations when merging systems, 154 Pibaunit, 173, 207 Piconfig, 127, 203 Abbreviations, 220 Commands, 176, 186, 223 Configuration.Persistence, 223 Echo command, 184 Modes, 178 Overview, 171 Remote sessions, 185 Starting, 172 Stopping, 172 using quotes, 221 values sent as strings, 222 pidemo user account, 125 pidiag, 263 about, 21 -ad, 270 -ahd, 271 -ar, 271 -ara, 270 -e errorcode, 265 -fb, 269 -fb utility, 236 -fbc <path>, 269 -fbf <path>, 270 -h or -?, 265 -host, 278 interpreting error messages, 21 operating system errors, 21 PI Server System Management Guide Page 357

380 Recovery utility, 247 -rgs, 279 -t time <U>, 265 -tz, 266 -udf <path>, 278 -v, 265 Pidiag -crash, 278 Interpreting Error Messages, 293 Utility, 293 -w msec, 278 Pidiff Keyword mappings, 224 Pidignam.dat, 236 Pidigst.dat, 236 Pids Table, 195 Pifilebase, 236 pigetmsg about, 18 default values, 19 parameters, 18 remote login, 20 searching messages, 19 Utility, 229 Pigetmsg Utility, 281 pigrp, 126, 215 Pilastsnap.dat, 237 Pilistupd utility, 238 Troubleshooting, 230 pimannnn.dat, 237 Pimapevq.dat, 237 pimsgss offline, viewing messages, 20 offline mode, 20 Pimsgss, 229 Pimsgtxt.dat, 237 PINet Nodes, 95 PINet/OpenVMS, 115 Manager Subsystem, 229 Pinetmgr, 229 Messages from, 290, 291 Pinetmgrstats, 212 PINetMgrStats, 173 piperfmon.dif, 340 Pipes WIN32, 212 PIPoint, 188 Pipoints.dat, 237 Piptalia.dat, 237 Piptattr.dat, 237 PIPTCLS, 173, 193, 194 Piptclss.dat, 237 Piptunit.dat, 238 Pisetpass utility, 126, 127 Pishutev, 5, 228, 231 Pisnap, 200, See also Snapshot Pisnap.dif list Snapshot values, 201 Pisnap2, 201, 202, See also Snapshot Pisnapss, 230 PIStartupTime, 210 pistop.sh script, 4 Pisubsys, 210 PISubsys, 173 PISubsysName, 211 Pisubsysstats, 211 PISubsysStats, 173 PIThread, 173 Pitimeout, 173, 219 PITimeout Table, 31 PItrust, 218 Piudsrdr.exe, 259 Piupdmgr, 230 Messages from, 293 PIUser, 214 field for trust logins, 134 Piusr.dat, 238 Piusrctx.dat, 238 Page 358

381 Piusrgrp.dat, 238 Piverify.sh script, 228 PIVersion, 210 Point access to, 124 data access, 122 Database, 189 Datagroup, 124 Dataowner, 124 object for security, 122 Ownership, Changing, 123 Point class, 188 Point Attributes access to, 122 Changing Owner, 123 Modifying, 189 With Operators, 189 Point Class Base, 188 Point Class Database, 192, 194 point counter, snapshot, 23 Point Database, 57, 188 migration from PI2, 224 Repairing, 250 table name, 188 PointID, 200 PointSource attribute, 103 Command line parameters, 102 PoolName, 215 predicting archive shifts, 47 primary archive, 33 Primary Archive, 35, 46 Recovering, 242 primary archives creating new, 55 failing to register, 55 Primary index Connection, 212 Primary key, 172 Default, 181 Primary Offsets piartool -al, 47 primary record, 34 Priority Trust Records, 135 PRODEXPR, 208 ProdIDsearch Batch Subsystem, 209 Producer pilistupd utility, 238 Prompt, 187 ProtocolVersion, 212 PtClass, 187 Ptclass command, 188 queue number of overflow events, 25 number of overflow queues, 25 remaining capacity, 25 queue, event monitoring, 25 Quit command, 183 Quote, 187 character, 223 Quote marks used in piconfig, 221 RampSoak, 232, 240 Random, 240 Random Simulator, 232 record archive, 34 Record, 188 attributes, 175 Record Size piartool -al, 47 records determining percentage used, 47 listing details, 49 Records Trust, Weighting, 135 Recovery tool, 247 Recsep, 187 RecvErrors, 211, 212 PI Server System Management Guide Page 359

382 Redirection Output to files, 185 Redirector confirming installation, 257 dump script, 261 starting, 258 troubleshooting, 257 registering archives, 56 Registry archive, 56 regsvr32, 262 Remote piconfig sessions, 185 Procedure Calls, 251, 292 remote logins pigetmsg, 20 Remove consumer from update table, 293 removing archives, 56 Repairs Archive Registry, 246 Data file, 241 Excessive CPU Usage by Utilities, 252 Module Database, 250 Point Database, 250 Snapshot, 247 System Time, 249 Tuning the Server, 251 Repeating attributes Ellipsis construct, 182 Replacesp mode, 206 resolver error message, 22 Resolver Messages, 293 Restore Archive, 244 PI Server from backup, 243 Subsystem Databases, 245 Reusing an Output File as an Input File piconfig, 185 Reverse Name Lookup, 129 Troubleshooting, 254 Root, 3, 116 Router, 116 rpc resolver error message, 22 RPCs, 251, 292, 293 Rval attributeattributes, 202 Sam utility, 235 Scan classes, 104 Score Trust Records, 135 SearchStart Batch Subsystem, 209 Security, 115 Attributes Changing, 123 Client, 125 Default points, 125 Firewall, 117 Network, 116 Operating System, 116 Physical, 115 Scenario for Users and Groups, 122 Table Edits, 216 Tag, 122 Troubleshooting, 230 Trust Login, 128 User Name and Password, 125 Select, 188 command, 176, 181 PI table, 172 SendErrors, 211, 212 server messages, 18 Services Troubleshooting, 228 trust login OSUser Names, 133 SET, 191, 193, 194, 195 SETNO, 191, 193, 195 Shift Archives, 57 shift flag piartool -al, 47 Page 360

383 shift predicting, 47 shift, archive, 33 Shift-enable flag, 57 Shutdown Events, 4 Shutdown.dat, 4, 5, 238 Sigd, 188 Sign up for updates, 293 Significant decimal digits, 188 sinusoid, 232 Site-specific files, 2 size of file buffer, 95 size, archive records, 34 Smit utility, 234 SMT about, vi snapshot event count, 22 events counter, 23 events in queue counter, 24 events read counter, 24 events sent to queue counter, 24 listing current information, 22 monitoring data flow, 22 number of overflow queues counter, 25 out of order events counter, 23 point counter, 23 remaining queue capacity, 25 total overflow events counter, 25 Snapshot, 5 list values, 201 repairing, 247 Subsystem Adding digital state values, 200 recovering, 248 Troubleshooting, 230 Snapshot Subsystem performance counters, 334 Span Modify, 189 Special Characters, Changing, 223 Specifications Compression, 122 Spreadsheet, 190 SQL Subsystem performance counters, 336 Start Messages, 281 PI, 1 UNIX, 3 Windows, 2 piconfig, 172 Redirector, 258 Starting PI, 2 Starttime, 203 State piartool -al, 47 STATE, 195 State Sets listing, 195 statistics performance counters, 331 Status, 188 command, 173 PI processes, 228 Stdout, 2 Stop PI, 1 on UNIX, 4 on Windows, 3 piconfig, 172 String to Integer Format, 266 Structure, 187, 188 Specifications, 181 Type, 179 STYP, 188 Stype, 179 Subnet, 118 specifying for trust login, 132, 143 PI Server System Management Guide Page 361

384 Subsystem Attributes, 210 Connection Messages, 291 PI Message, 229 Restore from Backup, 245 Update Manager, 230 subsystem health check failed, 22 Sun Solaris process count, 235 Superuser Privileges, 122 Sysdef utility, 235 SYST, 188 System Clock resetting, 249 digital state set name, 195 set number, 201 Statistics, 211 system aggregate compression ratio, 24 system clock, 23 on interface nodes, 101 system error codes, 21 System Management Tools, vi system message logs pigetmsg, 18 System State Set modifying, 197 Table Attributes Displaying, 174 With Ellipsis, 182 Batch Alias, 208 Batch Unit, 207 Command, 188 piconfig, 173 Database Security, 216 For accessing the PI Archive, 202 Names, 172 how to list, 173 PI_GEN, 219 Piarc, 202 Pibaalias, 208 Pibatch, 209 Pibaunit, 207 Pids, 195 PIFIREWALL, 219 Pigroup, 215 Pinetmgrstats, 212 Pipoint, 188 Pisnap, 200 Pisnap2, 201 Pisubsys, 210 Pisubsysstats, 211 Pitimeout, 219 PItrust, 218 PIUser, 214 Selecting, 172, 173 Snapshot, 200, 201 Specifications,persistence, 223 Tag Adding Values to the Snapshot Table, 201 creating, 199 Datagroup, 124 Dataowner, 124 Listing information, 178 Mask, for shutdown, 6 Removing point security, 124 Security, 122 TagConfigurator, 171 TCP/IP, 212 Default port, 229 Technical Support, 345 Thread Table, 215 actions, 216 Threading, 253 Threads, 173 time setting on interface nodes, 101 Time Page 362

385 Attributes, 207 conversion file, 44 Filtering, 43 future times in Snapshot removing, 248 piconfig millisecond, 206 piconfig TimeFormat, 206 Time Zone, 266, 268 utilities, 265 time limits on modifying data, 52 Time Transformation Processing, 245 conversion file, 246 time zones and interface nodes, 101 TimeFormat, 206 TimeNum, 200 Timenum Attributes, 207 Timeout Database, 219 Timestamp Corrections, 44 Millisecond, 207 Timformat, 188 Timing Parameters, 219, 251 Totalizer Subsystem performance counters, 337 totalupdatequeue, 31 TotalUpdateQueue, 31 Troubleshooting Checklist, 225 PI Update Manager, 230 Redirector, 257 Strategy, 225 Trust Database, 128, 218 defining a record, 130 fields, 131 how to configure, 131 Trust Login, 128 evaluating, 134 examples, 137 installation, 136 network definitions, 278 shutdowns, 135 Trust Records Weighting, Score, 135 Tuning Utilities timeout value, 252 Tuning the PI System, 251 Type Files, 236 piartool -al, 47 UniInt downloading documentation for, vi UnitName, Batch Subsystem, 207, 209 Universal Interface downloading documentation for, vi UNIX, 212 Case-sensitive, 220 Sockets protocol, 251 UNIX Process Stopping, 232 UNIX Process Quotas, 233 Unregister Archive list unregistered files, 271 unregistering archives, 56 Update Manager, 30 MaxUpdateQueue, 31 Pending Update Limit, 31 Statistics, 340 TotalUpdateQueue, 31 Troubleshooting, 230 Upgrade Post Upgrade Tasks on UNIX, 147 User Adding, 127 Database, 126 Name and Password Security, 125 Passwords changing, 127 PI Server System Management Guide Page 363

386 Table for, 214 User Group. See Group Utility File-base, 269 piconfig, 126, 127, 171 pidiag, 263 pidiag -fb, 236 pidiag recovery, 247 pidiff, 171 pisetpass, 126, 127 sam, 235 smit, 234 sysdef, 235 time, 265 Values Attributes, Modifying, 189 Verifying PI Processes, 228 Version piartool -al, 47 pidiag, 265 Visual Basic, API, 96 VMS and PI API, 95 Wait for passed milliseconds command pidiag, 278 Weighting Trust Records, 135 Wildcards, 182 WIN32 named pipes, 212 Windows performance counters, 331 Stopping Processes, 232 Write Flag piartool -al, 47 Page 364