Contact Rockwell

Contact Rockwell

Customer Support Telephone — 1.440.646.3434

Online Support — http://support.rockwellautomation.com

Copyright Notice

© 2007 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA.

This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation Technologies, Inc. is strictly prohibited. Please refer to the license agreement for details.

Trademark Notices

FactoryTalk, Rockwell Automation, Rockwell Software, the Rockwell Software logo are registered trademarks of Rockwell Automation, Inc.

The following logos and products are trademarks of Rockwell Automation, Inc.:

FactoryTalk Historian Site Edition (SE), RSView, FactoryTalk View, RSView Studio, FactoryTalk View Studio, RSView Machine Edition, RSView ME Station, RSLinx Enterprise, FactoryTalk Services Platform, and FactoryTalk Live Data.

The following logos and products are trademarks of OSIsoft, Inc.:

PI System, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK.

Other Trademarks

ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows, Windows ME, Windows NT, Windows 2000, Windows Server 2003, and Windows XP are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

ControlNet is a registered trademark of ControlNet International.

DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA).

Ethernet is a registered trademark of Digital Equipment Corporation, Intel, and Xerox Corporation.

OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.

Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.

All other trademarks are the property of their respective holders and are hereby acknowledged.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)

of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Warranty

This product is warranted in accordance with the product license. The product’s performance may be affected by system configuration, the application being performed, operator control, maintenance, and other related factors. Rockwell Automation is not responsible for these intervening factors. The instructions in this document do not cover all the details or variations in the equipment, procedure, or process described, nor do they provide directions for meeting every possible contingency during installation, operation, or maintenance. This product’s implementation may vary among users.

This document is current as of the time of release of the product; however, the accompanying software may have changed since the release. Rockwell Automation, Inc. reserves the right to change any information contained in this document or the software at anytime without prior notice. It is your responsibility to obtain the most current information available from Rockwell when installing or using this product.

Version: 9.00.05

PI Server System Management Guide Page iii

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.

Preface - Using this Guide

Page iv

The PI Server Documentation Set

The PI Server Documentation Set includes seven user guides, described below. These documents are included on the FactoryTalk Historian SE installation CD under Redist > Docs.

Title Subject Matter

Introduction to PI System Management

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.

PI Server Installation and Upgrade Guide

A guide for installing, upgrading and removing PI Servers on Windows and UNIX platforms, including cluster and silent installations.

PI Server System Management Guide

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.

PI Server Reference Guide

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

Auditing the PI Server

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.

PI Server Applications User Guide

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.

PINet and PIonPINet User Guide

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.


PI Server System Management Guide Page v

Conventions Used in this Guide This guide uses the following formatting and typographic conventions.

Format Use Examples

Title Case PI Client Tools PI System Elements PI Server Subsystems

Use the client tool, FactoryTalk Historian ProcessBook, to verify that all data has been recovered.

All incoming data is queued in the Event Queue by the Snapshot Subsystem.

Italic text Files, Directories, Paths Emphasis New Terms Fields References to a chapter or section

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.

System and Application components: Subsystems Tools / Utilities Processes / Scripts / Variables Arguments / Switches / Options Parameters / Attributes / Values Properties / Methods / Events /

Functions

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.

Procedures and Key Commands On the Tools menu, click Advanced Options. Press CTRL+ALT+DELETE to reboot

Bold text

Interface components Menus / Menu Items Icons / Buttons / Tabs Dialog box titles and options

Click Tools > Tag Search to open the Tag Search tool.

Click the Advanced Search tab. Use the search parameters PImean Value = 1.

Monospace

type:

"Consolas" font

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

To list current Snapshot information every 5 seconds, use the piartool -ss command. For example:

Light Blue - Underlined

Links to URL / Web sites, and email addresses

http://support.rockwellautomation.com


Page vi

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.

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.

PI Server System Management Guide Page vii

QUICK TABLE OF CONTENTS

Chapter 1. Starting and Stopping PI ............................................................................................1

Chapter 2. Monitoring PI System Health ...................................................................................19

Chapter 3. Managing Archives ...................................................................................................35

Chapter 4. Backing up the PI Server..........................................................................................65

Chapter 5. Managing Interfaces .................................................................................................95

Chapter 6. Managing Security ..................................................................................................117

Chapter 7. Moving PI Servers ...................................................................................................149

Chapter 8. Copying a PI Server ................................................................................................153

Chapter 9. Merging Two PI Servers .........................................................................................155

Chapter 10. The piconfig Utility..................................................................................................173

Chapter 11. PI Troubleshooting and Repair..............................................................................229

Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................269

PI Server System Management Guide Page ix

TABLE OF CONTENTS

Preface – Using this Guide ..............................................................................................................iii

Table of Tables................................................................................................................................xix

Table of Figures ..............................................................................................................................xxi

Chapter 1. Starting and Stopping PI ............................................................................................1 1.1 Starting PI...........................................................................................................................1

1.1.1 Starting PI on Windows Systems ...........................................................................2 1.1.2 Starting PI on UNIX Systems .................................................................................3

1.2 Stopping PI.........................................................................................................................3 1.2.1 Stopping PI on Windows Systems .........................................................................3 1.2.2 Stopping PI on UNIX Systems ...............................................................................4

1.3 Automatic Startup .............................................................................................................6 1.3.1 Automatic Startup and Shutdown on UNIX Systems .............................................7

1.4 Shutting Down an Individual Subsystem......................................................................17

Chapter 2. Monitoring PI System Health ...................................................................................19 2.1 Checking Key System Indicators...................................................................................19 2.2 Viewing System Messages.............................................................................................20

2.2.1 Available Log History............................................................................................20 2.2.2 Viewing System Messages with pigetmsg ...........................................................20 2.2.3 Viewing Messages When the Message Subsystem Goes Down.........................22 2.2.4 Viewing Message Log Files Generated on other Servers....................................22 2.2.5 Interpreting Error Messages (pidiag)....................................................................23 2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages) ................................24

2.3 Monitoring Snapshot Data Flow.....................................................................................24 2.3.1 Listing Current Snapshot Information with piartool -ss.........................................24

2.4 Monitoring the Event Queue...........................................................................................27 2.4.1 piartool -qs............................................................................................................27

2.5 Monitoring the Archive ...................................................................................................29 2.5.1 piartool -as............................................................................................................29

Table of Contents

Page x

2.6 Monitoring the Update Manager ....................................................................................33 2.6.1 Adjusting the Pending Update Limit .....................................................................33

2.7 System Date and Time ....................................................................................................34

Chapter 3. Managing Archives ...................................................................................................35 3.1 Tasks for Managing Archives.........................................................................................35 3.2 About Archives ................................................................................................................35

3.2.1 About Archive Shifts .............................................................................................35 3.2.2 About Archive Files...............................................................................................36 3.2.3 About Primary Archives ........................................................................................37 3.2.4 About Fixed and Dynamic Archives .....................................................................37 3.2.5 About Read-Only Archives ...................................................................................39

3.3 Tools for Managing Archives .........................................................................................39 3.3.1 Using the piartool Utility........................................................................................39 3.3.2 Using the Offline Archive Utility (piarchss) ...........................................................42

3.4 Listing the Registered Archives ....................................................................................48 3.4.1 Determining an Archive Sequence Number from a Listing ..................................50

3.5 Listing Archive Record Details ......................................................................................51 3.5.1 Performing an Archive Walk with piartool -aw......................................................52

3.6 Estimating Archive Utilization........................................................................................54 3.7 Editing Archives ..............................................................................................................54 3.8 Creating Archives............................................................................................................54

3.8.1 Naming Archives ..................................................................................................55 3.8.2 Choosing an Archive Size ....................................................................................55 3.8.3 Selecting an Archive Type: Fixed or Dynamic......................................................55 3.8.4 Specifying the Number of Points in the Archive ...................................................55 3.8.5 Specifying the Maximum Archive Size .................................................................56

3.9 Creating Data Archives Prior to the Installation Date..................................................56 3.10 Creating a New Primary Archive....................................................................................58

3.10.1 Registering an Archive .........................................................................................58 3.10.2 Unregistering an Archive ......................................................................................58 3.10.3 Deleting an Archive ..............................................................................................58 3.10.4 Moving an Archive ................................................................................................58

3.11 Managing Archive Shifts.................................................................................................59 3.11.1 Archive Shift Enable Flag .....................................................................................60 3.11.2 Forcing Archive Shifts...........................................................................................61

3.12 Combining and Dividing Archives.................................................................................62

Table of Contents

PI Server System Management Guide Page xi

3.12.1 Combining Archives into a Single Archive............................................................62 3.12.2 Event Queue Recovery ........................................................................................63

Chapter 4. Backing up the PI Server..........................................................................................65 4.1 Planning for Backups......................................................................................................65

4.1.1 Choosing the Backup Platform (VSS vs. Non-VSS) ............................................65 4.1.2 Choosing a Backup Strategy................................................................................65

4.2 Other Backup Considerations........................................................................................66 4.2.1 Guidelines for VSS Backups ................................................................................66 4.2.2 Guidelines for non-VSS Backups .........................................................................67

4.3 Guidelines for Backing Up Before Upgrading..............................................................67 4.4 Automating PI Backups ..................................................................................................68

4.4.1 Automating Backups on Windows........................................................................68 4.4.2 Do a Test Backup .................................................................................................71 4.4.3 Do a Test Restore ................................................................................................72 4.4.4 Automating Backups on Windows with a 3rd Party Backup Application..............74

4.5 Automating Backups on a Windows Cluster................................................................75 4.6 Automating Backups on UNIX........................................................................................75 4.7 How The PI Backup Subsystem Works.........................................................................76

4.7.1 Principles of Operation .........................................................................................76 4.7.2 Selecting Files or Components for Backup ..........................................................77 4.7.3 The Backup Components of PI ............................................................................79 4.7.4 The Files and Components for each Subsystem .................................................80 4.7.5 Lifetime of a Backup .............................................................................................83

4.8 Launching Non-VSS Backups with piartool -backup <path>......................................86 4.9 Managing Backups with piartool ...................................................................................87

4.9.1 Backup Command Summary ...............................................................................87 4.9.2 piartool -backup -query.........................................................................................88 4.9.3 piartool -backup -identify ......................................................................................89

4.10 Timeout Parameters ........................................................................................................90 4.11 Troubleshooting Backups ..............................................................................................92

4.11.1 Log Messages ......................................................................................................92 4.11.2 VSSADMIN...........................................................................................................93

Chapter 5. Managing Interfaces .................................................................................................95 5.1 Introduction......................................................................................................................95 5.2 General Interface Principles...........................................................................................96

5.2.1 About PI Interfaces ...............................................................................................96

Table of Contents

Page xii

5.2.2 About PI Interface Nodes .....................................................................................96 5.2.3 About Data Buffering ............................................................................................97 5.2.4 About the PI API ...................................................................................................98 5.2.5 About the PI SDK .................................................................................................98 5.2.6 About UniInt-Based Interfaces .............................................................................98

5.3 Basic Interface Node Configuration ..............................................................................99 5.3.1 Install the PI SDK and/or the PI API.....................................................................99 5.3.2 Connect to PI with apisnap.exe..........................................................................100 5.3.3 Connect with AboutPI SDK.exe..........................................................................100 5.3.4 Configure PI Trusts for the Interface Node.........................................................100 5.3.5 Install the Interface .............................................................................................103 5.3.6 Set the Interface Node Time ..............................................................................103 5.3.7 Connect to the PI Server with the Interface........................................................104 5.3.8 Configure Points for the Interface.......................................................................105 5.3.9 Configure Buffering.............................................................................................106 5.3.10 Configure Interface for Automatic Startup ..........................................................108 5.3.11 Configure Site-Specific Startup Scripts ..............................................................109 5.3.12 Configure PointSource Table .............................................................................110 5.3.13 Monitor Interface Performance...........................................................................110 5.3.14 Configure the PI Interface Status Utility .............................................................115 5.3.15 Configure Auto Point Synchronization................................................................115

Chapter 6. Managing Security ..................................................................................................117 6.1 Physical Security...........................................................................................................117 6.2 Network Security ...........................................................................................................117 6.3 Operating System Security...........................................................................................118 6.4 PI Server Security..........................................................................................................118

6.4.1 Running applications on the system console .....................................................119 6.4.2 Running applications remotely ...........................................................................119

6.5 Firewall Security ............................................................................................................119 6.5.1 Firewall Database...............................................................................................119

6.6 Database Security .........................................................................................................122 6.6.1 PIDBSEC............................................................................................................122 6.6.2 PIARCADMIN .....................................................................................................122 6.6.3 PIARCDATA .......................................................................................................122 6.6.4 PIBatch ...............................................................................................................123 6.6.5 PICampaign........................................................................................................123

Table of Contents

PI Server System Management Guide Page xiii

6.6.6 PIDS ...................................................................................................................123 6.6.7 PIHeadingSets....................................................................................................123 6.6.8 PIModules...........................................................................................................123 6.6.9 PIPOINT .............................................................................................................123 6.6.10 PITransferRecords .............................................................................................123 6.6.11 PIUSER ..............................................................................................................123 6.6.12 Individual Subsystem Tokens.............................................................................123

6.7 Point Security.................................................................................................................124 6.7.1 Point Data Access ..............................................................................................124 6.7.2 Point Attribute Access ........................................................................................124 6.7.3 Access Algorithm................................................................................................124 6.7.4 Assigning and Changing Ownership and Access Permissions..........................125 6.7.5 How to Make All Points Accessible ....................................................................127 6.7.6 Security for Default Points in the PI Server ........................................................127

6.8 User Security .................................................................................................................127 6.8.1 Group Database .................................................................................................128 6.8.2 User Database....................................................................................................129

6.9 Trust Login Security......................................................................................................130 6.9.1 Connection Credentials ......................................................................................130 6.9.2 Defining Trust Records in the Trust Database ...................................................132 6.9.3 Evaluating the Match Between Trust Records and Connection Credentials .....137 6.9.4 New PI Server Installations ................................................................................138 6.9.5 Trust changes on System Startup ......................................................................138 6.9.6 Multiple Network Cards ......................................................................................139 6.9.7 Examples............................................................................................................139

6.10 Resolving Ambiguities..................................................................................................146

Chapter 7. Moving PI Servers ...................................................................................................149 7.1 Preparation.....................................................................................................................149 7.2 Different Computer........................................................................................................149 7.3 Same Computer .............................................................................................................150

Chapter 8. Copying a PI Server ................................................................................................153 8.1 Understanding the Server ID ........................................................................................153 8.2 Situations where Server ID must be Addressed ........................................................153

Chapter 9. Merging Two PI Servers .........................................................................................155 9.1 Server Merging - Procedures .......................................................................................155

Table of Contents

Page xiv

9.2 Server Merge Procedure - Example.............................................................................158 9.3 Shut Down the Retired System ....................................................................................165

9.3.1 Add Retired Point Configuration to Destination System.....................................167 9.3.2 Add PI Batch Unit Configuration to Destination System ....................................167 9.3.3 Convert the Archives ..........................................................................................168 9.3.4 Merge the PI Batches .........................................................................................172

Chapter 10. The piconfig Utility..................................................................................................173 10.1 PI TagConfigurator & PI SMT Point Builder plug-in...................................................173 10.2 A Note to Pidiff Users....................................................................................................173 10.3 Key Concepts for Using Piconfig ................................................................................174

10.3.1 Starting and Stopping Piconfig ...........................................................................174 10.3.2 Interactive Session vs. Batch Method ................................................................174 10.3.3 Selecting PI Tables.............................................................................................174 10.3.4 Table Attributes ..................................................................................................176 10.3.5 Records ..............................................................................................................177 10.3.6 Piconfig Commands ...........................................................................................179 10.3.7 Mode...................................................................................................................180 10.3.8 Structure Type ....................................................................................................181 10.3.9 Select Command ................................................................................................183 10.3.10 Operators............................................................................................................184 10.3.11 Wildcards............................................................................................................184 10.3.12 The Ellipsis (…) Construct for Repeating Attributes...........................................184 10.3.13 Endsection..........................................................................................................185 10.3.14 Exit......................................................................................................................185 10.3.15 Batch Methods....................................................................................................185 10.3.16 Security on Piconfig Sessions ............................................................................187 10.3.17 Remote Piconfig Sessions..................................................................................187

10.4 Piconfig Commands and Tables..................................................................................188 10.4.1 Point Database Table .........................................................................................191 10.4.2 PI Attribute Set Table .........................................................................................193 10.4.3 Point Class Database.........................................................................................195 10.4.4 Point Source Database.......................................................................................197 10.4.5 Digital States Table ............................................................................................198 10.4.6 Snapshot and Snapshot2 Tables .......................................................................203 10.4.7 Archive Table......................................................................................................205 10.4.8 PI Batch Unit Table.............................................................................................211

Table of Contents

PI Server System Management Guide Page xv

10.4.9 PI Batch Alias Table ...........................................................................................211 10.4.10 PI Batch Table ....................................................................................................212 10.4.11 PI Subsystem Table ...........................................................................................213 10.4.12 PI Subsystem Statistics Table............................................................................214 10.4.13 PINet Manager Statistics Table..........................................................................215 10.4.14 PI Users Table....................................................................................................218 10.4.15 PI Group Table ...................................................................................................218 10.4.16 PI Thread Table..................................................................................................219 10.4.17 PI Database Security Table................................................................................220 10.4.18 PI Trust Database...............................................................................................221 10.4.19 PI General Table Interface .................................................................................222

10.5 Helpful Hints...................................................................................................................224 10.5.1 Abbreviations......................................................................................................224 10.5.2 Case-sensitivity ..................................................................................................224 10.5.3 Command Input Files .........................................................................................224 10.5.4 Input Line Length................................................................................................224 10.5.5 Using Quoted Strings .........................................................................................224 10.5.6 Sending Values as Strings .................................................................................226 10.5.7 Boolean Values ..................................................................................................226 10.5.8 Configuration Persistence ..................................................................................226 10.5.9 Command Line Parameters................................................................................227 10.5.10 Changing Special Characters.............................................................................227 10.5.11 Convert Mode Example ......................................................................................228 10.5.12 Converting Point Database Information from PI2 to PI Server...........................228 10.5.13 Hexadecimal and Octal Numbers.......................................................................228

Chapter 11. PI Troubleshooting and Repair..............................................................................229 11.1 Troubleshooting Checklist ...........................................................................................229 11.2 Verifying PI Processes..................................................................................................232

11.2.1 Verifying PI Processes on Windows Systems....................................................232 11.2.2 Verifying PI Processes on UNIX Systems..........................................................232 11.2.3 Communication with PINet Manager..................................................................233 11.2.4 Pimsgss ..............................................................................................................233 11.2.5 PI Update Manager ............................................................................................234 11.2.6 PI Base Subsystem ............................................................................................234 11.2.7 Snapshot Subsystem..........................................................................................235 11.2.8 Archive Subsystem.............................................................................................235

Table of Contents

Page xvi

11.2.9 Pishutev..............................................................................................................236 11.2.10 Random Interface ...............................................................................................236 11.2.11 RampSoak Interface...........................................................................................236 11.2.12 Running PI Processes Independently ................................................................236

11.3 UNIX Process Quotas....................................................................................................237 11.3.1 IBM AIX...............................................................................................................238 11.3.2 Compaq Tru64....................................................................................................238 11.3.3 HP-UX.................................................................................................................239 11.3.4 Sun Solaris .........................................................................................................239

11.4 PI Server Data Files .......................................................................................................240 11.5 Identifying the Update Manager Issues: the pilistupd utility ....................................242 11.6 Repairs............................................................................................................................245

11.6.1 Recovering Data from Corrupted Archives.........................................................245 11.6.2 Restoring a Complete Server from Backup........................................................247 11.6.3 Restoring Archives From Backup.......................................................................249 11.6.4 Restoring Subsystem Databases From Backup.................................................249 11.6.5 Correcting Archive Event Timestamps ...............................................................249 11.6.6 Repairing the Archive Registry...........................................................................251 11.6.7 How to Repair the Snapshot...............................................................................251 11.6.8 Recovering from Accidental Change to System Time........................................253 11.6.9 How to Repair the Point Database .....................................................................255 11.6.10 How to Repair the Module Database .................................................................255

11.7 Tuning the PI Server......................................................................................................255 11.7.1 Communications Layer of the PI Server.............................................................255 11.7.2 Resolving Excessive CPU Usage by Utilities .....................................................257 11.7.3 Identifying Abusive Usage..................................................................................258

11.8 Solving Other Problems................................................................................................259 11.8.1 Failed Backups ...................................................................................................259 11.8.2 Slow Reverse Name Lookup..............................................................................259 11.8.3 Slow Domain Controller Access .........................................................................259 11.8.4 Flatline in a FactoryTalk Historian ProcessBook Trend .....................................260

11.9 COM Connectors ...........................................................................................................261 11.9.1 Redirector Troubleshooting ................................................................................262 11.9.2 COM Connector Troubleshooting.......................................................................266

Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................269 12.1 General Information ......................................................................................................271

Table of Contents

PI Server System Management Guide Page xvii

12.1.1 Version Information ............................................................................................271 12.1.2 Error Code Translation .......................................................................................271

12.2 Time Utilities ..................................................................................................................271 12.2.1 Time Translations ...............................................................................................271 12.2.2 Time Zone ..........................................................................................................272

12.3 File-base Utilities ...........................................................................................................275 12.3.1 Dump File-base Data File...................................................................................275 12.3.2 Compact a File-base Data File...........................................................................276 12.3.3 Recover File-base Data File Index .....................................................................276

12.4 Archive Management ....................................................................................................276 12.4.1 Dump the Archive Manager Data File ................................................................276 12.4.2 Automatic Recovery of the Archive Manager Data File .....................................277 12.4.3 Manual Recovery of the Archive Manager Data File..........................................277 12.4.4 Information about Unregistered Archives ...........................................................277 12.4.5 Verify the Integrity of Archive Files.....................................................................278 12.4.6 Downgrade Archive File to Older Versions ........................................................280

12.5 Server ID Utilities...........................................................................................................281 12.6 Performance Counter Utilities (Windows Only) .........................................................282

12.6.1 Get Performance Counter Path..........................................................................282 12.6.2 Uninstall Performance Counters ........................................................................283 12.6.3 Get Performance Counter Values ......................................................................283

12.7 Miscellaneous ................................................................................................................284 12.7.1 Wait for Passed Milliseconds..............................................................................284 12.7.2 Testing Crash Dump Capability of an OS ..........................................................284 12.7.3 Reset Password to Blank ...................................................................................285 12.7.4 Display Network Definitions................................................................................285 12.7.5 Register a COM Component ..............................................................................285 12.7.6 Replaceable Parameter......................................................................................286 12.7.7 GUID Generation................................................................................................286 12.7.8 Machine-specific Programming Information .......................................................286

Appendix A: PI Messages .............................................................................................................289

Appendix B: PI Performance Counters .......................................................................................341

Technical Support and Resources...............................................................................................355

Index of Topics...............................................................................................................................357

PI Server System Management Guide Page xix

TABLE OF TABLES

Table 3–1. Options for Use with piartool..................................................................................39 Table 10–1. PI Tables Accessible Through piconfig..............................................................174 Table 10–2. Piconfig Commands...........................................................................................188 Table 10–3. Snapshot and Snapshot2 Tables Attributes ......................................................203 Table 10–4. Archive Table Attributes.....................................................................................206 Table 10–5. PI Batch Unit Table Attributes............................................................................211 Table 10–6. PI Batch Alias Table Attributes ..........................................................................212 Table 10–7. PI Batch Table Attributes ...................................................................................212 Table 10–8. Subsystem Table Attributes ...............................................................................213 Table 10–9. PI Subsystem Statistics Table Attributes ...........................................................214 Table 10–10. PINet Manager Statistics Table Attributes .......................................................215 Table 10–11. PI Users Table Attributes .................................................................................218 Table 10–12. PI Group Table Attributes ................................................................................219 Table 10–13. PI Thread Table Attributes ...............................................................................219 Table 10–14. PI Thread Table Actions ..................................................................................219 Table 10–15. PI Database Security Table Attributes.............................................................220 Table 10–16. Trust Table Attributes.......................................................................................222 Table 10–17. PI Timeout Table Attributes .............................................................................223 Table 10–18. PI Firewall Table Attributes ..............................................................................223 Table 12-1. Error Codes 1-99, With Messages......................................................................303 Table 12–2. Error Codes 100-199, With Messages...............................................................306 Table 12–3. Error Codes 200-299, With Messages...............................................................306 Table 12–4. Error Codes 500-599, With Messages...............................................................308 Table 12–5. Error Codes 800-899, With Messages...............................................................309 Table 12–6. Error Codes 900-999, With Messages...............................................................310 Table 12–7. Error Codes 1000-1099, With Messages...........................................................311 Table 12–8. Error Codes 10000-10999, With Messages.......................................................311 Table 12–9. Error Codes 11000-11999, With Messages.......................................................317 Table 12–10. Error Codes 12000-12999, With Messages.....................................................323

Table of Tables

Page xx

Table 12–11. Error Codes 13000-13999, With Messages.....................................................328 Table 12–12. Error Codes15000-15999, With Messages......................................................330 Table 12–13. Error Codes 16000-16999, With Messages.....................................................331 Table 12–14. Error Codes 17000-17999, With Messages.....................................................338 Table 12–15. Error Codes 30000-30999, With Messages.....................................................338 Table 12–16. PI Performance Counters ................................................................................351

PI Server System Management Guide Page xxi

TABLE OF FIGURES

Figure 6-1. Establishing PI Performance Monitor as a Windows Service..............................136 Figure 11-1. Distributed COM Configuration Properties ........................................................262 Figure 11-2. Windows Task Manager Processes ..................................................................263 Figure 11-3. Application Log Properties.................................................................................265 Figure 11-4. COM Connector Loading...................................................................................266

PI Server System Management Guide Page 1

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:

Chapter 1 - Starting and Stopping PI

Page 2

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

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


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.

1.2 - Stopping PI


Some interfaces on Windows cannot be run as services. Check the interface documentation.

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


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.

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


Page 4

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

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

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

! @(#)shutdown.dat 1.1 05/24/96

! default shutdown events file


Page 6

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

1.3 - Automatic Startup


1.3.1 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 Purpose

s or S 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.


Page 8

#!/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



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

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 Purpose

s or S 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.


Page 10

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

#



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"

;;

*)


;;

esac

#!/bin/ksh

#

# Filename: /sbin/init.d/PIstart



# places

#


cd /opt/pi/adm


fi

#!/bin/ksh

#

# Filename: /sbin/init.d/PIstop





# places

#


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



root> sh /sbin/rc2.d/K004PI stop


root> sh /sbin/rc3.d/S960PI start


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)


Page 12

Run Level Purpose

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.

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 single-user 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

#



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

;;

*)




;;

esac

#!/bin/ksh

#

# Filename: /sbin/init.d/PIstart



# places

#


cd /opt/pi/adm


fi

#!/bin/ksh

#

# Filename: /sbin/init.d/PIstop



# places

#


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> sh /sbin/rc2.d/K04PI stop


root> sh /sbin/rc3.d/S96PI start



Page 14

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 Purpose

s (S) or m (M) 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 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


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*


root> su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1


root> su - piadmin -c /etc/rc.pistart > /dev/console 2>&1


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


Page 16

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

#

if [ -f /export/PI/adm/pistart.sh ] ; then

cd /export/PI/adm


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.

1.4 - Shutting Down an Individual Subsystem


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.


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 Check the System Message Log to see whether unusual events have occurred.

pigetmsg

Update Manager Are the clients connecting to the PI Server normally?

pilistupd

Tag Data Does the Archive data for a reference tag look normal?

