Server System Management

PI Server System Management Guide
PI3 Server
Version 3.4.370
© 1998-2006 OSIsoft, Inc. All rights reserved

OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: support@osisoft.com
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK

Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors

Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006

Send documentation requests, comments and corrections to customerfeedback@osisoft.com.
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PI Server System Management Guide is an in-depth manual that provides the
information and instructions that system administrators need to operate the PI System.
This guide includes comprehensive instructions to assist you in:
Using PI Server command-line tools such as PIConfig, PIDiag, and PIArtool
Configuration and tuning of your PI Server for optimum performance
Monitoring system health, and ensuring data preservation and integrity
Managing the Snapshot, Event Queue and Data Archive
Troubleshooting and repair
To effectively manage a PI System, follow the recommendations and procedures for each of
the following topics:
Starting and Stopping PI Systems
Backing Up PI Servers
Managing Archives
Managing Interfaces
Managing Security
Monitoring PI System Health
Moving, Copying or Merging PI Servers
For troubleshooting and performance issues, this guide includes Appendices of error
messages provided in the System Message Log, and an extensive list of performance
measurements (statistics) you can use to optimize the System.
PI Server System Management Guide Page iii

Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set includes seven user guides, described below.
Tip: Updated user guides, which provide the most up-to-date information, may be
available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management 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 A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide 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 A comprehensive reference guide for the system administrator and
Guide 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 An administration guide that explains the Audit Database, which provides a
Server 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 A guide to key add-on PI Server Applications: Performance Equations (PE),

Applications User Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality
Guide Control). Includes a reference guide for Performance Equations, and Steam
calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
Page iv
Conventions Used in this Guide

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

Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins that provide all the basic tools you need to manage a PI
System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management User Guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. Starting and Stopping PI ............................................................................................1
Chapter 2. Monitoring PI System Health ...................................................................................17
Chapter 3. Managing Archives ...................................................................................................33
Chapter 4. Backing up the PI Server..........................................................................................63
Chapter 5. Managing Interfaces .................................................................................................93
Chapter 6. Managing Security ..................................................................................................115
Chapter 7. Moving PI Servers ...................................................................................................147
Chapter 8. Copying a PI Server ................................................................................................151
Chapter 9. Merging Two PI Servers .........................................................................................153
Chapter 10. The piconfig Utility..................................................................................................171
Chapter 11. PI Troubleshooting and Repair..............................................................................225
Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................263
PI Server System Management Guide Page vii

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......................................................................16
Chapter 2. Monitoring PI System Health ...................................................................................17

2.1 Checking Key System Indicators...................................................................................17
2.2 Viewing System Messages .............................................................................................18
2.2.1 Available Log History............................................................................................18
2.2.2 Viewing System Messages with pigetmsg ...........................................................18
2.2.3 Viewing Messages When the Message Subsystem Goes Down.........................20
2.2.4 Viewing Message Log Files Generated on other Servers....................................20
2.2.5 Interpreting Error Messages (pidiag)....................................................................21
2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages) ................................22
2.3 Monitoring Snapshot Data Flow.....................................................................................22
2.3.1 Listing Current Snapshot Information with piartool -ss.........................................22
2.4 Monitoring the Event Queue...........................................................................................25
2.4.1 piartool -qs ............................................................................................................25
2.5 Monitoring the Archive ...................................................................................................27
2.5.1 piartool -as ............................................................................................................27
PI Server System Management Guide Page ix

Table of Contents
2.6 Monitoring the Update Manager ....................................................................................30

2.6.1 Adjusting the Pending Update Limit .....................................................................31
2.7 System Date and Time ....................................................................................................31
Chapter 3. Managing Archives ...................................................................................................33

3.1 Tasks for Managing Archives.........................................................................................33
3.2 About Archives ................................................................................................................33
3.2.1 About Archive Shifts .............................................................................................33
3.2.2 About Archive Files...............................................................................................34
3.2.3 About Primary Archives ........................................................................................35
3.2.4 About Fixed and Dynamic Archives .....................................................................35
3.2.5 About Read-Only Archives ...................................................................................37
3.3 Tools for Managing Archives .........................................................................................37
3.3.1 Using the piartool Utility........................................................................................37
3.3.2 Using the Offline Archive Utility (piarchss) ...........................................................40
3.4 Listing the Registered Archives ....................................................................................46
3.4.1 Determining an Archive Sequence Number from a Listing ..................................47
3.5 Listing Archive Record Details ......................................................................................49
3.5.1 Performing an Archive Walk with piartool -aw......................................................49
3.6 Estimating Archive Utilization........................................................................................51
3.7 Editing Archives ..............................................................................................................51
3.8 Creating Archives............................................................................................................52
3.8.1 Naming Archives ..................................................................................................52
3.8.2 Choosing an Archive Size ....................................................................................52
3.8.3 Selecting an Archive Type: Fixed or Dynamic......................................................53
3.8.4 Specifying the Number of Points in the Archive ...................................................53
3.8.5 Specifying the Maximum Archive Size .................................................................54
3.9 Creating Data Archives Prior to the Installation Date..................................................54
3.10 Creating a New Primary Archive ....................................................................................55
3.10.1 Registering an Archive .........................................................................................56
3.10.2 Unregistering an Archive ......................................................................................56
3.10.3 Deleting an Archive ..............................................................................................56
3.10.4 Moving an Archive ................................................................................................56
3.11 Managing Archive Shifts.................................................................................................57
3.11.1 Archive Shift Enable Flag .....................................................................................58
3.11.2 Forcing Archive Shifts...........................................................................................58
3.12 Combining and Dividing Archives .................................................................................59
Page x
Table of Contents
3.12.1 Combining Archives into a Single Archive............................................................59

3.12.2 Event Queue Recovery ........................................................................................61
Chapter 4. Backing up the PI Server..........................................................................................63

4.1 Planning for Backups......................................................................................................63
4.1.1 Choosing the Backup Platform (VSS vs. Non-VSS) ............................................63
4.1.2 Choosing a Backup Strategy ................................................................................63
4.2 Other Backup Considerations........................................................................................64
4.2.1 Guidelines for VSS Backups ................................................................................64
4.2.2 Guidelines for non-VSS Backups .........................................................................65
4.3 Guidelines for Backing Up Before Upgrading ..............................................................65
4.4 Automating PI Backups ..................................................................................................66
4.4.1 Automating Backups on Windows........................................................................66
4.4.2 Do a Test Backup .................................................................................................69
4.4.3 Do a Test Restore ................................................................................................70
4.4.4 Automating Backups on Windows with a 3rd Party Backup Application..............72
4.5 Automating Backups on a Windows Cluster................................................................73
4.6 Automating Backups on UNIX........................................................................................73
4.7 How The PI Backup Subsystem Works.........................................................................74
4.7.1 Principles of Operation .........................................................................................74
4.7.2 Selecting Files or Components for Backup ..........................................................75
4.7.3 The Backup Components of PI ............................................................................77
4.7.4 The Files and Components for each Subsystem .................................................78
4.7.5 Lifetime of a Backup .............................................................................................80
4.8 Launching Non-VSS Backups with piartool -backup <path>......................................83
4.9 Managing Backups with piartool ...................................................................................84
4.9.1 Backup Command Summary ...............................................................................84
4.9.2 piartool -backup -query.........................................................................................85
4.9.3 piartool -backup -identify ......................................................................................87
4.10 Timeout Parameters ........................................................................................................87
4.11 Troubleshooting Backups ..............................................................................................89
4.11.1 Log Messages ......................................................................................................89
4.11.2 VSSADMIN ...........................................................................................................90
Chapter 5. Managing Interfaces .................................................................................................93

5.1 Introduction......................................................................................................................93
5.2 General Interface Principles ...........................................................................................94
5.2.1 About PI Interfaces ...............................................................................................94
PI Server System Management Guide Page xi

Table of Contents
5.2.2 About PI Interface Nodes .....................................................................................94

5.2.3 About Data Buffering ............................................................................................95
5.2.4 About the PI API ...................................................................................................96
5.2.5 About the PI SDK .................................................................................................96
5.2.6 About UniInt-Based Interfaces .............................................................................96
5.3 Basic Interface Node Configuration ..............................................................................97
5.3.1 Install the PI SDK and/or the PI API.....................................................................97
5.3.2 Connect to PI with apisnap.exe............................................................................98
5.3.3 Connect with AboutPI SDK.exe............................................................................98
5.3.4 Configure PI Trusts for the Interface Node...........................................................98
5.3.5 Install the Interface .............................................................................................101
5.3.6 Set the Interface Node Time ..............................................................................101
5.3.7 Connect to the PI Server with the Interface........................................................102
5.3.8 Configure Points for the Interface.......................................................................103
5.3.9 Configure Buffering.............................................................................................104
5.3.10 Configure Interface for Automatic Startup ..........................................................106
5.3.11 Configure Site-Specific Startup Scripts ..............................................................107
5.3.12 Configure PointSource Table .............................................................................108
5.3.13 Monitor Interface Performance...........................................................................108
5.3.14 Configure the PI Interface Status Utility .............................................................112
5.3.15 Configure Auto Point Synchronization................................................................113
Chapter 6. Managing Security ..................................................................................................115

6.1 Physical Security...........................................................................................................115
6.2 Network Security ...........................................................................................................115
6.3 Operating System Security...........................................................................................116
6.4 PI Server Security..........................................................................................................116
6.4.1 Running applications on the system console .....................................................117
6.4.2 Running applications remotely ...........................................................................117
6.5 Firewall Security ............................................................................................................117
6.5.1 Firewall Database...............................................................................................118
6.6 Database Security .........................................................................................................120
6.6.1 PIDBSEC ............................................................................................................120
6.6.2 PIARCADMIN .....................................................................................................120
6.6.3 PIARCDATA .......................................................................................................121
6.6.4 PIBatch ...............................................................................................................121
6.6.5 PICampaign........................................................................................................121
Page xii
Table of Contents
6.6.6 PIDS ...................................................................................................................121

6.6.7 PIHeadingSets....................................................................................................121
6.6.8 PIModules...........................................................................................................121
6.6.9 PIPOINT .............................................................................................................121
6.6.10 PITransferRecords .............................................................................................121
6.6.11 PIUSER ..............................................................................................................121
6.6.12 Individual Subsystem Tokens.............................................................................121
6.7 Point Security.................................................................................................................122
6.7.1 Point Data Access ..............................................................................................122
6.7.2 Point Attribute Access ........................................................................................122
6.7.3 Access Algorithm................................................................................................122
6.7.4 Assigning and Changing Ownership and Access Permissions..........................123
6.7.5 How to Make All Points Accessible ....................................................................124
6.7.6 Security for Default Points in the PI Server ........................................................125
6.8 User Security .................................................................................................................125
6.8.1 Group Database .................................................................................................125
6.8.2 User Database....................................................................................................126
6.9 Trust Login Security......................................................................................................128
6.9.1 Connection Credentials ......................................................................................128
6.9.2 Defining Trust Records in the Trust Database ...................................................130
6.9.3 Evaluating the Match Between Trust Records and Connection Credentials .....134
6.9.4 New PI Server Installations ................................................................................136
6.9.5 Trust changes on System Startup ......................................................................136
6.9.6 Multiple Network Cards ......................................................................................136
6.9.7 Examples ............................................................................................................137
6.10 Resolving Ambiguities..................................................................................................144
Chapter 7. Moving PI Servers ...................................................................................................147

7.1 Preparation.....................................................................................................................147
7.2 Different Computer........................................................................................................147
7.3 Same Computer .............................................................................................................148
Chapter 8. Copying a PI Server ................................................................................................151

8.1 Understanding the Server ID ........................................................................................151
8.2 Situations where Server ID must be Addressed ........................................................151
Chapter 9. Merging Two PI Servers .........................................................................................153

9.1 Server Merging - Procedures .......................................................................................153
PI Server System Management Guide Page xiii

Table of Contents
9.2 Server Merge Procedure - Example.............................................................................156

9.3 Shut Down the Retired System ....................................................................................163
9.3.1 Add Retired Point Configuration to Destination System.....................................164
9.3.2 Add PI Batch Unit Configuration to Destination System ....................................165
9.3.3 Convert the Archives ..........................................................................................165
9.3.4 Merge the PI Batches .........................................................................................169
Chapter 10. The piconfig Utility..................................................................................................171

10.1 PI TagConfigurator & PI SMT Point Builder plug-in...................................................171
10.2 A Note to Pidiff Users....................................................................................................171
10.3 Key Concepts for Using Piconfig ................................................................................172
10.3.1 Starting and Stopping Piconfig ...........................................................................172
10.3.2 Interactive Session vs. Batch Method ................................................................172
10.3.3 Selecting PI Tables.............................................................................................172
10.3.4 Table Attributes ..................................................................................................174
10.3.5 Records ..............................................................................................................175
10.3.6 Piconfig Commands ...........................................................................................176
10.3.7 Mode...................................................................................................................178
10.3.8 Structure Type ....................................................................................................179
10.3.9 Select Command ................................................................................................181
10.3.10 Operators............................................................................................................181
10.3.11 Wildcards ............................................................................................................182
10.3.12 The Ellipsis (…) Construct for Repeating Attributes...........................................182
10.3.13 Endsection..........................................................................................................182
10.3.14 Exit......................................................................................................................183
10.3.15 Batch Methods....................................................................................................183
10.3.16 Security on Piconfig Sessions ............................................................................185
10.3.17 Remote Piconfig Sessions..................................................................................185
10.4 Piconfig Commands and Tables ..................................................................................186
10.4.1 Point Database Table .........................................................................................188
10.4.2 PI Attribute Set Table .........................................................................................191
10.4.3 Point Class Database .........................................................................................192
10.4.4 Point Source Database.......................................................................................194
10.4.5 Digital States Table ............................................................................................195
10.4.6 Snapshot and Snapshot2 Tables .......................................................................200
10.4.7 Archive Table......................................................................................................202
10.4.8 PI Batch Unit Table.............................................................................................207
Page xiv
Table of Contents
10.4.9 PI Batch Alias Table ...........................................................................................208

10.4.10 PI Batch Table ....................................................................................................209
10.4.11 PI Subsystem Table ...........................................................................................210
10.4.12 PI Subsystem Statistics Table ............................................................................211
10.4.13 PINet Manager Statistics Table..........................................................................212
10.4.14 PI Users Table....................................................................................................214
10.4.15 PI Group Table ...................................................................................................215
10.4.16 PI Thread Table..................................................................................................215
10.4.17 PI Database Security Table................................................................................216
10.4.18 PI Trust Database...............................................................................................218
10.4.19 PI General Table Interface .................................................................................219
10.5 Helpful Hints...................................................................................................................220
10.5.1 Abbreviations......................................................................................................220
10.5.2 Case-sensitivity ..................................................................................................220
10.5.3 Command Input Files .........................................................................................220
10.5.4 Input Line Length................................................................................................220
10.5.5 Using Quoted Strings .........................................................................................221
10.5.6 Sending Values as Strings .................................................................................222
10.5.7 Boolean Values ..................................................................................................222
10.5.8 Configuration Persistence ..................................................................................223
10.5.9 Command Line Parameters................................................................................223
10.5.10 Changing Special Characters.............................................................................223
10.5.11 Convert Mode Example ......................................................................................224
10.5.12 Converting Point Database Information from PI2 to PI Server...........................224
10.5.13 Hexadecimal and Octal Numbers.......................................................................224
Chapter 11. PI Troubleshooting and Repair..............................................................................225

11.1 Troubleshooting Checklist ...........................................................................................225
11.2 Verifying PI Processes..................................................................................................228
11.2.1 Verifying PI Processes on Windows Systems....................................................228
11.2.2 Verifying PI Processes on UNIX Systems..........................................................228
11.2.3 Communication with PINet Manager..................................................................229
11.2.4 Pimsgss ..............................................................................................................229
11.2.5 PI Update Manager ............................................................................................230
11.2.6 PI Base Subsystem ............................................................................................230
11.2.7 Snapshot Subsystem..........................................................................................230
11.2.8 Archive Subsystem.............................................................................................231
PI Server System Management Guide Page xv

Table of Contents
11.2.9 Pishutev ..............................................................................................................231

11.2.10 Random Interface ...............................................................................................232
11.2.11 RampSoak Interface...........................................................................................232
11.2.12 Running PI Processes Independently ................................................................232
11.3 UNIX Process Quotas....................................................................................................233
11.3.1 IBM AIX...............................................................................................................234
11.3.2 Compaq Tru64....................................................................................................234
11.3.3 HP-UX.................................................................................................................235
11.3.4 Sun Solaris .........................................................................................................235
11.4 PI Server Data Files .......................................................................................................235
11.5 Identifying the Update Manager Issues: the pilistupd utility ....................................238
11.6 Repairs............................................................................................................................241
11.6.1 Recovering Data from Corrupted Archives.........................................................241
11.6.2 Restoring a Complete Server from Backup........................................................243
11.6.3 Restoring Archives From Backup.......................................................................244
11.6.4 Restoring Subsystem Databases From Backup.................................................245
11.6.5 Correcting Archive Event Timestamps ...............................................................245
11.6.6 Repairing the Archive Registry...........................................................................246
11.6.7 How to Repair the Snapshot...............................................................................247
11.6.8 Recovering from Accidental Change to System Time........................................249
11.6.9 How to Repair the Point Database .....................................................................250
11.6.10 How to Repair the Module Database .................................................................250
11.7 Tuning the PI Server......................................................................................................251
11.7.1 Communications Layer of the PI Server.............................................................251
11.7.2 Resolving Excessive CPU Usage by Utilities .....................................................252
11.7.3 Identifying Abusive Usage ..................................................................................253
11.8 Solving Other Problems................................................................................................254
11.8.1 Failed Backups ...................................................................................................254
11.8.2 Slow Reverse Name Lookup ..............................................................................254
11.8.3 Slow Domain Controller Access .........................................................................255
11.8.4 Flatline in a PI ProcessBook Trend ....................................................................255
11.9 COM Connectors ...........................................................................................................257
11.9.1 Redirector Troubleshooting ................................................................................257
11.9.2 COM Connector Troubleshooting.......................................................................261
Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................263
12.1 General Information ......................................................................................................265
Page xvi
Table of Contents
12.1.1 Version Information ............................................................................................265

12.1.2 Error Code Translation .......................................................................................265
12.2 Time Utilities ..................................................................................................................265
12.2.1 Time Translations ...............................................................................................265
12.2.2 Time Zone ..........................................................................................................266
12.3 File-base Utilities ...........................................................................................................269
12.3.1 Dump File-base Data File...................................................................................269
12.3.2 Compact a File-base Data File ...........................................................................269
12.3.3 Recover File-base Data File Index .....................................................................270
12.4 Archive Management ....................................................................................................270
12.4.1 Dump the Archive Manager Data File ................................................................270
12.4.2 Automatic Recovery of the Archive Manager Data File .....................................270
12.4.3 Manual Recovery of the Archive Manager Data File..........................................271
12.4.4 Information about Unregistered Archives ...........................................................271
12.4.5 Verify the Integrity of Archive Files.....................................................................272
12.4.6 Downgrade Archive File to Older Versions ........................................................274
12.5 Server ID Utilities...........................................................................................................275
12.6 Performance Counter Utilities (Windows Only) .........................................................276
12.6.1 Get Performance Counter Path ..........................................................................276
12.6.2 Uninstall Performance Counters ........................................................................276
12.6.3 Get Performance Counter Values ......................................................................276
12.7 Miscellaneous ................................................................................................................278
12.7.1 Wait for Passed Milliseconds..............................................................................278
12.7.2 Testing Crash Dump Capability of an OS ..........................................................278
12.7.3 Reset Password to Blank ...................................................................................278
12.7.4 Display Network Definitions................................................................................278
12.7.5 Register a COM Component ..............................................................................279
12.7.6 Replaceable Parameter......................................................................................279
12.7.7 GUID Generation................................................................................................280
12.7.8 Machine-specific Programming Information .......................................................280
Appendix A: PI Messages .............................................................................................................281
Appendix B: PI Performance Counters .......................................................................................331
Technical Support and Resources...............................................................................................345
Index of Topics...............................................................................................................................347
PI Server System Management Guide Page xvii