pisnap.bat or pisnap.sh

Snapshot data flow

Is the Snapshot data flow normal? piartool -ss

Archive data flow Is the Archive data flow normal? piartool -as and piartool -qs

Archive Shift Verify that the expected archives are registered and that you have prepared for the next archive shift.

piartool -al

Interface Logs Check the interface logs to see whether unusual events have occurred.

IO Rate Counters

Interfaces support writing snapshot rates to PI Points. The IO rate values and timestamps are a good indicator of interface health.

FactoryTalk Historian Datalink or FactoryTalk Historian ProcessBook to view or trend the IO rate points.

Performance Counters (Windows)

All Subsystems publish key performance counters to Windows. Subsystem counters are discussed in this chapter.

Windows Performance Monitor. PI Performance Monitor Interface.

License limits and usage

Check the usage statistics and point counts for your system. Anticipate license increase needs.

piartool -lic

Chapter 2 - Monitoring PI System Health

Page 20

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

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

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

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 Description

-st Start time. This should be entered in PI time format.

-et End time. This should be entered in PI time format.

-mc Max count. This is an integer the total number of messages to return.

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

-pn This is the message source, either a specific program name (pinetmgr) or a wild-card mask (* for all programs, *arc* for all archive related sources, etc.). The default is all programs.

-msg A string mask selection for the message text. The default is * (show everything).

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


Page 22

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 Description

-username Remote PI Server username

-port TCP/IP port number

-node Remote PI Server node name

-password 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 5450 -password buddy

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

2.2.4 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

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_1030227.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_1030227.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,

208.243.230.129

2.2.5 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

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


Page 24

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

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

2.3.1 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: 10033 0

Snapshot Events: 1228011 0

Out of Order Snapshot Events: 130 0

Snapshot Event Reads: 392 0

Events Sent to Queue: 771952 0

Events in Queue: 0 0

Number of Overflow Queues: 0 0

2.3 - Monitoring Snapshot Data Flow


Total Overflow Events: 0 0

Primary Capacity Remaining: 2540349 0

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.


Page 26

When using repeats, the utility is stopped with <CTRL-C>.

$ piartool -ooo -r 10

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.

2.4 - Monitoring the Event Queue


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.

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.

2.4.1 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


Physical File Size (MB): 64 0

Page Size (KB): 1024 0

Total Data Pages: 63 0

Write Page Index: 0 0

Read Page Index: 0 0


Page 28

Total Page Shifts: 0 0

Available Pages: 63 0 (100.0%)

Average Events per Page: 40330 1

Estimated Remaining Capacity: 2540790 63 (2.2 hr)

Total Bytes Written (MB): 0 0

Total Event Writes: 14476 8007 (579/sec)

Total Event Reads: 14476 8007 (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).

2.5 - Monitoring the Archive


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

2.5.1 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


Archived Events: 1050621 1485

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

Archive Record Disk Writes: 152737 226

Unflushed Events: 12431 -203

Unflushed Points: 3131 -48

Point Flush Count: 133491 211

Primary Archive Number: 5 0

Archive Shift Prediction (hr): 1 0

Archiving Flag: 1 0

Archive Backup Flag: 0 0


Page 30

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

These counters are explained below.

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

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.

2.5 - Monitoring the Archive


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.

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 FactoryTalk Historian 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 un-flushed 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.


Page 32

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.

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


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 FactoryTalk Historian 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.

2.6.1 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 - ) Piconfig> @tabl pi_gen,pitimeout

* (Ls - PI_GEN) Piconfig> @mode create

* (Cr - PI_GEN) Piconfig> @istr name,value

* (Cr - PI_GEN) Piconfig> maxupdatequeue,6000

*> maxupdatequeue,6000

* (Cr - PI_GEN) Piconfig> @ends

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 update-manager database. The default is 100,000. You can use piconfig to change the limit.


Page 34

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

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.


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.

3.2.1 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 58 for more information.

Chapter 3 - Managing Archives

Page 36

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.

3.2.2 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

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 150-160 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.

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

3.2.4 About Fixed and Dynamic Archives There are two types of Archive files, fixed and dynamic.


Page 38

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. Newly-created 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.

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.

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

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


Page 40

Option Name Action

-ads Archive disable shift

Removed specified archive from shift participation.

-aes Archive enable shift

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] Archive cache diagnostics

Archive cache diagnostics for a specified point. Display the events sitting in the read and write cache.

-cas ['tagmask'] Archive cache summary

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.

-cs [For troubleshooting only]

PINetmgr connection stress test

PI Network Manager connection stress test.

-de <path> [-pt tagname] [recno]

Dump eventqueue Dump specified Event Queue file. Optionally select a specific tag and/or specific record in the file.



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>

ID conversion file creation

Create ID conversion file from specified input file.

-lic [Options listed under Action]

Licensing Information

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

-mpt <0|1> [For troubleshooting only]

Message protocol trace

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 Rockwell Automation provides on request, e.g.:

Mptconsolveview .\24-Aug-05_12-10-06.mpt

-msg "message" [-pro "procname"] [-nrep m] [-nbuf l] [-nmps n] [For troubleshooting only]

Message Subsystem Test

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.

-msgtest <startsize in bytes> <endsize in bytes> [For troubleshooting only]

PINetmgr Communications Test

Send a series of test messages to the PInetmgr. Message size increases by one byte increments starting from startsize to endsize.


Page 42

Option Name Action

-netstress [-SendBlocks 1] [-RecvBlocks 1] [-loops 1] [For troubleshooting only]

PINetmgr stress test.

Test PINetmgr subsystem by sending and receiving specified 4k blocks.

-ooo <-r><Sec> Out of order snap events

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

Times the RPC round trip to the specified sub-system.

-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

-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

3.3.2 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



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> Input Archive File

Required. The full path, including drive letter is required. This is true for all file arguments passed.

-of <full path name> Output Archive File

Required.

-ost <option> Output file Start Time

Options: Input, Event, <time>, NFE See “Specifying a Start Time for the Output File (-ost).”

-oet <option> Output file End Time

Options: Input, Event, <time>, NFE, Primary, NoChange


Page 44

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 Sets the start time to the start time of input. This is the default behavior.

event Sets the start time to time of first event in input.

time (where time is specified in absolute PI time format)

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-02 21-Feb Output file start and end times must differ by at least one second.

NFE Sets the start time to time of first event which passes the time filter.



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 Sets the end time to the end time of input file.This is the default behavior.

event Sets the end time to the time of last event in input file.

time (where time is specified in absolute PI time format)

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-02 21-Feb Output file start and end times must differ by at least one second.

NFE Sets the end time to time of last event which passes the time filter.

primary Sets the end time to indicate the archive is a primary archive.

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


Page 46

piartool reports any point in the input file that does not exist in the target system.

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 - ) Piconfig> @table pipoint

* (Ls - PIPOINT) Piconfig> @ostru pointid, recno, tag

* (Ls - PIPOINT) Piconfig> @output pointidconv.txt

@ends

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

2000000000,3600

Move entire archive ahead by 1 hour (another format):

01-Jan-70 00:00:00,3600

01-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,3600

26-Oct-02 02:00:00,0

31-Dec-02 23:59:59,0

A series of UTC values and offsets:

814953600,-61200

828871200,-57600

846403200,-61200

860320800,-57600

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 non-shiftable 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.


Page 48

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

3.4 - Listing the Registered Archives


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

Version: 7 Path: e:\pi\arc\piarch-2GB.3

State: 4 Type: 0 Write Flag: 1 Shift Flag: 1

Record Size: 1024 Count: 2097152 Add Rate/Hour: 154207.3

Offsets: Primary: 253063/1048576 Overflow: 1231270/2097152

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 Description

Shift Prediction Provides estimated time for the next shift and the target archive. This is important for backup planning.

Used Percentage of archive records used. This is an estimate, as only empty records are considered in the calculation.

Version Identifier of the archive's internal architecture. This label allows PI Server to mount and upgrade archives from older versions of PI.

Path Full path of the archive file.

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

Type 0 = Fixed, 1 = Dynamic.

Write Flag 1 = Archive is currently writeable, 0 otherwise.

Shift Flag 1 = Archive is potentially a target for archive shift, 0 otherwise.

Record Size Size in bytes of one record. This is always 1024.

Count Number of records in the archive file.

Add Rate Average number of overflow-records added per hour, over the archive lifetime.

Offsets: Primary Start and end record numbers for primary records. The end record number is always 1/2 of the Record Count.


Page 50

Label Description

Offsets: Overflow Start and end record numbers for overflow records.

Annotations Number of annotations used and the maximum number available. The archive shifts when this number is reached.

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


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%)


Version: 7 Path: g:\PI\arc\piarc.045





Start Time: 11-Aug-05 12:59:35


Backup Time: Never

Last Modified: 9-Sep-05 22:26:55

Archive[1]: g:\pi\arc\piarc144.arc (Used: 16.2%)


Version: 7 Path: g:\pi\arc\piarc144.arc





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%)


Version: 7 Path: g:\pi\arc\piarc145.arc




3.5 - Listing Archive Record Details



Start Time: 2-Jun-05 09:21:00

End Time: 11-Aug-05 09:12:35

Backup Time: Never


Archive[3]: g:\pi\arc\piarch.011 (Used: 99.8%)


Version: 7 Path: g:\pi\arc\piarch.011





Start Time: 5-Jan-05 08:15:06

End Time: 2-Jun-05 09:21:00

Backup Time: Never


Archive[4]: g:\pi\arc\piarc.144 (Used: 99.3%)


Version: 7 Path: g:\pi\arc\piarc.144






End Time: 5-Jan-05 08:15:06

Backup Time: Never


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


Page 52

records in an archive gets down below a certain number, this is when an automated archive shift will occur.

3.5.1 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

Point ID: 18 Record Number: 40

Chain Record Mumber - Next: 80531 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 00000000 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: 59421

Chain Record Mumber - Next: 0 Prev: 71411 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 00000000 Data Head: 26

Event Count: 121

Storage (bytes) - Available: 994 Used: 288

121 Event(s):

0: 9-Sep-05 18:57:04, S,O,A,S,Q [3,1,0,0,0]:

3.5 - Listing Archive Record Details


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

Meaning

S StateSet

O Offset in StateSet; 248 corresponds to "No Data"

A Annotated (0=no, 1=yes)

S Substitute (0=no, 1=yes)

Q Questionable (0=no, 1=yes)

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 Float32

101 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 278.

The archive offline utility will repair any chaining problem.


Page 54

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.

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.

3.8 - Creating Archives


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

3.8.2 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 1000.

For example, to allow for 20,000 configured points, the minimum archive size is: (20,000 x 2) / 1000 = 40 MB

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.

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

3.8.4 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


Page 56

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


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%)


Version: 7 Path: e:\pi\arc\piarch-2GB.3







Backup Time: Never

Last Modified: 5-Oct-05 13:26:21

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

@table pi_gen,pifirewall

@mode edit,t

@istr hostmask,value

"*.*.*.*",DISALLOW

3.9 - Creating Data Archives Prior to the Installation Date


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.

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.


Page 58

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.

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

A valid primary archive must have a specified start time and null end-time, which signifies current time.

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

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

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

3.10.4 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

3.11 - Managing Archive Shifts


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.

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.


Page 60

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

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

3.11 - Managing Archive Shifts


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.

3.11.2 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.001

0 piarcmgr 2-Apr-03 14:32:39

>> Target Archive for Shift: d:\pi\dat\piarch.003

0 piarsrv 2-Apr-03 14:32:39

>> Clear and Initialize archive file: d:\pi\dat\piarch.003

0 piarsrv 2-Apr-03 14:32:48

>> Archive clear progress: 51200 records cleared.

0 piarsrv 2-Apr-03 14:32:58


0 piarsrv 2-Apr-03 14:33:08


0 piarsrv 2-Apr-03 14:33:19


0 piarsrv 2-Apr-03 14:33:28

>> Archive successfully cleared 256000 records

0 piarsrv 2-Apr-03 14:33:28

>> Archive successfully initialized 16285 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.001

0 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


Page 62

>> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary Archive is

d:\pi\dat\piarch.003

3.12 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

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

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.

3.12 - Combining and Dividing Archives


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.

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


Page 64

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.


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

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

4.1.2 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 68).

You can also run the scripts manually (see Customize Your Backup, on page 70). 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 77).

Chapter 4 - Backing up the PI Server

Page 66

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.

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

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.

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


Page 68

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

4.4.1 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 74.

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.

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 99999 *-60d -install

The assumption above is that less than 99999 archives are mounted, so 99999 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 90). The default cutoff date is “1-Jan-1970 00: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


Page 70

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

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

-----------------------------------------------------------------

1 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 backup is performed. The second argument on the command line @%PISERVER%dat\pibackupfiles.bks 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.

4.4.2 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 2000.

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

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


Page 72

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

4.4.3 Do a Test Restore

General Considerations The following files require special treatment during a restore.

File Name Special Treatment

Pisubsys.cfg 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.

Piarstat.dat 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.



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.


Page 74

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.

4.4.4 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

4.5 - Automating Backups on a Windows Cluster


using NTBackup is that it comes with Windows free of charge, which allows Rockwell Automation 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 77.

4.5 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 68. 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 non-clustered Windows nodes are the same.

4.6 Automating Backups on UNIX

Contact Rockwell Automation technical support for updated instructions, at http://support.rockwellautomation.com.


Page 76

4.7 How The PI Backup Subsystem Works

4.7.1 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 http://msdn.microsoft.com/library then browsing the tree as follows.

WIN32 AND COM DEVELOPMENT

SYSTEM SERVICES

FILE SERVICES

VOLUME SHADOW COPY SERVICE

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.

4.7.2 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


Page 78

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.



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.

4.7.3 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 PI Archive Subsystem

Archive Registry and Archive Audit Database

Piarchive_<UTCprimary>_<GUID> PI Archive Subsystem

Archive0 dd-mmm-yy hh:mm:ss to Current

Piarchive_<UTCarch1>_<GUID> PI Archive Subsystem

Archive1 dd-mmm-yy hh:mm:ss to dd-mmm-yy hh:mm:ss

... … …

Piarchive_<UTCarchN>_<GUID> PI Archive Subsystem

ArchiveN dd-mmm-yy hh:mm:ss to dd-mmm-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_01123289768_{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


Page 80

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.

4.7.4 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 Firewall database

Pipeschd.bat PI-Performance Equation Scheduler command file

pisql.ini Initialization settings for the SQL Subsystem

pisql.res Parsing resource for the SQL Subsystem

Pisubsys.cfg Inter-process communication information file used by PI Network Manager

PISysID.dat Server ID data file

Pisystem.res PI-Performance Equation Scheduler equation parsing symbol database

Pitimeout.tbl Timeout database

Shutdown.dat Shutdown event configuration file used by the Shutdown Subsystem (pishutev)

Plicmgr The Pilicmgr subsystem has a single component called Pilicmgr.





pilicense.dat License Information

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.



Pimsg_*.dat PI Message Log Files

Pibasess The Pibasess subsystem has a single component called Pibasess.



pidbsec.dat PI Database Security Database

pidignam.dat Digital State Name Database

pidigst.dat Digital Set Database

PIModuleDb.dat PI Module Database

pipoints.dat PI Point Database

piptalia.dat PI Point Aliases Database

piptattr.dat PI Point Attributes Database

piptclss.dat PI Point Class database

piptsrcind.dat PI Point Source Index Database

piptunit.dat PI Point Unit Database

pitrstrl.dat PI Trust Table

piusr.dat PI User Database

piusrctx.dat User Context Database

piusrgrp.dat PI User Group Database

pibasessAudit.dat Base Subsystem Audit Database


Page 82

Pisnapss The Pisnapss subsystem has a single component called Pisnapss.



piarcmem.dat Snapshot Information

pisnapssAudit.dat 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:


piarstat.dat PI Archive Manager Data File (Contains list of registered archives)

piarchssAudit.dat Archive Subsystem Audit Database

The following files are backed up with the archive components:


Archive and Annotation (.ann) files for all components

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

PIBatch The Pibatch subsystem has a single component called Pibatch.



pibaalias.nt Batch Alias Database

pibaunit1.nt PI Batch Unit Database



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

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 Description

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

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

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

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


Page 84


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.

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

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

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

The backup events are summarized in the following table.


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

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

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

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

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

BackupShutdown 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


Page 86


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.

Argument Description

<path> Path must be the complete drive letter and path to a directory with sufficient space for the entire backup.

-component <comp> 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.

-numarch <number> 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.

-cutoff <date> 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-1970 00:00:00, unless otherwise specified by the Backup_ArchiveCutoffDate timeout parameter.

-wait <sec> 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


4.9 Managing Backups with piartool

4.9.1 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 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 Description

-abort Abort a current running backup. Example:

piartool -backup -abort

-query [-verbose] 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

-identify [-numarch <number>] [-cutoff <date>] [-verbose]

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

-trace <level> Debug messages are written to the log file when the trace level is non-zero. 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


Page 88

Backup Command Description

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 1

4.9.2 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

Subsystems Registered for Backup

Name, Registration Time, Version, Status

pibatch, 29-Jul-05 12:09:36, 3.4.370.38, [0] Success

pilicmgr, 29-Jul-05 12:09:52, 3.4.370.38, [0] Success

piarchss, 29-Jul-05 12:10:37, 3.4.370.38, [0] Success

pibasess, 29-Jul-05 12:11:53, 3.4.370.38, [0] Success

pisnapss, 29-Jul-05 12:11:54, 3.4.370.38, [0] Success

pimsgss, 29-Jul-05 12:11:56, 3.4.370.38, [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 Registers for backup

PI Message Subsystem Registers for backup

PI Snapshot Subsystem Registers for backup

PI Archive Subsystem Registers for backup

PI Base Subsystem Registers for backup

4.9 - Managing Backups with piartool


PI Network Manager

PI Batch Subsystem 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

VSS Supported: TRUE

Subsystems Registered for Backup

Name, Registration Time, Version, Status

pibatch, 28-Jul-05 16:09:18, 3.4.370.38, [0] Success

pisnapss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success

piarchss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success

pilicmgr, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success

pibasess, 28-Jul-05 16:09:52, 3.4.370.38, [0] Success

pimsgss, 28-Jul-05 16:09:53, 3.4.370.38, [0] Success

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


Page 90

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 79 and the expected files listed in the section on page Error! Bookmark not defined..

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

Subsystem(s) Name Default Value

Min Max Read Description

Archive archive_backupleadtime

1800 sec

5 86400 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_BSTimeout

1800 sec

1 86400 Once a minute

This timeout parameter is obsolete. It is for internal use only.

Backup Backup_NumArchives

3 1 1000000 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.

4.10 - Timeout Parameters




Backup Backup_ArchiveCutoffDate

01-Jan-70

01-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_TraceLevel

0 0 1000 Startup only

The default backup trace level. Non-zero 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.

All <subsysname>_WriteModTimesToFilePeriod

60 sec 10 900 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.


Page 92



All <subsysname>_BackupTimeout

1800 sec

30 86400 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.

4.11 Troubleshooting Backups

4.11.1 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_14.16.22.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.

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.

4.11 - Troubleshooting Backups


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.

4.11.2 VSSADMIN 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.

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 1.0 - Volume Shadow Copy Service administrative command-line tool

(C) Copyright 2001 Microsoft Corp.

No shadow copies present in the system.


Page 94

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 1.0 - Volume Shadow Copy Service administrative command-line tool


Provider name: 'MS Software Shadow Copy provider 1.0'

Provider type: System

Provider Id: {b5946137-7b9f-4925-af80-51abd60b20d5}

Version: 1.0.0.7

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 1.0 - Volume Shadow Copy Service administrative command-line tool


Writer name: 'OSISoft PI Server'

Writer Id: {0fd0891d-b731-4e59-a35d-48f164383155}

Writer Instance Id: {cf8d5ded-e931-4692-91a0-6b3064c756c3}

State: [1] Stable

Writer name: 'Microsoft Writer (Bootable State)'

Writer Id: {f2436e37-09f5-41af-9b2a-4ca2435dbfd5}

Writer Instance Id: {c89ae65c-9f26-4bd4-8220-db66757defc7}

State: [1] Stable

Writer name: 'MSDEWriter'

Writer Id: {f8544ac1-0611-4fa5-b04b-f7ee00b03277}

Writer Instance Id: {190c16a5-d378-43d6-bdb5-712983abea2b}

State: [1] Stable

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


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 Notes

PI API Installation Instructions

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.

UniInt End User Manual 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.

PI Interface Configuration Utility User Manual

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.

PI Performance Monitor Interface Manual

The PI Performance Monitor interface, PIPerfMon, obtains Microsoft Windows performance counter data and sends it to the PI System.

PI Interface Status Utility 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.

PI AutoPointSync User Manual

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.

Chapter 5 - Managing Interfaces

Page 96

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.

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

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

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.

5.2.3 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


Page 98

the PI Server. If you then look ProcessBook, for example, your data appears as a continuous flow of data, with no gaps.

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

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

5.2.6 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 OSIsoft-developed 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

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

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


Page 100

5.3.2 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).

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

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



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

New Pinet 1 connection: snapE No Trust established for:

apollo.osisoft.int|192.168.9.198|snapE using default login

and

Access Denied: [-10413] No trust relation for this request ID: 64. Address:

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


Page 102

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



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.

5.3.5 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 pre-installed 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.

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


Page 104

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.

5.3.7 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 interface-specific documentation must be consulted, the following command line parameters should be mentioned because they are fundamental to most UniInt-based interfaces.


/ps=x

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

/id=x

sometimes required 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.




/host=host:port

recommended parameter 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.

/f=SS or

/f=SS,SS or

/f=HH:MM:SS or

/f=HH:MM:SS,hh:mm:ss required for scan-based interfaces

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.

/stopstat

recommended parameter 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.

5.3.8 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 Description

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


Page 106

Point Attribute Description

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

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

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

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

5.3.9 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

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.


Page 108

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.

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.

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

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

Corresponding shutdown scripts and site-specific scripts Startup script

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


Page 110

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.


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


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


Shutdown script



Script location

pistart.sh pistop.sh sitestart.sh sitestop.sh $pihome/bin/

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

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

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 Description

Interface up-time (seconds)

The number of seconds since the interface has started. This counter is incremented once a second.


Page 112


IO Rate (events/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 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 Number of points loaded by the interface.

Scan Time (milliseconds)

Time in milliseconds to call developer function and to write values to PI. There is one “Scan Time” counter per scan class.

Scheduled Scans: % Missed

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

Scheduled Scans, % Skipped

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

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

Log file message count Number of messages that have been written to the log file. Only applies to the instance _Total.

Points edited in the interface

Number of point edits that have occurred. Only applies to the instance _Total.

Points added to the interface

Number of point that have been added to the interface. Only applies to the instance _Total




Points removed from the interface

Number of point that have been removed from the interface. Only applies to the instance _Total

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 0.95. 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 51-100. This counter must be unique within iorates.dat


Page 114

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

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:

PERFORMANCE_POINT

or to:

PERFORMANCE_POINT=interface_id

where interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.

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.



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

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


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 un-interruptible 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

Chapter 6 - Managing Security

Page 118

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.

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.

Maintaining the Trust Database for automated logins

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

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

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


Page 120

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:

192.168.149.55

192.168.177.*

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 192.168.168.22 matches a Hostmask of 192.168.*.*. A matching Disallow has precedence over an Allow.

Here is an example:

Host/Mask Value

192.168.168.* ALLOW

192.168.168.67 DISALLOW

Only hosts within the 192.168.168.0 subnet are allowed connections. 192.168.168.67 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:

Piconfig> @table pi_gen,pifirewall

Piconfig> @ostructure hostmask,value

Piconfig> @select hostmask="*"

Piconfig> @endsection

*.*.*.* ALLOW

The listing shows the default firewall setting - all connections are allowed.

Limit Connections Example The next example modifies the Firewall Database to only allow connections from the subnet 123.45.678.0.


Piconfig> @mode create,t

6.5 - Firewall Security


Piconfig> @istructure hostmask,value

Piconfig> 192.168.168.*, 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:


Piconfig> @mode create


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:


Piconfig> @mode list

Piconfig> @ostructure hostmask,value

Piconfig> @select hostmask=*

192.168.168.*,ALLOW

bobcat.somewhere.com,DISALLOW

Piconfig> @mode edit

Piconfig> @istructure 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 1.2.3.4

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,

192.168.168.129

Modify the Hostmask *.*.*.* Example If you wish to modify the hostmask *.*.*.*, you must use the following example.


Page 122

Do not use a wild card selection.


Piconfig> @mode edit


Piconfig> "*.*.*.*",DISALLOW

To delete the global mask entry use the following:

Piconfig> @mode delete

Piconfig> @istructure 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:

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

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

6.6.3 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

6.6 - Database Security


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

6.6.4 PIBatch Controls the PIbatch database.

6.6.5 PICampaign Controls the PIcampaign database.

6.6.6 PIDS Controls the Digital States table. To create or edit sets or states the user needs write access to this token.

6.6.7 PIHeadingSets Controls the PIheadingsets database.

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

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

6.6.10 PITransferRecords Controls the creation and modification of transfer records in the MDB.

6.6.11 PIUSER This token controls several tables: PIusers, PIgroups, PIContext and PItrust.

6.6.12 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


Page 124

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.

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

6.7.2 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 127.

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.

6.7.3 Access Algorithm Whenever a user logs in, the following algorithm is used to determine what access to a point is granted:

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.

6.7.4 Assigning and Changing Ownership and Access Permissions Ownership and access permissions are assigned using the piconfig utility. The piconfig Utility on page 173 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) Piconfig> @table pipoint

* (Ls) Piconfig> @ostructure tag, ptowner

* (Ls) Piconfig> @select tag=sinusoid

* (Ls) Piconfig> @endsection

SINUSOID,piadmin

* (Ls) Piconfig> @mode edit

* (Ed) Piconfig> @istructure, tag, ptowner

* (Ed) Piconfig> sinusoid, tom

* (Ed) Piconfig> @mode list

* (Ls) Piconfig> @ostructure tag, ptowner



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) Piconfig> @ostructure tag, ptaccess



SINUSOID,o:rw g: w:


Page 126


* (Ed) Piconfig> @istructure tag, ptaccess

* (Ed) Piconfig> sinusoid,o:rw g:r w:r


* (Ls) Piconfig> @ostructure tag, ptaccess



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) Piconfig> @ostructure tag, dataowner, datagroup



SINUSOID,piadmin,piadmin


* (Ed) Piconfig> @istructure tag, dataowner, datagroup

* (Ed) Piconfig> sinusoid, Operator1, OperationsGroup




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) Piconfig> @ostructure tag, dataaccess



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:


* (Ed) Piconfig> @istructure, tag, dataaccess

* (Ed) Piconfig> sinusoid, o:rw g:rw w:


* (Ls) Piconfig> @ostructure tag, dataaccess



6.8 - User Security


SINUSOID,o:rw g:rw w:

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

@table pipoint

@mode edit

@modify ptaccess=o:rw g:rw w:rw

@modify dataaccess=o:rw g:rw w:rw

@select tag="*"

@endsection

@exit

6.7.6 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 FactoryTalk Historian ProcessBook or FactoryTalk Historian 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 read-write 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.


Page 128

Do not delete either account. You should establish passwords for both accounts. This does not affect the trust login process.

6.8.1 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 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) Piconfig> @table pigroup

* (Cr) Piconfig> @mode list

* (Ls) Piconfig> @ostructure group, description,users,...

* (Ls) Piconfig> @select group="*"


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) Piconfig> @mode create

* (Cr) Piconfig> @istructure group, description

* (Cr) Piconfig> Section1, Section1 crew chiefs and engineers

*> Section1, Section1 crew chiefs and engineers


* (Ls) Piconfig> @ostru group,description

* (Ls) Piconfig> @select group="*"


piadmin,Administration

piuser,User

ptmaintenance,

Section1,Section1 crew chiefs and engineers

6.8 - User Security


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


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) Piconfig> @table piuser

* (Ls) Piconfig> @ostructure user, description, groups

* (Ls) Piconfig> @select user="*"


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 email 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) Piconfig> @mode create

* (Cr) Piconfig> @istructure user, description, groups, ...

* (Cr) Piconfig> tom/mypassword, [email protected], piadmin, piuser


* (Ls) Piconfig> @ostructure user, description, groups, ...

* (Ls) Piconfig> @select user=tom


tom, [email protected], piadmin,piuser


Page 130

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.

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

6.9.1 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

6.9 - Trust Login Security


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.

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


Page 132

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.

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.

6.9.2 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



Field in Trust Record

Req or Opt.

PI API

PI SDK on Win98

PI SDK on WinNT or greater

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.

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 129. 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 - ) Piconfig> @tabl pitrust

* (Ls - PITRUST) Piconfig> @?atr

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

@table pitrust

@mode create

@istru trust, appname, piuser


Page 134

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.

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 0.0.0.0 indicates that a match is not required. If these fields are left blank, PI Server will store 0.0.0.0 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 255.255.255.255. If you are specifying a Class C subnet, specify the Netmask as 255.255.255.0 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.

Rockwell Automation 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.

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.


Page 136

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.

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.

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

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


Page 138

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 119, 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.

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.

6.9.4 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) Piconfig> @ostr

trust,appname,domain,ipaddr,iphost,netmask,osuser,piuser

* (Ls - PITRUST) Piconfig> @select trust="*"

* (Ls - PITRUST) Piconfig> @ends

!Default_ServerIP!,,,28.62.163.161,,255.255.255.255,,piadmin

!Default_ServerMachine!,,,0.0.0.0,bilbo,0.0.0.0,,piadmin

!Proxy_127!,,,127.0.0.1,,255.255.255.255,,piadmin

!Proxy_localhost!,,,0.0.0.0,localhost,0.0.0.0,,piadmin

The initial entries are two with IP address and two with IPhost name:

The IP addresses are the TCP/IP standard local host address (127.0.0.1) 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.

6.9.5 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, 0

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

6.9.7 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 0.0.0.0.

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.


Page 140

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

Domain Domain

IPAddr 0.0.0.0 IPAddr 192.168.168.121

Netmask 0.0.0.0

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 = 192.168.168.121

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 SDKIF1




AppName piperfmon.exe yes AppName piperfmon.exe

Domain Domain

IPAddr 0.0.0.0 IPAddr 192.168.168.121

Netmask 0.0.0.0

IPHost IPHost Vaughan

OSUser OSUser

PIUser IFTypeB

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 (123.123.123.22) the rights of a PI user Operator1.

* (Ls - PITRUST) Piconfig> @mode create

* (Cr - PITRUST) Piconfig> @istru trust,IPHost,ipaddr,netmask,appname,piuser

* (Cr - PITRUST) Piconfig> GTinterface,GT55,123.123.123.22,

255.255.255.255,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 IFUser1.

@table pitrust

@mode create

@istru Trust,IPAddr,Netmask,PIUser

MyTrust1,206.79.198.12,255.255.255.255,IFUser1

@endsection

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


Page 142

@table pitrust

@mode create

@istru Trust, IPHost, PIUser

MyTrust2,lychee.osisoft.com,IFUser2

@endsection

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.



Trust NT/2000/XP

AppName AppName piperfmon.exe

Domain OSI yes Domain OSI

IPAddr 0.0.0.0 IPAddr 192.168.168.121

Netmask 0.0.0.0

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 192.168.168.121 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 MatchUserName


Domain OSI yes Domain OSI

IPAddr 0.0.0.0 IPAddr 192.168.168.121

Netmask 0.0.0.0


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 Matchmachine


Domain Domain OSI

IPAddr 0.0.0.0 IPAddr 192.168.168.12


Page 144


1

Netmask 0.0.0.0

IPHost $ yes IPHost Suzanne2

OSUser OSUser Perfmon

PIUser OSI

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 0.0.0.0 0.0.0.0 192.168.168.121 0.0.0.0 Yes

B 192.168.168.0 255.255.255.0 192.168.168.121 192.168.168.0 Yes

C 192.168.168.0 255.255.255.0 192.168.175.004 192.168.175.0 No

D 192.168.168.176 255.255.255.240 192.168.168.178 192.168.168.176 Yes

E 192.168.168.176 255.255.255.240 192.168.168.121 192.168.168.112 No

F 192.168.168.22 255.255.255.255 192.168.168.22 192.168.168.22 Yes

G 192.168.168.22 255.255.255.255 192.168.168.20 192.168.168.20 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 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 Matchmachine


Domain Domain OS*I

IPAddr 192.168.168.121 yes IPAddr 192.168.168.121

Netmask 255.255.255.255


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 SubnetC1


Domain Domain OSI*

IPAddr 192.168.168.0 yes IPAddr 192.168.168.121

Netmask 255.255.255.0



Page 146


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

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 123.125.125.0 with a name MGr and logged with a user named interface the access rights of PI user Mginter.

* (Cr - PITRUST) Piconfig> @istru trust,appname,domain,IPaddr,netmask,

IPHost,osuser,piuser

* (Cr - PITRUST) Piconfig> MGinterface, MG.exe, plant1, 123.124.125.0,

255.255.255.0, 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 123.123.123.3.

A trust record called Operator1 is defined for IPhost = PIclient1, IPaddr = 123.123.123.3, and PIUser = Operator1.

Another trust record called Operator2 is defined for IPHost = PIclient1, IP address = 123.123.123.0, and PIUser = Operator2.

Trust Records Connection Credentials

Field Name Field Value Field Value Name Value

Trust Operator1 Operator2


Domain Domain OSI

IPAddr 123.123.123.3 123.123.123.0 IPAddr 123.123.123.3

Netmask 255.255.255.255 255.255.255.0

IPHost PIclient1 PIclient1 IPHost PIclient1

OSUser OSUser perfmon

6.10 - Resolving Ambiguities


Trust Records Connection Credentials

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 123.123.123.0, 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.

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


Domain Domain OSI

IPAddr 0.0.0.0 0.0.0.0 IPAddr 123.123.123.3

Netmask 0.0.0.0 0.0.0.0

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 Field Value

Trust AddedFirst

AppName


Page 148


Domain OSI

IPAddr 192.168.168.0

Netmask 255.255.255.0

IPHost

OSUser

PIUser UserA

Now suppose you add another trust record called NewNetmask and point to UserB like this:


Trust NewNetmask

AppName

Domain OSI

IPAddr 192.168.168.0

Netmask 255.255.255.240

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.


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 Rockwell Automation 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 -11043 errors because only the primary archive will be registered.

To move the PI Server:

Chapter 7 - Moving PI Servers

Page 150

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

7.3 - Same Computer


3. Run piartool -al redirecting the output to a text file. This is a record of all registered archives.

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.


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 149, 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 149. In this case the Server ID file is copied to the new computer as part of the moving process. No other action is needed.

Chapter 8 - Copying a PI Server

Page 154

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.


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.

Chapter 9 - Merging Two PI Servers

Page 156

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

@table pipoint

@ostr pointid,recno,tag

@select tag=*

@ends

@exit

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.

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.


Page 158

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

9.2 - Server Merge Procedure - Example


Archive: D:\PI\dat\piarch.002

PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:

Version: 4 Path: D:\PI\dat\piarch.002


Record Size: 1024 Count: 2048


Start Time: 2-Mar-98 12:51:41


Backup Time: Never








End Time: 2-Mar-98 12:51:41

Backup Time: Never







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


Page 160

pitot2

pitot3

pitot4

pitot5

pitot5est

pitot5ramp

pitot5run

pitot6count

pitot6time

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








Backup Time: Never







Start Time: Current Time


Backup Time: Never









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 - ) PIconfig> @table pipoint

* (Ls - PIPOINT) PIconfig> @mode edit

* (Ed - PIPOINT) PIconfig> @istr 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 - ) PIconfig> @table pibaunit


Page 162

* (Ls - PIBAUNIT) PIconfig> @?atr

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) PIconfig> @Ostr

unitname,activetag,bidexpr,description,prodexpr

* (Ls - PIBAUNIT) PIconfig> @ends

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

@table pibaunit

@mode create

@istr 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 script:

@table pipoint

@ostr pointid,recno,tag

@select tag=*

@output retiredidconv.txt

@ends

@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




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

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


35,35,pipe:sine2tRetired


Page 164




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

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

@table pibaunit

@ostr unitname

@sele unitname=*

@output unitlist.txt

@ends

@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

Reactor1,*-1000d,*

@exit

9.3 - Shut Down the Retired System


The script and procedure for dumping the batches follows:

D:\PI\adm>type pibatchlist.dif

@table pibatch

@mode list

@ostr unitname,bid,prodid,starttime,stoptime

@ostr ...

@istr unitname,searchstart,searchstop

D:\PI\adm>piconfig input pibatchlist.dif input unitlist.txt > pibatchlist.txt

@exit

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

@table pibatch

@mode create

@istr 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

Reactor1Retired,XYZ3,Green,3-Mar-98 12:24:23,12:44:00

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


Page 166

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.

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:










End Time: 3-Mar-98 11:15:03

Backup Time: Never








End Time: 2-Mar-98 12:51:41

Backup Time: Never







Start Time: 25-Feb-98 14:16:40

End Time: 2-Mar-98 12:50:27

Backup Time: Never

9.3.1 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

9.3.2 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



Page 168

1 Records Created

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

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



Empty records: 0




Begining Output pass. Output archive: piarchconv.002


Invalid ID Conversion on input Point ID 13 . Record not processed.

22722 Loaded in 3( 1 + 2 ) Seconds 7574 Event/Sec.

80269 Archive Total seconds - ratio: 26756

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


Shift Time: 18-Jan-38 19:14:07.7930

Target Archive: /opt/PI/dat/piarch.002









Backup Time: Never








End Time: 3-Mar-98 16:32:27

Backup Time: Never









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


Page 170



Archive input file: /opt/PI/dat/piarch.001









Empty records: 11







Empty records: 0




Begining Output pass. Output archive: /opt/PI/dat/piarchcomb.001





Now combine the converted archive.

$ ../bin/piarchss -if /opt/PI/dat/piarchconv.002 -of /opt/PI/dat/piarchcomb.001



Archive input file: /opt/PI/dat/piarchconv.002









Empty records: 71










Empty records: 0




Begining Output pass. Output archive: /opt/PI/dat/piarchcomb.001





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


Shift Time: 18-Jan-38 19:14:07.7930

Target Archive: /opt/PI/dat/piarch.002









Backup Time: Never

Archive: /opt/PI/dat/piarchcomb.001


Version: 4 Path: /opt/PI/dat/piarchcomb.001





End Time: 3-Mar-98 16:32:27

Backup Time: Never








Page 172



Backup Time: Never

$ piconfig

* (Ls - ) PIconfig>

* (Ls - ) PIconfig> @Input piarc.dif

* (Ls - PIARC) PIconfig> sinusoidRetired,2-mar-98,*,

*> sinusoidRetired,2-mar-98,*,

87.71619,GOOD,2-Mar-98 13:37:56

99.23527,GOOD,2-Mar-98 14:39:56

96.20524,GOOD,2-Mar-98 15:44:56

75.77717,GOOD,2-Mar-98 16:57:56

14.20552,GOOD,2-Mar-98 19:31:26

1.545739,GOOD,2-Mar-98 20:31:26

1.869217,GOOD,2-Mar-98 21:31:26

18.17325,GOOD,2-Mar-98 22:40:56

86.39859,GOOD,3-Mar-98 01:33:26

99.15742,GOOD,3-Mar-98 02:38:56

96.37012,GOOD,3-Mar-98 03:43:56

75.96362,GOOD,3-Mar-98 04:57:26

14.35799,GOOD,3-Mar-98 07:30:56

0.7647065,GOOD,3-Mar-98 08:39:56

3.794814,GOOD,3-Mar-98 09:44:56

24.22295,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:48

98.3448,GOOD,3-Mar-98 14:30:26

98.2471,GOOD,3-Mar-98 15:30:26

82.16194,GOOD,3-Mar-98 16:39:56

79.05913,GOOD,3-Mar-98 16:48:56

End Repeat...

Take a good look at several points before proceeding.

9.3.4 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 - ) PIconfig> @input 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.


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.

10.1 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 Rockwell Automation 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.

10.2 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 Rockwell Automation Web site.

Chapter 10 - The piconfig Utility

Page 174

10.3 Key Concepts for Using Piconfig

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

piconfig> @exit

The command character must precede every command.

By default, the command character is @.

Data are on separate lines that are not preceded by the command character.

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

@prompt yes

@prompt 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 the @table command:

* (Ls - ) piconfig> @table pipoint

* (Ls - PIPOINT) piconfig> @help

Modes and tables are explained later in this chapter.

10.3.3 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 10–1. 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

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


Page 176

Example of ?tbl, Table, and Status Commands These commands are illustrated in the example below:

* (Ls - ) piconfig> @?tbl

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) piconfig> @status

---- piconfig Status at 18-Mar-02 10:46:51 ----

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: <127.0.0.1,piadmin>

10.3.4 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) piconfig> @?atr

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

9 compmin Uint16 D: 0 C: 0

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

19 engunits String D: C:

20 excdev Float32 D: 1. C: 1.

21 Excdevpercent Float32 D: 1 C: 1.

22 excmax Uint16 D: 600 C: 600

23 excmin Uint16 D: 0 C: 0

24 exdesc String D: C:

25 PointID Uint32 D: 0 C: 2009

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

33 scan BYTE D: 1 C: 1

34 shutdown BYTE D: 1 C: 1

35 SourceTag String D: C:

36 span Float32 D: 100. C: 100.

37 step BYTE D: 0 C: 0

38 typicalvalue Float32 D: 50. C: 50.

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

10.3.5 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


Page 178

SINUSOID 68.973 14-Jun-03 10:00:00

SINUSOIDU 11.184 14-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.

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

@select 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) piconfig> @mode edit

* (Ed - PIPOINT) piconfig> @istructure 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.



10.3.6 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) piconfig> @help

*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


Page 180

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

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) piconfig> @mode list

* (Ls - PIPOINT) piconfig> @stype delimited

* (Ls - PIPOINT) piconfig> @ostructure tag, pointsource, pointtype

* (Ls - PIPOINT) piconfig> @select tag=s*, pointsource=R

* (Ls - PIPOINT) piconfig> @endsection

SINUSOID,R,Float32

SINUSOIDU,R,Float32

SQF100,R,Float32

SQF101,R,Float32


*> @exit

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.

10.3.7 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



(Ls) List mode (read only) Output formatted records from a table to screen or file

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

@mode create, t

@mode edit, t

The specified mode persists until the next mode command is issued.

Check Only The character c (for check) may be specified with either create or edit mode.

@mode create, c

@mode 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/Edit.

@mode create, t, c

@mode edit, t, c

The specified mode persists until the next mode command is issued.

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


Page 182

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

@istructure tag, pointsource,pointtype

SINUSOID,R,FLOAT32

As shown above, the command is preceded by the command character (@) while the data are not.

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

@delimiter \

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

@istructure tag, 1, 1, 12

@istructure pointsource, 1, 14, 1

@istructure pointtype, 1, 19, 7

*

*234567890123456789

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:

@ostructure tag

@ostructure pointsource

@ostructure pointtype

To output all attributes for the current table, issue the command:

@ostructure *

This works in both keyword and delimited formats.

Note: The command @ostructure 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 as follows:

@ostructure ?

@istructure ?

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

@select ?


Page 184

10.3.10 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

These operators can be used for date, numeric or text fields. Text comparison is based on ASCII values.

10.3.11 Wildcards Wildcards, * and ?, may be used in text fields. * matches all characters; ? matches a single character.

10.3.12 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) piconfig> @ostructure set,state,...

* (Ls - PIDS) piconfig> @select set=modes

* (Ls - PIDS) piconfig> @endsection

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.



10.3.13 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) piconfig> @sele tag=sinusoid

* (Ls - PISNAP) piconfig> @ends

SINUSOID,86.71634,20-Nov-02 16:25:30

* (Ls - PISNAP) piconfig> @istru tag

* (Ls - PISNAP) piconfig> sinusoid

*> sinusoid

sinusoid,86.71634,20-Nov-02 16:25:30

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

10.3.15 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

*


Page 186

@table pipoint

@mode list

@stype delimited

@ostructure tag, pointsource, pointtype

@select tag=s*, pointsource=R

@endsection

Start piconfig and run this input file using the input command:

$ piconfig

* (Ls - ) piconfig> @input list.inp

The following output is generated:

SINUSOID,Float32,R

SINUSOIDU,Float32,R

SQF100,Float32,R

SQF101,Float32,R


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


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


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:

*> @echo 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

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.

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

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


Page 188

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 example;

@login 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.

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 5450 -username piadmin -

password myadminpassword

You may specify the parameters -node, -port, -username and -password in any order, after -remote.

10.4 Piconfig Commands and Tables

This section contains details on piconfig commands and tables.

Table 10–2. 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 (case-insensitive

Sets case-sensitivity-ignore mode. Flag may be: Data, Names, or All.

10.4 - Piconfig Commands and Tables



) 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 C @ 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

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.


Page 190


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.

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 time-zone indication



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

@ptclassname classic

Optionally the ptclass can be specified at Pipoint Table load; the syntax is:

@table pipoint,<ptclass>

This example selects the Pipoint Table and classic ptclass:

@table pipoint,classic

When listing classic point attributes of non-classic points, attributes unique to classic will appear to be blank.

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 - ) piconfig> @table pipoint

(Ls - PIPOINT) piconfig> @?atr

(Ls - PIPOINT) piconfig> @ptclassname classic

(Ls - PIPOINT) piconfig> @?atr

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

@modify <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”:

@table pipoint

@mode edit

@modify Span=150

@select tag=MyTag*

@endsection


Page 192

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

@table pipoint

@mode edit

@select tag=*, pointsource=X

@modify zero-=10, span*=1.1

@endsection

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:

[-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 Rockwell Automation Technical Support Web site at http://support.rockwellautomation.com.

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

*

@table pipoint

@mode create, t

@istructure tag, pointsource, pointtype

@input taglist.dat

@endsection

*

*List tags to verify creation or modification

*

@mode list

@ostructure tag, pointsource, pointtype

@select tag=*, pointsource=Lab, pointtype=float16

@endsection

@exit

Run piconfig using the structure file as input.

piconfig < example3.str

10.4.2 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 Description

SET name of attribute set

ATTRIB Attribute name; a set has many of these

DEFAULT Default value of the attribute

TYPE… Data type of the attribute. For example, String, Float32


Page 194

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) PIconfig> @table piatrset

* (Ls - PIATRSET) PIconfig> @ostr set

* (Ls - PIATRSET) PIconfig> @ends

*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) PIconfig> @table piatrset

* (Ls - PIATRSET) PIconfig> @ostr attrib, default, type

* (Ls - PIATRSET) PIconfig> @ostr ...

* (Ls - PIATRSET) PIconfig> @istr set

* (Ls - PIATRSET) PIconfig> classic

*> classic

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


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

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

The table name is PIPTCLS. It has the following attributes:


Class name of the class

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

ATTRIB Attribute name; a class has many of these

DEFAULT Default value of the attribute

TYPE… Data type of the attribute. For example, String, Float32


Page 196

The following piconfig session lists the point classes on the server:

* (Ls - PIPTCLS) PIconfig> @ostr class

* (Ls - PIPTCLS) PIconfig> @ends

*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) PIconfig> @tabl piptcls

* (Ls - PIPTCLS) PIconfig> @mode list

* (Ls - PIPTCLS) PIconfig> @ostr attrib,default,type

* (Ls - PIPTCLS) PIconfig> @ostr ...

* (Ls - PIPTCLS) PIconfig> @istr 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

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



* End Repeat...

* (Ls - PIPTCLS) PIconfig>

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


Ptsrc The point source character or string

Code The internal code, used for point source update signup

Count Number of points in this point source

Desc… Free format descriptor

The following piconfig session lists the point sources on the server:

* (Ls - PIPTSRC) PIconfig> @ostru ptsrc,code,count,desc

* (Ls - PIPTSRC) PIconfig> @ends

*PIconfig Err> Wild-card specs. missing, default to '*'.

#,15,26,

*,13,1,

1,7,5589,

9,2,11,

?,14,1,

@,10,4,

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,


Page 198

PIUnitBatch-InternalUse-1,8,109,

R,1,9865,

T,6,15,Totalizer Points

U,12,2,

10.4.5 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 16383 sets with up to 16383 states in each set.

The table name is PIDS. The primary key is SET. The following attributes are defined:


SET name of digital state set

SETNO digital state set number (read only)

STATE… 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 - ) piconfig> @table pids

(Ls - PIDS) piconfig> @?atr

1 - SET (D) Setxxx

2 - SETNO (D) 0

3 - STATE (D) Statexxx

4 - OLDCODE (D) 0

5 - NEWSET (D)

(Ls - PIDS) piconfig> @ostructure set

(Ls - PIDS) piconfig> @select set=*

(Ls - PIDS) piconfig> @endsection

SYSTEM

BATCHACT

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) piconfig> @table pids

2. Prepare to write to the table

(Ls - PIDS) piconfig> @mode 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) piconfig> @istructure 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) piconfig> @mode list

(Ls - PIDS) piconfig> @ostructure set, state, ...

(Ls - PIDS) piconfig> @select set=V*


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.




(Ls - PIDS) piconfig> @mode 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) piconfig> @istructure set

(Cr - PIDS) piconfig> @istructure state

(Cr - PIDS) piconfig> @istructure ...

The input lines are the set name followed by any number of states:

ValveStateSet

Open

Closed

Subsequent lines are treated as input until the next piconfig command is issued.


Page 200

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:




(Ls - PIDS) piconfig> @mode 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) piconfig> @istructure set, state, ...

4. 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) piconfig> @mode list

(Ls - PIDS) piconfig> @ostructure set, state, ...

6. Select only those sets that start with “V”

(Ls - PIDS) piconfig> @select set=V*

7. Start processing


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

@istru set

@istru oldcode,state

@istru ...

system



0,??????????

1,

2,?2

3,

4,?4

@istru set

@istru state

@istru ...

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 - ) piconfig> @table pistate

(Ls - PISTATE) piconfig> @mode edit

(Ed - PISTATE) piconfig> @istr 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 - ) piconfig> @table pids

(Ls - PIDS) piconfig> @mode list




Page 202


SYSTEM

BATCHACT

PHASES

MODES

VALVESTATESET

(Ls - PIDS) piconfig> @mode edit

(Ed - PIDS) piconfig> @istru set,newset

(Ed - PIDS) piconfig> ValveStateSet,NewValveStateSet

(Ed - PIDS) piconfig> @mode list




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 - ) piconfig> @table pipoint

2. Prepare it for writing

(Ls - PIPOINT) piconfig> @mode create

3. Specify the input data format

(Cr - PIPOINT) piconfig> @istructure tag, pointtype, digitalset

*> istructure tag, pointtype, digitalset

4. Specify the data

(Cr - PIPOINT) piconfig> ValveStateTag, Digital, ValveStateSet

*> ValveStateTag, Digital, ValveStateSet


(Cr - PIPOINT) piconfig> @mode list

(Ls - PIPOINT) piconfig> @ostructure tag, pointtype, digitalset

6. Select only those tags that start with “V”

(Ls - PIPOINT) piconfig> @select tag=V*



7. Now force processing

(Ls - PIPOINT) piconfig> @endsection

ValveStateTag, Digital, ValveStateSet

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 - ) piconfig> @table pisnap

2. Prepare for writing

(Ls - PISNAP) piconfig> @mode edit

3. Specify the input data format:

(Ed - PISNAP) piconfig> @istructure tag, time, value

4. Specify the data. The timestamp is *, which indicates that the current time should be used.

(Ed - PISNAP) piconfig> ValveStateTag, *, Open


(Ed - PISNAP) piconfig> @mode list

(Ls - PISNAP) piconfig> @ostructure tag, time, value

6. Select only those tags that start with “V:”

(Ls - PISNAP) piconfig> @select tag=V*

7. Now start processing:

(Ls - PISNAP) piconfig> @endsection

ValveStateTag, 26-SEP-03 15:45:32, Open

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


Table 10–3. 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)


Page 204


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 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) piconfig> @sele tag=c*

* (Ls - PISNAP) piconfig> @ends

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


RVAL real values; or 0 for other point types

ISTAT 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 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 - ) piconfig> @table pisnap

(Ls - PISNAP) piconfig> @mode edit

Specify the format of the input data. (Ed - PISNAP) piconfig> @istruc 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 - ) piconfig> @table pisnap2

* (Ls - PISNAP2) piconfig> @mode edit

* (Ed - PISNAP2) piconfig> @istru 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.

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



Page 206

Table 10–4. Archive Table Attributes


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)

Status the value status (read only)

Flags (Q)uestionable (M)odifed (A)nnotated Only Q is read/write

Annot Annotation

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


Count Maximum number of events to retrieve in list mode

Mode Archive editing mode – see below

Starttime Start time for events retrieval

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


COMP Compressed events

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

@input piarc.dif

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

@input piarc.dif

sinusoid, *-4h, *, 100

@endsection

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) piconfig> @table piarc

* (Ls - PIARC) piconfig> @istru tag, starttime, endtime, count, mode

* (Ls - PIARC) piconfig> @ostr value,status,time

* (Ls - PIARC) piconfig> @ostr ...

* (Ls - PIARC) piconfig> sinusoid,*,*-4h,5,even

*> sinusoid,*,*-4h,5,even

71.32876,GOOD,20-Nov-02 17:52:51

77.07982,GOOD,20-Nov-02 16:52:51

Digital State,Shutdown,20-Nov-02 15:52:51



* End Repeat...

Edit Mode Attribute for PIArc Table In edit mode, the MODE attribute can be one of the following:


noreplace add unless event(s) exist at same time (PI 2.x)

append add event regardless of existing events

replace add event, replace if event at same time

replacex Replace existing event (fail if no event at time)

replaceSp Replace a specified value when multiple values at the same time

remove Remove existing event

appendx as append + no compression; that is, if this is the Snapshot, force into Archive


Page 208

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.

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

@table piarc

@mode edit,t

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

@mode edit,t

or

@mode create,t

The piconfig selection and modification may be used. For example one might create an input file (input.txt) with the following command lines

@istructure tag, starttime, endtime, count

@ostructure tag, value, status, time

@ostructure ...

@output 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 example:

@mode edit

@istructure tag, value, status, time

@modify value*= 1.1, mode=replace

@input 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 delevents.dif.

@table piarc

@mode list

@istructure tag, starttime, endtime, count

@ostructure tag, time, value

@ostructure ...

@timf 9

@sigd 9

@output tmpdelevents.dat

%1%,%2%,%3%,10000

@output

*@exit - uncomment this to exit and review before deleting

@mode ed,t

@modify mode=remove

@istructure tag, time

@input tmpdelevents.dat

@exit

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 10000 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) PIconfig> @input piarc.dif

* (Ls - PIARC) PIconfig> rpflt1,*,y,100

*> rpflt1,*,y,100

123.,GOOD,24-Jun-03 17:43:01

1123.,GOOD,24-Jun-03 01:00:00

112.,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) PIconfig> @mode edit,t

* (Ed - PIARC) PIconfig> @istru tag,value,newvalue,time,mode

* (Ed - PIARC) PIconfig> rpflt1,11,0.11,t+1h,replacesp