TABLE OF TABLES
Table 3–1. Options for Use with piartool..................................................................................37

Table 10–1. PI Tables Accessible Through piconfig..............................................................172
Table 10–2. Piconfig Commands ...........................................................................................186
Table 10–3. Snapshot and Snapshot2 Tables Attributes ......................................................200
Table 10–4. Archive Table Attributes .....................................................................................202
Table 10–5. PI Batch Unit Table Attributes............................................................................207
Table 10–6. PI Batch Alias Table Attributes ..........................................................................209
Table 10–7. PI Batch Table Attributes ...................................................................................209
Table 10–8. Subsystem Table Attributes ...............................................................................210
Table 10–9. PI Subsystem Statistics Table Attributes ...........................................................211
Table 10–10. PINet Manager Statistics Table Attributes .......................................................212
Table 10–11. PI Users Table Attributes .................................................................................214
Table 10–12. PI Group Table Attributes ................................................................................215
Table 10–13. PI Thread Table Attributes ...............................................................................215
Table 10–14. PI Thread Table Actions ..................................................................................216
Table 10–15. PI Database Security Table Attributes .............................................................216
Table 10–16. Trust Table Attributes.......................................................................................218
Table 10–17. PI Timeout Table Attributes .............................................................................219
Table 10–18. PI Firewall Table Attributes ..............................................................................219
Table A–1. Error Codes 1-99, With Messages ......................................................................294
Table A–2. Error Codes 100-199, With Messages ................................................................297
Table A–7. Error Codes 1000-1099, With Messages ............................................................301
Table A–8. Error Codes 10000-10999, With Messages ........................................................302
Table A–9. Error Codes 11000-11999, With Messages ........................................................308
Table A–10. Error Codes 12000-12999, With Messages ......................................................314
PI Server System Management Guide Page xix

Table of Tables

Table A–12. Error Codes15000-15999, With Messages .......................................................321
Table B–16. PI Performance Counters ..................................................................................341
Page xx
TABLE OF FIGURES
Figure 6-1. Establishing PI Performance Monitor as a Windows Service..............................134

Figure 11-1. Distributed COM Configuration Properties ........................................................258
Figure 11-2. Windows Task Manager Processes ..................................................................259
Figure 11-3. Application Log Properties.................................................................................260
Figure 11-4. COM Connector Loading...................................................................................261
PI Server System Management Guide Page xxi

Chapter 1. STARTING AND STOPPING PI
The PI Server includes several separate processes that participate in startup and shutdown.
These are referred to as PI processes or PI subsystems. This section describes the relationship
between the processes, and the startup and shutdown scripts used to control them.
PI should only be started or stopped by the PI System manager. It is important to remember
that stopping PI affects all client applications, performance equation calculations, and the
archiving of data.
PI Server startup is performed with a pair of scripts: a generic PI startup script starts all PI
processes, which then calls a site-specific script to start interfaces and other site specific
programs. The system manager should modify only the site-specific script since the generic
startup script may be replaced during a PI Server upgrade. The actual file names of these
scripts vary with the operating system. Platform-specific details are provided in the following
subsections.
In general, the PI Server shutdown scripts are similar: a generic PI shutdown script calls a
site-specific script to shut down interfaces and site specific programs, and then shuts down all
PI processes.
Note: The only exception to this is shutting down PI processes running as individual
command windows. In this case, you must bring each window in focus and type
<CTRL-C>. Running PI subsystems in command windows is very rare; and usually
only encountered in troubleshooting scenarios.
It is important to configure Shutdown Events. Generally, points collected by interfaces

running on the PI Server node should be configured for shutdown events; points collected on
remote, buffered nodes usually are not configured for shutdown events. See Stopping PI on
page 3.
Production systems are usually configured so that PI is automatically started when the
computer is powered on. See Automatic Startup on page 6 for more information.
1.1 Starting PI
The PI Subsystems may take several minutes to start. Remote or PI API based interfaces and
other applications are blocked from connecting until the core PI Subsystems have completed
startup. The connection blocking is accomplished by opening the TCP/IP listener when the
core subsystems are ready to service requests. The following message is posted to the PI
Server log when the listener is opened:
PI Server System Management Guide Page 1

Chapter 1 - Starting and Stopping PI
>> TCP/IP connection listener opened on port: 5450

Connection attempts before the listener is opened will fail. Interfaces will retry until a
connection is made.
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.
Page 2
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.

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

! login info - only localhost is supported

localhost
! tag mask
*
! attrib selection
! add here point attributes,value to select points receiving shutdown
shutdown,1
! pointsource,R*
! location1, 1
! etc...
To specify more than one tag name use a tag mask. The tag mask may contain the wildcards *
and ?. The symbol * matches all possibilities with any number of characters. The symbol ?
matches a single character and may be used any number of times.
Caution: Do not specify additional tags by appending comma separated tag masks
or by using additional lines. Only one tag mask may be specified.
If you do not specify a tag-mask, the interface exists with an error. To prevent all shutdown
events, specify a tag mask that does not match any tag.
Other point attributes and values may be used in addition to or instead of the shutdown flag.
These conditions are logically ANDed together.
For example, the following configuration file selects only tags that start with s, have the
location1 attribute set to 0, and Pointsource set to H. No other tags will receive shutdown
events.
! tag mask
s*
! point attributes
location1,0
pointsource,H
If no point attributes are specified, all tags specified by the tag mask are selected to receive
shutdown events.
Caution: The Shutev process is used to execute post installation procedures;

therefore the Shutev process should not be disabled or removed from the normal
startup procedures. The shutdown.dat file, or point shutdown attribute should be
used to prevent writing shutdown events.
1.3 Automatic Startup
The procedure to configure PI for automatic startup depends on the operating system.
PI Server on Windows is normally run as a collection of services. The installation procedure
provides a dialog to optionally set automatic startup on reboot. The reboot startup behavior of
PI can also be set using the Control Panel Services applet.
Page 6
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.

#!/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*
Page 8
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.
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
#!/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
directory:
Page 10
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
those directories.
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)
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
#!/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
Page 12

# places
#
cd /opt/pi/adm
ksh pistop.sh
fi
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
those directories.
root> sh /sbin/rc2.d/K04PI stop
root> sh /sbin/rc3.d/S96PI 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 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
Page 14
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
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.
If there is any problem with stopping or restarting PI, you will need to restore your original
/etc/rc file, and remove the new file from the /etc/shutdown.d directory.
1.4 Shutting Down an Individual Subsystem
Shutting down an individual subsystem depends on the operating system. On Windows, look
in the file adm\pisrvstop.bat for the shutdown procedure; on UNIX, adm/pistop.sh. For restart
procedure check adm\pisrvstart.bat and adm/pistart.sh onWindows and UNIX, respectively.
Page 16
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 pigetmsg

whether unusual events have occurred.
Update Manager Are the clients connecting to the pilistupd

PI Server normally?
Tag Data Does the Archive data for a reference tag pisnap.bat or pisnap.sh
look normal?
Snapshot data Is the Snapshot data flow normal? piartool -ss

flow
Archive data flow Is the Archive data flow normal? piartool -as and piartool -qs
Archive Shift Verify that the expected archives are piartool -al
registered and that you have prepared
for the next archive shift.
Interface Logs Check the interface logs to see whether

unusual events have occurred.
IO Rate Interfaces support writing snapshot rates PI Datalink or PI ProcessBook to

Counters to PI Points. The IO rate values and view or trend the IO rate points.
timestamps are a good indicator of
interface health.
Performance All Subsystems publish key performance Windows Performance Monitor.

Counters counters to Windows. Subsystem PI Performance Monitor
(Windows) counters are discussed in this chapter. Interface.
License limits Check the usage statistics and point piartool -lic
and usage counts for your system. Anticipate
license increase needs.

Chapter 2 - Monitoring PI System Health
2.2 Viewing System Messages
During normal operation, the PI Message Subsystem maintains a central log file for messages
from all PI subsystems. PI creates a new log every day, on universal time coordinate (UTC)
time. PI puts the log files in the PI\log directory and names each log according to the date.
The file names are of the form, pimsg_YYMMDD.dat, where:
YYY is years since 1900 (for example,if the year is 2000, YY is 100)
MM is the month (for example, if the month is January, MM is 01)
DD is the day (for example, if it is the fifth of the month, DD is 05)
For example, the log file for January 5, 2000 is named pimsg_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.
Page 18
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:

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
Page 20
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
[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
Total Overflow Events: 0 0
Primary Capacity Remaining: 2540349 0
Page 22
2.3 - Monitoring Snapshot Data Flow
Each of the counters in the output is explained in the following sections.
Note: The piartool utility can monitor a remote PI Server by specifying the -remote
argument after all other arguments. piartool prompts the user for remote connection
information.
Point Count
The Point Count is the number of points that are currently defined in the Point Database. It is
incremented when a point is created and decremented when a point is deleted.
Snapshot Events Counter

An “Event” is the fundamental PI data element. It represents a value or status of a unique data
source at a specific time. Specifically an event is a Value, Timestamp, and PointID. Most
events come from PI API- or PI-SDK-based interfaces. The PI Subsystems (“Applications”)
PI Batch, PI Performance Equations, PI Total, and PI Alarm, as well as manual input and
laboratory systems are also event sources.
Every Snapshot event increments the Snapshot Events Counter. The PI Snapshot Subsystem
applies a compression algorithm to every event. The compression algorithm determines if the
previous Snapshot event is passed on to the archive.
Out of Order Snapshot Events Counter

Events older than the current Snapshot event are out-of-order events. These events bypass
compression and are sent directly to the archive. This counter shows the number of times this
has occurred. The Archive Subsystem maintains a similar counter; see the Monitor Archive
section in this chapter.
Large out of order event counts might indicate a problem with the PI Server; this may lead to
poor performance. A common cause is an erroneous system clock changes of the server
machine or a data source machine. To identify the tags receiving out of order data use:
piartool -ooo
This gives a list of all the tags with any out of order events since the Snapshot Subsystem
started or since the out of order flags reset. To reset the flags use:
piartool -ooo -r
When the -r flag is used, only tags that received an out-of-order event since the last piartool -
ooo query are listed. The utility can run repeatedly with or without the -r flag by specifying a
wait time (in seconds) between repeats. This is useful for catching the offending tags as new
events come in:
piartool -ooo 10
Whenever a repeat time is specified, a current timestamp appears in the output each time the
utility writes data.
When using repeats, the utility is stopped with <CTRL-C>.
$ piartool -ooo -r 10

7-Aug-03 14:42:12> The following points had out-of-order Snapshot

events:
15: pitot1
17: pitot3
18: pitot4
19: pitot5
20: pitot5run
21: pitot5ramp
22: pitot5est
23: pitot_avg
24: pitot_max
25: pitot_min
26: pitot6count
27: pitot6time
28: pitot6timeNE
29: pitot_1
7-Aug-03 14:42:22> No out-of-order Snapshot events found
7-Aug-03 14:42:32> No out-of-order Snapshot events found
Snapshots Events Read Counter

Count of all Snapshot reads. This is a simple measurement of how many Snapshot values are
read by all applications.
Events Sent to Queue Counter

Events that pass compression, or are out of order are sent to the Event Queue, and thus
increment this counter. Under normal operating conditions this count indicates the number of
events that passed the compression test (that is, the events were different from existing events
and could not be eliminated) and are being sent to the archive.
The ratio of Snapshot events to Events Sent to Queue is the system aggregate compression
ratio. This ratio gives a quick view of overall system compression tuning. Ratios less then 2:1
indicate low compression; a compression tuning evaluation should be performed. Ratios
greater than 10:1 indicate over compression; a compression tuning evaluation should also be
performed.
Three Point Database attributes affect compression: CompDev, CompMin, and CompMax.
These are known as the compression specifications.
If a point has its Compressing point attribute set to FALSE, all new events are sent to the
Archive Subsystem.
Events in Queue Counter

Events passed to the EventQueue are put in First-In-First-Out order. The Events in Queue
Counter is incremented when the event is put in the Queue; it is decremented when the
Archive Subsystem successfully retrieves and processes an event.
When the system is shutdown, the Event Queue is preserved in the file PI\dat\pimapevq.dat.
This assures no data loss when the system shuts down or when the archive subsystem is not
processing events at the same rate as they come in.
Page 24
2.4 - Monitoring the Event Queue
Number of Overflow Queues Counter

If the queue PI\dat\pimapevq.dat becomes completely full, a new queue is created. This
should not occur under normal circumstances and this number will be 0. However, if the
archive is not processing events, a number of such queues (up to 65536) can be created. This
counter shows how many queues were created. These additional queues are automatically
deleted after the archive subsystem processes them.
Note: When multiple Event Queues exist, the file pimapevq.dat is renamed to
pimq0000.dat and additional queues are named pimq<id>.dat where id is the queue
number in hexadecimal representation (from 0000 to FFFF). The piartool -qs
command always shows information from the queue to which the Snapshot
Subsystem is writing (primary queue).
Total Overflow Events Counter

This is the total number of events in all Overflow Queues. The sum of this counter and the
Events in Queue counter are all the events not yet processed by the archive.
Primary Capacity Remaining Counter

This counter shows the estimated number of additional events that can be placed in the
primary queue.
2.4 Monitoring the Event Queue
After installation and regularly after significant changes, the System Manager should verify
the proper sizing and functioning of the Event Queue. The command piartool -qs allows you
to look at internal counters and statistics about the queue activity.
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
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).
Overflow Queues
When the current queue is entirely full, the Snapshot Subsystem creates additional queue files
of the same size. The Overflow Queues counters and Total Overflow Events (same as in
piartool -ss) indicates how many queues exist and how many events they hold. The Current
Page 26
2.5 - Monitoring the Archive
Queue Id shows the sequence number of the primary queue (always 0 under normal
conditions).
2.5 Monitoring the Archive
On a daily basis, the System Manager should look at the internal counters for the Archive
Subsystem. This enables you to predict the next archive shift as well as to monitor ongoing
system behavior and performance. You can use piartool -as and piartool -al for this purpose.
Other piartool commands are discussed in the chapter, Managing Archives.
Note: Windows-based PI Server exposes the Archive data displayed by piartool -as
as Windows Performance Counters. These counters may be viewed with the
Windows Performance Monitor or recorded to PI Server with the OSI Performance
Monitor Interfaces. This subject is covered in detail later in this chapter.
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
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 37.
Archived Events Counter

The Archived Events counter is incremented for every new event written to the archive (via
the archive cache). This count includes delete and edit events.
Out-of-Order Events Counter

The Archive Subsystem receives events from the Snapshot Subsystem. If the timestamp of
the event is older than the last event in the target record, it is considered an out-of-order event
and is added to this counter.
Excessive out-of-order events might lead to system problems such as excess CPU
consumption, excessive disk I/O, and archives filling faster than expected.
Events Cascade Count

Out of order events are inserted into the target record. The insert requires moving other
events within the record. If the record is full, one or more events are forced out of the record
into the adjacent record. This counter is incremented each time an insertion forces an event
out of a record. This counter is an indication of the impact of out of order events on the
archive.
Events Read Counter

Number of events read by all applications. For example, a trending application requests an
array of events over a specified time period. This counter is incremented for each event
returned.
Read Operations Counter

Number of archive read requests. Each archive read request increments this counter once,
regardless of the number of events returned.
Archive Memory Cache Counters

The Archive Subsystem uses a memory cache when handling events sent to the archive disk
file.
During routine operation, the cache is automatically flushed to disk at least every 15 minutes.
Abrupt system shutdowns, such as power loss, should lose no more than the last 15 minutes
of data. This value may be changed via a configurable timeout table parameter.
The data archive cache architecture provides large performance gains over reading and
writing directly to disk. The cache even provides significant performance over the Operating
System file cache. As with all file cache designs, the disk image will often be slightly
inconsistent; therefore archive backup cannot be performed without coordination with the
Archive Subsystem. The utility piartool -bs places the archive in a safe consistent state for
backups; piartool -be returns the archive to normal operation. This is discussed in detail in
the system backup section in Chapter 3, Troubleshooting and Repair.
Page 28
2.5 - Monitoring the Archive
The cache consists of archive records loaded into memory. Records are added as needed; they
are deleted when unused for a certain length of time. Cache Record Count yields the current
count. Cache Records Created is incremented when memory is allocated for a new record.
When archive data is requested (for example, the user is trying to trend a point in PI
ProcessBook), the Archive Subsystem goes to the cache to retrieve the event data. If the
record is not there, the Archive Subsystem loads the record from disk to the cache; Archive
Record Disk Reads is incremented.
When writing events to the archive, they are stored first in memory. Unflushed Events
Counter indicates the total number of events not yet flushed to disk. Unflushed Points counter
indicated the number of points with any number of events not yet flushed.
Archive Record Disk Writes is incremented each time a record is written to disk. This occurs
during the regular cache flush every 15 minutes. It also occurs when the number of 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.
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
The Update Manager provides change notification of Snapshot events, Point Database,
Module Database, Batch Database and Archive changes for applications such as PI
ProcessBook, Interfaces, and other PI API or PI-SDK-based applications. For example, a
trend application can request Snapshot update notification on points being trended. The
Update Manager queues all new Snapshots for these points. Periodically the trend application
retrieves and plots the new events.
Page 30
2.7 - System Date and Time
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.
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.
Page 32
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 56
for more information.

Chapter 3 - Managing Archives
If no eligible archives are available for an Archive Shift, PI uses the oldest available filled
archive as the new Primary Archive, overwriting the data in the old archive. For example in
the preceding illustration, after the shift from piarch.003 to piarch.004, no empty registered
archives are left on the Server. If the System Manager does not create new archives on this PI
Server, then at archive shif piarch.001 becomes the next Primary Archive and the PI Server
overwrites the existing data in that archive.
It takes PI a few minutes to complete an Archive Shift. During that time, you are not allowed
to add, edit or delete points. PI stores incoming data in the Event Queue until the shift is
complete and then writes the queued events into the new Primary Archive.
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
Page 34
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.

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.
Page 36
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 Enable/Disable the archive activity grid, and list the
Grid Archive access information.
-ac Archive create Create an archive for specified period
-acd Dynamic archive Create a dynamic archive for specified period.

create

Option Name Action
-ads Archive disable Removed specified archive from shift participation.

shift
-aes Archive enable Add specified archive to shift participation.

shift
-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'] [- Perform a System Start/End/Query a backup of the PI system. The