*> rpflt1,11,0.11,t+1h, replacesp

* (Ed - PIARC) PIconfig> @input piarc.dif

* (Ls - PIARC) PIconfig> rpflt1,*,y,100


Page 210

*> rpflt1,*,y,100

123.,GOOD,24-Jun-03 17:43:01

1123.,GOOD,24-Jun-03 01:00:00

112.,GOOD,24-Jun-03 01:00:00

0.11,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.

To set the number of sub-second digits to 4 and turn on time zone information display, you would enter the command:

@timf 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, 1970 00:00:00.0000. The archive preserves the timestamp with accuracy of 15.25 microseconds.

Note: The default time accuracy of 5 digits might compromise a sub-second time-stamp. 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.



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


Table 10–5. PI Batch Unit Table Attributes

Attribute Definition

UNITNAME Defines the UNIT name. UNITNAME is the primary index of the Pibaunit Table. Cannot include the \ character.

NEWUnitName Used to rename an existing unit.

ActiveTag PI Tag which indicates batch activity on Unit.

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

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

DataAccess Security attribute, which specifies access to batches created on the unit.

DataGroup Group membership of the batches created by the unit.

DataOwner Owner of batches created by the unit.

Description Description of unit.

EvalDelay Specifies delay, from batch start, before evaluating product and batch ID expressions.

MergeConsecutive If non-zero, treats short batch stop and restarts as one contiguous batch.

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

UnitAccess Security attribute, which specifies access to the unit.

UnitGroup Unit group membership.

UnitOwner Unit owner.

10.4.9 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


Page 212

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.

Table 10–6. PI Batch Alias Table Attributes


Alias Unit name and attribute. The syntax for alias names in this table is: \\unitname\attribute.

Tag PI tag corresponding to the attribute.

NEWAlias Used to rename an existing alias.

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


Table 10–7. PI Batch Table Attributes


UnitName Unit name to search

Handle Unique identifier for a single batch entry

BID Batch ID

ProdID Product ID

StartTime Batch start time

StartStatus Status of batch start time

StopTime Batch end time




StopStatus Status of batch end time

BIDsearch Wild card search string for batch IDs

ProdIDsearch Wild card search string for product IDs

SearchStart Time to search from

SearchStop Time to search to

Count Maximum number of batches to retrieve

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

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

piconfig> @table 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 10–8. 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


Page 214

Attribute Description Operating System

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) piconfig> @ostr pisubsysname

(Ls - PISUBSYS) piconfig> @ostr osbuild, osversion

(Ls - PISUBSYS) piconfig> @ostr pistartuptime, piversion

(Ls - PISUBSYS) piconfig> @selec pisubsysname=*

(Ls - PISUBSYS) piconfig> @ends

pisnapss

Service Pack 6,4.0.1381

4-May-03 17:08:20,PI 3.3.361.43

The operating system attribute names may vary because they are operating system dependent.

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

piconfig> @table pisubsysstats,pisnapss

The table attributes are:

Table 10–9. PI Subsystem Statistics Table Attributes


PISubsysName Subsystem Name

BytesRecv Number of bytes received since startup.

BytesSent Number of bytes sent since startup.

MsgRecv Number of messages received since startup.

MsgSent Number of messages sent since startup.

RecvErrors Number of receive errors since startup.

SendErrors Number of send errors since startup.

StartTime 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) piconfig> @ostr PIsubsysname

(Ls - PISUBSYSSTATS) piconfig> @ostr bytesrecv, bytessent

(Ls - PISUBSYSSTATS) piconfig> @ostr msgrecv, msgsent

(Ls - PISUBSYSSTATS) piconfig> @ostr recverrors, senderrors

(Ls - PISUBSYSSTATS) piconfig> @ostr starttime

(Ls - PISUBSYSSTATS) piconfig> @select pisubsysname=*

(Ls - PISUBSYSSTATS) piconfig> @ends

pisnapss

99626,57637

434,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 the @?atr command.

10.4.13 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 10–10. PINet Manager Statistics Table Attributes


ID Connection ID. This is the primary key.

BytesRecv Bytes received by the connection.

BytesSent Bytes sent by the connection.

ConStatus Connection status.

ConTime Time connection was established.

ConType 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)

MsgSent Messages sent by connection.


Page 216


Name Connection name.

NetType Connection network type WIN32 named pipes, UNIX, or TCP/IP

OSBuild Operating system build.

OSSysName Operating system name.

OSVersion Operating system version.

PeerAddress IP Address of connecting machine.

PeerName Host name of connecting machine.

PIVersion Version of PI Network Manager.

PIPath PI Server root directory on the server. This item is the same for all connections.

ProtocolVersion PI Protocol version of connecting application.

RecvErrors Number of receive errors on the connection.

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

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) piconfig> @ostr ID, BytesRecv, BytesSent, ConStatus

* (Ls - PINETMGRSTATS) piconfig> @ostr contime, contype, msgsent, name

* (Ls - PINETMGRSTATS) piconfig> @ostr nettype, peeraddress, peername

* (Ls - PINETMGRSTATS) piconfig> @ostr protocolversion,recverrors,senderrors

* (Ls - PINETMGRSTATS) piconfig> @selec id=*

* (Ls - PINETMGRSTATS) piconfig> @ends

6,24,132447,[0] Success

4-Sep-02 17:08:05,Local connection,759,pimsgss

WIN32 Named pipe,,

3.1,0,0

*----------

7,24,108008716,[0] Success

4-Sep-02 17:08:12,Local connection,1794287,piupdmgr

WIN32 Named pipe,,

3.1,0,0



*----------

8,24,3710706,[0] Success

4-Sep-02 17:08:19,Local connection,64851,pisnapss

WIN32 Named pipe,,

3.1,0,0

*----------

9,24,1974873,[0] Success

4-Sep-02 17:08:27,Local connection,24266,piarchss

WIN32 Named pipe,,

3.1,0,0

*----------

10,24,102724,[0] Success

4-Sep-02 17:08:34,Local connection,1072,pibasess

WIN32 Named pipe,,

3.1,0,0

*----------

16,24,372707,[0] Success

4-Sep-02 17:09:13,Local connection,2059,PIPESCHD

WIN32 Named pipe,,

3.1,0,0

*----------

12,24,60055,[0] Success

4-Sep-02 17:08:49,Local connection,672,pisqlss

WIN32 Named pipe,,

3.1,0,0

*----------

13,24,9420677,[0] Success

4-Sep-02 17:08:57,Local connection,198466,pitotal

WIN32 Named pipe,,

3.1,0,0

*----------

14,24,154881,[0] Success

4-Sep-02 17:09:04,Local connection,2828,pibatch

WIN32 Named pipe,,

3.1,0,0

*----------

15,20,12987712,[0] Success

4-Sep-02 17:09:12,Local connection,1618340,PipeE

WIN32 Named pipe,127.0.0.1,localhost

1.8,0,0

*----------

20,20,33340,[0] Success

4-Sep-02 17:43:44,Local connection,2715,RmpSE


1.8,0,0

*----------


Page 218

21,20,50446,[0] Success

4-Sep-02 17:43:45,Local connection,3349,RandE


1.8,0,0

*----------

23,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, ,

*----------

10.4.14 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 10–11. PI Users Table Attributes


User User name

Description User description

Groups List of groups to which the user belongs

Context Reserved for future use

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

10.4.15 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 10–12. PI Group Table Attributes


Group Group name

Description User description

Users List of users belonging to the group

NEWGroup Used to rename an existing group

10.4.16 PI Thread Table

Table 10–13. PI Thread Table Attributes


ID Operating system thread ID

Action Edit only – see table below

ActValue Edit only – value for the action performed

Calls Number of calls served by the thread

Handle Subsystem handle

PoolName Every thread belongs to a thread-pool. We are mainly interested in the RPC thread pool, which serves client calls to a subsystem.

Priority The thread priority

State The thread state – generally “Wait” or “InUse”

Table 10–14. PI Thread Table Actions

Action Description Action Value

Priority Change thread priority 1 to increase -1 to decrease

Suspend Temporary suspensions of thread execution

Resume Resume a thread previously suspended

Terminate End this thread

* (Ls - ) PIconfig> @table pithread,piarchss

* (Ls - PITHREAD) PIconfig> @ostru id,calls,handle,poolname,priority,state

* (Ls - PITHREAD) PIconfig> @ends

1500,7,212,RPC,0,Wait

1596,9,216,RPC,0,Wait

1504,11,220,RPC,0,Wait

1116,18,224,RPC,0,InUse


Page 220

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.

10.4.17 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 10–15. PI Database Security Table Attributes


DBName Database name

Access Security attribute, which specifies access to the table

Group Group name

Owner 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) PIconfig> @ostru dbname, owner,group,access

* (Ls - DBSECURITY) PIconfig> @ends


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) PIconfig> @mode ed,t

* (Ed - DBSECURITY) PIconfig> @istru 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) PIconfig> @mode list

* (Ls - DBSECURITY) PIconfig> @ends


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

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.

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


Page 222

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

@table PITRUST

The primary key is TRUST. The table attributes are:

Table 10–16. Trust Table Attributes


Trust A name for this trust relationship

Domain The domain name for the client machine

IPAddr IP address of client machine

NetMask Network address mask in the format (255.255.255.255)

IPHost Name of client machine

OSUser User name under which the client is running

AppName Application name

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

10.4.19 PI General Table Interface piconfig has a General Table interface, which includes the Timeout, Firewall, and Trust databases. Select the table using the command:

@table 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.


@table PI_GEN, pitimeout

The primary key is NAME. The table attributes are:

Table 10–17. PI Timeout Table Attributes


Name Timing attribute name

Value Timing value as a string

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


@table PI_GEN, pifirewall

The primary key is HOSTMASK. The table attributes are:

Table 10–18. PI Firewall Table Attributes


HostMask The name or IP address of a client computer

Value ALLOW or DISALLOW

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


Page 224

10.5 Helpful Hints

10.5.1 Abbreviations All piconfig commands can be abbreviated to four characters.

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

10.5.3 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 be useful:

@command @command_file

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.

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

@line 4000

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

10.5 - Helpful Hints


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\""

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:

@quote "

or

@quote '


Page 226

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

10.5.7 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: “S-true S-false”.

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

10.5 - Helpful Hints


10.5.9 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

10.5.10 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> @comment !

*piconfig> ! Now we have a new comment character.

*piconfig> !Change back to the original comment character.

*piconfig> @comment *

*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

---- piconfig Status ----

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: <127.0.0.1,piadmin>


Page 228

10.5.11 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

*123456789012345678901234567890

Tag1 0 100

tag2 -5 555

e:\PI\adm>piconfig mode convert

* (Cv - ) piconfig> @isty fixed

* (Cv - ) piconfig> @osty delim

* (Cv - ) piconfig> @istru tag,1,1,10

* (Cv - ) piconfig> @istru zero,1,10,5

* (Cv - ) piconfig> @istru span,1,20,5

* (Cv - ) piconfig> @ostru zero,span,tag

* (Cv - ) piconfig> @echo none

* (Cv - ) piconfig> @input fixed.dat

0 , 200,Tag1

-5 , 655,tag2

10.5.12 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 Rockwell Automation support Web site for more information.

10.5.13 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 Rockwell Automation support Web site for more information.


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

The second step is to isolate the problem further to a particular client program or PI subsystem. See Verifying PI Processes on page 232, and PI System Data Files on page 240, 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 Rockwell Automation 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.

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

Chapter 11 - PI Troubleshooting and Repair

Page 230

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 289. If a trend in FactoryTalk Historian ProcessBook “flatlines,” see the section on p. 260.

4. 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 289.

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

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

11.1 - 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. Rockwell Automation 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 5450. 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.


Page 232

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 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 289. 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 Rockwell Automation Technical Support Web site, http://support.rockwellautomation.com, which has technical notes posted.

If you haven’t solved the problem after working through this checklist, you will need to phone or email Rockwell Automation Technical Support.

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

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

11.2.2 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

11.2 - Verifying PI Processes


11.2.3 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 5450. 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 Rockwell Automation Technical Support if you are affected by this problem.

11.2.4 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


Page 234

Random.log

Rmp_Sk.log

Pipeschd.log

Pibatch.log

Pishutev.log

PIsqlss.log

Pitotal.log

Pialarm.log

11.2.5 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

11.2.6 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


Attempting connection to localhost:5450

Error -994, connecting to localhost:5450

$ piconfig


*PIConfig Err> Table initialization error (PIPOINT

*@table pipoint

*[-10733] PINET: RPC Resolver is Off-Line

11.2 - Verifying PI Processes


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

$ piartool -ss

Getsnaptablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line

$ pisnap.sh



Enter tagname: sinusoid

Error: pisn_getsnapshotsx 3745992

Error: piar_getarcvaluex 3745992

Error: piar_getarcvaluesx 100

Tag = SINUSOID Point Number = 1 Type = Real-32

13 Hour Sine Wave!

Snapshot value

Value = ERROR ERROR

Status = ERROR

Latest archive value

Value = ERROR ERROR

Status = ERROR

11.2.8 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



Enter tagname: sinusoid

Error: piar_getarcvaluex 0

Error: piar_getarcvaluesx 100

Tag = SINUSOID Point Number = 1 Type = Real-32

13 Hour Sine Wave!

Snapshot value

Value = ERROR ERROR

Status = ERROR


Page 236

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.

11.2.9 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 completion; therefore, this process will not be present on systems that have been running for a while.

11.2.10 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 Rockwell Automation Web site for current interface documentation.

11.2.11 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 Rockwell Automation Web site for current interface documentation.

11.2.12 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

11.3 - UNIX Process Quotas


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.

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

12578 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 -2 777

$ ../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


Page 238

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.

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.

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

11.3.2 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

11.3 - UNIX Process Quotas


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.

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

11.3.4 Sun Solaris Run the sysdef utility. It will give a long list of current parameters. Somewhere in the middle is:

*

* Tunable Parameters

*

1298432 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


Page 240

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

11.4 PI Server Data Files

The PI Server data files are located in the PI\dat directory. Archives are likely to be elsewhere.

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.

11.4 - PI Server Data Files


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.

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.


Page 242

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.

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.

11.5 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

11.5 - Identifying the Update Manager Issues: the pilistupd utility


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


Page 244

e:\pi\adm>pilistupd -p ptupdates


ptupdates Pibatch|1 0 0 0

ptupdates Pitotal|2 0 0 0

ptupdates PipeE|14|3 0 0 0

ptupdates RandE|16|4 0 0 0

ptupdates RmpSE|17|5 0 0 0

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 FactoryTalk Historian ProcessBook Display Open The next table was generated by running pilistupd with an open FactoryTalk Historian ProcessBook display, trending 5 points.

e:\pi\adm>pilistupd


ptupdates Pibatch|1 0 0 0

ptupdates Pitotal|2 0 0 0

ptupdates PipeE|14|3 0 0 0

ptupdates RandE|16|4 0 0 0

Ptupdates RmpSE|17|5 0 0 0

snapshots PiadE|33|9 1 0 1





The last 5 lines of results are all the same display—consumer piadE|33|9. 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

11.6 - Repairs


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.

e:\pi\adm>pilistupd -p snapshots -m 1 -r 100

No Matching entries

No Matching entries


--------- --------- ------ ------ --------

snapshots piadE|15|5 4 0 1





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.

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

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


Page 246

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

...First pass...

...Sorting input archive...

...Output pass...



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)

11.6 - Repairs


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 3.3.361.43, 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

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



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.

11.6.2 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 4.

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


Page 248

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

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 3.4.370 or greater, then skip this step because the snapshot is backed up as of 3.4.370 and there is no need to rename the piarcmem.dat file. Otherwise, if the backup was performed with a version of PI prior to 3.4.370, rename the PI\dat\piarcmem.dat to PI\dat\piarcmem.dat.old.

14. If the backup was performed using PI Version 3.4.370 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 (FactoryTalk Historian ProcessBook and FactoryTalk Historian 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

11.6 - Repairs


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.

11.6.3 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 58.

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

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.

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

11.6.5 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>]


Page 250

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.

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 2000000000 is well into the 21st century. The offset is a positive 3600--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

2000000000,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 -3600. 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,-3600

01-Jan-30 00:00:00,-3600

Example 3 applies a missed daylight savings time conversion for the Northern Hemisphere summer of 1997. 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.

11.6 - Repairs


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 1997

01-Jan-97 00:00:00,0

06-Apr-97 02:00:00,3600

26-Oct-97 02:00:00,0

31-Dec-97 23:59:59,0

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

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 Dumps the current piarstat.dat file. This is used to review the data in the file.

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

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

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


Page 252

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. 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 Rockwell Automation 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

11.6 - Repairs


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) piconfig> @sele tag=*,time>"*+10m"

* (Ls - PISNAP) piconfig> @ostru tag,value,time

* (Ls - PISNAP) piconfig> @sigd 8

* (Ls - PISNAP) piconfig> @output deletesnap.dat

@endsection

@output

* (Ls - PISNAP) piconfig> @table piarc

* (Ls - PIARC) piconfig> @mode ed,t

* (Ed - PIARC) piconfig> @modify mode=remove

* (Ed - PIARC) piconfig> @istru tag,value,time

* (Ed - PIARC) piconfig> @echo v

* (Ed - PIARC) piconfig> @input 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.

The “@sigd 8” command ensures that rounding errors do not cause events to not be found.

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


Page 254

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:

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.

11.7 - Tuning the PI Server


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

11.6.10 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

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.

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

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


Page 256

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.

-10731 PINET: Incomplete Message.

-10732 PINET: Corrupted Message.

-10745 PINET: Message verification failure.

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 By: @(#)piinstall.cxx 1.47 1.47 10/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 By: @(#)piinstall.cxx 1.47 1.47 10/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 5451. The port number can be any unused port greater than 1024; it cannot be the default listener port of 5450. 5451 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.

11.7 - Tuning the PI Server


Note: This technique if only used for advanced troubleshooting. This should only be done under the advice of Rockwell Automation Technical Support.

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

piconfig> @table pi_gen, pitimeout

piconfig> @mode edit

piconfig> @istructure name, value

piconfig> piartool, 100

piconfig> piconfig,1000

piconfig> pigetmsg,1000

piconfig> pilistupd,1000

piconfig> @endsection

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 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 Rockwell Automation Technical Support.

To increase the time-outs:


piconfig> @mode edit


piconfig> readtimeout,62500

piconfig> writetimeout,62500

piconfig> readretry,350

piconfig> writeretry,350

piconfig> @endsection

Note: PI Server installation sets all timeout values to well-tested initial values. Changes to these values should be done under the advice of Rockwell Automation 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.


Page 258

11.7.3 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 173 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

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

CDT158 100 - 3

CDM158 110 - 4

The following gets the number of event-retrieval calls, arranged by user.

d:\pi\adm>piartool -aag user access

Name Count ID

pidemo 3320 2

11.8 - Solving Other Problems


11.8 Solving Other Problems

11.8.1 Failed Backups For tips on troubleshooting backups, see Troubleshooting Backups in the chapter Backing up the PI Server.

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

Here is an example piconfig session which disables Reverse Name Lookup.


piconfig> @mode create,t


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.

11.8.3 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


Page 260

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.

11.8.4 Flatline in a FactoryTalk Historian ProcessBook Trend If a FactoryTalk Historian ProcessBook trend “flatlines,” you may have a problem with FactoryTalk Historian 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 4.

2. 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 4.

3. If no tags are producing trends, run pilistupd on the PI Server to see if the flatline is due to the FactoryTalk Historian 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 FactoryTalk Historian ProcessBook. If data is not arriving from the data source, the pending number remains at zero. If the client FactoryTalk Historian 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 Rockwell Automation Technical Support for additional assistance. If the pending updates remain zero, go to step 4.

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

9. If the trend for sinusoid does not appear correctly, go to step 5.

10. Verify that the archive program is working (piartool -as, piartool -al)

11.9 - COM Connectors


11. Try inserting data into a test point (using piconfig or FactoryTalk Historian DataLink) and try trending this point. If this is successful, go to step 6. If not, contact Rockwell Automation 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 7.

16. 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 FactoryTalk Historian 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. FactoryTalk Historian ProcessBook must have read access to all these points.

If none of the above steps have resolved the problem, contact Rockwell Automation Technical Support for additional assistance.

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 -11200 to -11209, 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 Rockwell Automation Technical Support COM Connector page, available at http://support.rockwellautomation.com.


Page 262

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

Figure 11-1. 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:

piconfig

@table pipoint,classicctr

@mode list

@ostructure tag, ctr_progid, ctr_strmap, ctr_lmap

@select ptclassname=classicctr

@ends

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 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 11-2. Windows Task Manager Processes


Page 264

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

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 11-3. Application Log Properties.



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

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 Rockwell Automation Technical Support Web site at http://support.rockwellautomation.com.

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.


Page 266

11.9.2 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 11-4. COM Connector Loading shows the result of the Redirector loading a simulator COM Connector.

Figure 11-4. COM Connector Loading

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 http://www.sysinternals.com.

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.


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 Rockwell Automation 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 Description

-ad Dump archive manager data file.

-adg <version> 'path' Downgrade archive file(s) to a specific version

-ahd 'path' Dump the archive file header.

-ar Recover archive manager data file.

-ara Auto recover archive manager data file. Described in this chapter.

-archk 'path' [complete] Archive integrity check utility.

-cid [ < ServerID > < APIServerID> ] | [-install] | [-upgrade]

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.

-crash Simulate a process crash.

-dapi [hostname] Create and display PI API Server ID based on supplied host name. Machine host name is used if host name is not supplied.

-did Dump Server ID file.

-e code Translate error code.

Chapter 12 - Finding and Fixing Problems: the pidiag Utility

Page 270

Option Description

-fb 'path' Dump file base data file.

-fbc 'path' Compact a file base data file.

-fbf 'path' <’outpath’> Recover (fix) file base data file index, optionally copying into a new file.

-gpc 'name' Gets performance counter path.

-host Display host information as used for Trust-Login.

-machine Machine and compile information.

-n number Format and display number as various types.

-qd [HeaderOnly| RecNo=n |PointId=<id>] 'path'

Dump header or all/filtered events from Event Queue file.

-qs 'path' Get offline queue file statistics.

-rgs [-?] [-u] 'path' {ReplaceableParameter="Value"}

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 ]

Show timezone information.

-tz [ -if path | -ifrule [path] ] [-of path]

Special DST settings.

-udf 'path' Resets the piadmin (userid #1) password to blank.

-upc 'name' Uninstalls performance counters for named subsystem.

-uuid [count] 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.

12.1 - 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 Rockwell Automation 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

12.1.1 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 3.4.363.24

Program: pidiag

PI Path: D:\PI

12.1.2 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


C:\PI\adm>pidiag -e -11002

[-11002] Record Header Data Mismatch

12.2 Time Utilities

12.2.1 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).


Page 272

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.

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: 904608000 UTC: 904633200

C:\PI\adm>pidiag -t t+1h

21-Oct-02 01:00:00 PDT - Local: 908931600 UTC: 908956800

C:\PI\adm>pidiag -t "*"

21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210

Integer Format to String C:\PI\adm>pidiag -t 0909000010

21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210

C:\PI\adm>pidiag -t 0909025210 U

21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210

12.2.2 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, -3600

1970, 2038, 10, 5, 1, 7200, 0

The transitions rules are defined as follows.

StartYear is the first year that the rule is in effect

12.2 - Time Utilities


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.

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, -3600 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"


Standard Time Name: Pacific Standard Time (PST)

Daylight Time Name: Pacific Daylight Time (PDT)


1970, 2038, 4, 1, 1, 7200, -3600

1970, 2038, 10, 5, 1, 7200, 0

Passed Time: 25-Oct-02 01:30:00 PDT Local: 1035509400 UTC: 1035534600

If your time zone does not observe daylight savings time, the utility will indicate this.

C:\PI\adm> pidiag -tz


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.


Page 274

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 year-specific rules, but there are still issues for time zones in which the change rule is different from year to year.

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)

12.3 - File-base Utilities



1970, 2037, 4, 1, 1, 7200, -3600

1970, 2037, 10, 5, 1, 7200, 0

Passed Time: 8-Oct-03 20:27:04 BST Local: 1065644824 UTC: 1065641224

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

12.3 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!

12.3.1 Dump File-base Data File pidiag -fb <path>

This lists the inner structure of a file-base index.

Rockwell Automation 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 1.27 09/30/96]::

User ID: 1 Group ID: 1 Access: [113] [o:rw g:rw:r]

Index Dump:

Record, Offset, Size: 0, 2994, 1266


Page 276




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

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

12.4 Archive Management

The commands in this section assist with archive file management.

12.4.1 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 4.

1. C:\PI\dat\piarch.001



Alphabetical index:

12.4 - Archive Management


C:\PI\dat\piarch.001



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.

12.4.2 Automatic Recovery of the Archive Manager Data File The command:

pidiag -ara

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.

12.4.3 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 3.4.370 to earlier versions of the PI Archive.

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

pidiag -ahd <path>


Page 278

for example:

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


Version: 6 Path: e:\pi\dat\piarch.001




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

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.

12.4.5 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.001

-----------------------------------------------------------------------

recno: 1 id: 1 indices: 1 records: 5 events: 636 fr: 89.4%














12.4 - Archive Management







----------------------------------------------------------------------

0 errors detected

23 total index records

2399 total data records

593701 total events

247.5 events per record

10800 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%.

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

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

-------------------------------------------------------------------------------


Page 280









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: 130516, start: 19-Oct-05 12:39:10, events: 142, fr: 99.4%

1: record id: 130811, start: 30-Oct-05 15:33:27, events: 142, fr: 99.7%

2: record id: 130515, start: 12-Nov-05 09:29:36, events: 142, fr: 99.9%

3: record id: 130210, start: 22-Nov-05 04:44:08, events: 142, fr: 99.9%

4: record id: 128814, start: 15-Dec-05 13:31:42, events: 68, fr: 47.9%

[...]

12.4.6 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

3.3 5

3.4.363/364 6

3.4.370 7

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 3.4.370 to 3.4.364:

D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005


Path: D:\PI\dat\piarch.005




12.5 - Server ID Utilities




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.005... [0] Success

D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005


Path: D:\PI\dat\piarch.005






End Time: 1-Jan-05 00:00:00

Backup Time: Never

End of Dump

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.


Page 282

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

4. MinorBuild: 98

5. ServerID: 1eb5cdbe-0666-43a5-900d-235344ee43ea

6. APIServerID: 91049

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

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)

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

12.6 - Performance Counter Utilities (Windows Only)


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.

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

12.6.3 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 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 OS-provided 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.


Page 284

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

Connector Point Count: 0

Point Create or Edit/sec: 0

Digital State Translations/sec: 165

Wild Card Searches/sec: 200

Point Accesses/sec: 200710

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

12.7 Miscellaneous

12.7.1 Wait for Passed Milliseconds The command to wait for passed milliseconds is:

pidiag -w msec

This is used in several PI command procedures.

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

12.7 - Miscellaneous


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.

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

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

d:\pi\adm>pidiag -host

Domain <OSI>

Machine <bilbo>

User <Bagins>

IP Addr <205.171.76.181>

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.

12.7.5 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


Page 286

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.

12.7.6 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}'

'TypeLib' = s '{8FC8B7AF-0C07-11D4-84C4-00C04F6102DF}'

}

}

}

pidiag -rgs MYOBJECT.RGS MODULE=

"c:\Program Files\MyProgram\myobject.exe"

12.7.7 GUID Generation The -uuid options of pidiag can be used to generate globally unique identifiers, known as GUIDs.

pidiag -uuid

43157bae-8156-403e-b0f6-a3c1581fe86a

12.7.8 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

12.7 - Miscellaneous


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.


int64s are 8 bytes.


float32s are 4 bytes.

float64s are 8 bytes.


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: 0.195313, 1984MB, Previous

settings: 0.195313, 1.34766MB

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


settings: 0.195313, 1.34766MB

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 3.4.370.52

0 pilicmgr 27-Oct-05 16:23:17


settings: 0.195313, 1.34766MB

0 pilicmgr 27-Oct-05 16:23:17

>> Rpcservertablelist successfully registered to pinetmgr.

0 pinetmgr 27-Oct-05 16:23:20


0 pinetmgr 27-Oct-05 16:23:23


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


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 3.4.370.52

0 piupdmgr 27-Oct-05 16:23:27


settings: 0.195313, 1.34766MB

0 piupdmgr 27-Oct-05 16:23:27


0 pinetmgr 27-Oct-05 16:23:29

>> Connection accepted: Process name: pibasess(2732) ID: 7

0 pinetmgr 27-Oct-05 16:23:29


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 3.4.370.52

0 pibasess 27-Oct-05 16:23:31


settings: 0.195313, 1.34766MB

0 pibasess 27-Oct-05 16:23:31


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


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

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

0 pisnapss 27-Oct-05 16:23:35


settings: 0.195313, 1.34766MB

0 pisnapss 27-Oct-05 16:23:35

>> Digital State table synchronized with Base Subsystem

0 pisnapss 27-Oct-05 16:23:35


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






0 pinetmgr 27-Oct-05 16:23:36

>> Connection accepted: Process name: piarchss(356) ID: 11

0 pinetmgr 27-Oct-05 16:23:36


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

0 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 3.4.370.52

0 piarchss 27-Oct-05 16:23:38


settings: 0.195313, 1.34766MB

0 piarchss 27-Oct-05 16:23:38

>> Digital State table synchronized with Base Subsystem

0 piarchss 27-Oct-05 16:23:38


0 pinetmgr 27-Oct-05 16:23:39


0 pinetmgr 27-Oct-05 16:23:42


0 pinetmgr 27-Oct-05 16:23:44


0 pinetmgr 27-Oct-05 16:23:47


piartool(2728) (8), ID: 10


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






0 pinetmgr 27-Oct-05 16:23:47






0 pinetmgr 27-Oct-05 16:23:47






0 pinetmgr 27-Oct-05 16:23:47


>> WorkingSet Parameters: 0.195313MB, 1984MB.

0 pinetmgr 27-Oct-05 16:23:47


0 pinetmgr 27-Oct-05 16:23:50


0 pinetmgr 27-Oct-05 16:23:53


0 pinetmgr 27-Oct-05 16:23:56


0 pinetmgr 27-Oct-05 16:23:58


piartool(1984) (8), ID: 15




0 pinetmgr 27-Oct-05 16:23:58


piartool(3920) (8), ID: 14




0 pinetmgr 27-Oct-05 16:23:58


piartool(3544) (8), ID: 13




0 pinetmgr 27-Oct-05 16:23:58


piartool(2720) (8), ID: 12




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 3.4.370.52

0 pishutev 27-Oct-05 16:24:00


settings: 0.195313, 1.34766MB

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


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


0 pisqlss 27-Oct-05 16:24:06

>> PI subsystem pisqlss is now running, version: PI 3.4.370.52

0 pisqlss 27-Oct-05 16:24:06


settings: 0.195313, 1.34766MB

0 pisqlss 27-Oct-05 16:24:06


0 pinetmgr 27-Oct-05 16:24:08

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


piartool(2184) (8), ID: 19




0 pinetmgr 27-Oct-05 16:24:09


piartool(3684) (8), ID: 18




0 pinetmgr 27-Oct-05 16:24:09


piartool(3052) (8), ID: 17




0 pinetmgr 27-Oct-05 16:24:09


piartool(3724) (8), ID: 16





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


0 pibackup 27-Oct-05 16:24:11

>> PI subsystem pibackup is now running, version: PI 3.4.370.52

0 pibackup 27-Oct-05 16:24:11


settings: 0.195313, 1.34766MB

0 pibackup 27-Oct-05 16:24:11


0 pinetmgr 27-Oct-05 16:24:12

>> TCP/IP (IPV4) connection listener opened on port: 5450

0 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


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.

0 pinetmgr 27-Oct-05 16:24:20


piartool(2748) (8), ID: 23



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


piartool(3780) (8), ID: 21




0 pinetmgr 27-Oct-05 16:24:20


0 pialarm 27-Oct-05 16:24:21

>> PI subsystem pialarm is now running, version: PI 3.4.370.52

0 pialarm 27-Oct-05 16:24:21


settings: 0.195313, 1.34766MB

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


0 pinetmgr 27-Oct-05 16:24:23

>> PInet accepted TCP/IP connection, cnxn ID 30 Hostname: samson.osisoft.com,

127.0.0.1:1104

0 pinetmgr 27-Oct-05 16:24:23

>> New Pinet 1 connection: PipeE Protocol: 00010008

0 pinetmgr 27-Oct-05 16:24:23

>> New Pinet 1 connection: PipeE Successful Trust-Relation login:

samson.osisoft.com|127.0.0.1|PipeE piadmin.

0 pinetmgr 27-Oct-05 16:24:23

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


0 pitotal 27-Oct-05 16:24:26

>> PI subsystem pitotal is now running, version: PI 3.4.370.52

0 pitotal 27-Oct-05 16:24:26


settings: 0.195313, 1.34766MB

0 pitotal 27-Oct-05 16:24:26


0 pitotal 27-Oct-05 16:24:26



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


0 pinetmgr 27-Oct-05 16:24:27

>> Successful login ID: 30. Address: 127.0.0.1. 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


0 pibatch 27-Oct-05 16:24:31

>> PI subsystem pibatch is now running, version: PI 3.4.370.52

0 pibatch 27-Oct-05 16:24:31


settings: 0.195313, 1.34766MB

0 pibatch 27-Oct-05 16:24:31

>> Starting pibatch

0 pibatch 27-Oct-05 16:24:31


0 pibatch 27-Oct-05 16:24:31


0 pibatch 27-Oct-05 16:24:31

>> Batch databases loaded

0 pibatch 27-Oct-05 16:24:31


0 pibackup 27-Oct-05 16:24:31

>> Successfully registered subsystem pibatch, version 3.4.370.52

0 pinetmgr 27-Oct-05 16:24:32


piartool(1152) (8), ID: 27




0 pinetmgr 27-Oct-05 16:24:32


piartool(3256) (8), ID: 25




0 pinetmgr 27-Oct-05 16:24:38


0 pinetmgr 27-Oct-05 16:24:40


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


piartool(2504) (8), ID: 34




0 pinetmgr 27-Oct-05 16:24:44


piartool(2592) (8), ID: 29




0 pinetmgr 27-Oct-05 16:24:44


piartool(2628) (8), ID: 32




0 pinetmgr 27-Oct-05 16:24:52


127.0.0.1:1105

0 pinetmgr 27-Oct-05 16:24:52

>> New Pinet 1 connection: RmpSE Protocol: 00010008

0 pinetmgr 27-Oct-05 16:24:52

>> New Pinet 1 connection: RmpSE Successful Trust-Relation login:

samson.osisoft.com|127.0.0.1|RmpSE piadmin.

0 pinetmgr 27-Oct-05 16:24:52


127.0.0.1:1106

0 pinetmgr 27-Oct-05 16:24:52

>> New Pinet 1 connection: RandE Protocol: 00010008

0 pinetmgr 27-Oct-05 16:24:52

>> New Pinet 1 connection: RandE Successful Trust-Relation login:

samson.osisoft.com|127.0.0.1|RandE piadmin.

0 pinetmgr 27-Oct-05 16:24:55



piartool(1240) (8), ID: 36




0 pinetmgr 27-Oct-05 16:24:55


piartool(3348) (8), ID: 35




0 pinetmgr 27-Oct-05 16:24:57


Name: RmpSE. User: piadmin. Trust: !Proxy_127!

0 pinetmgr 27-Oct-05 16:24:57


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 3.4.370.52

0 pibackup 27-Oct-05 16:25:08

>> Successfully registered subsystem piarchss, version 3.4.370.52

0 pibackup 27-Oct-05 16:25:08

>> Successfully registered subsystem pimsgss, version 3.4.370.52

0 pibackup 27-Oct-05 16:25:09

>> Successfully registered subsystem pilicmgr, version 3.4.370.52

0 pibackup 27-Oct-05 16:25:09

>> Successfully registered subsystem pibasess, version 3.4.370.52

0 pinetmgr 27-Oct-05 16:25:19

>> Deleting connection: pishutev(2540), Shutdown request received from

pishutev(2540) (8), ID: 20



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

>> PInet accepted TCP/IP connection, cnxn ID 44 Hostname: samson.osisoft.int,

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

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|127.0.0.1|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|24.20.166.163|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,

192.1.1.114:4508

0 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|192.1.1.114|AboutPI

SDK.exe

(108 ms)

0 pinetmgr 27-Oct-05 19:04:46

>> Successful login ID: 49. Address: 192.1.1.114. 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

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

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


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

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


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


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:

pidiag -e 2


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

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





-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

-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

-79 PI_EVM_BADTIMEOUT Bad timeout value

Table 12–2. Error Codes 100-199, With Messages


-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



-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

-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



-501 PI_SQC_BADCHARTTYPE Sqc: illegal chart type

-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



-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



-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




-1000 PI_NET2_BADGRID Grid not implemented

-1001 PI_NET2_NODEFHOST Default host not found

-1002 PI_NET2_NOBATSUBSYS No Batch Subsystem on PI2 server



-10000 PI_ERR_MALLOC Failed memory allocation

-10001 PI_ERR_NEW Failed new operation

-10002 PI_ERR_ACTIVATE Unable to Activate Object

-10003 PI_ERR_PASSIVATE Unable to Passivate Object

-10004 PI_ERR_IMPOSS Internal error (impossible)

-10005 PI_ERR_UNDERRANGE Subscript under range

-10006 PI_ERR_OVERRANGE Subscript over range

-10007 PI_ERR_BADPOINTER Bad or Null Pointer

-10008 PI_ERR_UNSUPPORTED Unsupported or Unimplemented Call

-10009 PI_SHUTDOWN PI system shutting down

-10010 PI_ERR_TIMEOUT PI system timed out

-10011 PI_ERR_ACCESSLOCK Target Object in Use or Locked

-10400 PI_XS_NOREAD No read access – secure object

-10401 PI_XS_NOWRITE No write access – secure object

-10402 PI_XS_BADSTRING Badly formed access string

-10403 PI_XS_BADUGVER Version Mismatch in Usergroup Activate

-10404 PI_XS_BADUSERVER Version Mismatch in User Activate

-10405 PI_XS_CTXIDINUSE User Context ID in Use

-10406 PI_XS_GROUPINUSE Group ID in Use

-10407 PI_XS_NOACCESS No access – secure object

-10408 PI_XS_BADUSERSTR Invalid security user/owner string

-10409 PI_XS_BADGRPSTR Invalid security group string


-10410 PI_XS_BADDBNAME Invalid security database name

-10411 PI_XS_MISMATCH security or trust relation mismatch

-10412 PI_XS_TRUSTUNSUP Trust relation not supported on server

-10413 PI_XS_NOTRUST No trust relation for this request

-10414 PI_XS_SIMILARTRUST Trust records must differ more than name and Piuser

-10415 PI_XS_IPANDMASK Must specify both IP address and Net Mask

-10416 PI_XS_NONULLTRUST Trust definition must include more than name and Piuser.

-10417 PI_XS_NOPIADMIN User must be piadmin for this operation

-10418 PI_XS_DBSECNOTINIT DB Security not initialized

-10419 PI_XS_NULLSECOBJ Unable to retrieve secure object

-10450 PI_FB_BADCREATEFILE Create new file failed

-10451 PI_FB_BADOPENFILE Open existing file failed

-10452 PI_FB_BADFILECLOSE Close file failed

-10453 PI_FB_BADFILEREMOVE Delete file failed

-10454 PI_FB_BADFILETRUNCATE Truncate file failed

-10455 PI_FB_INVALIDFILE Fstat Failed

-10456 PI_FB_BADFILELOCK Fcntl Failed to Get Lock

-10457 PI_FB_BADFILEUNLOCK Fcntl Failed to Free Lock

-10458 PI_FB_BADHEADER Illegal file header parameters

-10459 PI_FB_FILEOPEN File open

-10460 PI_FB_FILECLOSED File closed

-10461 PI_FB_BADFILEREAD Read from file failed

-10462 PI_FB_BADFILEWRITE Write to file failed

-10463 PI_FB_BADRECNOVALUE Recno Greater Than Directory Size

-10464 PI_FB_RECNOINUSE Recno In Use

-10466 PI_FB_RECNONOTFOUND No Record Available for Passed recno

-10467 PI_FB_BADRECLEN Reclen Greater Than Maximum Allowed Size



-10468 PI_FB_TIMETOGROWDIR Getting New recno, Directory is Full

-10469 PI_FB_BADBUFFERSIZE Passed Buffer Too Small to Hold Record

-10470 PI_FB_BADFILESEEK Lseek Failed

-10471 PI_FB_BADFILEHEADER Fatally corrupted file header

-10472 PI_FB_DIRTYHEADER Dirty header

-10473 PI_FB_INVUSERBLOCK Invalid user block size

-10474 PI_FB_BADVERSION Version mismatch

-10475 PI_FB_CNTMISMATCH Record count mismatch between header and index

-10476 PI_FB_LOWDISKSPACE low disk space, file size cannot be increased

-10477 PI_FB_PATHNOTDIRECTORY The path is valid, but the path is not a directory

-10478 PI_FB_NULLPATHSTRING Cannot extract file and path from null string

-10550 PI_PD_TAGEXISTS Tag Already Exists in Table

-10551 PI_PD_INVTAG Invalid Characters in Tag

-10552 PI_PD_BADCHAIN Broken Context Chain in Table

-10553 PI_PD_INVPTID Ptid is Not a Valid Point

-10554 PI_PD_CTXEXISTS Tag Already Exists for Context

-10555 PI_PD_NOTAG Tag Does Not Exist in Table

-10556 PI_PD_ENDSEARCH End of Table Reached

-10557 PI_PD_BADASVER Bad ptattributeset Version

-10558 PI_PD_BADPTCLVER Bad ptclass Version

-10559 PI_PD_BADPOINTVER Bad point version

-10560 PI_PD_POINTINUSE Point Already Has a ptclass

-10561 PI_PD_PTCLASSINUSE Point class already defined

-10562 PI_PD_CLASSESINUSE Ptclasses Already Defined

-10563 PI_PD_BADPTCLASSREV Point class revision mismatch

-10564 PI_PD_NOPTCLASS Point class not defined

-10565 PI_PD_NOMOREPTS No More Points in Search


-10566 PI_PD_VALIDFAIL Point validation failed

-10567 PI_PD_AMBIGUOUS Point ID does not match Tag or Tag rename to same name

-10568 PI_PD_NOMATCHINGPOINTS No points found in search

-10569 PI_PD_BADATTRIBUTE Point does not contain specified attribute

-10570 PI_PD_NOEDIT Attempt to edit or set internally set point attribute

-10571 PI_PD_INVALIDATT Attempt to create attribute set with invalid attribute name

-10572 PI_PD_INVALIDNAME Invalid name for point class or attribute set

-10573 PI_PD_NOBASEATT Base attribute set not included in point class definition

-10574 PI_PD_NODELBASEATT Attribute set delete not allowed.

-10575 PI_PD_ATTSETINUSE Attribute set is in use.

-10576 PI_PD_MISSINGREQATTRIBUTES Required attribute missing in the attribute set

-10577 PI_PD_BASEATTNAME Attribute name being used by base attribute set

-10578 PI_PD_BUILTINATTNAME Attribute name being used by built-in

-10579 PI_PD_BADPTTYPECHANGE Unsupported point type change

-10580 PI_PD_RESERVEDNAME Name reserved for internal use

-10581 PI_PD_INVALIDBASEATTNAME Invalid attribute name for base attribute set

-10582 PI_PD_NOATTSETRENAME Rename not allowed for this attribute set

-10583 PI_PD_CLASSINUSE Point class is in use

-10584 PI_PD_BADPTCLASSESREV PIptclasses revision mismatch

-10585 PI_PD_NOEDITBASECLASS Base point class edit/delete not allowed

-10586 PI_PD_INVALIDATTTYPE Unsupported attribute type

-10587 PI_PD_NOEDITBASEATT Base attribute set edit not allowed except for default change

-10588 PI_PD_MISSINGREQATTRIBUTESETS

Required attribute set missing in the point class

-10589 PI_PD_NODELSET Delete not allowed for this attribute set

-10590 PI_PD_NODELCLASS Delete not allowed for this point class



-10591 PI_PD_NOPTCLSRENAME Rename not allowed for this point class

-10592 PI_PD_ATRTYPECHANGEINPREDEFORINUSEATRSET

Attribute type change in this attribute set not allowed

-10593 PI_PD_ATTRIBDELINPREDEFORINUSEATTRIBSET

Attribute delete in this attribute set not allowed

-10594 PI_PD_ATTRIBSETDELINPREDEFORINUSEPTCLASS

Attribute set delete in this point class not allowed

-10595 PI_PD_STANDALONEMODEREQUIRED

This operation requires StandAlone mode

-10650 PI_UD_INVALIDGRPUSRNM Invalid Group or User Name

-10651 PI_UD_INVGRPSLFREF Invalid Group self reference

-10652 PI_UD_INVGRPLAYER Super Group cannot be member Super Group

-10700 PI_DS_NAMEEXISTS State Already Exists in Table

-10701 PI_DS_SETNOTFOUND Set not found

-10702 PI_DS_STATENOTFOUND State not found

-10703 PI_DS_ILLEGALSETDEFINITION Illegal set definition: no states defined

-10704 PI_DS_CANTDELETESYSSET Cannot delete system state-set

-10705 PI_DS_TOOMANYSETS Maximum number of Sets Exceeded

-10706 PI_DS_TOOMANYSTATES Maximum number of States Exceeded

-10707 PI_DS_SETMISMATCH Digital set number mismatch during type coercion

-10708 PI_DS_NEGATIVEOFFSET Negative state number in digital type coercion

-10721 PI_NET_ABORT PINet: client aborted connection

-10722 PI_NET_TIMEOUT PINet: Timeout on PI RPC or System Call

-10723 PI_NET_NOCONNECTION PINet: no connection

-10724 PI_NET_QUEOVERFLOW PINet: queue overflow

-10725 PI_NET_SYNCHRONOUS PINet: synchronous

-10726 PI_NET_ASYNCHRONOUS PINet: asynchronous

-10727 PI_NET_RPC_NONEXISTENT PINet: RPC is Non-Existent

-10728 PI_NET_SEND_ERROR PINet: send error

-10729 PI_NET_RECV_ERROR PINet: receive error


-10730 PI_NET_NO_MESSAGE PINet: no message

-10731 PI_NET_INCOMPLETE_MESSAGE PINet: incomplete message

-10732 PI_NET_CORRUPTED_MESSAGE PINet: corrupted message

-10733 PI_NET_RPCRESOLVEROFFLINE PINet: RPC Resolver is Off-Line

-10734 PI_NET_BROKENCONNECTION PINet: broken connection

-10735 PI_NET_TRANSACTIONLISTFULL PINet: session manager transaction list full

-10736 PI_NET_ILLEGALRPCID PINet: RPC Table ID or Entry ID set to illegal value of 0.

-10737 PI_NET_PENDING PINet: Asynchronous connection to pinetmgr is Pending

-10738 PI_NET_DISABLED PINet: connection disabled

-10739 PI_NET_INVALIDRPCSERVERTABLELIST

PINet: Invalid or Null RPC Server Table List

-10740 PI_NET_INVALIDHOST PINet: invalid host

-10741 PI_NET_RPCRESOLVERNOTAVAILABLE

PINet: RPC Resolver chooses to not service request

-10742 PI_NET_CONNECTIONLISTFULL PINet: Connection list full

-10743 PI_NET_RPCRESOLVERTMPOFFLINE

PINet: RPC Resolver temporarily Off-Line

-10744 PI_NET_TRANSLATORINUSE PINet: PI API client attempted two or more simultaneous calls.

-10745 PI_NET_MESSAGEVERIFICATIONFAILURE

PINet: Message verification failure.

-10746 PI_NET_MESSAGETOOLARGE PINet: Attempt to send or receive message larger than maximum allowable

-10747 PI_NET_TRANSLATORVERIFICATIONFAILURE

PINet: PIAPI translator verification failure.

-10748 PI_NET_NOROUTEENTRY PINet: No routing entry exists for RPC

-10749 PI_NET_NORPCCODE PINet: No RPC entry for table/function code

-10750 PI_NET_NORPCNAME PINet: No RPC entry for table/function name

-10751 PI_NET_NORPCCALLBACK PINet: No callback function for RPC entry

-10752 PI_NET_EXCESSIVEZEROBYTEREADS

PINet: Connection broken by peer



-10753 PI_NET_INVALIDSESSIONID PINET: Invalid session ID

-10754 PI_NET_RPCTABLEGENMISMATCH PINET: RPC Table Generation mismatch

-10755 PI_NET_COMPLETIONPORTERROR

PINET: Completion Port Error

-10756 PI_NEWERSERVERVERSIONREQUIRED

PINET: Newer server version required

-10757 PI_NOREMOTECONNECTION PINET: No remote connection

-10758 PI_NET_FAILEDREMOTECONNECTION

PINET: Failed remote connection

-10759 PI_NET_NO_BYTES recv() returned zero bytes

-10760 PI_NET_EXCESSIVEREADRETRIES Read retry limit exceeded.

-10761 PI_NET_FORCEDDISCONNECT Connection deleted by request of administrator

-10762 PI_NET_MAXCONNIDLETIME Maximum Connection Idle time reached: Connection Closed

-10763 PI_NET_INVALIDPINETMGRCONTROLMODE

Invalid PINetMgr Control Mode

-10764 PI_NET_NOTLOCALSESSION Access only allowed by local PI Server connection

-10765 PI_NET_USERCANCELEDCONNECTION

ser canceled session login

-10766 PI_NET_TRANSACTIONABORTED PINET: Transaction aborted by local session thread

-10767 PI_NET_CONCURMSGABOVELIMIT Client exceeded maximum concurrent queries in RPC thread pool



-11001 PI_AR_RCHDVMM Record header version mismatch.

-11002 PI_AR_RCHDDMM Record header data mismatch.

-11003 PI_AR_RCHDSMM Record header size mismatch.

-11004 PI_AR_RCHDBADPTRECID Record header bad (0) point record ID.

-11005 PI_AR_RCHDBADRECID Record header bad (0) record ID.

-11006 PI_AR_RCHDBADSIZE Record header bad set size byte count.


-11007 PI_AR_RCHDOVERWRITE Record header stream overwrite.

-11008 PI_AR_RCBADDATATYPE Attempted to Add Event With Invalid Data Type.

-11009 PI_AR_RCOBJTOOBIG Event Contents Are Too Big to Fit in Any Record.

-11010 PI_AR_NOTTYPEDIG Record not type=digital.

-11011 PI_AR_NOTTYPEFLOAT2 Record not type=float2 – zero/span do not apply.

-11012 PI_AR_INVRECCNT Invalid record count for creating archive.

-11013 PI_AR_INVRECSIZE Invalid record size for creating archive.

-11014 PI_AR_BADSTREAMATT Failed to Attach Archive File to Stream.

-11015 PI_AR_ARCFILEVMM Archive file version mismatch.

-11016 PI_AR_ARCFILERAB Archive File in Unrecognized State.

-11017 PI_AR_CRPTTIME Corrupt Time Values in Archive Header.

-11018 PI_AR_CRPTPTRS Corrupt Overflow or Primary Record Pointers.

-11019 PI_AR_ARCNOTMNTD Archive file not mounted.

-11020 PI_AR_INVPTCNT Point Count Out of Range.

-11021 PI_AR_CRPTCACHEREC Cache record corrupt.

-11022 PI_AR_PTRECIDBND Invalid Value for Requested ptrecid.

-11023 PI_AR_BOUNDS Archive record full.

-11024 PI_AR_BADCACHELOAD Cache->loadrecord Failed.

-11025 PI_AR_BADGETTARREC Arcmgr::gettargetrecord Failed.

-11026 PI_AR_BADOVERFLOW Arcfile::overflowrecord Failed.

-11027 PI_AR_BADARLOADREC Arcfile::loadrecord Failed.

-11028 PI_AR_DUPARCFAIL Requested to Load Archive File Already Loaded.

-11029 PI_AR_BADSETINDEX An Index Record Does Not Have an Index.

-11030 PI_AR_BADINDEXSRC Set Index Did Not Receive an Index Record.

-11031 PI_AR_EMPTYRECORD No Events in Record.

-11032 PI_AR_NOEVENTAFTER No Events After Passed Eventide.

-11033 PI_AR_NOEVENTBEFORE No Events Before Passed Eventid

-11034 PI_AR_BADPTRECID Invalid ptrecid Passed.



-11035 PI_AR_STOREOPEN Underlying Storage is Open.

-11036 PI_AR_BADARCRECORD Invalid archive record pointer passed.

-11037 PI_AR_BADARCFILE Invalid archive file pointer passed.

-11038 PI_AR_NOARCHIVEBEFORE No archive before passed archive.

-11039 PI_AR_NOARCHIVEAFTER No archive after passed archive.

-11040 PI_AR_NORECORDBEFORE No record before passed record.

-11041 PI_AR_NORECORDAFTER No record after passed record.

-11042 PI_AR_RECNOTINCACHE Target Record Not in Cache.

-11043 PI_AR_DATENOTONLINE No archive online for target time.

-11044 PI_AR_EVENTOUTOFORDER Attempting to Add an Event Before Last Event.

-11045 PI_AR_INDEXRECMISMATCH Add event index mismatch.

-11046 PI_AR_DATEINFUTURE Target Date in Future.

-11047 PI_AR_INVMAXCOUNT Invalid maximum count.

-11048 PI_AR_INVINTERVAL Invalid intervals for archive call.

-11049 PI_AR_INVTIMES Invalid times for archive call.

-11050 PI_AR_INVRECTYPE Invalid record type.

-11051 PI_AR_COUNTTOOSMALL Count not large enough for interval.

-11052 PI_AR_SNAPMISMATCH Count mismatch loading snapshot.

-11053 PI_AR_ARCHIVEFULL No More Available Records in This Archive.

-11054 PI_AR_INVALIDSTATE Invalid Archive State For Mounting or Dismounting.

-11055 PI_AR_INVSTIME Invalid start time.

-11056 PI_AR_INVETIME Invalid end time.

-11057 PI_AR_NOTENOUGHVALS Not enough good values for calculation.

-11058 PI_AR_INVSUMMARYCODE Invalid code for summary function.

-11059 PI_AR_NOGOODDATA No good data for this time.

-11060 PI_AR_CALCFAILED Calculation Failed (e.g. Division by Zero).

-11061 PI_AR_INVMODEADD Invalid mode for archive add event.

-11062 PI_AR_INVMODEEDIT Invalid mode for archive edit event.


-11063 PI_AR_INVMODEDEL Invalid mode for archive delete event.

-11064 PI_AR_RCHDRMM Mismatch in record header record ID.

-11065 PI_AR_RCHDPMM Mismatch in record header chain pointer.

-11066 PI_AR_EMPTYDRECORD Empty data archive record.

-11067 PI_AR_EMPTYIRECORD Empty index archive record.

-11068 PI_AR_BADPRIMARY Failed to get primary archive.

-11069 PI_AR_CREATEFLAG Archive creation flag already set.