component <comp>] Backup path points to where the resulting backup files are
[-numarch <number>] placed. The optional component specifies which
part of the PI system is backed up. The numarch
[More Options listed option specifies how many archives (starting from
under Action] 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 Archive cache diagnostics for a specified point.
diagnostics Display the events sitting in the read and write
cache.
-cas ['tagmask'] Archive cache Display a summary of the contents of the archive
summary cache, including the number of events in the Read
and Write caches for every point that matches the
tagmask.
-cs PINetmgr PI Network Manager connection stress test.

[For troubleshooting connection stress
only] test
-de <path> Dump eventqueue Dump specified Event Queue file.

[-pt tagname] [recno] Optionally select a specific tag and/or specific
record in the file.
Page 38
Option Name Action
-disconnect - Force Subsystem Force the specified subsystem to disconnect from

subsystem <name> [- Disconnect pinetmgr, or if pinetmgr is specified, instruct
id <id>] pinetmgr to disconnect the connection based on
[For troubleshooting the connection ID passed.
only] 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> ID conversion file Create ID conversion file from specified input file.
-idco <outfile> creation
-lic [Options listed Licensing Usage List options for viewing license info
under Action] Information 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> Message protocol Log all communication coming to and from the
[For troubleshooting trace server.
only] To enable tracing run with -mpt 1. Call a second
time with -mpt 0 to stop tracing.
The resulting output file appears in the “\pi\temp
directory” with the .mpt extension.
The file can be read with the mptconsolveview
utility, which OSISoft provides on request, e.g.:
Mptconsolveview .\24-Aug-05_12-10-06.mpt
-msg "message" Message Sends a series of test messages to the PI

[-pro "procname"] Subsystem Test message log. Can emulate sending messages
from any process. Nrep sets how many messages
[-nrep m] are sent, nbuf sets how many messages are sent
[-nbuf l] at a time, nmps attempts to throttle how many
[-nmps n] messages are sent per second.
[For troubleshooting
only]
-msgtest <startsize in PINetmgr Send a series of test messages to the PInetmgr.

bytes> <endsize in Communications Message size increases by one byte increments
bytes> Test starting from startsize to endsize.
only]

Option Name Action
-netstress PINetmgr stress Test PINetmgr subsystem by sending and

[-SendBlocks 1] [- test. receiving specified 4k blocks.
RecvBlocks 1] [-loops
1]
only]
-ooo <-r><Sec> Out of order snap Show tags with Out of Order events. Optional
events Reset and Repeat.
-qs Queue statistics Monitor Event-Queue activity and statistics
-re [-subsystem Raise Exception Raise exception in specified subsystem (force a

<name> crash). This call only works locally; remote is not
|-pid <#> ] supported.
only]
-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> Inter-process Times the RPC round trip to the specified sub-
<count> Communication system.
[For troubleshooting Test
only]
-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' Subsystem Thread -info List a subsystem's threads

[Options listed under Control -id <Thread ID>
Action]
<-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
Page 40
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 Required. The full path, including drive letter is
File required. This is true for all file arguments passed.
-of <full path name> Output Archive Required.

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

Parameter Name Notes

See “Specifying an End Time for the Output File (-oet).”
-f <size in Mbytes> Make output If size = 0, the input file size is used. Default is dynamic
archive a fixed archive.
archive
-tzf <full path name> TimeZone Use when PI2 input different from standard DST - see
specification also the PI Server Reference Guide, Appendix D.
file
-filter <start end> Filter Process events only within the time range specified.
Both timestamps must be provided. See “Time Filtering
(-filter).”
-dup Duplicate Allow input archive records with duplicate times. By

Records 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 Apply a validation algorithm. Multiple events

Annotation referencing a single annotation are detected and fixed.
Handles 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 Sets the start time to the specified time string. Times are specified in absolute PI
(where time is time format. Relative times are not supported. Times must be enclosed in double
specified in quotes when containing spaces. If only date is specified the time defaults to
absolute PI 00:00:00 (midnight)
time format) 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.
Page 42
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 Sets the end time to the specified time string. Times are specified in absolute PI
(where time is time format. Relative times are not supported. Times must be enclosed in double
specified in quotes when containing spaces. If only date is specified the time defaults to
absolute PI time 00:00:00 (midnight).
format) 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.
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):
Page 44
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.
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.
Here is a sample archive listing:
D:\PI\adm>piartool -al
Archive shift prediction:
Shift Time: 5-Oct-05 19:42:01
Target Archive: e:\pi\arc\piarch-2GB.1
Archive[0]: e:\pi\arc\piarch-2GB.3 (Used: 53.4%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Page 46
3.4 - Listing the Registered Archives
Version: 7 Path: e:\pi\arc\piarch-2GB.3

State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 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.
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
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
Page 48
3.5 - Listing Archive Record Details
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
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]:
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 Meaning

Coding
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)
Page 50
3.6 - Estimating Archive Utilization
Index shows whether the values in the records are data values or pointers to data records,
where 0 indicates that it is NOT an index record. If they are pointers, the pointers are actually
record numbers corresponding to the start time. When events for a point exceed two records
in a single archive, an index record is created. An index record holds about 150 pointers to
data records.
RecNo (Record Number) is a read-only point attribute which contains a pointer to the point's
primary record in the archive. This is useful when using tools such as piartool -aw to
examine the archives. Do not confuse RecNo with the PointID attribute. If the point is
deleted, the RecNo will be reused but the PointID will not.
Data Type Meaning
8 Int32 (all records which have the index flag set will also show datatype 8)
12 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 272.
The archive offline utility will repair any chaining problem.
3.6 Estimating Archive Utilization
The space that a fixed archive uses is completely allocated at archive creation time. Use
piartool -al to list the registered archives. For each archive an estimate of the used space is
displayed.
3.7 Editing Archives
The piconfig utility, the PI API and the PI-SDK may be used to add, edit, or delete archive
values.
Note: Contrary to the above title “Editing an Archive”, all archive edits are first
handled by the Snapshot Subsystem. The Snapshot Subsystem performs some
security and data checks then, if appropriate, forwards the edit events to the Archive
Subsystem.

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.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
Page 52
3.8 - Creating Archives
Maximum archive size is 2 Terabytes (2000 Gigabytes).

The archive size affects backups, frequency of shifting, and total number of points allowed
The general rule is to size your archives such that they last three to five weeks before shifting.
How Archive Size Affects Shifting Frequency

If the PI Server has larger archive files, the shift will occur less frequently. To decide what
archive size is optimal for your system, consider the backup device, available disk space and
average incoming data rate. These will determine the shift frequency.
How Archive Size Limits Point Count

It is important to note that the archive size limits the number of points that may be created.
No more than 1/2 of the archive records of a fixed archive can be primary records. If the
allotment of primary records gets used up, you will get an error if you try to create an
additional point, even though the primary archive is not full. To resolve this, force the
archives to shift into a larger archive in order to create additional points. Archive shifting can
be forced using the command piartool -fs.
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
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
Note: Entries that allow access to specific names or addresses override the
above “disallow”. Edit all other entries to “Disallow”. Local connections are not
affected by pifirewall entries; make applications that may write data are not
running.
3. Start PI with the -base parameter. This ensures that PI starts up with only the
minimum required subsystems.
On Windows hosts, issue the command:
pisrvstart.bat -base
4. Create and register archive files for the backfilling period (using piartool -ac or -
acd).
5. Insert one event for every point at the earliest time on-line.
6. Delete all the PointCreated events from the snapshot. This will bring into the
snapshot the old events. Steps 5,6 can be done with a PI API or PI-SDK program or
using the piconfig utility. Make sure that the old event is in the snapshot.
Page 54
3.10 - Creating a New Primary Archive
7. Backfill the archives by reading in the data In Time Sequential Order. This way the
data is compressed.
Caution: The Archive Subsystem assumes the archive end time is the most
recent time stamp written to any point. It is important to keep all current data
sources from writing to the PI Server. This is why Random, Ramp Soak,
Performance Equations, PI Total, PI Alarm, or any other interfaces cannot be
running.
8. If you used the technique of modifying the PIFIREWALL table in Step 4 above, run
piconfig to either change the hostmask value to Allow or to delete the above
hostmask altogether.
9. Start the interfaces using pisitestart.sh or pisrvsitestart.bat.
Backfilling Data without Compression

1. Install PI Server and create all points. The points that you want to backfill must be
created prior to the archive initialization, otherwise the archive has no primary
records for these points.
Note: An archive can be created with a start time prior to point creation time, as long
as the point exists when that archive is created. Reprocessing an old archive with
the offline utility adds to that archive all existing points, while preserving all the old
data.
2. Use piartool -ac to create and initialize back fill archives. The start and end times
must be specified (that is why piarcreate cannot be used). The start time should be
the timestamp of the oldest data to be backfilled; the end time should be just prior to
the oldest archive time specified using piartool -al.
3. Backfill the data. The data that you backfill will not be compressed, since it is prior
to the snapshot time.
4. If the backfill archive is filled before all of the backfill data is entered, you must
delete the backfill archive, and create two backfill archives, dividing the target time
range between the two, or creating a single larger archive, and then retry the data
backfilling.
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
requires some additional steps, since you cannot unregister it while the PI archive process is
running.
To move the primary archive, do the following:
1. If any empty archives exist in the original directory, move them to the new directory
and register them there. One of these archives will become the new primary archive.
2. Verify that there is at least one empty archive registered in the new directory (create
one if there is not one).
3. Force an archive shift using piartool -fs. This will result in a new primary archive,
which is one of the empty archives in the new directory.
4. Move the previous primary archive to the new directory by the usual method:
unregister it, copy it to the new directory, and then re-register it.
Note: Renaming archive files is generally not necessary. If you must do this,
remember to rename the annotation file as well. Check the release notes for a
description of issues associated with archive file renaming.
Page 56
3.11 - Managing Archive Shifts
3.11 Managing Archive Shifts
When the primary archive file becomes full, the next empty (shiftable, writeable) archive is
used to store the new data. If none of the archives are empty, the archive file with the oldest
data (which is also shiftable and writeable) is cleared and used for new data. The start time of
this archive is set to the end time of the archive file that just became full.
The process of clearing the oldest archive and preparing it to be the new primary archive is
called an archive shift. It is important that all eligible archives are backed up prior to the
archive shift to ensure that no data is lost.
When an archive is assigned a start time, it is initialized. Archives are only initialized at
installation and during an archive shift.
The archive shift process takes a few minutes to initialize a new archive file. Adding, editing,
or deleting points is not allowed during archive shift. Events sent to the Archive during an
archive shift are queued. When the shift is complete, the queued events are written to the
Archive.
Which Archives are Shiftable

For an archive file to be eligible to be the new primary archive, it must be registered,
shiftable, writeable, and large enough to handle the current size of the Point Database. If an
archive does not meet these criteria, it will be skipped over during an archive shift. By
making an archive non-shiftable or read only, an archive may be excluded from the shift
cycle.
Predicting Time of Next Archive Shift

The command piartool -as is used to monitor archive activity, performance and to estimate
the next archive shift
The utility piartool -as predicts the time for the next archive shift. The prediction is based on
the average number of archive records consumed per hour, plus the rate of consumption. If
the primary archive is less than 20% full, the prediction is based on the previous archive
rates.
Archive Shift Enable Flag

Fixed archives of varying sizes can be shifted. However, archives that are too small to
accommodate the number of points in the Point Database are automatically excluded from
archive shifts. Used dynamic archives are never shiftable.
Both fixed and dynamic archives have a shift-enable flag. If the flag is 0 then the archive will
not participate in archive shifts. A user can view or set this flag using the piartool utility.
Failed Archive Shifts

If an archive shift fails for any reason, all further shifts are disabled and a message is sent to
the log. When the cause of the failure is resolved, restart the Archive Subsystem to enable
archive shifts. If the cause of failure was a lack of available archive to shift into, then

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.
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
Page 58
3.12 - Combining and Dividing Archives
>> 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
>> 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.
Dividing an Archive into Smaller Archives

To break a single archive into smaller archives, invoke the Offline Archive Utility once for
each output file, using the same input file for all the outputs. Each time, a different start and
end time is specified. These times are specified in absolute PI time format.
Example of dividing an archive into two smaller archives:
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat -filter "1-jan"
"31-jan-02 23:59:59" -ost "1-jan" -oet "31-jan-02 23:59:59"
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\february.dat -filter "1-feb"
"28-feb-02 23:59:59" -ost "1-feb" -oet "28-feb-02 23:59:59"
In this example, january.dat and february.dat do not exist prior to the operation. They are
created as dynamic archives by default. After they are created, they may be registered using
piartool -ar, and then events may be added to the archive files in the usual way. Both output
archives are not shiftable because they were created by the Offline Archive Utility as
dynamic archives.
The filter start time of january.dat is specified as 1-jan. This defaults to 1-jan, of the current
year, at 00:00:00. The filter end time is enclosed in double quotes because of the embedded
space character. The output archive start and end times are explicitly specified. Failing to
include the “-ost” and “-oet” flags will get the default behavior. See the above discussion of
output archive time settings for more information.
If the input file were registered prior to the operation, it would be unregistered during the
operation. When the operation is complete, it may be registered again using piartool -ar.
Page 60
3.12 - Combining and Dividing Archives
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.
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 66).
You can also run the scripts manually (see Customize Your Backup, on page 68). The backup
script initiates backups via NTBackup on platforms that support VSS, and/or with the
piartool -backup command on platforms that do not support VSS. It is highly recommended
that you run PI on a platform that supports VSS because VSS backups cause minimal
disruption to the operation of PI.
On Windows 2003 server, as an alternative to using the backup scripts, you can backup PI
with any third-party backup application that supports VSS. Third-party backup applications
may support features that are not supported by NTBackup. For example, NTBackup currently
supports only non-component mode backups (see Selecting Files or Components for Backup,
on page 75).

Chapter 4 - Backing up the PI Server
4.2 Other Backup Considerations
While PI is running, PI cannot be backed up with standard operating system

commands such as copy (Windows) or cp (UNIX) because PI opens its databases
with exclusive read/write access. This means that the copy commands will outright
fail. PI prevents access by the operating system because a lot of the information that
is needed to backup the databases of PI is in memory and a simple file copy would
most likely lead to a corrupt backup.
When PI is not running, PI can be backed up with standard operating system
commands such as copy (Windows) or cp (UNIX).
Do not try to include the PI folder in your daily system backup. The PI archives
typically consist of a large number of huge files that undergo frequent small changes.
The PI backup scripts are designed to back up the archive files efficiently.
Make sure you have enough space on the disk where PI creates the backup files.
Check the disk space regularly.
Run a trial backup and restore to make sure everything works correctly. Test your
backups in this way periodically. See the section, Restoring Archives from Backup.
To avoid losing incoming data while the backups are running, turn on PI API
buffering for your interfaces wherever possible. On VMS PINet nodes, buffering is
done automatically, so buffering does not need to be turned on for VMS PINet nodes.
After PI Server installations or upgrades, shut down the PI Server and make a
complete backup of all PI directories and archives. Note that archives may not be
located under the PI\dat directory. On Windows, include the registry entries under
HKEY_LOCAL_MACHINE/SOFTWARE/PI System/PI. On UNIX, include the
/etc/piparams.default file.
When you make a major change to PI, such as a major edit of the Point Database or
User Database, consider immediately making a backup that includes those changes,
rather than waiting for the automated backup.
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.
Page 64
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.

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 72.
The procedure for automating the PI backup script can be summarized as follows.
Install PIBackup.bat as a scheduled task
View and edit the scheduled tasks
Customize your backup
Do a test backup
Do a test restore
Install PIBackup.bat as a scheduled task
The pibackup.bat script in the PI\adm directory can be used to start a backup from the
command line or to install backup task. The default backup task will run automatically every
day at 2 AM. On Windows NT and Windows 2000, the default task name will be Atn, where
n is an integer. On Windows 2003 Sever, the default task name will be PI Server Backup.
When the scheduled task is run, the PI\adm\pibackuptask.bat script is executed. The
pibackuptask.bat script calls the backup script pibackup.bat and redirects the standard output
to a log file with a name similar to pibackup_dd-mmm-yy_hh.mm.ss.txt in the PI\backup
directory. The pibackup.bat backup script will automatically determine whether or not VSS is
supported, and the script will perform either a VSS or non-VSS backup as appropriate.
The syntax for using the pibackup.bat file is as follows.
PIbackup.bat <path> [number of archives]
[archive cutoff date] [-install]
where < > indicates a required parameter and [ ] indicates an optional parameter. The
command line parameters must be specified in the above order. If the -install flag is not
specified, a backup is performed immediately. The more restrictive of [number of archives]
and [archive cutoff date] takes precedence. Regardless of [number of archives] and
[archive cutoff date] archives that do not contain data are not backed up.
Page 66
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 87). 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

administering the backups. This recommendation is simply for convenience purposes for
viewing the NTBackup log file. This is discussed further in Do a Test Backup on page 69.
Scheduled tasks can be viewed and edited via the Scheduled Tasks control panel.
Alternatively, tasks can be viewed and edited via the command line.
On Windows NT and Windows 2000, the scheduled tasks can be displayed with the at
command.
C:\pi\adm>at
Status ID Day Time Command Line
-----------------------------------------------------------------
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
Page 68
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.
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.
Page 70
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.

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

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

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

Path (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 Archive Registry and Archive Audit

Subsystem Database
Piarchive_<UTCprimary>_<GUID> PI Archive Archive0 dd-mmm-yy hh:mm:ss to

Subsystem Current
Piarchive_<UTCarch1>_<GUID> PI Archive Archive1 dd-mmm-yy hh:mm:ss to dd-

Subsystem mmm-yy hh:mm:ss
... … …
Piarchive_<UTCarchN>_<GUID> PI Archive ArchiveN dd-mmm-yy hh:mm:ss to dd-

Subsystem 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

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
Page 78
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
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 Archive file names can be anything. The annotation file name is the same
Annotation (.ann) as the archive file name with “.ann” appended to it.
files for all
components
Each archive is contained in a separate component as described in The Components in the

Archive Subsystem on page 77.
PIBatch
The Pibatch subsystem has a single component called Pibatch.
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.
Page 80
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.
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.
Page 82
4.8 - Launching Non-VSS Backups with piartool -backup <path>
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
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.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
Page 84
4.9 - Managing Backups with piartool
non-VSS backup. If <Arg1> begins with a hyphen (-), then <Arg1> is assumed to be a backup
command. The following backup commands are valid.
Backup Command 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 The identify command reports the list of files that PI will backup. If the -
<number>] [-cutoff verbose flag is specified, PI will report a list of files and components.
<date>] [-verbose] 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
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
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
Page 86
4.10 - Timeout Parameters
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.
e:\pi\adm>piartool -backup -identify -verbose
FileList
Name, ComponentName, LastBackup
<FileName_1>, <ComponentName_A>, <BackupDateFile_1>
<FileName_2>, <ComponentName_A>, <BackupDateFile_2>
<FileName_3>, <ComponentName_B>, <BackupDateFile_3>
...
ComponentList
Name, ComponentDescription, ComponentPath
<ComponentName_A>, <Description_A>, <ComponentPath_A>
<ComponentName_B>, <Description_B>, <ComponentPath_A>
...
The output should correspond to the expected components listed in the section The Backup
Components of PI on page 77 and the expected files listed in the section on page Error!
Bookmark not defined..
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 Min Max Read Description

Value
Archive archive_back 1800 5 86400 On backup Number of seconds before the
upleadtime sec startup predicted archive shift that a non-VSS
archive backup may start. The PI
Backup Subsystem waits up to 30
minutes for the archive shift to
complete. This timeout parameter has
no effect on VSS backups.
Archive Archive_BSTi 1800 1 86400 Once a This timeout parameter is obsolete. It
meout sec minute is for internal use only.
Backup Backup_Num 3 1 1000000 Before If the number of archives to be backed
Archives every up is not explicitly specified in
backup arguments to the pibackup.bat backup
script, then this timeout parameter
defines the default number of archives
to back up.
Backup Backup_Archi 01-Jan- 01- N/A Before If the cutoff date is not explicitly
veCutoffDate 70 Jan- every specified in arguments to the
70 backup pibackup.bat backup script, then this
timeout parameter defines the default
cutoff date. Archives that contain any
data between
Backup_ArchiveCutoffDate and
current time are backed up. For
example, if "*-30d" is specified, then
at least 30 days of data is backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict
the number of archives for backup.
Whichever timeout parameter is most
restrictive takes precedence.
Backup Backup_Trac 0 0 1000 Startup The default backup trace level. Non-
eLevel only 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.
Page 88
4.11 - Troubleshooting Backups
Subsystem(s) Name Default Min Max Read Description