-11070 PI_AR_NOARCHMOUNT No archives mounted.

-11071 PI_AR_NOSHIFTARC No archive qualified for shift.

-11072 PI_AR_REMNER No events in record for removal.

-11073 PI_AR_REMENF Target event for removal not found in record.

-11074 PI_AR_REPNER No events in record to replace.

-11075 PI_AR_REPENF Target event for replacement not found in record.

-11076 PI_AR_NAVBEFORE Target time before archive start time.

-11077 PI_AR_NAVAFTER Target time after archive end time.

-11078 PI_AR_NOTWRITEABLE Target archive is not writeable.

-11079 PI_AR_NOTSHIFTABLE Target archive is not shiftable.

-11080 PI_AR_DUPPRIMARY Attempted to register two primary archives.

-11081 PI_AR_OVERLAP Attempted to register overlapping archives.

-11082 PI_AR_RECLOCKFAIL Attempted to lock a locked archive record.

-11083 PI_AR_RECUNLOCKFAIL Attempted to unlock an unlocked archive record.

-11090 PI_AR_EMPTYFILE Attempting operation on an empty archive file.

-11091 PI_AR_TOOMANYEVENTS Event collection exceeded maximum allowed.

-11092 PI_AR_NOANNOTATION Annotation not found in archive.

-11093 PI_AR_ANNOTMISMATCH Annotation mismatch (archive).

-11094 PI_AR_ANNOTEXIST Annotation already exist in archive.

-11095 PI_AR_SHIFTINPROG: Archive Shift already in progress.

-11096 PI_AR_BCKUPINPROG: Archive Backup already in progress.



-11097 PI_AR_BCKMODEMISMTCH: Backup End must follow Start and vice versa.

-11098 PI_AR_BADDIGDATA: Cannot convert to a Digital State.

-11099 PI_AR_SAMETIMEREC: Start time equal end time in archive record.

-11100 PI_AR_SAMETIMEARG: Start time equal end time argument in archive call.

-11101 PI_AR_SCALLFILTER: All data events are filtered in summary calculation.

-11102 PI_AR_SCNOEVENT: No events found within the time range of summary calculation.

-11103 PI_AR_SCOOSCALL: Out of sequence calls in summary calculation.

-11104 PI_AR_SCOOSEVENT: Out of sequence data events in summary calculation.

-11105 PI_AR_NULLLOADREC: Invalid record pointer for loading.

-11106 PI_AR_PTLOCKFAIL: Failed to lock archive-cache point.

-11107 PI_AR_NAVUNEXPECTED: Unexpected error navigating the archive.

-11108 PI_AR_ARCITERINVALID: Archive event iterator not properly initialized.

-11109 PI_AR_INVSAMPMODE: Invalid sample mode.

-11110 PI_AR_INVSAMPTIMES: Error with sample time array specification.

-11111 PI_AR_INVTIMECONST: Error with summary calculation time array.

-11112 PI_AR_INVNUMINTERVALS: Error with the summary calculation numInterval array.

-11113 PI_AR_SCNINVCB: Invalid CalculationBasis.

-11114 PI_AR_SCNINVTYPE: Invalid Summary CalcType.

-11115 PI_AR_SCNINVTIMES: Error with time constraint array in Sumnav object.

-11116 PI_AR_SCNINVFILTER: Error with the filter constraint array in Sumnav object.

-11117 PI_AR_SCNOOSRESCALL: Calling getresult before done in sumnav object.

-11118 PI_AR_SCNBADRE Internal error with result in sumnav object.

-11119 PI_AR_SCNINVARG: Invalid parameter in sumnav object.

-11120 PI_AR_SCNINTERPERR: Error interpolating data in sumnav object.

-11121 PI_AR_SCNOOSCALL: Out of sequence call in sumnav object.

-11122 PI_AR_SCNOOSEVENT: Out of sequence data event in sumnav object.


-11123 PI_AR_RCOVERFLOW: Point query exceeded maximum cache record count.

-11124 PI_AR_NONNUMERICSUM: Non-numeric tag in summary calculation.

-11125 PI_AR_LOWDISKSPACE: Low disk space, file cannot be created.

-11126 PI_AR_ANNGUIDMISMATCH: Annotation file ID is not matching archive file.

-11127 PI_AR_NODOWNGRADE: Archive file downgrade to requested version not supported.

-11128 PI_AR_TOOMANYREQEVENTS:

Number of requested events exceeded the maximum allowed.

-11129 PI_AR_NOTARCHIVING: Archive subsystem not in archiving state.

-11130 PI_AR_NEEDARCSIZE: Missing size information for new archive file creation.

-11131 PI_AR_RCEXCEEDSLIMIT Point has more cache records than maximum configured

-11132 PI_AR_CACHEUSECOUNT Cache record found with invalid reference count on clean operation

-11133 PI_AR_RECEIVEDNEWSNAP New snapshot event received while pending delete

-11134 PI_AR_SHIFTIMMINENT Archive Shift predicted withing backup lead time

-11135 PI_AR_FLUSHQLIMIT Reached maximum write cache events in lock contention

-11136 PI_AR_FLUSHEVTIMEOUT Timeout waiting for point flush operation

-11137 PI_AR_PRIMARYREADONLY Primary archive is Read-only. Archiving and archive shifts disabled

-11138 PI_AR_INVMODEADDCACHE Invalid mode for adding event to cache

-11200 PI_3PHUNAVAIL PI Server is not installed properly or is not running

-11201 PI_RDR_HISTTIMEDVALUEFAIL

PI Redirector could not get archived value from foreign system

-11202 PI_ RDR _HISTTIMEDVALUESFAIL

PI Redirector could not get archived data from foreign system

-11203 PI_ RDR _SNAPTIMEDVALUEFAIL

PI Redirector could not get snapshot value from foreign system

-11204 PI_ RDR _SNAPISLOCALFAIL PI Redirector could not determine whether to cache snapshot values from foreign system

-11205 PI_ RDR _SNAPSSIGNUP PI Redirector could not signup for updates with foreign system.



-11206 PI_ RDR _SNAPSUPDATESFAIL

PI Redirector could not get updates from foreign system.

-11207 PI_ RDR _SNAPPUTTIMEDVALUEFAIL

PI Redirector could not write snapshots to foreign system.

-11208 PI_ RDR _ADDCONNECTORFAIL

PI Redirector could not load connector or set PI Server system name.

-11209 PI_ RDR _ARCSUMMARYFAIL PI Redirector could not get arcsummary/summaries directly from foreign system.

-11300 PI_V_NOANNOTATION Annotation not found in Pivalue.

-11301 PI_V_ANNOTMISMATCH Annotation mismatch.

-11302 PI_V_ANNOTEXIST Annotation already exist.

-11303 PI_V_ANNOTTOOLONG Annotation exceeds size limit.

-11304 PI_V_INVALID_VARIANT_TYPE

Invalid variant type code.

-11305 PI_V_MISMATCH PIvalue mismatch

-11306 PI_V_NOTATIME Variant type is not a time

-11307 PI_V_NOTAUID Variant type is not a UID

-11901 PI_OFFL_BADOPENFILE Error opening offline file

-11902 PI_OFFL_BADRECNO Bad record number for offline input

-11903 PI_OFFL_BADIDCONV Bad Id conversion table

-11904 PI_OFFL_BADFILEREAD Failed to read input file (PI2)

-11905 PI_OFFL_NOTINIDCONV Point ID not found in ID conversion table

-11906 PI_OFFL_PTIDMM Point ID mismatch in offline loading

-11907 PI_OFFL_NOTARGETREC Cannot post events, no target record

-11908 PI_OFFL_INVTIMES Invalid Times For Offline loading

-11909 PI_OFFL_BADARCTYPE Invalid archive type for processing

-11910 PI_OFFL_NOEVENTS No events from input file were added to output archive



-12000 PI_TABLEFROZEN Pint is Frozen from Changes


-12001 PI_TABLENONAME Name Not Found in pint

-12002 PI_TABLENOCODE Code Not Found in pint

-12003 PI_TABLEDUPNAME Name Already in Use in pint

-12004 PI_TABLEDUPCODE Code Already in Use in pint

-12005 PI_TABLEINVNAME Invalid Name for Use in pint

-12006 PI_TABLEINVSLOT Invalid Slot for Use in pint

-12007 PI_TABLEINUSE Table already contains entries

-12008 PI_TABLELOADMIS Count Mismatch on Load

-12009 PI_TABLEFILEUSE Underlying File Store in Use

-12010 PI_TABLEMAXENTRIESEXCEEDED Attempt to activate or create table larger than allowed

-12011 PI_TABLENOIDENTIFIER Identifier not found in PInttemplate

-12012 PI_TABLEINVIDENTIFIER Identifier in PInttemplate is not valid

-12013 PI_TABLENORECORDDEFINITION Record definition of generic table is empty

-12050 PI_ARG_N OOWNLIST Arglist is Not Owned

-12051 PI_ARG_OWNLIST Arglist is Owned

-12052 PI_ARG_FROZEN Operation is Invalid on a Frozen List

-12053 PI_ARG_BADMERGE Failed merge

-12100 PI_GRID_BADSETCOLINF Pigrid: setcolinfo Failed

-12101 PI_GRID_BADSETNUMROW Pigrid: setnumrows Failed

-12102 PI_GRID_BADVERSION Pigrid: Version Mismatch in Activate

-12103 PI_GRID_BADSETNUMCOL Pigrid: setnumcols Failed

-12150 PI_UPD_NOTREG Not registered in updmgr

-12151 PI_UPD_NOCONS Consumer not registered in updmgr

-12152 PI_UPD_NOPROD Producer not registered in updmgr

-12153 PI_UPD_MISMATCH Id mismatch

-12200 PILIC_NOLICFILE no license file

-12201 PILIC_ERROPENFILE error open license file

-12202 PILIC_BADKEY invalid license key



-12203 PILIC_INVSPECS invalid license specs

-12204 PILIC_NOSUCHLIC no such license

-12205 PILIC_NOTREGISTERED user not registered

-12206 PILIC_LICEXCEDED usage exceeded licensed amount

-12207 PILIC_LICEXPIRED license expired

-12208 PILIC_BADUSERKEY user mismatch

-12209 PILIC_MISMATCH amount or another mismatch

-12210 PILIC_NOLICFILE10 license error 10

-12211 PILIC_SERVIDFILEEXISTS Server ID file creation failure; file already exists.

-12212 PILIC_SDKCONNECTIONS Maximum licensed SDK Application connections exceeded. Connection refused.

-12213 PILIC_APICONNECTIONS Maximum licensed API Application connections exceeded. Connection refused.

-12214 PILIC_POINTCOUNT Maximum licensed Point Count exceeded.

-12215 PILIC_MODULECOUNT Maximum licensed Module Count exceeded.

-12216 PILIC_POINTMODULECOUNT Maximum licensed aggregate Point/Module Count exceeded.

-12217 PILIC_BDB Not licensed to use Batch Database.

-12218 PILIC_MDB Not licensed to use Module Database.

-12219 PILIC_COMCONNECTORS Not licensed to use COM Connector-mapped points.

-12220 PILIC_SERVERAPP Not licensed to use this server or UDS application.

-12221 PILIC_CLIENTAPP Not licensed to use this client application.

-12222 PILIC_MAXHISTORY Not licensed to access Archive for passed dates.

-12223 PILIC_ERRGETMAC Error getting Machine info

-12224 PILIC_NOLICMGR License Manager not accesible

-12225 PILIC_NOKNOWNAPPS Did not receive Known Application data

-12226 PILIC_OLDLICFILE License file too old to parse

-12227 PILIC_INTERFACE Not licensed to use this interface


-12228 PILIC_MIDDLEWARE Not licensed to use this middle-ware application

-12229 PILIC_NONCCPOINTCOUNT Maximum licensed non-COM Connector Point Count exceeded

-12250 PI_BA_DUPACTIVETAG Batch active tag is already being used by another unit

-12251 PI_BA_BADSIZE Number of arguments in PIarray is incorrect

-12252 PI_BA_BADACTIVETAGTYPE Batch Active Tag Type is not STEP or PULSE.

-12253 PI_BA_UNITARCHIVETAGMISSING Invalid unit identifier.

-12254 PI_BA_WAIT Wait for in use object.

-12255 PI_BA_BADSYNTAXBATCHID Batch ID expression Syntax Error.

-12256 PI_BA_BADSYNTAXPRODUCTID Product ID expression Syntax Error.

-12257 PI_BA_BADPTBATCHID Invalid tag in Batch ID expression.

-12258 PI_BA_BADPTPRODUCTID Invalid tag in Product ID expression.

-12259 PI_BA_UNSUPPORTEDACTIVETAGTYPE

Batch active tag is not integer, real, or digital.

-12260 PI_BA_NOBATCHINEVENT PIevent does not contain a batch record (PIblob len 0 ).

-12261 PI_BA_PIBANEXISTS Could not create a unique archive tag name for unit.

-12262 PI_BA_STARTTIMESTATUSINVALID Status of start time for a batch is invalid.

-12263 PI_BA_STOPTIMESTATUSINVALID Status of stop time for a batch is invalid.

-12264 PI_BA_BATCHEND This is an end of batch event.

-12265 PI_BA_BATCHSTART This is a start of batch event.

-12266 PI_BA_TIMENOTFOUND Time was outside boundaries of PIbaIndex Directory.

-12267 PI_BA_INVALIDINDEX Index for PIbaIndex Directory is invalid.

-12268 PI_BA_INVALIDTIMESPAN Time span within search contains no indexes.

-12269 PI_BA_NO_UNITS_MATCHED Unit mask matches none of the current units.

-12270 PI_BA_NO_END_EVENT_EXISTS No end event exists for this batch handle.

-12271 PI_BA_BATCHOREVENT_EXISTS Attempt to archive batch over existing batch.



-12272 PI_BA_INVALIDPIBLOB Archived batch record invalid.

-12273 PI_BA_CANTDELETE Attempt to delete an active batch or batch with null end timestamp

-12274 PI_BA_NOBATCHES No matching batches were found.

-12275 PI_BA_INVALIDHANDLE Invalid or missing batch handle. Batch edit requires specifying a valid batch handle.

-12299 PI_BA_DUPACTIVETAG Batch active tag is already being used by another unit

-12300 PI_PE_ERROR Performance equation error

-12301 PI_PE_PARSEERROR Performance equation parsing error

-12302 PI_PE_DIVIDEBYZERO Performance equation divide by zero error

-12303 PI_PE_OVERFLOW Performance equation overflow error

-12304 PI_PE_LEX_FILE_NOT_FOUND Performance Equation: File PExxx.llr not found in DAT directory

-12305 PI_PE_RULE_FILE_NOT_FOUND Performance Equation: File PExxx.dfa not found in DAT directory

-12306 PI_PE_RESOURCES_NOT_FOUND Performance Equation: File pisystem.res not found in DAT directory

-12307 PI_PE_INVALID_CONNECTION Performance Equation: Invalid Connection

-12308 PI_PE_BAD_TREE_AT_GENCODE Performance Equation: Bad parse tree during code generation

-12309 PI_PE_BAD_TREE_AT_TYPECHECK

Performance Equation: Bad parse tree during type check

-12310 PI_PE_FUNC_WRONG_NUMBER_OF_ARGS

Performance Equation: Function has wrong number of arguments

-12311 PI_PE_FUNC_NEEDS_ONE_ARG Performance Equation: Function needs at least one argument

-12312 PI_PE_FUNC_TO_MANY_ARGS Performance Equation: Function has too many arguments

-12313 PI_PE_FUNC_ARG1_NOT_DIGITAL Performance Equation: First argument for function is not digital

-12314 PI_PE_FUNC_ARG1_NOT_TIME Performance Equation: First argument for function is not a time

-12315 PI_PE_FUNC_BAD_ARG_TYPES Performance Equation: Function has bad argument data type


-12316 PI_PE_FUNC_NEEDS_MORE_ARGS

Performance Equation: Wrong number of arguments for function

-12317 PI_PE_FUNC_ARG1_INVALID Performance Equation: Invalid first argument

-12318 PI_PE_FUNC_ARG2_INVALID Performance Equation: Invalid second argument

-12319 PI_PE_FUNC_ARG3_INVALID Performance Equation: Invalid third argument

-12320 PI_PE_FUNC_ARG4_INVALID Performance Equation: Invalid fourth argument

-12321 PI_PE_FUNC_ARGS_NOT_SAME_TYPE

Performance Equation: All arguments must have same data type

-12322 PI_PE_FUNC_ARGS_NOT_NUMBERS

Performance Equation: All function arguments must be numbers or evaluate to numbers

-12323 PI_PE_TOO_MANY_ARGS Performance Equation: Function has too many arguments

-12324 PI_PE_ADD_CONNECT_FAILED Performance Equation: Connection failed

-12325 PI_PE_TOO_MANY_CONNECTS Performance Equation: Too many connections

-12330 PI_PE_PCT_GOOD_TOO_SMALL Performance Equation: Percent good is below requested threshold



-13000 PI_MSG_BADQUERY Bad query for messages in GetMessages

-13001 PI_MSG_BADMAXCOUNT The query for messages contains an invalid total number of messages parameter in GetMessages

-13002 PI_MSG_BADSTARTTIME The query for messages contains an invalid PI format start time in GetMessages

-13003 PI_MSG_BADENDTIME The query for messages contains an invalid PI format end time in GetMessages

-13004 PI_MSG_BADMESSAGEID The query for messages contains an invalid Message ID in GetMessages

-13005 PI_MSG_BADUSER The query for messages contains an invalid program name in GetMessages

-13006 PI_MSG_BADSEARCHSTRING The query for messages contains an invalid message search string in GetMessages

-13007 PI_MSG_BADOPTION1 The query for messages must have end time



and/or total message count in GetMessages

-13008 PI_MSG_BADOPTION2 The query for messages must have start time and/or total message count in GetMessages

-13009 PI_MSG_BADOPTION3 The query for messages must have start time and/or end time in GetMessages

-13010 PI_MSG_NAMEMISMATCH The query for messages contains an invalid name in the query name table in GetMessages

-13011 PI_MSG_BADFILE The PI Message file can not be read. It may be corrupt.

-13050 PI_AUD_FNF Cannot find audit file

-13051 PI_AUD_CREFAIL Cannot create audit file

-13052 PI_AUD_BCKUPINPROG Audit disabled during backup

-13053 PI_AUD_WRITEERR Failed to write audit record

-13100 PI_NTLOG_NOHANDLE No Application Event Log Handle

-13101 PI_NTLOG_NOUPDATE Unable to get updates from App Log

-13102 PI_NTLOG_NOSENDTOPI Unable to send event log messages to PI

-13103 PI_NTLOG_BADGETREGVAL Unable to get values for pimsgss service registry key

-13104 PI_NTLOG_NOREGKEY Unable to get registry key for service pimsgss

-13200 PI_CTR_BADPERFINFO PIPerfInfo struct is bad

-13201 PI_CTR_BADGETPERFREG Unable to get Perflib registration info

-13202 PI_CTR_BADSETPERFREG Unable to set Perflib registration info

-13203 PI_CTR_BADGETPIREG Unable to get PI performance registration info

-13204 PI_CTR_BADSETPIREG Unable to set PI performance registration info

-13205 PI_CTR_BADPERFLIBNUM Perflib Last Counter larger than Last Help

-13206 PI_CTR_ODDPERFLIB Perflib Last Counter is odd number or Last Help is even number

-13207 PI_CTR_BADPERFLIBSET Perflib Last Help is greater than Last Counter by more than one

-13208 PI_BADCOUNTERNAMELENGTH

he performance counter name is larger than 32 characters, counters will not be installed

-13250 PI_TST_NOTFOUND Test not found in DB

-13251 PI_TST_DBERROR Cannot record results in test DB


-13252 PI_TST_MAILERROR Cannot Email test results

-13253 PI_TST_NOPISYS Test requires running PI system

-13254 PI_TST_INVATR Invalid test attribute

-13255 PI_TST_FAILED Test failed

Table 12–12. Error Codes15000-15999, With Messages


-15000 PI_ISTREAMFAIL Istream::get Failed

-15001 PI_OSTREAMFAIL Ostream:: Failed

-15002 PI_BADOFFSET Generic Out-of-Bounds Error (pistring, piarray)

-15003 PI_NOTFOUND Element Not Found (piarray)

-15010 PI_OVERFLOW Number Too Big For pivalue

-15011 PI_NOTANUMBER Pivalue Type is Not Numeric

-15012 PI_INFINITY Pivalue Divide by Zero

-15013 PI_NOTAFLOAT Pivalue Type or pistring is Not Float

-15014 PI_NOTANINTEGER Pivalue Type or pistring is Not Integer

-15015 PI_BADFLOATFORMAT Number of Digits or Decimals Out of Range

-15016 PI_NOTASTRING Pivalue Type is Not a String

-15017 PI_WRONGVALTYPE Pivalue Type is Not Allowed For This Call

-15018 PI_NOTABLOB Pivalue Type is Not a Blob

-15019 PI_NOTAVALUETYPE Value Type is Not a Valid pivalue Type

-15020 PI_INVALIDPATH Invalid path specified

-15021 PI_BADTARGET Context sensitive bad target error

-15022 PI_BADINITIALIZE Context sensitive initialization failure

-15023 PI_BADVERSION Generic bad version failure

-15024 PI_DUPLICATE Generic duplicate name

-15025 PI_BADEVENTMODE Invalid or Unsupported pievent Mode

-15026 PI_MAXLENGTHEXCEEDED Attempt to activate or create a pistring or piblob larger than max allowable



-15027 PI_LOGMESSAGESTHROTTLED Excessive messages to PImsgss, log messages temporarily terminated

-15028 PI_INVALIDBOOKMARK Invalid or corrupt book mark

-15029 PI_INVALID Generic invalid call or argument

-15030 PI_MISMATCH Generic mismatch

-15031 PI_NOTADIG PIvalue type is not digital

-15032 PI_PATHNOTFOUND Requested path not found

-15033 PI_BCKUPINPROG Cannot perform operation during backup

-15034 PI_INVALIDTZCONFIG TimeZone configuration is invalid

-15035 PI_MAXARRLENGTHEXCEEDED Attempt to activate or create a PIarray larger than max allowable.

-15036 PI_UNABLETORETRIEVEUNIXERRNO A call on UNIX fails but errno is zero.

-15037 PI_BADARGUMENTCONVERSION No suitable conversion from a variant to RPC argument.

-15038 PI_INVALIDTIMESTAMP PIvalue cannot represent PIstring as a valid timestamp.

-15039 PI_ENVVAR_EXISTS System environment variable already exists

-15040 PI_MAXQUEUELIMIT Non-expandable PIfifo reached maximum capacity

-15041 PI_EMPTYQUEUE Attempt to extract data from empty PIfifo



-16000 PI_INVALIDEFFECTIVEDATE Object not found for passed effective date

-16001 PI_MODULENOTFOUND Module does not exist

-16002 PI_INVALIDMODULEVERSION Invalid or missing module version

-16003 PI_DUPLICATEEFFECTIVEDATE Value with passed effective date already exists

-16004 PI_LASTMODULEVALUE Cannot remove last module value. Use module remove

-16005 PI_ROOTMODULE Attempt to remove or edit a Built in module element


-16006 PI_MODULEHIERARCHYBREAK Attempt to delete or remove a module that breaks existing hierarchy

-16007 PI_UNEXPECTEDMODULEDBERROR Unexpected PI Module Database error

-16008 PI_MODULEVALUEEXISTS Effective date already exists for attempt add or move of a module value

-16009 PI_INVALIDPARENT Invalid parent specified for the operation

-16010 PI_DUPLICATEHIERARCHY Attempt to create or edit object with duplicate hierarchical level

-16011 PI_INVALIDHIERARCHY Attempt to create or edit object with invalided hierarchical level

-16012 PI_NOPARENTREFERENCE Module does not have parent reference to specified module

-16013 PI_NOCHILDREFERENCE Module does not have child reference to specified module

-16014 PI_INVALIDQUERYDATE Invalid or unspecified query date

-16015 PI_INVALIDUID Invalid or unspecified uid

-16016 PI_INVALIDMODE Invalid or unspecified module value access mode

-16017 PI_MODULEVALUENOTFOUND Module Value for passed effective date not found

-16018 PI_INVALIDHEADING Specified heading does not exist or is member of different heading set

-16019 PI_INVALIDTIMERANGE Invalid or unspecified time range for batch database search

-16020 PI_NOMATCHINGMODULES No matching PIModules for call

-16021 PI_NOMATCHINGBDBRECORDS No Matching Batch Database records

-16022 PI_MDBNOTSUPPORTED Attempted operation not supported by the specified database

-16023 PI_MDBCIRCULARREFERENCE Attempt to insert a PIModule that would cause a circular reference

-16024 PI_MDBNOMATCHINGVALUES No module values within the passed time range

-16025 PI_MDBLASTVALUE Attempt to remove the last module value.

-16026 PI_BDBCROSSREFERENCE Attempt to remove a Batch Database Record which contains a cross reference to another record.



-16027 PI_BDBBSSNOTSUPPORTED Batch Database does not support this action with Batch Subsystem Batch.

-16028 PI_INVALIDBDBTIME Invalid start or end time for Batch Database Record.

-16029 PI_BDBMAXRECORDSEXCEEDED Batch database search exceeded maximum allowed records

-16201 PI_THREADPOOLDISABLED Subsystem does not support thread pool or thread pool is disabled.

-16202 PI_THREADSUSPENDED Thread is in suspended state.

-16203 PI_INVALIDTHREADID Passed thread ID is invalid.

-16204 PI_THREADTIMEOUT Time out waiting for semaphore or lock.

-16205 PI_THREADABANDONED Thread or handle has been abandoned.

-16206 PI_THREADUNLOCK Attempt to release exclusive lock from thread that did not acquire the lock.

-16207 PI_THREADESCALATE Attempt to Escalate lock without prior non-exclusive lock.

-16208 PI_THREADEXCLUSIVE Thread already has exclusive lock.

-16209 PI_IOCOMPLETED Asynchronous IO has completed.

-16210 PI_THREADNOTSUPPORTED Thread control function not supported.

-16211 PI_UKNOWNLOCKERROR Unknown system error attempting to get lock.

-16212 PI_SHAREDLOCKTIMEOUT Timeout attempting to get non-excluseive lock.

-16213 PI_UNBALANCEDLOCKRETURN Lock return count greater than get count.

-16214 PI_EXCLUSIVELOCKTIMEOUT Timeout attempting to get excluseive lock.

-16215 PI_THREADPOOLOVERRANGE Attempt to create too many threads.

-16300 PI_ARCHK_OVFREVCHAIN Invalid backwards chaining of overflow record

-16301 PI_ARCHK_IDXREVCHAIN Invalid backwards chaining of index record

-16302 PI_ARCHK_RECIDXNOTFOUND Overflow record not found in index records

-16303 PI_ARCHK_MULTIPLEIDXREF Index entry referenced by multiple overflow records

-16304 PI_ARCHK_OOOIDXREC Out-of-order overflow record in index record


-16305 PI_ARCHK_OOOEVENT Out-of-order event found in overflow record

-16306 PI_ARCHK_INVANNHANDLE Event marked as annotated with no annotation handle

-16307 PI_ARCHK_INVANNOTATION Annotation record not found for annotated event

-16308 PI_ARCHK_DUPANNHANDLE Annotation record referenced by multiple events

-16309 PI_ARCHK_IDXTIMEMISMATCH Index not matching overflow record start time

-16310 PI_ARCHK_EVBEFORESTART Event before archive start time

-16311 PI_ARCHK_EVAFTEREND Event after archive end time

-16312 PI_ARCHK_IDXACTIVATION Unexpected error reading index record

-16313 PI_ARCHK_IDXSTARTERROR Index start time doesn't match archive start time

-16314 PI_ARCHK_1STRECNOTHEAD First overflow record has a previous record

-16315 PI_ARCHK_PTTYPEMISMATCH Point type not matching primary record

-16316 PI_ARCHK_INVALIDIDXTYPE Unexpected data type for index record

-16317 PI_ARCHK_INVALIDARCNUM Invalid archive file number

-16318 PI_ARCHK_OVFCIRCHAIN Circular chaining of overflow record

-16319 PI_ARCHK_IDXCIRCHAIN Circular chaining of index record

-16320 PI_ARCHK_TOOMANYERRORS Too many errors, filtering non-fatal errors

-16500 PI_MMQ_SYNC_CREATE Creation of Piarchss synchronization object failed

-16501 PI_MMQ_SYNC_OPEN Opening of Pisnapss synchronization object failed

-16502 PI_MMQ_SYNC_WRITETIMEOUT Timeout waiting for write access to Event Queue

-16503 PI_MMQ_SYNC_WRITEFAILED Wait for queue write returned a WAIT_FAILED status

-16504 PI_MMQ_SYNC_UNEXPECTED Unexpected error waiting for Event Queue access

-16505 PI_MMQ_SYNC_READTIMEOUT Timeout waiting for read access to Event Queue

-16506 PI_MMQ_SYNC_READFAILED Wait for queue read returned a



WAIT_FAILED status

-16600 PI_MMQ_INVALID_FILESIZE Invalid queue file size (requires inimum 2 data pages)

-16601 PI_MMQ_FILEPATH_TOOLONG File path and name exceed 260 characters (MAX_PATH)

-16602 PI_MMQ_PHYSFILE_CREATE Error while creating queue file (pimapevq.dat)

-16603 PI_MMQ_MAPFILE_CREATE Error while creating mapped file of Event Queue

-16604 PI_MMQ_MAPFILE_OPEN Error while opening mapped file of Event Queue

-16605 PI_MMQ_MAPFILE_MAPVIEW Error while mapping a page view of the queue file

-16606 PI_MMQ_MAPFILE_INIT Event queue not initialized before read or write access

-16607 PI_MMQ_MAPFILE_UNMAPVIEW Error while unmapping a page view of the queue file

-16608 PI_MMQ_MAPFILE_FULL Event queue file is entirely full

-16609 PI_MMQ_FILESIZE_MISMATCH Configured file size doesn’t match existing file

-16610 PI_MMQ_PAGESIZE_MISMATCH Configured page size doesn’t match existing file

-16611 PI_MMQ_FORWARD_VERSION Existing queue file is from a later version

-16612 PI_MMQ_INVALID_READPAGE Invalid read page index in existing queue file

-16613 PI_MMQ_INVALID_WRITEPAGE Invalid write page index in existing queue file

-16614 PI_MMQ_INVALID_FREEPAGES Inconsistent number of available pages in existing queue file

-16615 PI_MMQ_WRITEPAGE_FULL Write failedtarget write page is full

-16616 PI_MMQ_STREAMINIT_ERROR Error while creating i/o stream object

-16617 PI_MMQ_ACTIVATION_FAILED Read error while activating event from queue

-16618 PI_MMQ_UNRECOGNIZABLE_FILE File format is not a valid memory-mapped Event Queue file

-16619 PI_MMQ_MAPFILE_FLUSHVIEW Error while flushing to disk a view of the


queue file

-16620 PI_MMQ_EMPTY_READPAGE Attempt to read data from an empty page

-16621 PI_MMQ_BAD_FILENAME Invalid overflow file name template

-16622 PI_MMQ_BAD_EXTENSION Missing extension in overflow file name template

-16623 PI_MMQ_BAD_DATA_OFFSET Invalid data member offset within PImapfilepage

-16624 PI_MMQ_EVCOUNT_MISMATCH Event count mismatch with empty data pages

-16700 PI_SUBSYSINFO_INVALID_ARGUMENTS

Invalid arguments for Sub-system Information RPC

-16701 PI_SUBSYSINFO_INVALID_PROCESSID

Invalid process ID Sub-system Information RPC

-16821 PI_BCKFILE_FILENAME_NULL Cannot add file to the list of backed up files because the file name is null

-16823 PI_BCKFILE_REMOVE_ERROR_FILENOTFOUND

Cannot remove file from list of backed up files because the file name was not found in the list

-16824 PI_BCKFILE_ADD_ERROR_DUPLICATEFILENAME

Cannot add file to the list of backed up files because the file is already in the list

-16826 PI_BCKFILE_DUPLICATE_BACKEDUP_FILE_LIST

Only one backup file list object can be created

-16840 PI_BACKUP_BACKUPSUBSYS_NOT_INITIALIZED

Backup manager is not initialized

-16841 PI_BACKUP_VSS_UNSUPPORTED Unsupported operating system for Volume Shadow Copy Services

-16842 PI_BACKUP_INVALID_COMPONENT_NAME

Invalid component name

-16860 PI_VSSEVENT_FREEZE_IN_PROGRESS

VSS Freeze already in progress

-16861 PI_VSSEVENT_FREEZE_NOT_IN_PROGRESS

Expected VSS Freeze to be in progress, but freeze was not in progress

-16863 PI_BCKEVENT_FREEZE_TIMEOUT_WAITING_FOR_THAW_EVENT

VSS Freeze timed out waiting for VSS thaw event

-16864 PI_VSSEVENT_FREEZE_TIMEOUT_DURING_FREEZE_EVENT

VSS Freeze timed out before VSS freeze event could complete

-16868 PI_VSSEVENT_IDENTIFY_COMPONE VSS Identify failure. Two VSS components have the same name but different



NT_MISMATCH component properties

-16893 PI_BCKEVENT_SUBSYSTEM_NOT_PARTICIPATING

Subsystem does not participate in backups. The backup event was ignored

-16896 PI_BCKEVENT_RPCRESOLVEROFFLINE

RPC Resolver offline for a subsystem to which the backup subystem is communicating. Find -10733 error in message log to identify problematic RPC

-16898 PI_BCKEVENT_IN_PROGRESS Backup event in progress

-16914 PI_BCKSTATE_INVALID_STATE_TRANSITION

Invalid state transition for backup

-16915 PI_BCKSTATE_BACKUP_ABORTED Backup was aborted

-16916 PI_BCKSTATE_BACKUP_SHUTDOWN_NOCOMPLETE

Backup shutdown without completing

-16917 PI_BCKSTATE_BACKUP_IN_PROGRESS

Backup in progress

-16920 PI_BCKRPC_NO_RESPONSE Expected VSS Async callback function was not called within timeout period

-16921 PI_BCKRPC_CALLBACK_UNEXPECTED

Unexpected VSS Async callback. Callback function was called but was not expected

-16923 PI_BCKRPC_INVALID_BACKUP_COMMAND

Invalid backup command

-16940 PI_VSSAPI_ADDCOMPONENT_FAILED

VSS API call AddComponent failed

-16941 PI_VSSAPI_ADDDATABASEFILE_FAILED

VSS API call AddDatabaseFiles failed

-16942 PI_VSSAPI_BACKUPTYPE_UNKNOWN

Unknown backup type

-16943 PI_VSSAPI_BACKUPTYPE_LOG_UNSUPPORTED

Backup type of LOG is unsupported

-16944 PI_VSSAPI_BACKUPTYPE_OTHER_UNSUPPORTED

Backup type of OTHER is unsupported

-16980 PI_BCKLOCK_GETLOCK_TIMEOUT GetLock timeout for master backup lock

-16981 PI_BCKLOCK_GETEXCLUSIVELOCK_TIMEOUT

GetExclusiveLock timeout for master backup lock

-16983 PI_BCKLOCK_RETURNEXCLUSIVELOCK

ReturnExclusiveLock failed for master backup lock

-16984 PI_BCKLOCK_RETURNEXCLUSIVELO ReturnExclusiveLock for master lock failed


CK_NOTLOCKED because master lock was not locked

-16985 PI_BCKLOCK_GETLOCK_NONVSSBACKUP

GetLock failed for master backup lock because a non-VSS backup is in progress



-17000 PI_UNX_SEMRANGE Semaphore count out-of-range

-17001 PI_UNX_ARRSEM Semaphore belongs to array

-17002 PI_UNX_EVNONAME No name for shared event

-17003 PI_UNX_EVNOINIT Event not initialized

-17004 PI_UNX_BADEVSEM Named semaphore init failed



-30000 PI_WARNING Generic warning

-30100 PI_PD_IGNORE Attribute ignored

-30101 PI_PD_OPERATIONFAILED One or more point SDK operations failed

-30150 PI_BCKSTATE_NOTREADY_FORFREEZE

Warning - not ready for freeze yet

-30200 PI_NODATA Generic Nothing Found warning

-30201 PI_TMPUNAVAIL Generic temporary unavailable - try later

-30202 PI_RELOADED Generic reload warning

-30250 PI_UPD_OVERFLOW Update queue overflow, some events missing

-30260 PI_ALREADYLOCKED Request locking an already locked

-30300 PI_CTR_NOINSTALL Perflib registry is bad, will not install counters

-30301 PI_CTR_DONOTINSTALLCOUNTERS Performance counters chosen not to be installed

-30350 PILIC_GRACELICEXP License expired or exceeded grace period

-30400 PI_AR_DUPTIMESTAMPS Last event in collection has same timestamp as next event

-30401 PI_AR_REMGENEVENT Attempt to remove or replace a generated



event

-30402 PI_AR_ANNFILERENAMED Annotation file not matching archive ID, successfully renamed

-30403 PI_AR_INVCOMPEVENT Event for removal not found in snapshot record, passed to archive

-30404 PI_AR_NOTINBACKUPSTATE No archive file in backup state

-30500 PI_RDR_PARTIALSUCCESS One or more Redirector operations failed

-30501 PI_RDR_SUMMARYNOTSUPPORTED PI COM Connector does not support this summary. Summary will be performed on host.


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


Point Count Total number of defined points. This number includes the Connector Point Count.

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.

Point Create or Edit/sec Rate at which points are created or edited.

Digital State Translations/sec

Rate at which digital state strings are translated to offsets.

Wild Card Searches/sec Rate of wild card point searches. This counter represents the rate at which new searches are started, not the number of points found.

Point Accesses/sec Rate at which point information is accessed, not including point edits. This will include translations of tag to point id.

Module Count The total number of modules in the module database.

Heading Set Count The total number of heading sets in the module database.

Heading Count The total number of headings in the module database.

Module Database Record Count

The total number of records in the module database.

Module Create or Edit/sec Rate at which modules are created or edited.

Heading Set Create or Edit/sec

Rate at which heading sets are created or edited.

Heading Create or Edit/sec Rate at which headings are created or edited.

Module Database Create or Edit/sec

Rate at which MDB records are created or edited.


Module Accesses/sec Rate at which module information is accessed, not including module edits.

Heading Set Accesses/sec Rate at which heading set information is accessed, not including module edits.

Heading Accesses/sec Rate at which heading information is accessed, not including module edits.

Module Database Accesses/sec

Rate at which module database information is accessed, not including module edits.

PI Archive Subsystem Statistics


Archived Events/sec Rate of successful event addition to the archive.

Out of Order Events/sec Out of order events posted in the archive.

Events Cascade/sec Rate of Out-of-Order events causing record shifts.

Events Read/sec Rate of archive events read.

Read Operations/sec Rate of archive read calls. Each call can return multiple events. The rate of event retrieval is Events Read/sec.

Primary Archive Number Internal index number of archive current assigned to primary position.

Cache Record Count Archive cache records in memory.

Cache Records Created/sec

Rate at which archive cache records are created.

Cache Records Deleted/sec

Rate at which archive cache records are deleted.

Record Disk Reads/sec Rate of archive disk reads (includes Cache Record Disk Reads/sec).

Record Disk Writes/sec Rate of archive disk writes.

Cache Record Disk Reads/sec

Rate of archive cache disk reads.

Cache Record Memory Reads/sec

Rate of archive cache memory hits.

Overflow Index Record/sec Rate at which index archive records are created.

Overflow Data Record/sec Rate at which data archive records are created.

Cache Clean Operations/sec

Rate at which archive cache records are removed from memory.

Cache Flush Rate at which points are flushed to disk.



Operations/sec

Time to Archive Shift Number of seconds until the archive is projected to shift. This time is not calculated if the archive is less than 20% full.

Connector Read Operations/sec

Rate of calls to read events for mapped points through COM Connectors. This rate is NOT included in the Read Operations/sec counter.

Connector Events Read/sec

Rate of events read for mapped points through COM Connectors. This rate is NOT included in the Events Read/sec counter.

Connector Summaries/sec Rate of summaries for mapped points through COM Connectors. This rate is NOT included in the Events Read/sec counter.

Connector Events Read Exec Time

Time elapsed in milliseconds for one Events Read for a COM Connector point.

Connector Event Read Exec Time

Time elapsed in milliseconds for one Event Read for a COM Connector point.

Connector Summaries Exec Time

Time elapsed in milliseconds for one summaries call for a COM Connector point.

Point Flushes Last Cycle Number of points flushed to disk during last cycle. Busy points might get flushed several times per cycle.

Unflushed Points Number of points that have at least one unflushed event.

Archive Cycles/Sec Number of Subsystem cycles per second.

Total Unflushed Events Total number of unflushed events.

Configured Cache Record Pool

Maximum number of cache records in the read-only pool.

Current Cache Record Pool

Current maximum number of cache records, this may be lower that the configured value due to low memory resources.

Config. Max Unflushed Events/pt

Maximum number of unflushed events per point.

Current Max Unflushed Events/pt

Current maximum number of unflushed events per point, this may be lower that the configured value due to low memory resources.

Primary Archive % Used Percent of used records in Primary Archive File.

Event Queue Chunk Size Number of events read per Event Queue read operation.

Flush Queue Size Number of pending flush operations in memory queue.

Write Contentions/sec Rate of write lock contentions (EVQ threads).

Write Contention Points Number of points in write contention last cycle.

GetSnapshot Calls/sec Rate of internal calls to the Snapshot Subsystem.


ArcEvent Calls/sec Rate of single archive event calls.

CompEvents Calls/sec Rate of compressed events calls.

InterpEvents Calls/sec Rate of interpolated events calls.

PlotEvents Calls/sec Rate of plotted (trended) event calls

Summary Calls/sec Rate of summary/filter expression calls.

PICampaigns Created/sec Rate of PI Campaign creation.

PIBatches Created/sec Rate of PI Batch creation.

PIUnitBatches Created/sec Rate of PI Unit Batch creation.

PITransferRecords Created/sec

Rate of PI Transfer Record creation.

PICampaigns Edited/sec Rate of PI Campaign edits

PIBatches Edited/sec Rate of PI Batch edits

PIUnitBatches Edited/sec Rate of PI Unit Batch edits

PITransferRecords Edited/sec

Rate of PI Transfer Record edits.

PICampaigns Read /sec Rate of PI Campaign access.

PIBatches Read /sec Rate of PI Batch access.

PIUnitBatches Read /sec Rate of PI Unit Batch access.

PITransferRecords Read/sec

Rate of PI Transfer Record access.

PICampaigns Deleted /sec Rate of PI Campaign deletion.

PIBatches Deleted /sec Rate of PI Batch deletion.

PIUnitBatches Deleted /sec Rate of PI Unit Batch deletion.

PITransferRecords Deleted /sec

Rate of PI Transfer Record deletion.

PI Snapshot Subsystem Statistics


Snapshots/sec Rate at which events are sent to the snapshot.

Out Of Order Snapshots/sec

Rate at which out-of-order events are sent to the snapshot.



Queued Events/sec Rate at which events are sent to the Event Queue.

GetSnapshots/sec Rate at which events are read from the snapshot.

GetSnapshot Calls/sec Rate of individual snapshot value calls.

GetSnapshots Calls/sec Rate of multiple snapshot values calls.

Remove Snapshots/sec Rate of snapshot values being deleted.

Digital State Translations/sec

Rate of digital strings translated into offsets.

Connector Snapshots/sec Rate at which events are sent to mapped points through COM Connectors. This rate is NOT included in the Snapshots/sec counter.

Connector GetSnapshots/sec

Rate at which events are read from mapped points through COM Connectors. This rate is NOT included in the GetSnapshots/sec counter.

Connector Updates/sec Update events received from COM Connectors. This rate is NOT included in the Connector GetSnapshots/sec counter.

Connector Snapshot Put Elapsed Time

Time elapsed in milliseconds for Snapshot Put for COM Connector a point.

Connector Snapshot Read Elapsed Time

Time elapsed in milliseconds for Snapshot Read for a COM Connector point.

Connector Updates Elapsed Time

Time elapsed in milliseconds for Updates for COM Connector points.

Events in Primary Queue Number of events in the primary queue file.

Number of Overflow Queues

Number of overflow queue files (0 if only the primary queue is active).

Events in Overflow Queues Total of events in the overflow queue files.

Estimated Remaining Capacity

Estimated maximum number of events with current queue file.

Event Queue Total Pages Number of data pages in primary queue file.

Event Queue Used Pages Number of full data pages in primary queue file.

Event Queue Page Shifts/sec

Rate of data page shifts in primary queue file.

Primary Event Queue Id Identification number of primary queue (0 to 65,535).

PI Message Subsystem Statistics


Sent Messages/sec The number of messages sent to PI Message Subsystem per second.

Retrieved Messages/sec The number of messages retrieved by the PI Message Subsystem per second.

Inserted Messages/sec The number of messages that were inserted into the PI Message Subsystem from the Application Event Log per second.

PI SQL Subsystem Statistics


Callbacks/sec Rate of calls to PI-SQL execution callback routine.

ArcValueCompCalls/sec Rate of RPC calls made to the PI Archive Subsystem for compressed events.

ArcValueCompEvents/sec Rate at which compressed data events are returned by the PI Archive Subsystem.

WildcardSearches/sec Rate at which new wildcard searches are initiated in the PI Point Database.

WildcardPoints/sec Rate at which points are returned when performing wildcard searches of the PI Point Database.

ArcValueCalls/sec Rate of RPC calls made to the PI Archive Subsystem to obtain a single archived value.

SnapshotCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to obtain a single snapshot value.

WHERE Clause Evaluations/sec

Rate of full evaluations of the WHERE clause of a SELECT statement.

ArcValueTimedCalls/sec Rate of RPC calls made to the PI Archive Subsystem for interpolated or timed events.

ArcValueTimedEvents/sec Rate at which interpolated or timed data events are returned by the PI Archive Subsystem.

SummaryArcValueCalls/sec

Rate of RPC calls made to the PI Archive Subsystem for summarized values (i.e. average, total, standard deviation, etc.).

Dot Variable Evaluations/sec

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.

Next Point With Source Calls/sec

Rate at which points are returned by the PI Base Subsystem in searches for points with a specific PointSource attribute.



PostCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to post events from execution of SQL INSERT or UPDATE statements.

PostEvents/sec Rate at which data events are posted to the PI Snapshot Subsystem from execution of SQL INSERT or UPDATE statements.

Handles 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


Total Point Count The total number of active PI Totalizer Subsystem points.

Source Tag Values/sec Rate of Totalizer input events.

EventExpr/sec Rate of EventExpr evaluations.

FilterExpr/sec Rate of FilterExpr evaluations

Filter Changes/sec Rate of Filter state changes

Period End/sec Rate of Totalization period completions

Updates/sec Rate of snapshot values to Totalizer points

Update status 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


Connections The number of connections to the PI Network Manager. Applies to _Total only.

Messages Sent/sec The number of messages sent to the PI Network Manager.

Messages Received/sec

The number of messages received by the PI Network Manager.

Bytes Sent/sec The number of bytes sent to the PI Network Manager.

Bytes Received/sec The number of bytes received by the PI Network Manager.

Overflow/sec The number of times an overflow message is required by the PI Network Manager.

Receive Errors The number of times an error occurs during a receive of a message to the PI Network Manager.


Send Errors The number of times an error occurs during a send of a message to the PI Network Manager.

PI API Connections The number of PI API applications connected.

PI SDK Connections The number of PI SDK applications connected.

Licensing Failures The number of times an application was rejected due to licensing concerns

Licensing Warnings The number of times an application was warned of licensing concerns

PI Performance Equations Statistics


AlarmFuncCalls/sec Rate of calls made to alarm functions.

ArcFindCalls/sec Rate of calls made to the PI Archive Subsystem for finding values.

ArcSummaryCalls/sec Rate of calls made to the PI Archive Subsystem for summarized values.

ArcValueCalls/sec Rate of calls made to the PI Archive Subsystem for compressed events.

FailedEvaluations/sec Rate of PE evaluations that return the digital state Calc Failed.

NumberOfPEs Number of Performance Equations.

SnapshotCalls/sec Rate of calls made to the PI Snapshot Subsystem to obtain snapshot event(s).

SnapshotEvents/sec Rate of snapshot event retrieval.

SteamFuncCalls/sec Rate of calls made to steam functions.

TotalEvaluations/sec Rate of PE evaluations.

PI Session Statistics


Messages Sent/sec The number of messages sent by the PI session.

Messages Received/sec The number of messages received by the PI session.

Bytes Sent/sec The number of bytes sent by the PI session.

Bytes Received/sec The number of bytes received by the PI session.

Receive Errors The number of times an error occurs during a receive a message by the PI session.

Send Errors The number of times an error occurs during a send of a message by the PI session.


PI Subsystem Statistics


Message Queue Length Number of incoming messages in queue.

Pending Transactions Number of pending transactions.

Actual Pending Transactions

Only for internal debugging purpose. You should use it only under the suggestion of Rockwell Automation Technical Support.

Message Pickup Time Latency of incoming messages (time in message queue).

Message Execution Time

Execution time of incoming message (RPC).

Message Complete Time Total message handling time (including results sending).

Callback Execution Time Execution time of transaction callback.

Transaction Completed/sec

Number of transactions completed per second.

Transaction Cancelled/sec

Number of transactions cancelled per second.

Transaction Avg Time Average execution time of outgoing transactions.

Transaction Max Time Maximum execution time of outgoing transactions.

Lock Acquisitions/sec Number of successful lock acquisitions per second

Lock Timeouts/sec Number of lock timeouts (failed locks) per second.

Lock Contentions/sec Number of lock conflicts (threads waiting for the same lock).

RPC Threads Total Total number of RPC worker threads (query processing).

RPC Threads Active Number of RPC worker threads processing a query.

File Open Number of time File base Open called.

File Close Number of time File base Close called.

File Read/Sec Rate of File base Read.

File Write/Sec Rate of File base Write.

File Delete/Sec Rate of File base Delete.

File Create Number of time File base Create called.

File Compress Number of time File base Compress operations.

File Grow Number of time File Directory grow operations.

PI Update Manager Statistics


Pending events Total Events pending in the PI Update Manager database.

New events/sec Events sent to the PI Update Manager.

Lost events/sec Events lost due to the PI Update Manager database being full.

Update signups Queued signups in the PI Update Manager.

New registration/sec Consumer and Producer registration rate.

Consumer count Total number of registered consumers.

Max pending events Maximum pending events reached in the PI Update Manager database.

Get Events calls/sec Total consumers Getevent calls rate.

PI Update Consumer Statistics


Pending events Total Events pending for this consumer.

New events/sec Event rate for this consumer.

Lost events/sec Events lost due to the PI Update Manager database being full.

Update sign-ups Queued sign-ups for this consumer.

Get Events calls/sec Getevent calls rate.

PI Update Producer Statistics


Pending events Total Events pending for this producer.

New events/sec Event rate for this producer.

Update calls/sec Rate of incoming update calls

Update sign-ups 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.


Table 12–16. PI Performance Counters

Tag Explain Text

PERF.LOCALHOST.Logical Disk(_Total).Free Megabytes

Free Megabytes displays the unallocated space on the disk drive in megabytes. One megabyte = 1,048,576 bytes.

PERF.LOCALHOST.Memory.% Committed Bytes In Use

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

PERF.LOCALHOST.Memory.Page Faults/sec

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.

PERF.LOCALHOST.Processor(0).% Processor Time

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

PERF.LOCALHOST.TCP.Segments Retransmitted/sec

Segments Retransmitted/sec is the rate at which segments are retransmitted, that is, segments transmitted containing one or more previously transmitted bytes.

PERF.LOCALHOST.TCP.Segments Sent/sec

Segments Sent/sec is the rate at which segments are sent, including those on current connections, but excluding those containing only retransmitted bytes.

PERF.LOCALHOST.Process(piarchss).% Processor Time PERF.LOCALHOST.Process(pibasess).% Processor Time PERF.LOCALHOST.Process(pinetmgr).% Processor Time PERF.LOCALHOST.Process(pisnapss).% Processor Time

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

Tag Explain Text

PERF.LOCALHOST.PI Archive.Read Events operations/sec

Rate of archive events read.

PERF.LOCALHOST.PI Archive.Cache Record Disk Reads/sec

Archive cache disk reads.

PERF.LOCALHOST.PI Archive.Cache Record Memory Reads/sec

Archive cache memory hits.

PERF.LOCALHOST.PI Base Subsystem.Point Count

Total number of defined points. This number includes the Connector Point Count.

PERF.LOCALHOST.PI Network Manager(_Total).Connections

The number of connections to the PI Network Manager. This counter only applies to instance _Total.

PERF.LOCALHOST.PI Network Manager(_Total).Messages Sent/sec PERF.LOCALHOST.PI Network Manager(piarchss).Messages Sent/sec PERF.LOCALHOST.PI Network Manager(pibasess).Messages Sent/sec PERF.LOCALHOST.PI Network Manager(pisnapss).Messages Sent/sec

The number of messages sent to the PI Network Manager.

PERF.LOCALHOST.PI Snapshot.OutOfOrderSnapshots/sec

Out of order events sent to the snapshot.

PERF.LOCALHOST.PI Snapshot.Queued Events/sec

Events sent to Event Queue.

PERF.LOCALHOST.PI Snapshot.Snapshots/sec

Events sent to the snapshot.

PERF.LOCALHOST.PI Update-Manager.Pending events

Total Events pending in the PI Update Manager database.

PERF.LOCALHOST.CALCULATED.PI Compression Ratio

PI Compression Ratio is a performance equation that calculates amount of data that is compressed.


Tag Explain Text

PERF.LOCALHOST.CALCULATED.PI Archive.Cache Hit Rate

PI Archive.Cache Hit Rate is a performance equation that measures the rate at which data is accessed from memory as opposed to disk.


TECHNICAL SUPPORT AND RESOURCES

Technical Support Options

Contact Rockwell Automation Technical Support at the following:

• Customer Support Telephone — 1-440-646-3434 • Online Support — http://support.rockwellautomation.com

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

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

Before You Call or Write for Help

When you contact Rockwell Automation 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


INDEX OF TOPICS

? command, 195 ?atr command, 195 ?tbl command, 195

piconfig, 182 Abbreviations, 234 Access Permissions

algorithm, 129 Changing, 129 read-write, 128

Active Directory Slow access to, 270

Activity grid, 269 Adding a digital state Set, 206 Alias Table

Batch, 220 Annot, 212 Annotations, 219 API

about, 102 on VMS, 101

API buffering. See buffering API Nodes, 102 application programming interface,

102 AppName field, 138 APS utility, 120 architecture

distributed data collection, 100 Archive

Archived Events counter, 31 Archiving Flag, 33 Cache, 32

combining files, 66 contents of, 30 Corrupted, 258 dividing, 66 dynamic, 40 file recovery, 286 Files, 38 Fixed, 40 full, 40 initializing, 63 Listing values, 215 Management, 37

data file, 286 Memory Cache, 32 Performance