Value
All <subsysname 60 sec 10 900 Startup PI internally keeps track of the last
>_WriteModTi only modified date of most of the files that it
mesToFilePer needs to back up. The last modified
iod times for each subsystem are updated
every WriteModTimesToFilePeriod.
The smaller the period, the more
accurate the last modified time is.
A complete list of backed up files
along with their last modified dates
can be listed with the piartool -
backup -identify -verbose command.
For archives, the last modified date
can also be viewed with piartool -al.
Note for archive files:
When a value is written to a PI point,
the value is not actually written to the
archive until the archive cache is
flushed. The maximum period
between archive flushes is set by the
Archive_SecondsBetweenFlush
timeout parameter. After the cache is
flushed, the last modified time is
updated within
WriteModTimesToFilePeriod
seconds.
All <subsysname 1800 30 86400 Periodically The maximum number of seconds to
>_BackupTim sec when in remain in system backup mode. This
eout system timeout parameter only pertains to the
backup piartool -systembackup command,
mode 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.
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.
Page 90
4.11 - Troubleshooting Backups
VSSADMIN LIST SHADOWS

A shadow copy is created during the freeze event. If a backup is not currently in progress, the
output of vssadmin list shadows should look like the following output that was generated on
Windows XP.
e:\pi\adm>vssadmin list shadows
vssadmin 1.0 - Volume Shadow Copy Service administrative command-line
tool
(C) Copyright 2001 Microsoft Corp.
No shadow copies present in the system.
If there were problems create the shadow copy, look for errors in the NTBackup.exe log file
and run vssadmin list shadows to check the status of the failed shadow copy.
VSSADMIN LIST PROVIDERS

Windows XP and Windows 2003 server comes with a default VSS provider.
The following is sample output generated on Windows XP.
e:\pi\adm>vssadmin list providers
vssadmin 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
Page 92
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 On Windows, this manual is installed into the pipc\bin directory by
Instructions 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 The Interface Configuration Utility provides a graphical user

Utility User Manual interface for configuring the interface command line, interface
services, and various PI points that are useful for monitoring
interface performance.
PI Performance Monitor The PI Performance Monitor interface, PIPerfMon, obtains

Interface Manual 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 Some interfaces, such as the OPC Interface, support auto-point
Manual 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
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.
Page 94
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

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

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.
Page 98
[-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) *

Option 2 provides slightly tighter security. Instead of configuring the above two trusts, set up
the following trust.
• One trust based on IP address, netmask, and fully-qualified host name
In Option 2 if the IP address or fully-qualified host name changes, the trust will fail, whereas
in Option 1, it will not fail.
Interfaces Trusts for PI API and PI SDK Connections

Check your interface-specific documentation to see if your interface requires PI-SDK
connections in addition to PI API connections. We recommend configuring trusts in one of
two ways for applications that require both connection types.
Option 1 involves setting up the following 3 trusts.
One trust based on IP address and netmask. This trust works for both PI API and PI-
SDK connections.
One trust based on fully-qualified host name (i.e., apollo.osisoft.com). The PI API
always uses the fully-qualified host name as opposed to an abbreviated form of the
name.
One trust based on the simple host name (i.e. apollo). The SDK typically uses the
abbreviated simple host name. To verify the host name the PI-SDK will use, run
pidiag -host on the Interface Node.
With these 3 trusts established, the interface first attempts to connect by IP address. If the IP
address changes, then a trust is granted based on the host name. Because the PI-SDK and PI
API host name processing may differ, you should set up two trusts, one for each form of the
host name.
Option 2 provides slightly tighter security. Set up just 2 trusts, one for the PI API and one for
the SDK. In each trust, include host name, IP address, and netmask as qualifications for
connection.
One trust based on IP address, netmask, and fully-qualified host (i.e., apollo.osisoft.com).
This trust works for the PI API connection.
One trust based on IP address, netmask, and simple host name (i.e. apollo). This trust works
for the PI-SDK connection. To verify the host name the PI-SDK will use, run pidiag -host
on the Interface Node.
Trusts for Interface Nodes with Multiple NICs

If your Interface node has multiple NICs, you must set up a trust for each IP address, even if
you just see the connection with one. To see all IP addresses for a given computer, type
ipconfig -all at a command prompt.
Using the Application Name in Interface Trusts

Although it is possible to use the application name in trusts for PI API applications, the
additional security gains is typically not warranted by the increase in complexity. Before
adding complexity to your trusts be aware that interfaces is only as secure as the room the
Page 100
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.

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 The /ps flag specifies the point source for the interface. x
required 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 The /id flag is used to specify the interface identifier. For
sometimes required 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 The /host flag is used to specify the PI Home node. host
recommended parameter is the IP address of the PI Sever node or the domain name
of the PI Server node. port is the port number for TCP/IP
communication, which should always be specified as 5450
for communication to a PI 3 server.
Page 102
/f=SS Each occurrence of the /f flag on the command line

or specifies a scan class for the interface. A particular PI Point
is associated with a scan class via the Location4 PI Point
/f=SS,SS attribute.
or The /f flag defines the time period between scans in terms
/f=HH:MM:SS of hours (HH), minutes (MM), and seconds (SS). The scans
or can be scheduled to occur at discrete moments in time with
an optional time offset specified in terms of hours (hh),
/f=HH:MM:SS,hh:mm:ss
minutes (mm), and seconds (ss). If HH and MM are omitted,
required for scan-based interfaces then the time period that is specified is assumed to be in
seconds.
/stopstat If the /stopstat flag is present on the startup command

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

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

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.
Page 106
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.
Startup script Corresponding shutdown scripts and site-specific scripts
Shutdown Site-Specific Site-Specific stop Script

script startup script script location
pistart.bat None pisitestart.bat None \PI\adm
pisrvstart.bat pisrvstop.bat pisrvsitestart.bat pisrvsitestop.bat \PI\adm
On Windows the difference between pistart.bat and pisrvstart.bat is that the former is used to
start PI interactively and the latter is used to start PI as a service. To start your interface
interactively, add a line similar to the following to pisitestart.bat.
program files\pipc\interfaces\myinterface\myinterface.bat
To start your interface as a service, add a line similar to the following to pisrvsitestart.bat.
net start myinterface
PI Interface Node on Windows

The site-specific startup scripts are named differently on an Interface Node, than on the PI
Server node. The scripts provide a convenient means of shutting down all programs that use
the PI API and PI-SDK that communicate to the PI Server node.

Shutdown Site-Specific Site-Specific stop Script location

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

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.

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.
Page 108
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 The number of seconds since the interface has started. This counter is
(seconds) incremented once a second.
IO Rate The number of events per second received by the interface. If this
(events/second) 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

Counter Name Description