daily monitoring, 30 Primary Archive, 51

Number, 32 Registering, 51 Reorganizing files, 65 Repairing the Registry, 261 Restore, 259 Sequence Number, 53 Shift

Enable Flag, 64 Prediction, 32

Archive Manager Data File recovery, 287

archive record size, 39

archive registry, 62 Archive Subsystem

performance counters, 352 Archive Subsystem

Troubleshooting, 245 archive walk, 54 archives

archive registry, 62 annotation files, 58 anticipating overflow, 57 archive shift, 37 archive shifts, 63 archive walk, 54 backfilling without compression, 59, 61 command-line tools, 41 creating, 57 creating new primary, 61 deleting, 62 editing data in, 57 failing to register, 61 fixed and dynamic, 37, 40 for previously collected data, 59 forcing archive shifts, 64 gaps, 38 ID conversion file, 48 index records, 39 list record details, 54 maximum size, 59 minimum and maximum size, 58 moving, 62 moving to another server, 48 naming, 58 offline utility, 45 piarchss parameters, 46 piarchss utility, 45 piartool utility, 42 precentage records used, 52 predicting shifts, 51 processing, 45 records, 39 registering, 62

registering, 37 shift p rediction, 63 size considerations, 58 sizing, 58 slow access, 39 space needs, 57 specifying maximum size, 59 specifying number of points, 59 time limit on modifying, 57 unregistering, 62

Archives About, 37

ArchiveX, 214 ASCII file

using in piconfig, 192 Attribute Point

Location4, 110 PointSource, 110

Attribute Set Table, 201 Attributes

Access Permissions changing, 130

Displaying, 183 For subsystems, 222 Istructure, 200 Llisting for table, 195 Modifying

in Point Database, 199 Wrong Class, 200

Set Point Database, 198

Time, 219 Timenum, 219

Automatic Point Synchronization, 120

Automatic Startup Compaq Tru64 UNIX Systems, 12 HP-UX 10 Systems, 9 HP-UX 9 Systems, 15 IBM AIX Systems, 14


PI Server, 7 Solaris UNIX Systems, 7 Windows Services, 7

backfilling archives creating new primary archive, 61 without compression, 59, 61

backfilling data, 59 Backups

Automating, 72 PI Server, 69 Recommendations, 72

Base Subsystem, 244 performance counters, 351

Batch Alias Table, 220 Batch method

piconfig, 180 Batch mode, 192 Batch Subsystem

Batch Unit Table, 219 Batch Tables, 221 BATCHEXPR, 219 BID

Batch Subsystem, 221, 228, 229

BIDsearch Batch Subsystem, 221

Boolean values, 236 buffer, 101 buffering

about, 101 maximum size of buffer, 102 recommendations, 101

Buffering PI API, 102

bufserv file buffer size, 102

Bye command, 192 BytesRecv, 224, 225 BytesSent, 224, 225 C language, API, 102 Case command, 234

Case-preserving, 234 Case-sensitive, 234

Digital State Set, 209 flag, 195 UNIX operating system, 180

Cd command, 196 Character

special, Changing, 237 t for true, 187

Classic Point Attributes, 198

Classicctr, 274 Clear command, 196 Client Applications

Connection Messages, 310 Security, 132

clock setting on interface nodes, 108

clock, system, 26 codes, error

operating system, 24 COM component

register, 296 COM Connector

in-process, 277 out-of-process, 278 troubleshooting, 272, 277 Web site, 272

Combining Archives, 66 ComChar, 196, 237 Comma Separated Format, 188,

200 Command

?tbl, 182 All in piconfig, 195 Bye, 192 Case, 234 character, 196, 237

piconfig, 180 Comm, 189 Endsection, 191 Error, 193

help, 185 Iistructure, 207 input, 234 Llisting all, 195 Ostructure, 189 Output, 193 piconfig commands, 185 Quit, 192 Select, 184, 190 Status

piconfig, 182 Table, 182

Command Line Arguments, 237 Command Specification

Persistence, 236 Comment, 196

Character, 196, 200, 237 Changing, 189

Command, 189 Lines, 189

Communication layer, 266 Routing function of PINet Manager, 243

COMP mode, Piarc Table, 215

Compaq Tru64 process count, 248

Compare mode, 187 compression

backfilling archives without, 59, 61 for backfilling archives, 59 out of order events, 26 ratio, 27

Compression Specifications, 27

compression tuning, 27 Computer platform

Information, 366 Connection Credentials, 134, 135

evaluating matches for, 141

firewall, 142 Connections

connection credentials, 134 Display info on, 224 ID, 311 Messages

Clients, 310 Subsystems, 311

slow, 270 ConStatus, 225 Consumer

pilistupd utility, 253 ConTime, 225 ConType, 225 conversion files, ID, 48 Convert mode, 187, 238 Corrupted

Archives, 258 non-primary, 256 Primary, 257

Count Batch Subsystem, 222 PIARC Table, 214 piartool -al, 52

counter events, 25 events in queue, 27 events in queue counter, 27 events sent to queue counter, 27 number of overflow queues, 27 out of order events, 26 out-of-order events, 26 remaining queue capacity, 28 snapshot events read, 27 total overflow events, 28

Counter Archive Memory Cache counters, 32 Archived Events, 31 Events Read, 31


number of archive read requests, 31 out-of-order event

archive, 31 Overflow Data Record, 34 Overflow Index Record, 33 PI Server Performance, 361

counter, point, 25 counters

performance, 351 CPU

Excessive usage of, 268 CPU usage

by utilities, 267 Create

Mode, 187 creating archives for old data, 59 creating new primary archives, 61 CSV format, 200 ctr_lmap, 274 ctr_progid, 274 ctr_strmap, 274 data

time limit on modifying, 57 Data

File repairs, 256 Recovering from corrupted archives, 256

Data Archive Adding values, 213

data buffering about, 101

data flow buffering, 101 snapshot, 24

Database Firewall, 233 Point, 63, 199 Timeout, 233 Trust, 231

Database Security, 181 Database Security Table, 230

Dates overlapping, 259

Daylight Savings Time and interface nodes, 108 customizing changes, 284 list of changes, 283

Dbsecurity, 181 DbsecurityTable, 230 Dcomcnfg, 273, 278 Default

Digital State Set, 206 default values

pigetmsg parameters, 21 Delete

Mode, 187 deleting archives, 62 deleting connection error message,

24 Delimited

Structure type, 188 Delimiter, 196

Character, 189, 197, 237 Command, 188 Format, 188, 237

Digital State, 5, 181 Table, 205

Digital State Set adding, 206, 207 capitalization, 209 Changing the Name, 209 default, 206 limits, 205 modifying, 207

Digital State Table merging systems, 161

Digital State Value Sending to the Snapshot database, 211

Digital tag Creating, 210

DigitalSet, 210 Directory

PIHOME directory on NT, 107 Disconnect Messages, 312 distributed data collection, 100 Documentation

conventions, v for interfaces, vi

Domain Name Server, 136 trust logins, 139

Domain Controller Slow access to, 270

Dr. Watson, 295 DST

and interface nodes, 108 Dump capability

crash pidiag, 295 dxWindows, 248 Dynamic archive, 40 dynamic archives, 37, 40 Echo, 196 Edit Mode, 187 Edit Mode Attribute, 216 editing archives, 57 Ellipsis construct, 191 End of file, 192 EndRecord, 196 End-Repeat, 196 Endsection, 196

Command, 191 Endtime, 214 error

messages interpreting, 24

Error code number

translating to message text, 281

Command, 193 messages, 299

interpreting, 299 Negative or Positive, 313

error messages

about, 24 deleting connection, 24 interpreting, 24 operating system, 24 rpc resolver, 24 subsystem health check failed, 24

EVEN interpolated events, Piarc, 215

event definition of, 25 in the event queue, 27 out of order, 26 overflow events, 28 remaining primary queue capacity, 28 sent to the Event Queue, 27

Event Log configuring, 275

event queue events in, 27 events sent to, 27 monitoring, 28 number of overflow queues, 27 remaining capacity, 28 total overflow events, 28

Event Queue recovery, 67 Troubleshooting, 245

Event Timestamps correcting, 260

events time limit on modifying, 57

events counter, 25 events in queue counter, 27 events read counter, 27 events sent to queue counter, 27 Excel

Adding tags to Point Database, 200

Exit, 192, 196 FactoryTalk Historian DataLink


Data access, 132 FactoryTalk Historian ProcessBook

Data access, 132 Failed to unregister input archive

message, 257 file buffer, 101, See also buffering

maximum size, 102 File corruption, 256 File handles, 248 File-base Utility, 285

compact, 286 index, 285

Firewall, 233 Database, 233

Modifying, 124 Security, 123 troubleshooting, 242

Fixed Format, 189 structure Structure type, 188

Fixed Archive, 40 fixed archives, 37, 40 Flag

Shift-enable, 64 Flags, 212 Flatline in a trend

troubleshooting, 271 Force processing, 207 Format

Delimiter, 188, 191, 237 Fixed, 189 Keyword, 189, 196

full, archive, 37 gaps

archives, 38 General Table Interface

Timeout, Firewall, Proxy, 232 Group

assigning users to, 133 Database, 132 table for, 228

Handle

Batch Subsystem, 221, 228, 233

Help Command, 185 lists all commands, 196

Hexadecimal notation, 238 Hostmask, 181, 233

Modify, 126 HP-UX

process count, 249 I/O

Redirection, 193, 194 IBM AIX

process count, 248 ID

PINetMgr, 225 ID Conversion File, piarchss, 48 index record, 39 Initialization

archive, 63 Input

Command, 192, 234 redirect, 196 to piconfig, batch files, 192

Installation Redirector, 273

Integer Format to String, 282 Interactive session

piconfig, 180 interface nodes

setting clock, 108 Interface Nodes

definition of, 100 Interface Status Utility, 120 interfaces

and PI API, 102 APS utility, 120 definition of, 100 Interface Status Utility, 120 setting system clock, 108

Interfaces

downloading documentation for, vi

internal counters piartool-qs, 28

Inter-process communication TCP/IP, 267 UNIX Sockets, 266

IP Address, 123 IPAddr

trust logins, 139 IPHost

trust logins, 139 Istat

Attributes, 213 Istructure, 189, 196, 200

Command, 207 Istype, 188 Key

primary, 184 Keyword, 189

Delimiter, changing, 188 Structure type, 188

Limit digital state sets, 205

limits, time, 57 List, 197

Mode, 187 primary key default, 190

LocalHost Statistics, 361

Location4, 110 Performance point, 119

Login, 197 explicit over trust, 142 Trust, 134

login, remote pigetmsg, 22

Manager. See PI Server System Manager

Mapped points, 274 Max_nprocs, 250 Maxerr, 197

Maximum data segment, 248 file handles/descriptors, 248

maximum archive size, 58, 59 maxpoints, 59 maxsize, 59 MaxUpdateQueue, 34 Maxuprc, 250 Maxusers, 250 message log, 20 Message Log, 2, 3, 243 message logs

message subsystem offline, 22 pigetmsg, 20 remote login, 22 rpc resolver error, 24 searching messages, 21 viewing on other servers, 23 viewing with pigetmsg, 20

Message Subsystem performance counters, 356

message subsystem offline viewing messages, 22

Messages Client Connection, 310 Disconnects, 312 Interpreting, 299 Normal Startup, 299 RPC Resolver, 312 Subsystem, 243 Subsystem Connection, 311

Method batch or interactive, piconfig, 180

Millisecond timestamps, 219 minimum archive size, 58 Mode, 197

Edit, 187 Piarc Table, 215 piconfig, 185, 187 Specifications, persistence, 236


t option, 187 Modify, 197

Command, 199 Specifications, 199

Module Database Repairing, 265

moving archives, 62 XE "conversion files, ID" to another server, 48

Moving PI Servers, 155 MsgRecv, 224 MsgSent, 224, 225 Name

Connection name, 225 naming archives, 58 Netmask

trust logins, 139 NetType, 225 Network

definitions, display the, 295 Router, 122 Security, 122

Network Manager performance counters, 358

NEWhostmask, 125 Newset keyword, 184 Newtag keyword, 184 NEWUnitName, 219 nodes, 100 NT

Interface installation PIHOME directory, 107

Octal notation, 238 offline archive utility, 41, 45

list of parameters, 46 Offline Archive Utility

ID Conversion File, 48 time conversion file, 48 Time Filtering, 48

offline mode pimsgss, 23

offline, message subsystem, 22

OpenVMS and PI API, 101

Operating System Error Codes, 313 Security, 122

Operators Modify Point Attributes, 199 piconfig, 190

OSBuild, 223 OSIsoft Universal Interface. See

UNIINT OSSysName, 223 Ostructure, 196, 197

Command, 189 Ostype, 188, 196, 197 OSUser

trust logins, 140 OSVersion, 223 Out of order event

counter archive, 31

out of order events compression, 26

out of order events counter, 26 Output, 197

Command, 193 overflow events, 28 Overflow Offsets

piartool -al, 52 overflow queues, 27 overflow XE "primary record"

record, 39 Overlapping dates, 259 Owner

point attribute, 129 Parameter

Passing an input file, 193 Passing as Output, 194 Timing, 233

Password, 133 blank, 134 changing, 134

default, 134 reset piadmin, 295

Path piartool -al, 52

PeerAddress, 225 PeerName, 225 Pending Number

pilistupd utility, 253 Performance Counter

PI Server, 361 performance counters

Archive Subsystem, 352 Base Subsystem, 351 Message Subsystem, 356 Network Manager, 358, 359 PEs, 358 Snapshot Subsystem, 355 SQL Subsystem, 356 TotalizerSubsystem, 357

performance equations performance counters, 358

Performance Equations Subsystem performance counters, 358

performance problems out of order events, 26

Permissions Attributes, changing, 130

PEs performance counters, 358

PI API about, 102 Buffering, 102 impact on system set number, 213 on VMS, 101

PI API buffering. See buffering PI Attribute Set Table, 201 PI Base Subsystem

Troubleshooting, 244 PI Batch Alias Table, 220 PI Batch Table, 221 PI Connections, 226

PI Message Log, 243 Subsystem, 243

PI Processes, 243 Running independently, 246 Sign up for updates, 313 Status, 242 Stopping interactively, 4

PI Proxy Database, 234 PI Server

Automatic Startup, 7 Backups, 69 data files, 250 Error Codes, 313 Message Log, 310, 311 moving PI Systems, 155 performance counters, 361 performance monitoring, 30 restore from backup, 258 Security, 122 Starting, 1, 299

Windows, 2 Winpdows, 2

Stopping, 1, 3 System Manager, 122

Security responsibilities, 122

Timing parameters, 233 tuning, 266

PI Server System Manager, 122

PI session performance counters, 359

PI Session Statistics, 359

PI Subsystem, 224 Table, 223

PI Subsystem Table, 222 PI System

merging two systems, 161 PI tables

how to select, 180


PI TagConfigurator, 179 PI Thread Table, 229 PI_GEN, 181, 232 Piadmin, 123, 130, 132

reset password, 295 Piarc, 181

Edit mode attribute, 216 Piarc Table, 214 piarchss, 41, 45

offline archive utility, 45 Piarchss, 245 piarchss -id, 48 piarchss offline utility

list of parameters, 46 Piarcmem.dat, 251 piarcreate, 41, 57 Piarcreate, 57 piarstat.dat, 62 Piarstat.dat, 251 piartool, 41, 42

-aw, 54 creating archives with, 57 deleting archives, 62 moving archives, 62 -qs, 28 registering archives, 62 unregistering archives, 62

Piartool, 57 -al, 51

results from, 51 -as, 30

piartool -ac, 57 piartool -acd, 57 piartool -ar, 62 piartool -au, 62 piartool -ooo, 26 piartool -ss

events counter, 25 events in queue counter, 27 events read counter, 27 events sent to queue counter, 27

number of overflow queues, 27 out of order events counter, 26 point counter, 25 remaining capacity, 28 total overflow events, 28

piartool -ss, 25 PIATRSET, 181 Pibaalias, 181, 220 Pibasess, 244 Pibatch, 221 PIBatch

considerations when merging systems, 162

Pibaunit, 181, 219 Piconfig, 133, 215

Abbreviations, 234 Commands, 185, 195, 237 Configuration.Persistence, 236 Echo command, 194 Modes, 187 Overview, 179 Remote sessions, 194 Starting, 180 Stopping, 180 using quotes, 234 values sent as strings, 236

pidemo user account, 132 pidiag, 279

about, 24 -ad, 286 -ahd, 288 -ar, 287 -ara, 287 -e errorcode, 281 -fb, 285 -fb utility, 250 -fbc <path>, 286 -fbf <path>, 286 -h or -?, 281 -host, 295 interpreting error messages, 24 operating system errors, 24

Recovery utility, 262 -rgs, 296 -t time <U>, 281 -tz, 282 -udf <path>, 295 -v, 281

Pidiag -crash, 295 Interpreting Error Messages, 313 Utility, 313 -w msec, 294

Pidiff Keyword

mappings, 238 Pidignam.dat, 251 Pidigst.dat, 251 Pids

Table, 205, 206 Pifilebase, 250 pigetmsg

about, 20 default values, 21 parameters, 20 remote login, 22 searching messages, 21 Utility, 243

Pigetmsg Utility, 299

pigrp, 132, 228 Pilastsnap.dat, 251 Pilistupd utility, 252

Troubleshooting, 244 pimaNNNN.dat, 251 Pimapevq.dat, 251 pimsgss

offline, viewing messages, 22

offline mode, 23 Pimsgss, 243 Pimsgtxt.dat, 251 PINet Nodes, 101

PINet/OpenVMS, 121 Manager Subsystem, 243

Pinetmgr, 243 Messages from, 310, 311

Pinetmgrstats, 224 PINetMgrStats, 181 piperfmon.dif, 361 Pipes

WIN32, 225 PIPoint, 198 Pipoints.dat, 252 Piptalia.dat, 252 Piptattr.dat, 252 PIPTCLS, 181, 203, 205 Piptclss.dat, 252 Piptunit.dat, 252 Pisetpass utility, 133, 134 Pishutev, 5, 242, 246 Pisnap, 211, See also Snapshot

Pisnap.dif list Snapshot values, 212

Pisnap2, 212, 213, See also Snapshot

Pisnapss, 245 PIStartupTime, 223 pistop.sh script, 4 Pisubsys, 222 PISubsys, 181 PISubsysName, 223 Pisubsysstats, 223 PISubsysStats, 181 PIThread, 181 Pitimeout, 181, 233 PITimeout Table, 34, 35 PItrust, 232 Piudsrdr.exe, 274 Piupdmgr, 244

Messages from, 313 PIUser, 228

field for trust logins, 141 Piusr.dat, 252 Piusrctx.dat, 252


Piusrgrp.dat, 252 Piverify.sh script, 242 PIVersion, 223 Point

access to, 131 data access, 128 Database, 199 Datagroup, 130 Dataowner, 130 object for security, 128 Ownership, Changing, 129 Point class, 198

Point Attributes access to, 128 Changing Owner, 129 Modifying, 199

With Operators, 199 Point Class

Base, 198 Point Class Database, 203, 205 point counter, snapshot, 25 Point Database, 63, 198

migration from PI2, 238 Repairing, 265 table name, 198

PointID, 211 PointSource attribute, 110

Command line parameters, 109 PoolName, 229 predicting archive shifts, 51 primary archive, 37 Primary Archive, 39, 51

Recovering, 257 primary archives

creating new, 61 failing to register, 61

Primary index Connection, 226

Primary key, 180 Default, 190

Primary Offsets

piartool -al, 52 primary record, 39 Priority

Trust Records, 142 PRODEXPR, 220 ProdIDsearch

Batch Subsystem, 222 Producer

pilistupd utility, 253 Prompt, 197 ProtocolVersion, 225 PtClass, 197 Ptclass command, 198 queue

number of overflow events, 28 number of overflow queues, 27 remaining capacity, 28

queue, event monitoring, 28

Quit command, 192 Quote, 197

character, 237 Quote marks

used in piconfig, 234 RampSoak, 246, 254 Random, 254 Random Simulator, 246 record

archive, 39 Record, 197

attributes, 184 Record Size

piartool -al, 52 records

determining percentage used, 52 listing details, 54

Records Trust, Weighting, 142

Recovery tool, 262 Recsep, 197 RecvErrors, 224, 226

Redirection Output to files, 194

Redirector confirming installation, 273 dump script, 276 starting, 273 troubleshooting, 272

registering archives, 62 Registry

archive, 62 regsvr32, 278 Remote

piconfig sessions, 194 Procedure Calls, 266, 311

remote logins pigetmsg, 22

Remove consumer from update table, 313

removing archives, 62 Repairs

Archive Registry, 261 Data file, 256 Excessive CPU Usage by Utilities, 267 Module Database, 265 Point Database, 265 Snapshot, 262 System Time, 264 Tuning the Server, 266

Repeating attributes Ellipsis construct, 191

Replacesp mode, 218 resolver error message, 24 Resolver Messages, 312 Restore

Archive, 259 PI Server from backup, 258 Subsystem Databases, 259

Reusing an Output File as an Input File piconfig, 194

Reverse Name Lookup, 136

Troubleshooting, 270 Root, 3, 122 Router, 122 rpc resolver error message, 24 RPCs, 266, 311, 312 Rval attributeAttributes, 213 Sam utility, 249 Scan classes, 110 Score

Trust Records, 142 SearchStart

Batch Subsystem, 222 Security, 121

Attributes Changing, 129

Client, 132 Default points, 131 Firewall, 123 Network, 122 Operating System, 122 Physical, 121 Scenario for Users and Groups, 128 Table Edits, 230 Tag, 128 Troubleshooting, 244 Trust Login, 134 User Name and Password, 132

Select, 197 command, 184, 190 PI table, 180

SendErrors, 224, 226 server messages, 20 Services

Troubleshooting, 242 trust login OSUser Names, 140

SET, 201, 203, 205, 206 SETNO, 201, 203, 206 Shift

Archives, 63 shift flag

piartool -al, 52


shift predicting, 51 shift, archive, 37 Shift-enable flag, 64 Shutdown Events, 4 Shutdown.dat, 4, 5, 252 Sigd, 197 Sign up for updates, 313 Significant decimal digits, 197 sinusoid, 246 Site-specific files, 2 size of file buffer, 102 size, archive records, 39 Smit utility, 248 SMT

about, vi snapshot

event count, 25 events counter, 25 events in queue counter, 27 events read counter, 27 events sent to queue counter, 27 listing current information, 25 monitoring data flow, 24 number of overflow queues counter, 27 out of order events counter, 26 point counter, 25 remaining queue capacity, 28 total overflow events counter, 28

Snapshot, 5 list values, 212 repairing, 262 Subsystem

Adding digital state values, 211 recovering, 263 Troubleshooting, 245

Snapshot Subsystem performance counters, 355

Span

Modify, 199 Special Characters, Changing, 237 Specifications

Compression, 128 Spreadsheet, 200 SQL Subsystem

performance counters, 356 Start

Messages, 299 PI, 1

UNIX, 3 Windows, 2

piconfig, 180 Redirector, 273

Starting PI, 2

Starttime, 214 State

piartool -al, 52 STATE, 206 State Sets

listing, 206 statistics

performance counters, 351 Status, 197

command, 182 PI processes, 242

Stdout, 2 Stop

PI, 1 on UNIX, 4 on Windows, 3

piconfig, 180 String to Integer Format, 282 Structure, 196, 198

Specifications, 190 Type, 188

STYP, 198 Stype, 188 Subnet, 124

specifying for trust login, 139, 150

Subsystem Attributes, 223 Connection Messages, 311 PI Message, 243 Restore from Backup, 259 Update Manager, 244

subsystem health check failed, 24 Sun

Solaris process count, 249

Superuser Privileges, 129

Sysdef utility, 249 SYST, 198 System

Clock resetting, 264

digital state set name, 206 set number, 213 Statistics, 223, 224

system aggregate compression ratio, 27

system clock, 26 on interface nodes, 108

system error codes, 24 System Management Tools, vi system message logs

pigetmsg, 20 System State Set

modifying, 208 Table

Attributes Displaying, 183 With Ellipsis, 191

Batch Alias, 220 Batch Unit, 219 Command, 198

piconfig, 182 Database Security, 230 For accessing the PI Archive, 214 Names, 180

how to list, 182 PI_GEN, 232 Piarc, 214 Pibaalias, 220 Pibatch, 221 Pibaunit, 219 Pids, 205, 206 PIFIREWALL, 233 Pigroup, 228 Pinetmgrstats, 224 Pipoint, 198 Pisnap, 211 Pisnap2, 212 Pisubsys, 222 Pisubsysstats, 223 Pitimeout, 233 PItrust, 232 PIUser, 228 Selecting, 180, 182 Snapshot, 211, 213 Specifications,persistence, 236

Tag Adding Values to the Snapshot Table, 213 creating, 210 Datagroup, 130 Dataowner, 130 Listing information, 186 Mask, for shutdown, 6 Removing point security, 131 Security, 128

TagConfigurator, 179 TCP/IP, 225

Default port, 243 Thread Table, 229

actions, 229 Threading, 268 Threads, 181 time

setting on interface nodes, 108 Time

Attributes, 219


conversion file, 48 Filtering, 48 future times in Snapshot

removing, 263 piconfig millisecond, 218 piconfig TimeFormat, 218 Time Zone, 282, 284 utilities, 281

time limits on modifying data, 57 Time Transformation Processing,

260 conversion file, 260

time zones and interface nodes, 108

TimeFormat, 218 TimeNum, 212 Timenum Attributes, 219 Timeout Database, 233 Timestamp

Corrections, 48 Millisecond, 219

Timformat, 198 Timing Parameters, 233, 266 Totalizer Subsystem

performance counters, 357 totalUpdateQueue, 35 TotalUpdateQueue, 34 Troubleshooting

Checklist, 239 PI Update Manager, 244 Redirector, 272 Strategy, 239

Trust Database, 134, 231 defining a record, 137 fields, 138 how to configure, 138

Trust Login, 134 evaluating, 141 examples, 144 installation, 143 network definitions, 295 shutdowns, 143

Trust Records Weighting, Score, 142

Tuning Utilities timeout value, 267

Tuning the PI System, 266 Type

Files, 250 piartool -al, 52

UniInt downloading documentation for, vi

UnitName, Batch Subsystem, 219, 221

Universal Interface downloading documentation for, vi

UNIX, 225 Case-sensitive, 234 Sockets protocol, 266

UNIX Process Stopping, 247

UNIX Process Quotas, 248 Unregister Archive

list unregistered files, 288 unregistering archives, 62 Update Manager, 34

MaxUpdateQueue, 34 Pending Update Limit, 34 Statistics, 360 TotalUpdateQueue, 34, 35 Troubleshooting, 244

Upgrade Post Upgrade Tasks on UNIX, 155

User Adding, 133 Database, 133 Name and Password Security, 132 Passwords

changing, 134 Table for, 228

User Group. See Group Utility

File-base, 285 piconfig, 132, 133, 179 pidiag, 279 pidiag -fb, 250 pidiag recovery, 262 pidiff, 179 pisetpass, 133, 134 sam, 249 smit, 248 sysdef, 249 time, 281

Values Attributes, Modifying, 199

Verifying PI Processes, 242 Version

piartool -al, 52 pidiag, 281

Visual Basic, API, 102 VMS

and PI API, 101 Wait for passed milliseconds

command pidiag, 294

Weighting Trust Records, 142

Wildcards, 191 WIN32 named pipes, 225 Windows

performance counters, 351 Stopping Processes, 247

Write Flag piartool -al, 52

Contact Rockwell

Documents

Transcript of Contact Rockwell