update rate of the performance monitor to 5 seconds by selecting the
“Chart…” command from the Options menu. In the dialog box, change
the periodic update time to 5 seconds. If the update time is left at 1
second, then the IO Rate will appear to go to zero between scans
because no events are received between scans.
Point Count Number of points loaded by the interface.
Scan Time Time in milliseconds to call developer function and to write values to
(milliseconds) PI. There is one “Scan Time” counter per scan class.
Scheduled Scans: Percentage of missed scans since starting the interface. If a scan
% Missed 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, Percentage of skipped scans since starting the interface. If a scan
% Skipped 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: The total number of scans in the current performance interval. This
Scans this interval 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 Number of point edits that have occurred. Only applies to the instance
interface _Total.
Points added to the Number of point that have been added to the interface. Only applies to
interface the instance _Total
Points removed from Number of point that have been removed from the interface. Only
the interface applies to the instance _Total
Page 110
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
(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
Page 112
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
given node is controlled via the host table, domain name server, or DHCP. See your
networking documentation for details.
The network router may also be configured to restrict traffic on specified subnets.
Network setup and security is very important for satisfactory PI System operation. The details
of this are broad, diverse, and beyond the scope of this manual.
6.3 Operating System Security
The PI Server files are protected by the hosting operating system security. On all platforms,
each executable, data file, and directory may independently be given read, write, and execute
access on a per-user or per-group basis.
The System Manager’s account is called “administrator” on Windows systems and “root” on
UNIX systems. Since the System Manager’s account is central to a secure system, it is
imperative that the account password be well chosen (to guard against password guessing),
periodically changed, and known only to a small group of trusted managers.
During installation, all the PI system files are created with the system’s default security, and
are owned by the installing user. This should be the System Manager.
The System Manager may change the ownership and the access rights to these files. This
might be done to assure that only selected users can have any access to the PI system. It is
mandatory to keep full access to the System Manager and to make sure that the PI services
have full access to the PI files. It is best to keep the file ownership as the System Manager. If
tighter security is required, limit the access for group and world, and allow full access to the
System Manager and to the Administrators group.
6.4 PI Server Security
It is typical for a PI System Manager to implement restricted access to the Data Archive and
the Point Database beyond what is provided by physical, network, and operating system
security.
In using PI Server security features, the System Manager is responsible for:
Restricting access via the PI firewall
Creating PI users accounts and groups
Assigning users to groups
Assigning an owner and a group to all databases and setting the access rights. Each
database can have a different owner and a different group.
The default owner and group is piadmin. The default access is “o:rw g:r w:r.” See
the section on Database Security below.
Note: Membership in the piadmin group does not automatically give special
privileges. The piadmin user account does give unlimited access.
Page 116
6.5 - Firewall Security
Assigning owners and groups to points

Setting the access permissions on each point, both for attributes and for data
Assigning owners and groups to modules. Module level security is only accessible
with the System Management Tools, which you can obtain from the OSIsoft support
Web site.
Maintaining the Trust Database for automated logins
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.
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.
Page 118
6.5 - Firewall Security
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
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.
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.
Page 120
6.6 - Database Security
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
(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

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 125.
System Manager Privileges

System Manager privileges allow changing access permissions for any point, without regard
to the point attribute owner (ptowner). The manager can override and change any setting,
even if access is restricted.
Note: The user piadmin is a special user. This account is the PI System super user.
It has full access to all databases and database records regardless of security
attribute settings. piadmin is the only user that has this level of privileges.
6.7.3 Access Algorithm

Whenever a user logs in, the following algorithm is used to determine what access to a point
is granted:
Page 122
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 171 explains how to use this utility.
The point owner or data owner can change the security attributes in the Point Database using
piconfig.
Changing the Point Attribute Owner Example

In this piconfig example, open the table and list the point access ownership for a tag. Then
change the owner for this point.
* (Ls) 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:
* (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
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:
Page 124
6.8 - User Security
@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 PI ProcessBook or PI
DataLink, requires a PI user name and password or a valid PITrust. The user is also assigned
to one or more groups of users.
Note: The PI Server does support PI API based logins without supplying a user
name/password or a trust. This is the “default” user access that assigns world rights
to the connection. This feature may be disabled by adding the PITimeout table entry
“DefaultUserAccess” and setting the value 0. A non-zero value or no entry allows
default user access. If default user access is disabled no secure objects may be
accessed regardless of security attribute settings.
When a user accesses the PI Server, after the request passes the PI Firewall, the user ID and
password are used to determine what access to grant.
There are three types of user access: owner, group, and world. Owner access is typically 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.
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.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.
Page 126
6.8 - User Security

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, tom@somewhere.com, piadmin, piuser
* (Ls) Piconfig> @ostructure user, description, groups, ...
* (Ls) Piconfig> @select user=tom
tom, tom@somewhere.com, piadmin,piuser
Changing PI User Passwords

PI users may change their passwords by using the pisetpass utility in the PI\adm directory. PI
must be running for this utility to work. You must enter the current password in order to
change the password.
You can also set a password to a blank entry by using pisetpass, although this is not
recommended.
The manager can also specify the old password as "!" (exclamation mark) and new password
as required. This bypasses old-password verification when the user running pisetpass as
piadmin.

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
The three types of connection credentials, which are determined by the operating system
login of the connecting application, contain slightly different information.
PI Server determines the connection credentials for PI API applications based on the IP
address, the Host name, and a truncated application name.
PI-SDK applications on Windows 98 assemble their own credentials, based on the IP address,
the IPHost name, and a non-truncated application name.
PI-SDK applications on Windows assemble their own credentials, including Windows
Domain Membership, Domain User Name, IP address and/or host name, and Application
Process Name.
Page 128
6.9 - Trust Login Security
The three types of logins are discussed more fully in the following sections. Trust records are
discussed later, followed by examples.
Connection Credentials for PI API Applications

Connecting PI API applications that call piut_setprocname send a 4-character application
name to the PI Server. The application name is referred to as a “process name” in the PI API
User Guide. The PI Server uses reverse name lookup on the IP packet, to get the sender’s
address, and then looks up the host name.
PI Server can determine the IP Address of the connecting machine through a Reverse Name
Lookup. The name can come from a hosts file on the server machine, or, more commonly,
from a Domain Name Server (DNS).
The 4-character application name is determined by a call by the application to the PI API
routine piut_setprocname. When PI Server accepts a connection, PI Server logs this name
and adds a trailing “E.”
Thus, PI Server can assemble a 3-part set of connection credentials:
Application Process Name (4-characters + E)
IP Address
Host name of the connecting machine
Once PI Server assembles a set of connection credentials, PI Server compares these to each
trust record in the Trust Database. If a match is found, the connection is granted the same
access as the PI User defined in the trust record.
At connection, every PI API-based application attempts to receive a Trust Login
authorization. If the application has a subsequent user/password login, this subsequent login
overrides any trust authorization.
Connection Credentials for PI SDK Applications on Windows 98

The PI-SDK assembles connection credentials for an application internally on the connecting
client machine (Windows 98), including these attributes:
Application process name. This is the executable file name.
IP address
IPHost name
Run pidiag -host on the node where the application runs to view the connection credentials
as retrieved from the local operating system.
Domain and user name information cannot be obtained from Windows 98-based clients; the
connection credentials sent from PI-SDK applications on those operating systems will omit
those fields.
Once a set of connection credentials reach the PI Server, the Server compares these to each
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
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 Req or PI SDK on PI SDK on WinNT

Trust Record Opt. PI API Win98 or greater
Trust name req
AppName opt yes yes yes
Domain opt no no yes
IPAddr1 opt yes yes yes
Netmask opt yes yes yes
Host name opt yes yes yes
OSUser opt no no yes
PIUser req
If IPAddr is used, Netmask must also be configured.
Page 130
Before you configure records in the Trust Database, set up the entries in the User Database.
For more information, see Adding a New PI User, page 127. When you establish a new trust
record, if the PIUser you include does not already exist in the User Database, the trust record
will be rejected.
Note: Trust record with only Trust name and PIUser are not allowed. Always include
at least one optional entry.
PI Server does not allow two trust records that differ only in PIUser, because this would
create ambiguous trust login results.
Using Piconfig
Piconfig is the only tool that can modify the Trust Database. The key value of the Trust
Database is Trust.
D:\PI\adm>piconfig
* (Ls - ) 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
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.
OSIsoft recommends that you verify the IPHost name as discussed below.
For PI API connections, the IPHost name is retrieved by PI Server using the IP address of the
connecting client. The lookup generally requires access to a Domain Name Server (DNS). If
a DNS is not used, the client IPHost name must be defined in the hosts table of the PI Server.
To check this name, ping the client machine from the PI Server. For example, the DNS might
provide JoePC.osisoft.com.
For PI-SDK connections, the IPHost name comes from the information sent by the client to
the PI Server. This name is the short IPHost name. You can confirm this name by running
pidiag -host on the client. For example, the name might be JoePC.
Page 132
For PI-SDK connections, PI Server verifies domain membership of a client computer by

checking with a domain controller. If this field contains a dollar sign ($), it represents any
machine within the domain.
In the example above, one trust record with an IPHost entry would not match both PI API
and PI-SDK connection credentials.
OSUser
The OSUser (Operating system user) name field is used only for PI-SDK applications
running within a Windows NT or Windows 2000 Domain.
Leaving this field blank indicates a match is not required. Otherwise a case-insensitive match
is required.
Because Domain must be the same for both the PI Server and the connecting PI-SDK
application, it is recommended that you include Domain whenever you want to include
OSUser.
If this field contains a dollar sign ($), it represents any domain user. If the PIUser field in the
trust record is also $, then the OSUser name must match a name in the PIUser database.
If this field contains a dollar sign ($), and the PIUser field contains a specific PIUser, then
all domain users will be granted the access rights of that PI user.
OSUser Names for Services on Windows

Interfaces that run as automatic Windows Services have a default OSUser name on the host
machine. Unless overridden, this name is LocalSystem, which is not a Domain Username. If
you wish to include OSUser name as part of a trust login, you must change the default name
for the interface on the host machine to something that is defined in the Domain user
database.
User Manager in the Administrative Tools does not list the default LocalSystem name.
Instead, follow these steps to set a new OSUser Name.
Windows NT:
1. Open Services in the Control Panel.
2. Select the interface service name and click Startup….
3. In the dialog that appears, select Log on as This Account.
4. Type in a new User Name and Password (twice) or select a User Name from the
dropdown list. Click OK.
Windows 2000/XP:
1. In the Control Panel, open Administrative Tools and then Services.
2. Select the interface service name and click Properties.
3. On the Properties page, select the Log On tab.
4. In the dialog that appears, select This Account.

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.
Page 134
If incoming PI-SDK connection credentials do not match any trust record, then the default
user for that server as configured on the caller’s machine is tried with a blank password. If
that fails, the PI-SDK application is not connected.
Scoring Criteria to Determine the Best Match

When more than one trust record matches an incoming credential, the best match is
determined by weighting the fields and calculating the total for each matching record. PI
Server selects the trust record with the highest score.
Weight Matching Field
163 application name
131 specific OS user
115 any Domain Machine ($)
107 any Domain user ($)
103 IP address
103 IPHost
101 Subnet
100 Domain match
Other Applications on the PI Server Machine

PI API or PI-SDK applications running on the same machine as the PI Server are
automatically established with trust logins at the time PI Server is installed or upgraded. The
PI System Manager may modify these login privileges in the trust table.
Logins through a Node Already Using a Trust Login

If an application using an explicit login connects to PI Server through a network node that is
already using a trust login, the trust login connection is unaffected. A trust login and an
explicit login are independent from each other unless they apply to the same application, in
which instance, the explicit login overrides the trust login.
Interaction with PI Firewall Security

You can block connections from certain addresses through the PI Firewall mechanism. See PI
Firewall Security, page 117, for more information. This takes precedence over trust, i.e. a
connecting application must pass the firewall before trying to get a trust login.
Protection of PI API Application Connections During Backups and Other

Shutdowns
Interfaces and the PI API BufServ rely on successful trust logins because they run as
Services on Windows or as processes on UNIX. PI Server will not allow PI API connections
while Trust Login services are unavailable.

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.
Page 136
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.
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
Page 138
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.
@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
Page 140
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

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 Result of AND Trust IPAddr
IPAddr between Trust and result of
Netmask and AND match?
Machine IPaddr
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
Page 142
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
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
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.
Page 144
6.10 - Resolving Ambiguities
Example 12. Resolving Ambiguities—Scoring System

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

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

5. Save your dat directory, log directory and archives to a safe location.
6. Uninstall the PI Server.
7. Follow the instructions in the following sections; except, skip step 2 since this was
already done in step 3 above.

Chapter 8. COPYING A PI SERVER
If you want to create a second PI Server by moving an existing PI Server as described in

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

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

9.2 Server Merge Procedure - Example
The following example retires a small NT Intel PI System and merges it with an existing
HPUX PI System. Both systems consist of example points provided with installation. The
tags on the retired system were edited to create unique tags.
Here is the archive list and point list of each system before starting the merge:
Retired System
BA:Active.1
BA:CONC.1Retired
BA:LEVEL.1Retired
BA:PHASE.1Retired
BA:TEMP.1Retired
batchid-1Retired
CDEP158Retired
CDM158Retired
CDT158Retired
piba1
pipe:sine2Retired
pipe:sine2tRetired
pipe:sine3Retired
pipe:sine4Retired
pipe:sine5Retired
pipe:sineRetired
pitot1Retired
pitot2Retired
pitot3Retired
pitot4Retired
pitot5estRetired
pitot5rampRetired
pitot5Retired
pitot5runRetired
pitot6countRetired
pitot6timeNERetired
pitot6timeRetired
pitot_1Retired
pitot_avgRetired
pitot_maxRetired
pitot_minRetired
productid-1Retired
sin:h2Retired
sin:hourRetired
SINUSOIDRetired
SINUSOIDURetired
t_minRetired
t_state1Retired
Archive: D:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.002
Page 156
9.2 - Server Merge Procedure - Example
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
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
Page 158

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
* (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
Page 160
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
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
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
Page 162
9.3 - Shut Down the Retired System
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...
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
Page 164
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
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
Page 166
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
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
Backup Time: Never
Page 168
$ 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 OSIsoft to make this task easier:
PI Tag Configurator, is an Excel spreadsheet add-in that can facilitate creating
many new tags and modifying the attributes of existing tags in the Pipoint Table.
The PI System Management Tools (PI SMT) includes a PI Point Builder Plug-in
which is useful for editing or creating a small number of tags. PI SMT is available
from the Download Center at the technical support web site, and documentation is
included in the online Help file.
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 OSIsoft Web
site.

Chapter 10 - The piconfig Utility
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
Page 172
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.

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
Page 174
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
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
Page 176
*piconfig> ? - This menu

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

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
(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.
Page 178
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.
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:
Page 180
@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 ?
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
Page 182
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
*
@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
Page 184
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.
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- Sets case-sensitivity-ignore mode. Flag may be:
insensitive Data, Names, or All.
) This affects only tables accessed vie the PI_GEN
table – i.e. timeout and firewall.
Cd Directory None Change directory for input/output files
Clear None None Clears Modify and Select specifications
Comchar 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
Page 186
10.4 - Piconfig Commands and Tables
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 None Connect to a remote PI 3 home node using the

user name, given PI username, password, and TCP/IP port ID.
password, port
ID
Maxerr N 10 Sets the error tolerance. piconfig will exit when

the number of errors reaches n. However, piconfig
exits only when in non-interactive mode.
A Maxerr value of -1 causes piconfig to exit upon
the first error and display the line number of the
input file.
Mode Flag List Specifies mode of operation: Create, Edit, Delete,

List, Compare, Convert, Create, and Edit mode
can be modified to include both. Specify the mode
flag as Edit,t or Create,t.
For check only specify Edit,c or Create,c.
Modify Modification None Defines field modifications.
Ostructure Structure None Specifies format of output data. Only useful when
in list mode. A warning is issued if this command is
used in mode edit, create, or delete.
Ostype Flag D Selects output data format structure type: Fixed,

Delimited, or Keyword. (F,D,K)
Output File None Redirect output to file. If <file> not specified, the
output is directed back to standard output.
Prompt Flag No Sets prompt mode: yes (for interactive sessions) or

no (for batch sessions)
Ptclassname Classname Base Specifies the point class: base or classic. Pipoint
Table only.
Quote C None Tells piconfig to enclose output fields with quote

Must be ‘ or “ 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.
Page 188
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
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 OSIsoft Technical Support Web site at
http://techsupport.osisoft.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
Page 190
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
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.
Page 192
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
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,
Page 194
C,4,22,
G,9,18,
L,3,15,
Lab,5,4056,
PIBatch-InternalUse-1,11,2,
PICampaign-InternalUse-1,19,1,
PITest,16,1,
PIUnitBatch-InternalUse-1,8,109,
R,1,9865,
T,6,15,Totalizer Points
U,12,2,
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
Page 196
Subsequent lines are treated as input until the next piconfig command is issued.
Modifying a Digital State Set

If you want to modify an existing digital state set by adding a state, deleting a state, or
renaming a state, you must specify all of the states in the state set. Individual states cannot be
edited.
For example, add another state to the ValveStateSet as follows:
(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
SYSTEM
Page 198
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)
Value
TIME Event timestamp in the format DD-MMM-YY hh:mm:ss.ssss
TimeNum Timestamp as a number in seconds past 01-Jan-70 (Read only)
Page 200
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.
Table 10–4. Archive Table Attributes
TAG the tagname (read only)
PointID the point ID (read only)
Type the point type (float32 …) (read only)
Page 202
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
Note: Do not confuse the Piarc Table mode attribute with the piconfig mode
command. To delete archive events, use the Piarc Table mode attribute=remove in
piconfig edit mode.
Changing and Deleting Events in PIArc Table

The following commands can be used to add, edit, and delete events.
Page 204
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
*> 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.
Page 206
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.

Attribute Definition
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
process unit. The table is simple—it consists of two columns—an alias name and a PI tag
name. The alias name has two components: a unit name and an attribute name. Alias syntax
is:
\\unit name\common name
For example:
\\Reactor1\temperature
The unit name must be a defined PI Batch unit, that is, an entry for it must exist in the
PIbaunit Table. The PI tag name must also be valid.
See Batch Subsystem in the PI Server Applications Guide for details on how to manage data
in this table.
The table name is Pibaalias. The primary key is Alias.
Page 208
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
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.
Page 210
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.
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.
Page 212
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
*----------
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
Page 214
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
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
Page 216
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.
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
Page 218
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.
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
Page 220
10.5 - Helpful Hints
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.
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 '
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”.
Page 222
10.5 - Helpful Hints
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.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>
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 OSIsoft 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 OSIsoft support Web site for
more information.
Page 224
Chapter 11. PI TROUBLESHOOTING AND REPAIR
Data passes through many steps on the way into and out of the Archive. The main strategy to
apply when troubleshooting is to determine which parts of the data path are malfunctioning,
and also, which parts are functioning correctly.
The first step is to isolate the problem to a single computer, either client or server, or to the
network. Follow the steps in the Troubleshooting Checklist to isolate the problem area. A
table of error messages is available in Appendix A: PI Messages on page 281.
The second step is to isolate the problem further to a particular client program or PI
subsystem. See Verifying PI Processes on page 228, and PI System Data Files on page 235,
for help with this.
The third step is to determine the exact cause of the problem. This will lead to a good
understanding of what is needed to fix the problem, repair the damage, and prevent a
recurrence. If needed, go to the Repairs section to repair data files such as Archives or Point
Database.
After working through the Troubleshooting Checklist, you may still not have resolved your
problem. In this case, you will want to call OSIsoft Technical Support for some help. The
technical support engineer will ask for some key information and also may ask to dial into
your system in order to do some hands on troubleshooting.
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
3. If there is a client problem, check security. Log in as the user piadmin. Check the
setup.log and pipc.log files in the c:\pipc\dat directory. Also check the server central
log file using the pigetmsg utility. A table of error messages is available in Appendix
A: PI Messages on page 281. If a trend in PI ProcessBook “flatlines,” see the section
on p. 255.
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 281.
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 281.
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.
Page 226
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. OSIsoft Technical Support will arrange
for a download of a debug build of PI if necessary.
12. If you have a pinetmgr problem, use:
netstat -a
to determine if there is any other process talking on port 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.
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 281. If an
API interface is not able to connect, be sure that the PI Base Subsystem, PI Archive
Subsystem, and PI Snapshot Subsystem are running.
19. If an installation or upgrade problem, check the log file:
• UNIX - /tmp/piinstall.log
• Windows – PIPC\dat\SetupPIServer.log and PIPC\dat\PIServerMaster.log. See
the Getting Started manual for more information.
20. Check ownership and execute permissions on files that are giving trouble. Try
running as Root (UNIX) or Administrator (Windows). If the trouble goes away when
you run as the System Administrator, then you have a permission problem.
21. Read the PI release notes to determine if this is a known problem. Another source of
information is the OSIsoft Technical Support Web site, http//techsupport.osisoft.com,
which has technical notes posted.
If you haven’t solved the problem after working through this checklist, you will need to
phone or email OSIsoft 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
Page 228
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 OSIsoft 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
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.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:
Page 230
11.2 - Verifying PI Processes
$ 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
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 OSIsoft 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 OSIsoft 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
Stopping a Windows Process

To stop and start processes on Windows, use the Services dialog in the Control Panel. You
can also do this from a command prompt using the net stop command.
For example, to stop the PI Message Subsystem, issue the command:
net stop pimsgss
Stopping a UNIX Process

The pistop_ss.sh and pistart_ss.sh are used to stop and start subsystems on UNIX. The
following example shows how piarchss is stopped and restarted.
Page 232
11.3 - UNIX Process Quotas
pistop_ss.sh piarchss
pistart_ss.sh piarchss
Alternatively, the kill -2 command can be used to stop any PI process. The following
example shows how piarchss is stopped and restarted.
$ cd /export/PI/adm
$ ps -upiadmin
PID TTY TIME COMMAND
9313 ? 0:00 bufserv
834 ttyp4 2:16 random
9335 ? 0:00 iorates
794 ttyp4 0:22 pibasess
1507 ttys1 0:00 ps
760 ttyp4 10:31 PIsnapss
9330 ? 0:00 ioshmsrv
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
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
To change a value, you will have to create a stanza file. For more information about stanza
files, issue the UNIX command man stanza.
This file might look something like this:
proc:
max-proc-per-user=70
Before you apply any stanza file, always copy your current /etc/sysconfigdb file so that you
can back out your changes if you need to. To apply the changes to the system, use the
command
# sysconfigdb -m -f yourfile.name proc
where yourfile.name is the name of the file you created. You will have to reboot the system
before this change will take effect.
Page 234
11.4 - PI Server Data Files
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
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.
Pidignam.dat
This binary file stores each unique digital state name. This is a pifilebase-type database so its
validity can be checked and restored using pidiag -fb and pidiag -fbf.
Pidigst.dat
This binary file stores the digital sets; it references names stored in the above file. This is a
pifilebase-type database so its validity can be checked and restored using pidiag -fb and
pidiag -fbf.
Page 236
11.4 - PI Server Data Files
Pimapevq.dat
PimaNNNN.dat
These are the memory-mapped Event Queues. Most systems use the default single file
pimapevq.dat. Certain situations require multiple Event Queues; in this case the files take the
naming convention of pimaNNNN.dat where NNNN is an integer.
The memory mapped Event Queue serves two purposes. First, it used for moving events from
the Snapshot Subsystem to the Archive Subsystem. PISnapss places events which pass
compression into this queue. PIArchss takes these events and writes them to the Archive.
Second, this file provides storage of events when the Archive Subsystem cannot process
events such as during archive shifts or when the archive process is shutdown.
This file, as the name implies is a memory-mapped file. Memory mapped files allow for high
speed in-memory access with the security of being safely backed up to disk.
Pilastsnap.dat
This binary file stores the timestamp of the last completed Snapshot flush to disk. On PI
System startup, this timestamp is assumed to be the shutdown time and is used as the
timestamp for shutdown events. On orderly shutdown, this file will contain the true shutdown
time. On a system crash such as a power failure the Snapshot may be as old as the Snapshot
flush cycle time period. The Snapshot flush cycle is controlled by the SnapFlushCycle
timeout parameter, which is 15 minutes by default.
Pimsgtxt.dat
This binary file stores formatted message strings used by the pigetmsg utility. This is a
pifilebase-type database so its validity can be checked and restored using pidiag -fb and
pidiag -fbf.
Pipoints.dat
This binary file stores the Point database. This is a pifilebase-type database so its validity can
be checked and restored using pidiag -fb and pidiag -fbf.
Piptalia.dat
This binary file contains alias information. This is a pifilebase-type database so its validity
can be checked and restored using pidiag -fb and pidiag -fbf.
Piptattr.dat
This binary file stores the point attributes. This is a pifilebase-type database so its validity
can be checked and restored using pidiag -fb and pidiag -fbf.
Piptclss.dat
This binary file stores the point classes. This is a pifilebase-type database so its validity can
be checked and restored using pidiag -fb and pidiag -fbf.

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
Piusrctx.dat
This file stores the context database. This is a pifilebase-type database so its validity can be
Piusrgrp.dat
This file stores the group database. This is a pifilebase-type database so its validity can be
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
producer of Point Database and Module Database changes. The Archive Subsystem is a
producer of archive changes. The Batch Subsystem is a producer of Batch Database
changes.
Consumer: Application currently signed up as a consumer of specified producer. For PI
API applications, the consumer name is usually the first 4 letters of the login name of the
user running the application. These names are not unique so the PI Update
Manager assigned ID is appended to the name. PI API applications also have the PI
Network Manager ID appended. These integers are appended to help find specific
Page 238
11.5 - Identifying the Update Manager Issues: the pilistupd utility
consumers. For the PI-SDK, the consumer name is the complete application name with a
colon and a PI-SDK supplied identifier followed by a pipe character and a PI Update
Manager assigned ID.
Qual: This is the qualifier. The qualifier is a producer-specific integer. For example,
Snapshots update stores the requested point ID in the qualifier.
Flags: A producer-specific field.
Pending: Number of events available for the consumer to retrieve. The value goes up and
down as events come in and the consumer pulls them out. Values that increase
continuously might indicate that the consumer is not working properly or disconnected.
Note: The Pending number shows a maximum of 4096 events, even if more events
are in the queue. The Update Manager might limit individual consumers from
accumulating too many pending events. This is a display limitation and does imply
data loss.
Command line Switches for pilistupd

pilistupd has the following command line switches:
-v Show version
-h Help
-c consumer Select a specific consumer
-p producer Select producer
-m min Show only events with pending >= min
-t Show only the total number pending for this selection (specific cons./prod.)
-d piupdmgr dump to pi\adm\updmgr.dmp
-r C <S> Repeat C times every S sec.
-g A list of registered producers/consumers
-sp Sort output by producers
Example 1. Point Updates Only

For example, the following command limits output to the Producer ptupdates:
e:\pi\adm>pilistupd -p ptupdates
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 PI ProcessBook Display Open

The next table was generated by running pilistupd with an open PI ProcessBook display,
trending 5 points.
e:\pi\adm>pilistupd
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
point IDs being trended. There are three pending events, two for point ID 29761, and one for
point ID 1.
Example 3. Determining Whether Client Updates are Occurring

Running pilistupd several times should reveal changes in the pending numbers. This can be
done easily by using command line switches. The -m option, requests a minimum pending
value of 1. The -r requests that the command be run 100 times. In the example below, the
command is issued and then results appear for 4 runs before the command is stopped with
Ctrl C. For three of the runs, none of the producers have any pending updates, as indicated
by the No Matching entries output.
Page 240
11.6 - Repairs
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.
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)
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
Page 242
11.6 - Repairs
...First pass...
...Sorting input archive...
Failed to unregister input archive: [-10733] PINET: RPC Resolver is
Off-Line
Archive utility not running - or archive not registered
Continue processing...
...Output pass...
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.
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 (PI ProcessBook and PI DataLink) to verify that
all the data has been recovered. If the data is intact, you are done. Run the clients
locally, since the PI Server should be isolated from the network. It is very important
to confirm correct PI Server recovery before exposing the PI System to buffered data.
Failing to do so may cause data loss.
18. Connect the PI Server to the network. Verify the PI Server is reachable from clients
on the network. Monitor all buffered interface nodes.
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 56.
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.
Page 244
11.6 - Repairs
Note: The PI Server will not allow registering archives with overlapping dates. If you
find overlapping dates, you can use pidiag -ahd to check the exact start and end
times.
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>]
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.
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.
Page 246
11.6 - Repairs
3. Run pidiag -ad and collect the dump of piarstat.dat, verifying the output.
4. If the results of the dump look good, attempt the automated recovery. Otherwise, use
the interactive one.
5. Restart PI.
6. Check the message log to see if all archives are loaded. If the interactive version is
used, only the Primary Archive will be loaded.
7. Register any remaining archives. If the interactive version was used, all other
archives will need to be registered.
Options for Running Pidiag

There are three ways to run the recovery tool:
-ad 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.
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 OSIsoft Technical Support.
To do this, shut down pibasess, piarchss, and pisnapss. Rename the file
PI\dat\piarcmem.dat to another name. At a command prompt, change your current directory
to PI\bin and issue the command:
pibasess -snapfix
The PI Base Subsystem will write a message to the screen indicating that Snapshot recovery
mode has been specified and that recovery is in progress. When recovery is complete,
pibasess will write a final message to the screen and exit. You may then restart the PI
System.
This Snapshot recovery command can be run with the entire PI System shut down.
Removing Future Time Snapshots

The piconfig utility can be used to remove all or selected Snapshot events. When the
Snapshot event is removed, the Snapshot Subsystem attempts to retrieve the latest archived
event from the Archive and replace the Snapshot event with it. That event is removed from
the Archive. If there are no events for the point in the Archive, the Snapshot is deleted and
remains uninitialized until a new Snapshot event is sent.
The following piconfig script shows how to do that:
piconfig table pisnap
* (Ls - PISNAP) piconfig> @sele tag=*,time>"*+10m"
* (Ls - PISNAP) piconfig> @ostru tag,value,time
Page 248
11.6 - Repairs
* (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:
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.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
Page 250
11.7 - Tuning the PI Server
The following is performed:

Table and index entry count size checks are performed. The entry counts should be
the same.
Modules that have a record size of zero are removed. These modules would be
unrecoverable.
Parent and children references to non-existent modules are removed.
This utility may modify the Module Database. Therefore it is important to have a safe
backup.
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.
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.
Note: This technique if only used for advanced troubleshooting. This should only be
done under the advice of OSI 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
Page 252
11.7 - Tuning the PI Server
write time-outs default to 50,000 microseconds, read and write retries default to 250. We
recommend increasing the time-outs in increments of approximately 25% until the errors
disappear. If the errors persist when the timeout values are over 150,000 microseconds, call
OSI Technical Support.
To increase the time-outs:
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 OSI Technical Support.
Very short timeout values may cause specific utilities to “spin” faster and thus use
more CPU. Before making changes based on CPU consumption, isolate the CPU to
the offending processes. Use available tools to analyze each process. For example,
if pisnapss is in a high CPU state, run piartool -ss and look at Snapshot read and
write rates because excessive rates may be the true source of CPU load.
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 171 of this guide.
Activity Grid
The Archive Subsystem provides a tool for monitoring the rate of read-access to the Archive.
This tool creates, over a finite time period, a grid of activity. The grid indicates which users
and points account for the most activity. This monitoring requires significant computing
resources and therefore is normally turned off. Start the activity grid to identify the users that
present the greatest load on the system and the points that are being queried most often. Once
the load on the system is identified, it is best to turn off the activity grid.
To start the activity grid:
Piartool -aag start

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.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.
Page 254
11.8 - Solving Other Problems
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
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 PI ProcessBook Trend

If a PI ProcessBook trend “flatlines,” you may have a problem with PI ProcessBook, with the
PI Server, with network performance/connectivity/configuration, or with the data source.
Here are some possible diagnostic steps to take:
1. Determine whether only one tag is affected or several are affected. Check another
trend in the ProcessBook to see if the problem is limited to only some points. If the
problem involves multiple points, go to step 2. If the problem involves only one
point, go to step 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 PI ProcessBook program not being signed up for updates. See PIlistupd
Utility in the System Management chapter.
4. View the pending numbers in the results. Pending numbers represent the number of
events queued and not yet retrieved by the client such as PI ProcessBook. If data is
not arriving from the data source, the pending number remains at zero. If the client PI

ProcessBook is not retrieving the updates, the pending number continually grows and
does not shrink. This indicates whether the problem is with the PI Server or with the
client application.
5. If the pending updates are growing, try restarting the PI System. If this does not fix
the problem, contact OSIsoft Technical Support for additional assistance. If the
pending updates remain zero, go to step 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. Try inserting data into a test point (using piconfig or PI DataLink) and try trending
this point. If this is successful, go to step 6. If not, contact OSIsoft Technical Support
for additional assistance.
12. If all these tests are successful, the data source for the flatlined points may not be
working. Examine the Source-point attribute of the point to find out which interface
is feeding data for the point in question.
13. Check the PINetstats Table (See Chapter 1, PI System Management) to verify that the
interface program is running and connected to the Server.
14. Verify that the interface program is communicating with the external data source
(DCS system, RDB system, etc.). The documentation for the specific interface should
explain how to do this.
15. If the data source is running successfully, go to step 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
PI ProcessBook have the correct access to the system. Examine all messages about
trusts granted or refused.
17. If the points in question have some access restrictions, there must be established trust
logins. The interface must have access as a PI user with WRITE access to the points.
PI ProcessBook must have read access to all these points.
If none of the above steps have resolved the problem, contact OSIsoft Technical Support for
additional assistance.
Page 256
11.9 - COM Connectors
11.9 COM Connectors
Occasionally, errors are observed when OSI client applications fail to obtain process data. If
the errors are related to a foreign data historian, the applications generally receive error codes
in the range -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 OSI Technical
Support COM Connector page, available at http://techsupport.osisoft.com.
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
Page 258
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
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.
Page 260
3.) Run the Redirector Dump Script

Every COM Connector implements a method for obtaining information on its mapped points.
A script for requesting this information can be obtained from OSIsoft Technical Support Web
site at http://techsupport.osisoft.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.
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.
Page 262
Chapter 12. FINDING AND FIXING PROBLEMS: THE PIDIAG
UTILITY
The pidiag utility is a collection of tools for diagnostics, information, and simple repairs. It is
designed to help the PI System Manager and OSI Software technical support in gathering
information about a PI System, troubleshooting and solving some common problems.
The following sections explain in detail the various tools included in pidiag. To invoke
pidiag:
pidiag -xxx
where xxx identifies one tool. Depending on the specific tool, some additional parameters
might follow. The optional parameters are summarized in the following table and described
in this section, unless otherwise noted in the table.
Option 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 > Create Server ID file optionally passing Server ID and PI API ID. The PI
< APIServerID> ] | 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
[-install] | [-upgrade] 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
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| Dump header or all/filtered events from Event Queue file.
RecNo=n |PointId=<id>]
'path'
-qs 'path' Get offline queue file statistics.
-rgs [-?] [-u] 'path' Register or unregister COM component by running .rgs script in 'path'.
{ReplaceableParameter
="Value"}
-t time {U} Convert timestamp to string.
-tz {time} {TZ} Show timezone information.

[ -check | -dump
[-brief] | -full ]
-tz [ -if path | -ifrule [path] Special DST settings.

]
[-of path]
-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> Export audit records. This option is documented in Auditing the PI
[ -st <start> Server.
-et <end>
[-uid <unique id>]
[-xh <schema url>] ]
The pidiag utility resides in the PI\adm subdirectory.
Page 264
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 OSI technical support before using such tools. It is also advisable to make a
backup copy of the data file before compressing or repairing.
The following can be used to display a short help page with all the options.
pidiag -h
pidiag -?
12.1 General Information
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).
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
EndYear is the last year that the rule is in effect
Month is the month (1-12) that the rule is applied.
Week is the week (1-5) that the rule is applied. If week is 5 and there are only 4 weeks in
the month, then 5 designates the last week in the month. If week is -1, then week is to be
ignored and day becomes absolute.
Page 266
12.2 - Time Utilities
If week is greater than 0, then day is the relative day (1-7) that the rule is applied. A day
of 1 represents Sunday, a day of 2 represents Monday, and so on. For example, a week of
1 and a day of 1 means the first Sunday in April. If week is -1, then day is an absolute
day (1-31).
Time is the time in seconds after midnight that the rule is applied.
Offset is the time in seconds to subtract from standard time to get the local time. For
example, daylight saving time is in effect, -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.
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)
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
Page 268
12.3 - File-base Utilities
times, however, tend to reflect your system’s current time zone settings. Changing a
UNIX system’s time zone settings requires platform-specific techniques. You should
reboot your UNIX system after changing its time zone settings.
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.
OSI technical support can determine from this information if any errors occur in the structure
of the file:
C:\PI\adm>pidiag -fb c:\PI\dat\pidigst.dat
PIfilebaseheader::
File Name: C:\PI\dat\pidigst.dat
Major Version: 2
Minor Version: 0
Directory Location: 1024
Directory Size: 512
Record Count: 4
Last Recno: 0
Maximum Recno: 64
User Block Size: 512
Data Location: 1536
Data Size: 2724
PIsecureobject[@(#)pisecobj.cxx 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
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:
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
Page 270
12.4 - Archive Management
attempts an automatic recovery of the archive manager data file PI\dat\piarstat.dat.
Caution: Use only when the PI Server is shut down!
This option creates a new archive manager data file using the data in the existing data file. It
can be used if the index in the current file is corrupted.
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>
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%
----------------------------------------------------------------------
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%.
Page 272
12.4 - Archive Management
Looking at archive statistics and in order to maintain best performance, points should not
have more than one or two index records on average. If this is not the case for many points,
compression parameters should be reviewed for these points or the archive files should be
made smaller. In the above example, points 4 and 17 (recnos 4 and 11 respectively) clearly
have an excessive number of index records.
The archive check command will detect and report any errors in the archive file. Errors are
summarized at the end of the report but when running the command, they are sent to the
“standard error” (stderr) stream. As a result, when redirecting the output to a file, the
following syntax should be used so that errors are inserted into the output file report.txt:
pidiag -archk "archive_file" > report.txt 2>&1
Alternatively, the following construct can be used to redirect the output to two different files:
pidiag -archk "archive_file" 1> report.txt 2> errors.txt
The archive errors or corruptions could be the result of failures (crash, unexpected
termination, power failure, etc) or software bugs. In the case this happens, the offline archive
utility can be used to reprocess the corrupted archive file, recover the data and fix all issues.
For more information, see Using the Offline Archive Utility (piarchss) on page 40.
The -archk command can also be run with the optional argument complete, in order to
extract detailed information about the archive file structure. This extra information is similar
to what is provided by the archive walk command (see piartool -aw). It notably includes
point types and statistics (start time, event count, fill ratio) for every index or data record and
for each point in the archive file. The archive header information (see pidiag -ahd above) is
also included at the beginning of the report.
Here is an example of the detailed mode:
D:\PI\adm>pidiag -archk D:\PI\dat\piarch.001 complete
Analyzing archive: D:\PI\dat\piarch.001
-------------------------------------------------------------------------------
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
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
Page 274
12.5 - Server ID Utilities
12.5 Server ID Utilities
As of PI 3.3 SR1, the Server ID of the PI Server is stored in the PI\dat\PISysID.dat file. The
first time that any PI-SDK application connects to a PI Server from a given node, the PI-SDK
caches this server ID in the client’s local Registry. On subsequent connections, PI-SDK
applications compare the cached Server ID to the actual Server ID of the PI Server during the
Server.Open call to make sure that a connection is being made to the same PI Server.
Although the PISysID.dat file did not exist before PI 3.3 SR1, the PI Server still returned a
Server ID to PI-SDK applications. The PI Server used a hashing algorithm to determine the
Server ID, which took the name of the machine as input and generated a number as output.
This number was not a globally unique identifier (GUID), which meant that the hashing
algorithm could generate the same numeric identifier from two different machine names.
If PI 3.3 SR1 or greater is installed as a new system, the Server ID is generated as a GUID
and stored in the PISysID.dat file. If PI 3.3 SR1 or greater is installed as an upgrade from a
system that is less than 3.3 SR1, then the Server ID is generated using the old hashing
algorithm and stored in the in the PISysID.dat file.
There are three pidiag options, -dapi, -cid, and -did, that can be used to troubleshoot or to
generate a PISysID.dat file. The -dapi option echoes a Server ID to the standard output using
the old hashing algorithm. The usage is:
pidiag -dapi [hostname]
If hostname is not passed, then the host name of the machine is used in the hashing algorithm.
Here is some example output from the -dapi option.
pidiag -dapi MyServer Host: MyServer API Server ID: 6239
The -cid option generates a new PISysID.dat file. The usage is:
-cid [ < ServerID > < APIServerID> ] |install] | [-upgrade]
The optional APIServerID that can be passed on the command line is not used by any
application. If the optional ServerID is passed on the command line, simply pass the same
identifier for the APIServerID. The -install option causes the Server ID to be generated as a
GUID. The -upgrade option causes the Server ID to be generated using the old hashing
algorithm.
The -did option dumps the contents of the PISysID.dat file.
pidiag -did
Dumping file E:\PI\dat\PISysID.dat
1. MajorVersion: 3
2. MinorVersion: 3
3. MajorBuild: 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.
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
Page 276
12.6 - Performance Counter Utilities (Windows Only)
Interface (the Basic version is included with the PI Server distribution) can easily be set up to
historize the value of these performance counters in the PI Archive, as well as the 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.
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.
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:
Page 278
12.7 - Miscellaneous
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
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
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.
Page 280
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
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

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
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
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
Page 282
>> 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
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
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
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
Page 284
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
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
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
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.
Page 286
0 pinetmgr 27-Oct-05 16:24:20
piartool(2748) (8), ID: 23
0.54; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:20
>> Servertablelist received from: pialarm(3300). 3 entries: pialarm|1
pialarm_subsysquery|1 pialarm_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:20
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
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
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
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
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
Page 288
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
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
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
samson.osisoft.com. Name: RmpSE. User: piadmin. Trust: !Proxy_127!
0 pinetmgr 27-Oct-05 16:24:57
samson.osisoft.com. Name: RandE. User: piadmin. Trust: !Proxy_127!
0 pishutev 27-Oct-05 16:24:58
>> Shutdown of PI subsystem pishutev in progress.
0 pishutev 27-Oct-05 16:25:00
>> Shutdown Events at 27-Oct-05 16:21:46 sent for 10 Points
0 pishutev 27-Oct-05 16:25:00
>> Shutdown of PI subsystem pishutev complete.
0 pibackup 27-Oct-05 16:25:08
>> Successfully registered subsystem pisnapss, version 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
15.06; app: pishutev; user: ; osuser: ; trust: ; ip address: ; ip host:
Client Connection Messages

The pinetmgr utility writes messages to the PI System message log that track
communications between PI clients and the PI Server.
The following message from pinetmgr indicates that a client is attempting to connect to PI
Server. Note that a connection ID (cnxn ID) is assigned.
0 pinetmgr 27-Oct-05 17:23:14
Page 290
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
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
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
Page 292
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 A-1. Error Codes 1-99, With Messages
Code Code Identifier Message
0 PI_NORMAL Success
-1 PI_ERROR Generic Error or PI 2.x Point Out of Range or Not

Defined
-2 PI_ATT_BLANKTAG Blank tag
-3 PI_ATT_PTDBFULL Point data base full
-4 PI_ATT_MEMDBFULL Memory data base full
-5 PI_ATT_TAGNOTFOUND Tag not found
-6 PI_ATT_BADCHARTAG Illegal Characters in Tag
-7 PI_ATT_TAGEXISTS Tag already exists
-8 PI_ATT_BADTIME Time is After Current Time and Date or Time is <0
-9 PI_ATT_BADINTVALUE Illegal Status Value or Integer Value
-10 PI_ATT_OTHERPROC Cannot Create Tag Because Other Procedure is

Creating Tag
-11 PI_ATT_BADDIGCODERANGE Digital Code is Out of Range
-12 PI_ATT_NODSSTRING Digital state string not found
-13 PI_ATT_BADDSCODERANGE Digital State Code Out of Range For This Tag
-15 PI_ATT_NOSOURCETAG Source tag not found
-19 PI_ATT_PTATTZERO Point Attribute Zero Error or Disk Error for Point
Database
-20 PI_ATT_BADZEROSPAN Bad Zero or Span For Integer Point
-21 PI_ATT_NEGSPAN Span not greater than zero
-22 PI_ATT_BADTYPVALUE Typical Value Not Between Zero and Top of Range
Page 294
-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)

Point Source)

Point Source)

Point Source)

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
Page 296
-79 PI_EVM_BADTIMEOUT Bad timeout value
Table A–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
Page 298
-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
Page 300
-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
Page 302
-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
Page 304
-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_MISSINGREQATTRIBUTESE Required attribute set missing in the point

TS 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_ATRTYPECHANGEINPREDE Attribute type change in this attribute set not

FORINUSEATRSET allowed
-10593 PI_PD_ATTRIBDELINPREDEFORIN Attribute delete in this attribute set not allowed

USEATTRIBSET
-10594 PI_PD_ATTRIBSETDELINPREDEFO Attribute set delete in this point class not

RINUSEPTCLASS allowed

-10595 PI_PD_STANDALONEMODEREQUI This operation requires StandAlone mode

RED
-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
Page 306
-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_INVALIDRPCSERVERTABL PINet: Invalid or Null RPC Server Table List

ELIST
-10740 PI_NET_INVALIDHOST PINet: invalid host
-10741 PI_NET_RPCRESOLVERNOTAVAIL PINet: RPC Resolver chooses to not service

ABLE request
-10742 PI_NET_CONNECTIONLISTFULL PINet: Connection list full
-10743 PI_NET_RPCRESOLVERTMPOFFLI PINet: RPC Resolver temporarily Off-Line

NE
-10744 PI_NET_TRANSLATORINUSE PINet: PI API client attempted two or more

simultaneous calls.
-10745 PI_NET_MESSAGEVERIFICATIONF PINet: Message verification failure.

AILURE
-10746 PI_NET_MESSAGETOOLARGE PINet: Attempt to send or receive message

larger than maximum allowable
-10747 PI_NET_TRANSLATORVERIFICATI PINet: PIAPI translator verification failure.

ONFAILURE
-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_EXCESSIVEZEROBYTERE PINet: Connection broken by peer

ADS
-10753 PI_NET_INVALIDSESSIONID PINET: Invalid session ID
-10754 PI_NET_RPCTABLEGENMISMATCH PINET: RPC Table Generation mismatch
-10755 PI_NET_COMPLETIONPORTERRO PINET: Completion Port Error

R
-10756 PI_NEWERSERVERVERSIONREQU PINET: Newer server version required

IRED

-10757 PI_NOREMOTECONNECTION PINET: No remote connection
-10758 PI_NET_FAILEDREMOTECONNECT PINET: Failed remote connection

ION
-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_INVALIDPINETMGRCONTR Invalid PINetMgr Control Mode

OLMODE
-10764 PI_NET_NOTLOCALSESSION Access only allowed by local PI Server

connection
-10765 PI_NET_USERCANCELEDCONNEC ser canceled session login

TION
-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.
Page 308
-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.
Page 310
-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
Page 312
supported.
-11128 PI_AR_TOOMANYREQEVENT Number of requested events exceeded the

S: 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_HISTTIMEDVALUEFAI PI Redirector could not get archived value from

L foreign system
-11202 PI_ RDR PI Redirector could not get archived data from
_HISTTIMEDVALUESFAIL foreign system
-11203 PI_ RDR PI Redirector could not get snapshot value from
_SNAPTIMEDVALUEFAIL 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 PI Redirector could not get updates from foreign
_SNAPSUPDATESFAIL system.
-11207 PI_ RDR PI Redirector could not write snapshots to foreign

_SNAPPUTTIMEDVALUEFAIL system.
-11208 PI_ RDR PI Redirector could not load connector or set PI

_ADDCONNECTORFAIL 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_TYP Invalid variant type code.

E
-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
Page 314
-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
Page 316
-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_UNSUPPORTEDACTIVETAG Batch active tag is not integer, real, or digital.

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

-12306 PI_PE_RESOURCES_NOT_FOUND Performance Equation: File pisystem.res not

-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_TYPECHEC Performance Equation: Bad parse tree during

K type check
-12310 PI_PE_FUNC_WRONG_NUMBER_O Performance Equation: Function has wrong

F_ARGS 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_ARG Performance Equation: Wrong number of

S 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
Page 318
-12320 PI_PE_FUNC_ARG4_INVALID Performance Equation: Invalid fourth

argument
-12321 PI_PE_FUNC_ARGS_NOT_SAME_T Performance Equation: All arguments must

YPE have same data type
-12322 PI_PE_FUNC_ARGS_NOT_NUMBE Performance Equation: All function arguments

RS 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_BADCOUNTERNAMELENG he performance counter name is larger than 32

TH 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
Page 320
Table A–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
Page 322
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
Page 324
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
Page 326
-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_ARGUMEN Invalid arguments for Sub-system

TS Information RPC
-16701 PI_SUBSYSINFO_INVALID_PROCESSI Invalid process ID Sub-system Information

D 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_FILEN Cannot remove file from list of backed up

OTFOUND files because the file name was not found
in the list
-16824 PI_BCKFILE_ADD_ERROR_DUPLICAT Cannot add file to the list of backed up files

EFILENAME because the file is already in the list
-16826 PI_BCKFILE_DUPLICATE_BACKEDUP Only one backup file list object can be

_FILE_LIST created
-16840 PI_BACKUP_BACKUPSUBSYS_NOT_I Backup manager is not initialized

NITIALIZED
-16841 PI_BACKUP_VSS_UNSUPPORTED Unsupported operating system for Volume

Shadow Copy Services
-16842 PI_BACKUP_INVALID_COMPONENT_ Invalid component name

NAME
-16860 PI_VSSEVENT_FREEZE_IN_PROGRE VSS Freeze already in progress

SS
-16861 PI_VSSEVENT_FREEZE_NOT_IN_PR Expected VSS Freeze to be in progress,

OGRESS but freeze was not in progress
-16863 PI_BCKEVENT_FREEZE_TIMEOUT_W VSS Freeze timed out waiting for VSS thaw
AITING_FOR_THAW_EVENT event
-16864 PI_VSSEVENT_FREEZE_TIMEOUT_D VSS Freeze timed out before VSS freeze

URING_FREEZE_EVENT event could complete
-16868 PI_VSSEVENT_IDENTIFY_COMPONE VSS Identify failure. Two VSS components

NT_MISMATCH have the same name but different
component properties
-16893 PI_BCKEVENT_SUBSYSTEM_NOT_P Subsystem does not participate in backups.

ARTICIPATING The backup event was ignored
-16896 PI_BCKEVENT_RPCRESOLVEROFFLI RPC Resolver offline for a subsystem to

NE 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_TRA Invalid state transition for backup

NSITION
-16915 PI_BCKSTATE_BACKUP_ABORTED Backup was aborted
-16916 PI_BCKSTATE_BACKUP_SHUTDOWN Backup shutdown without completing

_NOCOMPLETE
-16917 PI_BCKSTATE_BACKUP_IN_PROGRE Backup in progress

SS
-16920 PI_BCKRPC_NO_RESPONSE Expected VSS Async callback function was

not called within timeout period
-16921 PI_BCKRPC_CALLBACK_UNEXPECTE Unexpected VSS Async callback. Callback

D function was called but was not expected
-16923 PI_BCKRPC_INVALID_BACKUP_COM Invalid backup command

MAND
-16940 PI_VSSAPI_ADDCOMPONENT_FAILE VSS API call AddComponent failed

D
-16941 PI_VSSAPI_ADDDATABASEFILE_FAIL VSS API call AddDatabaseFiles failed

ED
-16942 PI_VSSAPI_BACKUPTYPE_UNKNOW Unknown backup type

N
-16943 PI_VSSAPI_BACKUPTYPE_LOG_UNS Backup type of LOG is unsupported

UPPORTED
-16944 PI_VSSAPI_BACKUPTYPE_OTHER_U Backup type of OTHER is unsupported

NSUPPORTED
-16980 PI_BCKLOCK_GETLOCK_TIMEOUT GetLock timeout for master backup lock
-16981 PI_BCKLOCK_GETEXCLUSIVELOCK_ GetExclusiveLock timeout for master

TIMEOUT backup lock
-16983 PI_BCKLOCK_RETURNEXCLUSIVELO ReturnExclusiveLock failed for master

CK backup lock
-16984 PI_BCKLOCK_RETURNEXCLUSIVELO ReturnExclusiveLock for master lock failed

CK_NOTLOCKED because master lock was not locked
-16985 PI_BCKLOCK_GETLOCK_NONVSSBA GetLock failed for master backup lock

CKUP because a non-VSS backup is in progress
Page 328
-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_FORFRE Warning - not ready for freeze yet

EZE
-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.
Page 330
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 Rate at which digital state strings are translated to offsets.
Translations/sec
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 The total number of records in the module database.
Count
Module Create or Edit/sec Rate at which modules are created or edited.
Heading Set Create or Rate at which heading sets are created or edited.
Edit/sec
Heading Create or Edit/sec Rate at which headings are created or edited.
Module Database Create or Rate at which MDB records are created or edited.
Edit/sec

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 Rate at which module database information is accessed, not

Accesses/sec 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 Rate at which archive cache records are created.

Created/sec
Cache Records Rate at which archive cache records are deleted.

Deleted/sec
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 Rate of archive cache disk reads.

Reads/sec
Cache Record Memory Rate of archive cache memory hits.

Reads/sec
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 Rate at which archive cache records are removed from memory.
Operations/sec
Cache Flush Rate at which points are flushed to disk.
Page 332
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 Rate of calls to read events for mapped points through COM
Operations/sec Connectors. This rate is NOT included in the Read Operations/sec
counter.
Connector Events Rate of events read for mapped points through COM Connectors.
Read/sec 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 Time elapsed in milliseconds for one Events Read for a COM
Exec Time Connector point.
Connector Event Read Time elapsed in milliseconds for one Event Read for a COM
Connector Summaries Time elapsed in milliseconds for one summaries call for a COM
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 Maximum number of cache records in the read-only pool.
Pool
Current Cache Record Current maximum number of cache records, this may be lower that
Pool the configured value due to low memory resources.
Config. Max Unflushed Maximum number of unflushed events per point.

Events/pt
Current Max Unflushed Current maximum number of unflushed events per point, this may be
Events/pt 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 Rate of PI Transfer Record creation.

Created/sec
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 Rate of PI Transfer Record edits.

Edited/sec
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 Rate of PI Transfer Record access.

Read/sec
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 Rate of PI Transfer Record deletion.

/sec
PI Snapshot Subsystem Statistics
Snapshots/sec Rate at which events are sent to the snapshot.
Out Of Order Rate at which out-of-order events are sent to the snapshot.
Snapshots/sec
Page 334
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 Rate of digital strings translated into offsets.

Translations/sec
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 Rate at which events are read from mapped points through COM
GetSnapshots/sec 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 Time elapsed in milliseconds for Snapshot Put for COM Connector a
Elapsed Time point.
Connector Snapshot Read Time elapsed in milliseconds for Snapshot Read for a COM
Elapsed Time Connector point.
Connector Updates Time elapsed in milliseconds for Updates for COM Connector points.
Elapsed Time
Events in Primary Queue Number of events in the primary queue file.
Number of Overflow Number of overflow queue files (0 if only the primary queue is active).
Queues
Events in Overflow Queues Total of events in the overflow queue files.
Estimated Remaining Estimated maximum number of events with current queue file.
Capacity
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 Rate of data page shifts in primary queue file.
Shifts/sec
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 Rate of full evaluations of the WHERE clause of a SELECT

Evaluations/sec 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/se Rate of RPC calls made to the PI Archive Subsystem for summarized
c values (i.e. average, total, standard deviation, etc.).
Dot Variable Rate of "dot" variable evaluations made within the PI SQL Library. A
Evaluations/sec 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 Rate at which points are returned by the PI Base Subsystem in
Calls/sec searches for points with a specific PointSource attribute.
Page 336
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 The number of messages received by the PI Network Manager.

Received/sec
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.
Page 338
PI Subsystem Statistics
Message Queue Length Number of incoming messages in queue.
Pending Transactions Number of pending transactions.
Actual Pending Only for internal debugging purpose. You should use it only under the
Transactions suggestion of OSI Technical Support.
Message Pickup Time Latency of incoming messages (time in message queue).
Message Execution Execution time of incoming message (RPC).

Time
Message Complete Time Total message handling time (including results sending).
Callback Execution Time Execution time of transaction callback.
Transaction Number of transactions completed per second.

Completed/sec
Transaction Number of transactions cancelled per second.

Cancelled/sec
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.
Page 340
Table B–16. PI Performance Counters
Tag Explain Text
PERF.LOCALHOST.Logical Free Megabytes displays the unallocated space on the disk drive in
Disk(_Total).Free Megabytes megabytes. One megabyte = 1,048,576 bytes.
PERF.LOCALHOST.Memory % Committed Bytes In Use is the ratio of Memory: Committed

.% Committed Bytes In Use 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 is the overall rate that faulted pages are handled
.Page Faults/sec 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.Process % Processor Time is the percentage of time that the processor is

or(0).% Processor Time 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.Se Segments Retransmitted/sec is the rate at which segments are

gments Retransmitted/sec retransmitted, that is, segments transmitted containing one or more
previously transmitted bytes.
PERF.LOCALHOST.TCP.Se Segments Sent/sec is the rate at which segments are sent,

gments Sent/sec including those on current connections, but excluding those
containing only retransmitted bytes.
PERF.LOCALHOST.Process % Processor Time is the percentage of elapsed time that all of the
(piarchss).% Processor Time threads of this process used the processor to execute instructions.
PERF.LOCALHOST.Process An instruction is the basic unit of execution in a computer, a thread
(pibasess).% Processor Time is the object that executes instructions, and a process is the object
created when a program is run. Code executed to handle some
PERF.LOCALHOST.Process hardware interrupts and trap conditions are included in this count.
(pinetmgr).% Processor Time On Multi-processor machines the maximum value of the counter is
PERF.LOCALHOST.Process 100 % times the number of processors.
(pisnapss).% Processor Time

Tag Explain Text
PERF.LOCALHOST.PI Rate of archive events read.

Archive.Read Events
operations/sec
PERF.LOCALHOST.PI Archive cache disk reads.

Archive.Cache Record Disk
Reads/sec
PERF.LOCALHOST.PI Archive cache memory hits.

Archive.Cache Record
Memory Reads/sec
PERF.LOCALHOST.PI Base Total number of defined points. This number includes the
Subsystem.Point Count Connector Point Count.
PERF.LOCALHOST.PI The number of connections to the PI Network Manager. This

Network counter only applies to instance _Total.
Manager(_Total).Connection
s
PERF.LOCALHOST.PI The number of messages sent to the PI Network Manager.

Network
Manager(_Total).Messages
Sent/sec
PERF.LOCALHOST.PI
Network
Manager(piarchss).Message
s Sent/sec
PERF.LOCALHOST.PI
Network
Manager(pibasess).Message
s Sent/sec
PERF.LOCALHOST.PI
Network
Manager(pisnapss).Message
s Sent/sec
PERF.LOCALHOST.PI Out of order events sent to the snapshot.

Snapshot.OutOfOrderSnapsh
ots/sec
PERF.LOCALHOST.PI Events sent to Event Queue.

Snapshot.Queued
Events/sec
PERF.LOCALHOST.PI Events sent to the snapshot.

Snapshot.Snapshots/sec
PERF.LOCALHOST.PI Total Events pending in the PI Update Manager database.

Update-Manager.Pending
events
PERF.LOCALHOST.CALCU PI Compression Ratio is a performance equation that calculates

LATED.PI Compression amount of data that is compressed.
Ratio
Page 342
Tag Explain Text
PERF.LOCALHOST.CALCU PI Archive.Cache Hit Rate is a performance equation that

LATED.PI Archive.Cache Hit measures the rate at which data is accessed from memory as
Rate opposed to disk.

TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a

week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support

Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
techsupport@osisoft.com. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support

The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).

• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access

Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support

OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:

• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers

To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion -v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option -v (for example, piarchss.exe -v).
View Computer Platform Information

To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname -a
Page 346
INDEX OF TOPICS
? command, 186 combining files, 59

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

performance counters, 332 registering, 33
Archive Subsystem shift p rediction, 57
Troubleshooting, 231 size considerations, 53
archive walk, 49 sizing, 53
archives slow access, 35
archive registry, 56 space needs, 51
annotation files, 52 specifying maximum size, 54
anticipating overflow, 51 specifying number of points,
archive shift, 33 53
archive shifts, 57 time limit on modifying, 52
archive walk, 49 unregistering, 56
backfilling without Archives
compression, 54, 55 About, 33
command-line tools, 37 ArchiveX, 202
creating, 52 ASCII file
creating new primary, 55 using in piconfig, 183
deleting, 56 Attribute Point
editing data in, 51 Location4, 104
failing to register, 55 PointSource, 103
fixed and dynamic, 33, 35 Attribute Set Table, 191
for previously collected data, Attributes
54 Access Permissions
forcing archive shifts, 58 changing, 123
gaps, 34 Displaying, 174
ID conversion file, 43 For subsystems, 210
index records, 35 Istructure, 190
list record details, 49 Llisting for table, 186
maximum size, 53 Modifying
minimum and maximum size, in Point Database, 189
52
Wrong Class, 189
moving, 56
Set
moving to another server, 43
Point Database, 188
naming, 52
Time, 207
offline utility, 41
Timenum, 207
piarchss parameters, 41
Automatic Point Synchronization,
piarchss utility, 41 113
piartool utility, 37 Automatic Startup
precentage records used, 47 Compaq Tru64 UNIX
predicting shifts, 47 Systems, 11
processing, 41 HP-UX 10 Systems, 9
records, 34 HP-UX 9 Systems, 15
registering, 56 IBM AIX Systems, 13
Page 348
PI Server, 6 Case-preserving, 220
Solaris UNIX Systems, 7 Case-sensitive, 220
Windows Services, 6 Digital State Set, 198
backfilling archives flag, 186
creating new primary archive, UNIX operating system, 172
55 Cd command, 186
without compression, 54, 55 Character
backfilling data, 54 special, Changing, 223
Backups t for true, 178, 179
Automating, 66 Classic Point
PI Server, 63 Attributes, 189
Recommendations, 66 Classicctr, 258
Base Subsystem, 230 Clear command, 186
performance counters, 331 Client Applications
Batch Alias Table, 208 Connection Messages, 290
Batch method Security, 125
piconfig, 172 clock
Batch mode, 183 setting on interface nodes, 101
Batch Subsystem clock, system, 23
Batch Unit Table, 207 codes, error
Batch Tables, 209 operating system, 21
BATCHEXPR, 208 COM component
BID register, 279
Batch Subsystem, 209, 214, COM Connector
215
in-process, 262
BIDsearch
out-of-process, 262
Batch Subsystem, 209
troubleshooting, 257, 261
Boolean values, 222
Web site, 257
buffer, 95
Combining Archives, 59
buffering
ComChar, 186, 223
about, 95
Comma Separated Format, 179,
maximum size of buffer, 95 190
recommendations, 95 Command
Buffering ?tbl, 173
PI API, 96 All in piconfig, 186
bufserv Bye, 183
file buffer size, 95 Case, 220
Bye command, 183 character, 186, 223
BytesRecv, 211, 212 piconfig, 172
BytesSent, 211, 212 Comm, 180
C language, API, 96 Endsection, 182
Case command, 220 Error, 184

help, 176 firewall, 135
Iistructure, 196 Connections
input, 220 connection credentials, 128
Llisting all, 186 Display info on, 212
Ostructure, 180 ID, 291
Output, 184 Messages
piconfig commands, 176 Clients, 290
Quit, 183 Subsystems, 291
Select, 176, 181 slow, 254
Status ConStatus, 212
piconfig, 173 Consumer
Table, 173 pilistupd utility, 238
Command Line Arguments, 223 ConTime, 212
Command Specification ConType, 212
Persistence, 223 conversion files, ID, 43
Comment, 186 Convert mode, 178, 224
Character, 186, 190, 223 Corrupted
Changing, 180 Archives, 243
Command, 180 non-primary, 241
Lines, 180 Primary, 242
Communication Count
layer, 251 Batch Subsystem, 209
Routing function of PINet PIARC Table, 203
Manager, 229
piartool -al, 47
COMP
counter
mode, Piarc Table, 203
events, 23
Compaq Tru64
events in queue, 24
process count, 234
events in queue counter, 24
Compare mode, 178
events sent to queue counter,
compression 24
backfilling archives without, number of overflow queues, 25
54, 55
out of order events, 23
for backfilling archives, 54
out-of-order events, 23
out of order events, 23
remaining queue capacity, 25
ratio, 24
snapshot events read, 24
Compression
total overflow events, 25
Specifications, 24
Counter
compression tuning, 24
Archive Memory Cache
Computer platform counters, 28
Information, 346 Archived Events, 28
Connection Credentials, 128 Events Read, 28
evaluating matches for, 134
Page 350
number of archive read Dates
requests, 28 overlapping, 245
out-of-order event Daylight Savings Time
archive, 28 and interface nodes, 101
Overflow Data Record, 30 customizing changes, 267
Overflow Index Record, 30 list of changes, 267
PI Server Performance, 340 Dbsecurity, 173
counter, point, 23 DbsecurityTable, 216
counters Dcomcnfg, 257, 262
performance, 331 Default
CPU Digital State Set, 195
Excessive usage of, 253 default values
CPU usage pigetmsg parameters, 19
by utilities, 252 Delete
Create Mode, 178
Mode, 178 deleting archives, 56
creating archives for old data, 54 deleting connection error message,
creating new primary archives, 55 22
CSV format, 190 Delimited
ctr_lmap, 258 Structure type, 179
ctr_progid, 258 Delimiter, 186
ctr_strmap, 258 Character, 180, 187, 223
data Command, 180
time limit on modifying, 52 Format, 179, 223
Data Digital State, 5, 172
File repairs, 241 Table, 195
Recovering from corrupted Digital State Set
archives, 241 adding, 196
Data Archive capitalization, 198
Adding values, 201 Changing the Name, 198
data buffering default, 195
about, 95 limits, 195
data flow modifying, 197
buffering, 95 Digital State Table
snapshot, 22 merging systems, 153
Database Digital State Value
Firewall, 219 Sending to the Snapshot
Point, 57, 189 database, 200
Timeout, 219 Digital tag
Trust, 218 Creating, 199
Database Security, 173 DigitalSet, 199
Database Security Table, 216 Directory

PIHOME directory on NT, 101 error messages
Disconnect Messages, 292 about, 21
distributed data collection, 94 deleting connection, 22
Documentation interpreting, 21
conventions, v operating system, 21
for interfaces, vi rpc resolver, 22
Domain subsystem health check failed,
Name Server, 129 22
trust logins, 132 EVEN
Domain Controller interpolated events, Piarc, 203
Slow access to, 255 event
Dr. Watson, 278 definition of, 23
DST in the event queue, 24
and interface nodes, 101 out of order, 23
Dump capability overflow events, 25
crash pidiag, 278 remaining primary queue
capacity, 25
dxWindows, 234
sent to the Event Queue, 24
Dynamic archive, 36
Event Log
dynamic archives, 33, 35
configuring, 260
Echo, 186
event queue
Edit Mode, 178
events in, 24
Edit Mode Attribute, 204
events sent to, 24
editing archives, 51
monitoring, 25
Ellipsis construct, 182
number of overflow queues, 25
End of file, 183
remaining capacity, 25
EndRecord, 186
total overflow events, 25
End-Repeat, 186
Event Queue
Endsection, 186
recovery, 61
Command, 182
Troubleshooting, 230
Endtime, 203
Event Timestamps
error
correcting, 245
messages
events
interpreting, 21
time limit on modifying, 52
Error
events counter, 23
code number
events in queue counter, 24
translating to message
text, 265 events read counter, 24
Command, 184 events sent to queue counter, 24
messages, 281 Excel
interpreting, 281 Adding tags to Point Database,
190
Negative or Positive, 293,
294 Exit, 183, 187
Page 352
Failed to unregister input archive Command, 176
message, 242 lists all commands, 187
file buffer, 95, See also buffering Hexadecimal notation, 224
maximum size, 95 Hostmask, 173, 219
File corruption, 241 Modify, 120
File handles, 233 HP-UX
File-base Utility, 269 process count, 235
compact, 269 I/O
index, 269 Redirection, 184, 185
Firewall, 219 IBM AIX
Database, 219 process count, 234
Modifying, 118 ID
Security, 117 PINetMgr, 212
troubleshooting, 228 ID Conversion File, piarchss, 43
Fixed index record, 35
Format, 180 Initialization
structure Structure type, 179 archive, 57
Fixed Archive, 36 Input
fixed archives, 33, 35 Command, 183, 220
Flag redirect, 187
Shift-enable, 57 to piconfig, batch files, 183
Flags, 201 Installation
Flatline in a trend Redirector, 257
troubleshooting, 255 Integer Format to String, 266
Force processing, 196 Interactive session
Format piconfig, 172
Delimiter, 179, 182, 223 interface nodes
Fixed, 180 setting clock, 101
Keyword, 180, 186 Interface Nodes
full, archive, 33 definition of, 94
gaps Interface Status Utility, 113
archives, 34 interfaces
General Table Interface and PI API, 96
Timeout, Firewall, Proxy, 219 APS utility, 113
Group definition of, 94
assigning users to, 126 Interface Status Utility, 113
Database, 125 setting system clock, 101
table for, 215 Interfaces
Handle downloading documentation
Batch Subsystem, 209, 214, for, vi
215, 219 internal counters
Help piartool-qs, 25

Inter-process communication maxpoints, 53
TCP/IP, 252 maxsize, 54
UNIX Sockets, 251 MaxUpdateQueue, 31
IP Address, 117 Maxuprc, 235
IPAddr Maxusers, 235
trust logins, 132 message log, 18
IPHost Message Log, 2, 3, 229
trust logins, 132 message logs
Istat message subsystem offline, 20
Attributes, 202 pigetmsg, 18
Istructure, 180, 187, 190 remote login, 20
Command, 196 rpc resolver error, 22
Istype, 179 searching messages, 19
Key viewing on other servers, 20
primary, 176 viewing with pigetmsg, 18
Keyword, 180 Message Subsystem
Delimiter, changing, 180 performance counters, 336
Structure type, 179 message subsystem offline
Limit viewing messages, 20
digital state sets, 195 Messages
limits, time, 52 Client Connection, 290
List, 187 Disconnects, 292
Mode, 178 Interpreting, 281
primary key default, 181 Normal Startup, 281
LocalHost RPC Resolver, 293
Statistics, 340 Subsystem, 229
Location4, 104 Subsystem Connection, 291
Performance point, 112 Method
Login, 187 batch or interactive, piconfig,
explicit over trust, 135 172
Trust, 128 Millisecond timestamps, 207
login, remote minimum archive size, 52
pigetmsg, 20 Mode, 187
Manager. See PI Server System Edit, 178
Manager Piarc Table, 203
Mapped points, 258 piconfig, 176, 178
Max_nprocs, 235 Specifications, persistence,
Maxerr, 187 223
Maximum t option, 178
data segment, 233 Modify, 187
file handles/descriptors, 233 Command, 189
maximum archive size, 52, 53 Specifications, 189
Page 354
Module Database Security, 116
Repairing, 250 Operators
moving archives, 56 Modify Point Attributes, 189
XE "conversion files, ID" to piconfig, 181
another server, 43 OSBuild, 210
Moving PI Servers, 147 OSIsoft Universal Interface. See
MsgRecv, 211 UNIINT
MsgSent, 211, 212 OSSysName, 210
Name Ostructure, 187
Connection name, 212 Command, 180
naming archives, 52 Ostype, 179, 187
Netmask OSUser
trust logins, 132 trust logins, 133
NetType, 212 OSVersion, 210
Network Out of order event
definitions, display the, 278 counter
Router, 116 archive, 28
Security, 116 out of order events
Network Manager compression, 23
performance counters, 337 out of order events counter, 23
NEWhostmask, 119 Output, 187
Newset keyword, 176 Command, 184
Newtag keyword, 176 overflow events, 25
NEWUnitName, 207 Overflow Offsets
nodes, 94 piartool -al, 47
NT overflow queues, 25
Interface installation overflow XE "primary record"
PIHOME directory, 101 record, 34
Octal notation, 224 Overlapping dates, 245
offline archive utility, 37, 40, 41 Owner
list of parameters, 41 point attribute, 123
Offline Archive Utility Parameter
ID Conversion File, 43 Passing an input file, 184
time conversion file, 44 Passing as Output, 184
Time Filtering, 43 Timing, 219
offline mode Password, 126
pimsgss, 20 blank, 127
offline, message subsystem, 20 changing, 127
OpenVMS default, 127
and PI API, 95 reset piadmin, 278
Operating System Path
Error Codes, 293, 294 piartool -al, 47

PeerAddress, 212 Subsystem, 229
PeerName, 212 PI ProcessBook
Pending Number Data access, 125
pilistupd utility, 239 PI Processes, 229
Performance Counter Running independently, 232
PI Server, 340 Sign up for updates, 293
performance counters Status, 228
Archive Subsystem, 332 Stopping interactively, 4
Base Subsystem, 331 PI Proxy Database, 220
Message Subsystem, 336 PI Server
Network Manager, 337, 338 Automatic Startup, 6
PEs, 338 Backups, 63
Snapshot Subsystem, 334 data files, 235
SQL Subsystem, 336 Error Codes, 293, 294
TotalizerSubsystem, 337 Message Log, 290, 291
performance equations moving PI Systems, 147
performance counters, 338 performance counters, 340
Performance Equations Subsystem performance monitoring, 27
performance counters, 338 restore from backup, 243
performance problems Security, 116
out of order events, 23 Starting, 1, 281
Permissions Windows, 2
Attributes, changing, 123 Winpdows, 2
PEs Stopping, 1, 3
performance counters, 338 System Manager, 116
PI API Security responsibilities,
about, 96 116
Buffering, 96 Timing parameters, 219
impact on system set number, tuning, 251
201 PI Server System
on VMS, 95 Manager, 116
PI API buffering. See buffering PI session
PI Attribute Set Table, 191 performance counters, 338
PI Base Subsystem PI Session
Troubleshooting, 230 Statistics, 338, 339
PI Batch Alias Table, 208 PI Subsystem, 211
PI Batch Table, 209 Table, 211
PI Connections, 213 PI Subsystem Table, 210
PI DataLink PI System
Data access, 125 merging two systems, 153
PI Message PI tables
Log, 229 how to select, 172
Page 356
PI TagConfigurator, 171 number of overflow queues, 25
PI Thread Table, 215 out of order events counter, 23
PI_GEN, 173, 219 point counter, 23
Piadmin, 117, 124, 125 remaining capacity, 25
reset password, 278 total overflow events, 25
Piarc, 173 piartool -ss, 22
Edit mode attribute, 204 PIATRSET, 173
Piarc Table, 202 Pibaalias, 173, 208
piarchss, 37, 40 Pibasess, 230
offline archive utility, 41 Pibatch, 209
Piarchss, 231 PIBatch
piarchss -id, 43 considerations when merging
piarchss offline utility systems, 154
list of parameters, 41 Pibaunit, 173, 207
Piarcmem.dat, 236 Piconfig, 127, 203
piarcreate, 37, 52 Abbreviations, 220
Piarcreate, 52 Commands, 176, 186, 223
piarstat.dat, 56 Configuration.Persistence, 223
Piarstat.dat, 236 Echo command, 184
piartool, 37 Modes, 178
-aw, 49 Overview, 171
creating archives with, 52 Remote sessions, 185
deleting archives, 56 Starting, 172
moving archives, 56 Stopping, 172
-qs, 25 using quotes, 221
registering archives, 56 values sent as strings, 222
unregistering archives, 56 pidemo user account, 125
Piartool, 52 pidiag, 263
-al, 46 about, 21
results from, 47 -ad, 270
-as, 27 -ahd, 271
piartool -ac, 52 -ar, 271
piartool -acd, 52 -ara, 270
piartool -ar, 56 -e errorcode, 265
piartool -au, 56 -fb, 269
piartool -ooo, 23 -fb utility, 236
piartool -ss -fbc <path>, 269
events counter, 23 -fbf <path>, 270
events in queue counter, 24 -h or -?, 265
events read counter, 24 -host, 278
events sent to queue counter, interpreting error messages, 21
24 operating system errors, 21

Recovery utility, 247 PINet/OpenVMS, 115
-rgs, 279 Manager Subsystem, 229
-t time <U>, 265 Pinetmgr, 229
-tz, 266 Messages from, 290, 291
-udf <path>, 278 Pinetmgrstats, 212
-v, 265 PINetMgrStats, 173
Pidiag piperfmon.dif, 340
-crash, 278 Pipes
Interpreting Error Messages, WIN32, 212
293 PIPoint, 188
Utility, 293 Pipoints.dat, 237
-w msec, 278 Piptalia.dat, 237
Pidiff Piptattr.dat, 237
Keyword PIPTCLS, 173, 193, 194
mappings, 224 Piptclss.dat, 237
Pidignam.dat, 236 Piptunit.dat, 238
Pidigst.dat, 236 Pisetpass utility, 126, 127
Pids Pishutev, 5, 228, 231
Table, 195 Pisnap, 200, See also Snapshot
Pifilebase, 236 Pisnap.dif
pigetmsg list Snapshot values, 201
about, 18 Pisnap2, 201, 202, See also
default values, 19 Snapshot
parameters, 18 Pisnapss, 230
remote login, 20 PIStartupTime, 210
searching messages, 19 pistop.sh script, 4
Utility, 229 Pisubsys, 210
Pigetmsg PISubsys, 173
Utility, 281 PISubsysName, 211
pigrp, 126, 215 Pisubsysstats, 211
Pilastsnap.dat, 237 PISubsysStats, 173
Pilistupd utility, 238 PIThread, 173
Troubleshooting, 230 Pitimeout, 173, 219
pimaNNNN.dat, 237 PITimeout Table, 31
Pimapevq.dat, 237 PItrust, 218
pimsgss Piudsrdr.exe, 259
offline, viewing messages, Piupdmgr, 230
20 Messages from, 293
offline mode, 20 PIUser, 214
Pimsgss, 229 field for trust logins, 134
Pimsgtxt.dat, 237 Piusr.dat, 238
PINet Nodes, 95 Piusrctx.dat, 238
Page 358
Piusrgrp.dat, 238 piartool -al, 47
Piverify.sh script, 228 primary record, 34
PIVersion, 210 Priority
Point Trust Records, 135
access to, 124 PRODEXPR, 208
data access, 122 ProdIDsearch
Database, 189 Batch Subsystem, 209
Datagroup, 124 Producer
Dataowner, 124 pilistupd utility, 238
object for security, 122 Prompt, 187
Ownership, Changing, 123 ProtocolVersion, 212
Point class, 188 PtClass, 187
Point Attributes Ptclass command, 188
access to, 122 queue
Changing Owner, 123 number of overflow events, 25
Modifying, 189 number of overflow queues, 25
With Operators, 189 remaining capacity, 25
Point Class queue, event
Base, 188 monitoring, 25
Point Class Database, 192, 194 Quit command, 183
point counter, snapshot, 23 Quote, 187
Point Database, 57, 188 character, 223
migration from PI2, 224 Quote marks
Repairing, 250 used in piconfig, 221
table name, 188 RampSoak, 232, 240
PointID, 200 Random, 240
PointSource attribute, 103 Random Simulator, 232
Command line parameters, 102 record
PoolName, 215 archive, 34
predicting archive shifts, 47 Record, 188
primary archive, 33 attributes, 175
Primary Archive, 35, 46 Record Size
Recovering, 242 piartool -al, 47
primary archives records
creating new, 55 determining percentage used,
failing to register, 55 47
Primary index listing details, 49
Connection, 212 Records
Primary key, 172 Trust, Weighting, 135
Default, 181 Recovery tool, 247
Primary Offsets Recsep, 187
RecvErrors, 211, 212

Redirection Troubleshooting, 254
Output to files, 185 Root, 3, 116
Redirector Router, 116
confirming installation, 257 rpc resolver error message, 22
dump script, 261 RPCs, 251, 292, 293
starting, 258 Rval attributeAttributes, 202
troubleshooting, 257 Sam utility, 235
registering archives, 56 Scan classes, 104
Registry Score
archive, 56 Trust Records, 135
regsvr32, 262 SearchStart
Remote Batch Subsystem, 209
piconfig sessions, 185 Security, 115
Procedure Calls, 251, 292 Attributes
remote logins Changing, 123
pigetmsg, 20 Client, 125
Remove consumer from update Default points, 125
table, 293 Firewall, 117
removing archives, 56 Network, 116
Repairs Operating System, 116
Archive Registry, 246 Physical, 115
Data file, 241 Scenario for Users and Groups,
Excessive CPU Usage by 122
Utilities, 252 Table Edits, 216
Module Database, 250 Tag, 122
Point Database, 250 Troubleshooting, 230
Snapshot, 247 Trust Login, 128
System Time, 249 User Name and Password, 125
Tuning the Server, 251 Select, 188
Repeating attributes command, 176, 181
Ellipsis construct, 182 PI table, 172
Replacesp mode, 206 SendErrors, 211, 212
resolver error message, 22 server messages, 18
Resolver Messages, 293 Services
Restore Troubleshooting, 228
Archive, 244 trust login OSUser Names, 133
PI Server from backup, 243 SET, 191, 193, 194, 195
Subsystem Databases, 245 SETNO, 191, 193, 195
Reusing an Output File as an Input Shift
File
Archives, 57
piconfig, 185
shift flag
Reverse Name Lookup, 129
piartool -al, 47
Page 360
shift predicting, 47 Modify, 189
shift, archive, 33 Special Characters, Changing, 223
Shift-enable flag, 57 Specifications
Shutdown Events, 4 Compression, 122
Shutdown.dat, 4, 5, 238 Spreadsheet, 190
Sigd, 188 SQL Subsystem
Sign up for updates, 293 performance counters, 336
Significant decimal digits, 188 Start
sinusoid, 232 Messages, 281
Site-specific files, 2 PI, 1
size of file buffer, 95 UNIX, 3
size, archive records, 34 Windows, 2
Smit utility, 234 piconfig, 172
SMT Redirector, 258
about, vi Starting
snapshot PI, 2
event count, 22 Starttime, 203
events counter, 23 State
events in queue counter, 24 piartool -al, 47
events read counter, 24 STATE, 195
events sent to queue counter, State Sets
24 listing, 195
listing current information, 22 statistics
monitoring data flow, 22 performance counters, 331
number of overflow queues Status, 188
counter, 25
command, 173
out of order events counter, 23
PI processes, 228
point counter, 23
Stdout, 2
remaining queue capacity, 25
Stop
total overflow events counter,
PI, 1
25
on UNIX, 4
Snapshot, 5
on Windows, 3
list values, 201
piconfig, 172
repairing, 247
String to Integer Format, 266
Subsystem
Structure, 187, 188
Adding digital state
values, 200 Specifications, 181
recovering, 248 Type, 179
Troubleshooting, 230 STYP, 188
Snapshot Subsystem Stype, 179
performance counters, 334 Subnet, 118
Span specifying for trust login, 132,
143

Subsystem how to list, 173
Attributes, 210 PI_GEN, 219
Connection Messages, 291 Piarc, 202
PI Message, 229 Pibaalias, 208
Restore from Backup, 245 Pibatch, 209
Update Manager, 230 Pibaunit, 207
subsystem health check failed, 22 Pids, 195
Sun PIFIREWALL, 219
Solaris Pigroup, 215
process count, 235 Pinetmgrstats, 212
Superuser Pipoint, 188
Privileges, 122 Pisnap, 200
Sysdef utility, 235 Pisnap2, 201
SYST, 188 Pisubsys, 210
System Pisubsysstats, 211
Clock Pitimeout, 219
resetting, 249 PItrust, 218
digital state set name, 195 PIUser, 214
set number, 201 Selecting, 172, 173
Statistics, 211 Snapshot, 200, 201
system aggregate compression Specifications,persistence, 223
ratio, 24 Tag
system clock, 23 Adding Values to the Snapshot
on interface nodes, 101 Table, 201
system error codes, 21 creating, 199
System Management Tools, vi Datagroup, 124
system message logs Dataowner, 124
pigetmsg, 18 Listing information, 178
System State Set Mask, for shutdown, 6
modifying, 197 Removing point security, 124
Table Security, 122
Attributes TagConfigurator, 171
Displaying, 174 TCP/IP, 212
With Ellipsis, 182 Default port, 229
Batch Alias, 208 Technical Support, 345
Batch Unit, 207 Thread Table, 215
Command, 188 actions, 216
piconfig, 173 Threading, 253
Database Security, 216 Threads, 173
For accessing the PI Archive, time
202 setting on interface nodes, 101
Names, 172 Time
Page 362
Attributes, 207 shutdowns, 135
conversion file, 44 Trust Records
Filtering, 43 Weighting, Score, 135
future times in Snapshot Tuning
removing, 248 Utilities timeout value, 252
piconfig millisecond, 206 Tuning the PI System, 251
piconfig TimeFormat, 206 Type
Time Zone, 266, 268 Files, 236
utilities, 265 piartool -al, 47
time limits on modifying data, 52 UniInt
Time Transformation Processing, downloading documentation
245 for, vi
conversion file, 246 UnitName, Batch Subsystem, 207,
time zones 209
and interface nodes, 101 Universal Interface
TimeFormat, 206 downloading documentation
for, vi
TimeNum, 200
UNIX, 212
Timenum Attributes, 207
Case-sensitive, 220
Timeout Database, 219
Sockets protocol, 251
Timestamp
UNIX Process
Corrections, 44
Stopping, 232
Millisecond, 207
UNIX Process Quotas, 233
Timformat, 188
Unregister Archive
Timing Parameters, 219, 251
list unregistered files, 271
Totalizer Subsystem
unregistering archives, 56
performance counters, 337
Update Manager, 30
totalUpdateQueue, 31
MaxUpdateQueue, 31
TotalUpdateQueue, 31
Pending Update Limit, 31
Troubleshooting
Statistics, 340
Checklist, 225
TotalUpdateQueue, 31
PI Update Manager, 230
Troubleshooting, 230
Redirector, 257
Upgrade
Strategy, 225
Post Upgrade Tasks on UNIX,
Trust Database, 128, 218
147
defining a record, 130
User
fields, 131
Adding, 127
how to configure, 131
Database, 126
Trust Login, 128
Name and Password Security,
evaluating, 134 125
examples, 137 Passwords
installation, 136 changing, 127
network definitions, 278

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

Server System Management

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Server System Management

Caricato da

Copyright:

Formati disponibili

PI Server System Management Guide

© 1998-2006 OSIsoft, Inc. All rights reserved

OSIsoft Australia OSIsoft Japan KK

Sales Outlets and Distributors

Revised: January 2006

About this Guide

PI Server System Management Guide Page iii

The PI Server Documentation Set

Title Subject Matter

PI Server A guide to key add-on PI Server Applications: Performance Equations (PE),

Conventions Used in this Guide

PI Server System Management Guide Page v

Using PI Server Tools

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

Chapter 2. Monitoring PI System Health ...................................................................................17

Chapter 3. Managing Archives ...................................................................................................33

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

Chapter 5. Managing Interfaces .................................................................................................93

Chapter 6. Managing Security ..................................................................................................115

Chapter 7. Moving PI Servers ...................................................................................................147

Chapter 8. Copying a PI Server ................................................................................................151

Chapter 9. Merging Two PI Servers .........................................................................................153

Chapter 10. The piconfig Utility..................................................................................................171

Chapter 11. PI Troubleshooting and Repair..............................................................................225

PI Server System Management Guide Page vii

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

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

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

Chapter 2. Monitoring PI System Health ...................................................................................17

PI Server System Management Guide Page ix

2.6 Monitoring the Update Manager ....................................................................................30

Chapter 3. Managing Archives ...................................................................................................33

3.12.1 Combining Archives into a Single Archive............................................................59

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

Chapter 5. Managing Interfaces .................................................................................................93

PI Server System Management Guide Page xi

5.2.2 About PI Interface Nodes .....................................................................................94

Chapter 6. Managing Security ..................................................................................................115

6.6.6 PIDS ...................................................................................................................121

Chapter 7. Moving PI Servers ...................................................................................................147

Chapter 8. Copying a PI Server ................................................................................................151

Chapter 9. Merging Two PI Servers .........................................................................................153

PI Server System Management Guide Page xiii

9.2 Server Merge Procedure - Example.............................................................................156

Chapter 10. The piconfig Utility..................................................................................................171

10.4.9 PI Batch Alias Table ...........................................................................................208

Chapter 11. PI Troubleshooting and Repair..............................................................................225

PI Server System Management Guide Page xv

11.2.9 Pishutev ..............................................................................................................231

12.1.1 Version Information ............................................................................................265

Appendix A: PI Messages .............................................................................................................281

Appendix B: PI Performance Counters .......................................................................................331

Technical Support and Resources...............................................................................................345

PI Server System Management Guide Page xvii

Table 3–1. Options for Use with piartool..................................................................................37

PI Server System Management Guide Page xix

Table A–11. Error Codes 13000-13999, With Messages ......................................................319

Figure 6-1. Establishing PI Performance Monitor as a Windows Service..............................134

PI Server System Management Guide Page xxi

It is important to configure Shutdown Events. Generally, points collected by interfaces

PI Server System Management Guide Page 1

>> TCP/IP connection listener opened on port: 5450

1.1.1 Starting PI on Windows Systems

pigetmsg -et "" -mc 100 -msg "error*" -dc 10