PI 3.4.370 Install & New Features

PI Server 3.4.
370
Installation and New Feature Guide
Release: October 24, 2005
OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Worldwide Offices
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
OSI Software GmbH

Altenstadt, Germany
support@osisoft.com
OSIsoft Canada ULC

Montreal, Canada
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA
OSIsoft, Inc. Representative Office

Shanghai, Peoples Republic of China
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software Asia Pte Ltd.

Singapore
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
Brazil
Middle East/North Africa
Republic of South Africa
Russia/Central Asia
South America/Caribbean
Southeast Asia
South Korea
Taiwan
WWW.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
Unpublished -- rights reserved under the copyright laws of the United States
Version 2.4 -- November 23, 2005
PI Server 3.4.370
Page iii
TABLE OF CONTENTS
Click on a page number to go to a topic.
Chapter 1.
Introduction .................................................................................................................1
Chapter 2.
New Features...............................................................................................................5
Chapter 3.
Installation and Upgrade Procedures .......................................................................9
3.1
Overview.............................................................................................................................9
3.2
New Installation Procedure ..............................................................................................9
3.3
3.2.1
New Installation Routine.......................................................................................10
3.2.2
Sample Installation ...............................................................................................12
Upgrade Installation Procedure .....................................................................................18

3.3.1
Upgrade Installation Routine ................................................................................19
3.3.2
Sample Upgrade...................................................................................................21
Chapter 4.
PI Server Backup.......................................................................................................29
4.1
Introduction......................................................................................................................29
4.2
Planning for Backups......................................................................................................29
4.3
4.2.1
Choose the Backup Platform (VSS vs. Non-VSS) ...............................................29
4.2.2
Choose a Backup Strategy...................................................................................30
Backup Guidelines ..........................................................................................................30

4.3.1
General Guidelines...............................................................................................30
4.3.2
Guidelines for VSS Backups ................................................................................31
4.3.3
Guidelines for Non-VSS Backups ........................................................................32
4.4
Backup Prior to Upgrade ................................................................................................33
4.5
Automating PI Backups ..................................................................................................33
4.6
Page iv
4.5.1
Automate Backup in Windows..............................................................................33
4.5.2
Perform a Test Backup.........................................................................................36
4.5.3
Perform a Test Restore ........................................................................................37
Automate Backup in Windows with a Third Party Backup Application.....................40
4.7
4.6.1
Automate Backup in a Cluster Environment.........................................................41
4.6.2
Automate Backup in UNIX....................................................................................41
How the PI Backup Subsystem Works..........................................................................42

4.7.1
Principles of Operation .........................................................................................42
4.7.2
Selecting Files or Components for Backup ..........................................................43
4.7.3
The Backup Components of PI ............................................................................45
4.7.4
The Files and Components for Each Subsystem.................................................46
4.7.5
Lifetime of a Backup .............................................................................................49
4.8
Launching Non-VSS Backups ........................................................................................53
4.9
Managing VSS and Non-VSS Backups..........................................................................54

4.9.1
Backup Command Summary ...............................................................................54
4.9.2
Using piartool backup -query..............................................................................56
4.9.3
Using piartool backup -identify ...........................................................................57
4.10 Timeout Parameters ........................................................................................................58

4.11 Troubleshooting Backups ..............................................................................................60
4.11.1 Log Messages ......................................................................................................60
4.11.2 VSSADMIN ...........................................................................................................62
Chapter 5.
License Manager .......................................................................................................65
5.1
How It Works ....................................................................................................................65
5.2
License File ......................................................................................................................65
5.3
License Manager .............................................................................................................65
5.4
Monitoring ........................................................................................................................66
Chapter 6.
PI Point Class Edit ....................................................................................................67
6.1
Introduction......................................................................................................................67
6.2
Overview...........................................................................................................................68
6.3
User Interface for PI Point Class and Attribute Set Edit..............................................70
6.4
Attribute Sets Database Edit ..........................................................................................70
6.5
6.6
6.4.1
Attribute Set Creation ...........................................................................................70
6.4.2
Attribute Set Deletion............................................................................................72
6.4.3
Attribute Set Edit...................................................................................................73
Point Class Database Edit ..............................................................................................77

6.5.1
Point Class Creation.............................................................................................77
6.5.2
Point Class Deletion .............................................................................................77
6.5.3
Point Class Edit ....................................................................................................77
Editing a Point Class Attribute.......................................................................................79
PI Server 3.4.370
Page v
6.6.1
6.7
Point Database Audit ......................................................................................................81

6.7.1
6.8
Audit Records .......................................................................................................82
Thread-safety ...................................................................................................................84
Chapter 7.
7.1
Conversion of COM Connector Class to and from a Native PI Class ..................80
PI Point Type Edit......................................................................................................87
Editing Point Types .........................................................................................................87
Appendix A Predefined Attribute Sets and Point Classes .......................................................93
Page vi
INTRODUCTION
Chapter 1.
This guide is a supplement to the PI Server 3.4 Documentation Set, published December
2003. The PI Server Documentation Set includes:
Introduction to PI System Management
PI Server Installation and Upgrade Guide
PI Server System Management Guide
PI Server Reference Guide
Auditing the PI Server
PI Server Applications User Guide
PINet and PIonPINet User Guide
Use this guide as a reference, in addition to the PI Server 3.4 Documentation Set, when you
install or upgrade PI Server, 3.4.370.
Note: The PI Server Documentation Set is scheduled for revision and release in 4Q
2005. Information in this publication will be incorporated into the revised set. Check
the OSI Technical Support Website for updated documentation.
Scope
This guide provides information only about new and enhanced features.
The current release and this guide apply to PI Server applications for Windows
32-bit platforms only.
Upgrades and enhancements pertaining to Windows 64-bit and UNIX platforms will
be documented in the revised PI Server 3.4 Documentation Set.
PI Server 3.4.370
Page 1
Chapter 1 - Introduction
Document Organization
This guide includes the following information:
Overview
Chapter 2 New Features
Read the Release Notes for more information about these and additional
enhancements.
Changed Procedures
Chapter 3 Installation and Upgrade
Chapter 4 PI Server Backup
Chapters 3 and 4 supersede similar chapters in earlier publications.
New Features and Procedures

Chapter 5 License Manager
Chapter 6 PI Point Class Edit
Chapter 7 PI Point Type Edit
Chapter 5 is a new chapter. Chapter 6 and Chapter 7 supplement Archive
Management chapters in earlier publications.
Key Considerations
Page 2
Installation of (or upgrade to) PI Server 3.4.370 requires a License File.

Requirements are explained in Chapter 5.
The new Backup Subsystem requires careful consideration for the installation
platform for new installations. We recommend installation on a platform that
supports VSS. See section 0, There have been several key enhancements to backups
with the release of PI 3.4.370.
Subsystems no longer need to be shut down in order to perform backups.
PI databases remain readable during the entire backup process.
If the PI Server is running on a platform that supports Volume Shadow Copy

Services (VSS), then the backup will be performed using VSS. The
advantage of doing VSS backups is that the PI databases are unavailable for
writes for only a very brief period of time, typically on the order of
milliseconds.
Overview
Important: If you are upgrading your PI Server from a version prior to 3.4.370, then
you must re-configure your backups. Backups that you had previously configured will
cease to run. After you upgrade to version 3.4.370, you must re-define and
reschedule backups.
Planning for Backups for more information.
System Administrators must re-configure scheduled backups after an upgrade.
PI Server 3.4.370
Page 3
NEW FEATURES
Chapter 2.
Enhancements in PI Server Version 3.4.370

PI Server 3.4.370 includes several new subsystem changes, the use of new tools, and changes
in procedures. Enhancements include:
License Manager A License File is now required for installation and upgrade.
Backup Subsystem Backups no longer require system shut-down, allowing

virtually transparent operation.
Point Class and Point Type Editing System administrators now have the ability to
edit and delete Attribute Sets, Point Classes and Point Types.
Update Manager New, faster internal sign-up mechanism.
Archive Subsystem the Archive Subsystem is now optimized to handle higher

throughput at faster speeds, eliminating bottlenecks and performance slowdown.
System Digital State Set Change PI Server installation will attempt to insert
SYSTEM digital state 315 to Coercion Failed.
Security Enhancements The PI Server now offers more versatile and secure
Administrator account and privilege management, and enhanced audit trails.
License Manager
With this version of the PI Server, a License File is required for an installation or upgrade to
succeed. A License File, called pilicense.dat, is provided separately from PI Server
installation packages. You can obtain a License File from the OSIsoft, Inc. Technical Support
Download Center, or from a CD provided to you.
With the current and future versions of PI Server, installation or upgrade will fail if a License
File is missing, expired, or corrupt. The PI Server 3.4.740 and later will not operate without a
valid license. License management is provided with Piartool lic {argument} as
explained in this guide.
Backup Procedures
Backups of the PI System have been enhanced considerably in PI 3.4.370. Backups no longer
require any subsystem in PI to be shut down.
PI Server 3.4.370
Page 5
Chapter 2 - New Features
If PI is installed in Windows 2000 Server, the files for each subsystem are put into a readonly state during the backup. If PI is installed in Windows 2003 Server, PI uses Volume
Shadow Copy Services (VSS) to perform backups. For a VSS backup, PI database files are
placed into a read-only state for a very short period of time, typically less than 1 second.
Thus, VSS backups have very minimal impact on PI system operation.
The pibackupat.bat and pibackupclusterat.bat files are no longer installed or used by the PI
Server. Upgrading removes the pibackupat.bat and the pibackupclusterat.bat files, and the
replacement file, pibackuptask.bat, is installed.
The default backup time is changed from 2:00 am to 3:15 am to avoid ambiguous backup
time during Daylight Saving Time transitions.
After an upgrade, backups must be rescheduled. Earlier backup settings are not incorporated
in the upgrade.
Point Class and Point Type Editing
This release allows a new feature, the ability to edit/delete Attribute Sets and Point Classes
(with some restrictions.)
This feature allow users with uint16 type excmax and compmax attributes in base attribute
sets (which originate in earlier PI3 versions) to upgrade these attributes to uint32. This
feature also allows users who may have been using points in one Point Class to switch to a
different one (new or existing), or from one data type to another.
This feature allows the same points to continue to collect data seamlessly, but via a different
mechanism.
Update Manager
New, faster internal sign-up mechanism. Better handling of network interruptions that causes
ungraceful disconnects.
Archive Subsystem
Hyper-threading no longer an issue. The Archive Subsystem now has a higher throughput,
which can support archiving at well-over 100,000 events/second. Competition on read/write
threads on busy points that could cause a queue stall is no longer an issue. Remove/replace
events that previously caused an I/O per event are now handled similar to other events, and
thus perform at least two orders of magnitude faster.
System Digital State Set Change
During upgrades, the PI Server installation will attempt to insert SYSTEM digital state 315
with the string Coercion Failed. This state is used during failed Point Type edits. If you
have already created SYSTEM digital state 315 and its string is neither blank nor ?315, the
PI Server installation will warn you, and the state will not be changed. Since PI2, the reserved
range of states in the SYSTEM digital state set has been 193-320; thus, no system should
have created this state.
Page 6
Overview
Security Enhancements
PI Server version 3.4.364 and earlier include several tasks that require the PI Administrator
(PIADMIN) account. PI Server version 3.4.370 provides additional Database Security entries
(PIARCADMIN, PIARCDATA, and PIDBSEC.) These allow you to specify owners and
groups for specific databases and administrative tools. This enhancement allows granting
access privileges with more granularity and permits multiple system administrators to
perform various administrative tasks. In addition, this enhancement provides thorough logs
and audit trails of system database changes that can be tracked back to an individual user.
PI Server 3.4.370
Page 7
INSTALLATION AND UPGRADE PROCEDURES
Chapter 3.
3.1
Overview
There are two distribution kits available for the PI Server. A self-extracting executable is
available from OSIsoft Technical Support Download Center. A CD containing the installation
kit is available from Customer Support.
Note: This document does not provide system requirements or full preparation
considerations. Refer to the latest downloadable version of the PI Server
Documentation for additional installation requirements, planning and considerations.
License File
Be sure to review License File requirements in Chapter 5 before installation.
3.2
New Installation Procedure

The PI Server installation routine (Setup) for the Windows platform is fully automated.
Setup performs certain required checks on the system, including platform, hardware, installed
operating system, etc.
Setup determines the presence (or not) of required supporting Microsoft products, including
the version of relevant installed software. Setup installs (or upgrades) the following Microsoft
products, as needed. In the event that a reboot is needed, Setup automatically reboots your
computer and continues with PI Server installation after restart.
Microsoft Windows Installer, Microsoft Windows Script, Microsoft Data

Access Components
Installation Configuration
During installation, Setup asks you to provide certain information. Be prepared to decide or
define the following during installation:
PI Server 3.4.370
Page 9
Chapter 3 - Installation and Upgrade Procedures
Location of the PI Server License File, pilicense.dat
User and Company Name
System Serial Number
If Microsoft Cluster Service (MSCS) is installed, determine whether this will be a

clustered PI Server installation
PI SDK path (installation folder)
PI Server path (installation folder)
Whether to install default points?
Whether to start the PI Server services automatically after a reboot?
Data Archive path (installation folder)
Default Data Archive size (MB)
Optionally, custom (vs. default) Event Queue settings

Event Queue Path
Event Queue Size
Event Queue Page Size
Installation Considerations
3.2.1
Cluster Installation If you are installing PI in a cluster environment, see Appendix

A: PI Server Cluster Installation, in the PI Server Installation and Upgrade Guide.
New Installation Routine

The following is the Setup routine for new installations. System administrators may find this
helpful for planning or troubleshooting.
1. Setup opens a log file PIServerMaster.log in the root directory of the system
partition. For example, if Windows is installed in e:\winnt, the log file would reside
in the root of the e: drive: e:\PIServerMaster.log. This log file documents the overall
progress of the PI Server installation as well as the installations of the supporting
software.
2. Setup installs or upgrades supporting software such as Microsoft Windows
Installer, Microsoft Windows Script, Microsoft Data Access Components, and
Microsoft .NET Framework. In the event that a reboot is needed, the setup program
will automatically continue with the setup after the reboot.
3. Setup opens a log file SetupPIServer.log in the root directory of the system partition.
4. Certain system .dlls are checked for necessary installation or updates.
5. The version of the system to be installed is determined.
6. The system requirements are verified, such as Windows version, CPU, and network
installation.
Page 10
7. Setup checks for the Microsoft Cluster Service. If the service is detected, then the
user is prompted for a clustered installation of the PI Server.
8. Setup asks for the location of the license file (pilicense.dat).
9. User information is solicited, including the user name, company name, and the
system number (serial number). The system number identifies the installation to
OSIsoft and is provided on the packing list. This number is useful when contacting
OSIsoft Support or Sales.
10. Setup solicits the target path for installation and creates it if necessary.
11. If the pipc.ini file does not exist in the operating system directory or PIHOME is not
defined in the pipc.ini file, setup solicits the target path for the installation of the PI
SDK.
12. Setup allows the user to specify additional installation options. These include
whether PI services will be installed to automatically start on system reboot and
whether the default points should be installed (default points are recommended).
13. Setup solicits the default archive size and location.
14. Files are copied to the target.
15. The registry is updated with PI installation information.
16. PI databases are created. These include the Point Database, Digital State Table, and
Security Tables.
17. For clustered installations, Setup installs PI Cluster Wizard.
18. PI Services are registered.
19. The log file is closed and moved to the dat subdirectory of the directory indicated by
the PIHOME entry of the pipc.ini file.
20. If necessary, the PI SDK installation (which includes the PI API) is installed or
updated. It is recommended that for a clustered installation, the PI SDK be installed
on the non-shared disk.
21. The default PI interfaces are installed. Setup installs these interfaces in the Interfaces
subdirectory of the directory indicated by the PIHOME entry of the pipc.ini file. The
installation log files for each interface installation is located in the DAT subdirectory
of directory indicated by the PIHOME entry of the pipc.ini file
22. The PI Interface Configuration Utility is installed in the ICU subdirectory of the
directory indicated by the PIHOME entry of the pipc.ini file. The ICUs for the
default interfaces are installed in the same directory.
23. For clustered installs, if the installation is for the first cluster node, the installation
procedure will need to be repeated on the remaining cluster nodes.
24. The first time the PI Server is started, it will complete installation by processing the
PI\adm\pirunonce.dif script. After the first run, this script will no longer be
processed.
PI Server 3.4.370
Page 11
25. For clustered installs, after installation is complete on all cluster nodes, run the PI
Cluster Wizard (PIClusWizard.exe) located in the directory \PI\adm to configure the
cluster group and resources for the PI Server.
3.2.2
Sample Installation
In this example, Microsoft Windows Installer and Microsoft Windows Script is already
installed. The Microsoft Data Access Components (MDAC), Microsoft .NET Framework,
and the PI SDK need to be installed.
1.)
Setup surveys your system and provides a report of software that is already installed, and
that needs to be installed or upgraded.
Setup checks if MDAC is installed and if the version of MDAC is greater or equal to 2.7.
Setup launches the MDAC installation.
Page 12
2.)
Setup checks the version of Windows Installer, and silently installs the new version of
Windows Installer if needed. The Windows Installer installation may ask for a reboot to
complete.
3.)
Setup checks for the Microsoft Windows Script; it is installed (or upgraded) if needed.
4.)
The final pre-installation step is to install Microsoft .Net Framework if needed.
Click I Agree, and Install to continue.

PI Server Installation
5.)
After prerequisite installations are complete, the PI Server installation begins.
PI Server 3.4.370
Page 13
Page 14
6.)
Select the location of the license file, pilicense.dat. Click browse to change the location.
7.)
Provide Name, Organization, Serial Number, and define user options.
8.)
Define the installation directory for the PI SDK.
9.)
Define the installation directory for PI Server.
PI Server 3.4.370
Page 15
10.) Select whether to install Default Points, and if you want PI Server to start a reboot.
11.) Define the directory for Data Archive databases. Define the Default Archive size in MB.
Click Advanced to define custom Event Queue settings. Otherwise, click Next to
continue (and use default Event Queue settings. You can change these later.)
Page 16
12.) Define the installation directory for the Event Queue. Define the Event Queue Size and
Event Queue Page Size.
13.) Setup is ready to begin. Click Next to continue.
PI Server 3.4.370
Page 17
14.) Setup copies all files to proper locations and installs default interfaces.
15.) The PI SDK installation runs after the PI Server installation is complete.
16.) Setup installs default PI interfaces and other server applications in its own separate
Windows Installer window. As an example, the PI Random Simulator Interface Windows
Installer window is displayed.
17.) After all interface installations are complete, Setup is finished.
3.3
Upgrade Installation Procedure

The PI Server installation routine (Setup) for the Windows platform is fully automated.
Setup performs certain required checks on the system, including platform, hardware, installed
operating system, etc.
Page 18
Backup Now
Be sure to backup your PI server before performing an upgrade. See section 4.4,
Backup Prior to Upgrade.
Setup determines the presence (or not) of required supporting Microsoft products, including
the version of relevant installed software. Setup installs (or upgrades) the following Microsoft
products, as needed. In the event that a reboot is needed, Setup automatically reboots your
computer and continues with PI Server installation after restart.
Microsoft Windows Installer, Microsoft Windows Script, Microsoft Data

Access Components
Upgrade Installation Configuration Choices

During installation, Setup asks you to provide certain information. Be prepared to decide or
define the following during installation:
Location of the PI Server license file, pilicense.dat
User and Company Name
System Serial Number
Whether to start the PI Server services automatically after a reboot?
Whether to proceed with the upgrade, or stop to perform a backup first?
PI SDK path (installation folder, if not already installed.)
Upgrade Considerations
For a clustered PI Server installation, refer to PI Server Installation and Upgrade

Guide, Appendix B: PI Server Cluster Installation for instructions. With the upgrade
installation, you must use the PI Cluster Wizard (PIClusWizard.exe, in the \PI\adm
directory) to create clustered resources for the two new PI Server subsystems: PI
License Manager and PI Backup Subsystem. This procedure does not modify existing
clustered resources.
Note! If you have PI Server 3.1 or 3.0 installed, you must first upgrade to PI 3.2.
You cannot upgrade directly to PI Server 3.4.370.
3.3.1
Upgrade Installation Routine

The following is the Setup routine for upgrade installations. System administrators may find
this helpful for planning or troubleshooting.
1. Setup opens a log file PIServerMaster.log in the root directory of the system
partition. For example, if Windows is installed in e:\winnt, the log file would reside
in the root of the e: drive: e:\PIServerMaster.log. This log file documents the overall
PI Server 3.4.370
Page 19
progress of the PI Server installation as well as the installations of the supporting

software.
2. Setup installs or upgrades supporting software such as Microsoft Windows
Installer, Microsoft Windows Script, and Microsoft Data Access Components. In
the event that a reboot is needed, the setup program will automatically continue with
the setup after the reboot.
3. Setup opens a log file SetupPIServer.log in the root of the system partition.
4. Certain system .dlls are checked for necessary installation or updates.
5. The version of the system to be installed is determined.
6. The system requirements are verified, such as Windows version, CPU, and network
installation.
7. Setup checks for upgrade (any evidence of a prior installation). If detected, the
upgrade procedure is executed. If a new installation is desired, the existing PI Server
should first be removed. See the section below on Removing PI Installations.
8. Setup checks for the Microsoft Cluster Service. If the cluster service is detected and
is running, then the user is prompted for a clustered upgrade of the PI Server.
9. Setup checks for downgrades. Downgrading PI is not supported. To return to a prior
version (build) of PI, the entire system including the data file and archives need to be
restored from backup.
10. User information including the user name, company name, and the System Number
(serial number) is verified. The System Number identifies the installation to OSIsoft
and is provided on the packing list. This number is useful when contacting OSIsoft
Support or Sales.
11. Setup asks for the location of the license file (pilicense.dat).
12. Setup verifies the target path of the existing installation.
13. If the pipc.ini file does not exist in the operating system directory or the PI SDK is
not installed, Setup solicits the target path for the installation of the PI SDK.
14. Setup allows the user to specify whether PI services will be installed to automatically
start on system reboot.
15. Setup asks the user to acknowledge the new backup scheme.
16. The user is prompted to acknowledge that they have a good PI Server backup. It is
recommended that a complete backup of the PI Server be done before upgrading.
17. Setup checks for any running PI processes and asks to stop the PI services before
continuing with the upgrade.
18. Setup verifies and creates if necessary all target directories.
19. The remaining files are copied to the target.
20. If selected, the support symbols are copied to the Windows system disk.
Page 20
21. The registry is updated with PI installation information, and old registry information
is removed if found.
22. PI databases are updated if necessary.
23. Out-of-date files are removed.
24. Out-of-date files and services that belong to the PI Server Applications are removed.
25. The default interfaces are installed or upgraded. When upgrading from PI 3.2, the
upgrade will first check to see if each of the six interfaces have been installed in the
PI\interfaces directory. If found, then the interface will be upgraded in that directory.
Otherwise the interface will be installed in the directory that is indicated by the
pipc.ini file. Refer to the PI SDK documentation for further information regarding the
pipc.ini file.
26. PI Service registry entries are updated.
27. The log file is closed and offered to the user.
28. For clustered installs, if the installation is for the first cluster node, the installation
will need to be repeated on the remaining cluster nodes.
29. For clustered installs, after installation is complete on all cluster nodes, run the PI
Cluster Wizard (PIClusWizard.exe) located in the directory \PI\adm to create
clustered resources for the two new PI Server subsystems: PI License Manager and
PI Backup Subsystem; any existing clustered resources will not be modified
3.3.2
Sample Upgrade
In this example, Microsoft Windows Installer is already installed. Microsoft Windows
Script, Microsoft Data Access Components, Microsoft .NET Framework, and the PI SDK
need to be installed or upgraded.
18.) Setup surveys your system and provides a report of software that is already installed, and
that needs to be installed or upgraded.
PI Server 3.4.370
Page 21
Setup checks if MDAC is installed and if the version of MDAC is greater or equal to 2.7.
Setup launches the MDAC installation.
19.) Setup checks the version of Windows Installer, and silently installs the new version of
Windows Installer if needed. The Windows Installer installation may ask for a reboot to
complete.
20.) Setup checks for the Microsoft Windows Script; it is installed (or upgraded) if needed.
21.) The final pre-installation step is to install Microsoft .Net Framework if needed.
Click I Agree, and Install to continue.
Page 22
PI Server Installation
22.) After prerequisite installations are complete, the PI Server installation begins.
23.) Select the location of the license file, pilicense.dat. Click Browse to change the location.
PI Server 3.4.370
Page 23
24.) The user information from the previous installation is displayed. Optionally, change the
Name, Organization, Serial Number, and define user options.
25.) The location of the existing installation is displayed. Click Next.
Page 24
26.) Select whether you want PI Server services to start after installation.
27.) Review information about the new Backup procedure. If you are upgrading from PI
Server version 3.4.364.32 or earlier, Setup reminds you that the upgrade uses a new
backup subsystem and that previously scheduled backups will no longer run.
After you acknowledge and accept this change, click Next.
PI Server 3.4.370
Page 25
28.) Setup detects that PI Server processes are running. To continue, you must acknowledge
a.) that you have a good backup of the PI Server, and b.) that you can now allow the PI
Server to shut down to allow an upgrade.
[Click Cancel to install the upgrade at another time.]

Select options as illustrated to continue, and click Next.
29.) Setup stops the PI Server and services dependent on the PI Server.
Page 26
30.) If required, the PI SDK installation runs after the PI Server installation is complete.
31.) Setup installs default PI interfaces and other server applications in its own separate
Windows Installer window. As an example, the PI Random Simulator Interface Windows
Installer window is displayed.
32.) After all interface installations are complete, Setup is finished.
PI Server 3.4.370
Page 27
Chapter 4.
4.1
PI SERVER BACKUP
Introduction
There have been several key enhancements to backups with the release of PI 3.4.370.
Subsystems no longer need to be shut down in order to perform backups.
PI databases remain readable during the entire backup process.
If the PI Server is running on a platform that supports Volume Shadow Copy

Services (VSS), then the backup will be performed using VSS. The
advantage of doing VSS backups is that the PI databases are unavailable for
writes for only a very brief period of time, typically on the order of
milliseconds.
Important: If you are upgrading your PI Server from a version prior to 3.4.370, then
you must re-configure your backups. Backups that you had previously configured will
cease to run. After you upgrade to version 3.4.370, you must re-define and
reschedule backups.
4.2
Planning for Backups

Its important to back up the PI Server at least once a day, so that you don't lose data and
configuration information if something fails in your system. The PI Backup Subsystem
(\pi\bin\pibackup.exe) manages all backups of the PI Server.
Daily backups are performed while the PI System is running. With the release of PI Server
3.4.370, you do not need to stop any subsystems to perform a backup.
4.2.1
Choose 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, 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.exe, which is included with the default installation of Windows XP and Windows
PI Server 3.4.370
Page 29
Chapter 4 - PI Server Backup
2003 Server, or by a third-party backup application. During a non-VSS backup, the Backup
Subsystem itself backs up the files of the PI System, as opposed to another application.
Windows XP service pack 2 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.
It is highly recommended that you install PI on a platform that supports VSS because VSS
backups cause minimal disruption to the operation of PI.
4.2.2
Choose a Backup Strategy

The backup scripts provided with the PI Server works for both VSS and non-VSS backups.
The scripts can be set up to run automatically every day (see Automating PI Backup). By
default, the scripts will launch a VSS backup using NtBackup.exe on platforms that support
VSS; otherwise, the scripts will run a non-VSS backup with the piartool -backup
command.
On Windows 2003 Server, as an alternative to using the backup scripts, you can backup PI
with a third-party backup application that supports VSS. Third-party backup applications may
support features that are not supported by NtBackup.exe. Be aware, however, that some
backup vendors require 3rd party VSS writers (such as the PI System) to be validated against
their software before they will enable backups for the writer.
Both VSS and non-VSS backup schemes backup the same files and components. For details
on these files and components see The Files and Components of each Subsystem.
4.3
Backup Guidelines
4.3.1
Page 30
General Guidelines
If you use the standard PI Backup Scripts to backup the PI Server, only the most
recent archives are backed up. The number of archives that are actually backed up is
configurable. The scripts backs up a subset of all archives because the majority of
archives, except the most recent, typically do not change with time, and the extra
time to backup all archives is typically not warranted. Because all archives are not
backed up with each backup, you must save your old backups.
Occasionally, it is advisable to do a true full backup, where all PI Archives are

backed up, so that you do not need all of your previous backups to perform a restore.
You can perform a true full backup of the PI Server while PI is running with the PI
Server Backup Scripts or with a 3rd party VSS backup application by increasing the
configurable number of archives to be backed up to the total number of archives that
you have online. However, an opportune time to perform a full PI Backup is when
you have downtime scheduled for PI Server upgrades.
Before PI Server upgrades, make a complete backup of all PI directories and

archives. Since you must shut down the PI Server to perform an upgrade, it makes
sense to do a full backup at that time. After shutting down the PI Server, you can
backup PI by copying the PI directory and all directories that contain archives and
Backup Guidelines
event queues (archives and event queues may not be located under the PI\dat
directory) with standard operating system commands such as copy (Windows) or cp
(UNIX). Note that the backup script or 3rd party VSS backup applications will not
work when PI is not running. After the backup is complete, perform the upgrade. The
backup should always be performed before the upgrade. To avoid losing incoming
data while performing upgrades, 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.
4.3.2
The PI Server cannot be backed up with standard operating system commands such
as copy (Windows) or cp (UNIX) while PI is running 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).
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.
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.
Once a subsystem registers for backup, the subsystem must remain online during the
next backup or else the backup will fail. The subsystems that are currently registered
for backup can be listed with the piartool -backup -query command. 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.
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.
Guidelines for VSS Backups

During VSS backups, PI databases are unavailable for writes for a very brief period of time,
typically on the order of milliseconds. This means backups could potentially be done several
times a day without disrupting normal server operation.
Even though the PI databases are unavailable for only a brief period of time, it is unadvisable
to make database configuration changes such as creating, editing, and deleting PI Points
because there is a chance that the configuration changes will fail.
PI Server 3.4.370
Page 31
The time period where the databases of PI are unavailable for data writes starts with a Freeze
event and ends with a Thaw event. Be aware that it is possible to put PI through unintended
Freeze and Thaw events when non-component mode VSS backups are performed. 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 think that it is being backed up and will respond to the Freeze and Thaw
events as if it were being backed up. 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.
If you use a 3rd party VSS backup application to backup the PI Server, only the most recent
archives are backed up, even if a full backup is specified by the 3rd party VSS backup
application. The number of archives that are actually backed up for a full backup is
configurable with the Backup_NumArchives and Backup_ArchiveCutoffDate timeout
parameters.
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.
Typically, PI Server backups should work fine with SAN-based VSS backup solutions.
You must have at least one NTFS volume on your PI Server Node in order for VSS backups
to work. The files that are being backed up do not need to be on an NTFS volume. There
simply needs to be one NTFS volume available for shadow copy creation.
4.3.3
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. The reason for this is that PI Server 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 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.
Page 32
Backup Prior to Upgrade
4.4
Backup Prior to Upgrade

Before you perform an upgrade installation, perform a complete backup of the PI Server.
Shut down all PI Server services and copy all PI files to a backup medium, as follows:
4.5
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.
Automating PI Backups
The instructions for automating PI Backups vary depending on operating system, the backup
application that is used, etc. Refer to the appropriate section for the procedures to automate
your backup.
4.5.1
Automate Backup in Windows
Automate Backup in Windows with a Third-Party Backup Application
Automate Backup in a Cluster Environment
Automate Backups in UNIX (Note: This topic is not included in this publication.)
Automate Backup in Windows

Note: The following procedure works on Windows 2000 and Windows 2003 Server,
without installing third-party software. To implement a backup solution from a
particular vendor, follow the guidelines under Automate Backup in Windows with a
Third Party Backup Application.
Automating the PI backup script consists of the following steps:
Install pibackup.bat as a Scheduled Task
View and Edit Scheduled Tasks
Customize Backup
Perform a Test Backup
Perform a Test Restore
Install PIBackup.bat as a Scheduled Task

The pibackup.bat script in the \pi\adm directory is used to start a backup from the command
line or to install an automated backup task. The default backup task runs automatically every
day at 3:15 AM. On Windows 2000, the default task name is of the form Atn, where n is an
integer. On Windows 2003 Server, the default task name is PI Server Backup.
PI Server 3.4.370
Page 33
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 that is created in target directory of the backup. The log file name has the form
pibackup_dd-mmm-yy_hh.mm.ss.txt. The pibackup.bat backup script will automatically
determine whether or not VSS is supported, and the script will perform either a VSS or nonVSS 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 will be 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.
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]
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
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 3:15 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 will not be restricted by the cutoff date. Note that only archives that contain data are
backed up. This means that if archive1 and archive2 are empty archives, then these archives
will not be 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 will not restrict
the number of archives to be backed up.
Page 34
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. The default cutoff date is 1-Jan-1970 00:00:00,
unless otherwise specified by the Backup_ArchiveCutoffDate timeout parameter.
View and Edit Scheduled Tasks
After scheduling the backup tasks, 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.exe log file.
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 2000, 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 3:15 AM C:\PI\adm\pibackuptask.bat
c:\PI\backup." 3 "*-60d""
On Windows 2003 Server, 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 03:15: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.
PI Server 3.4.370
Page 35
The pisitebackup.bat File

If the pisitebackup.bat file exists, then the pibackup.bat backup script calls it immediately
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, you can use the adm\pisitebackup.bat file to move the backup directory to tape or
other offline media. You 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 executes pintbackup.bat
instead of executing NTBackup.exe. By default, the backup script executes NTBackup.exe
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 causes PI Server files listed in the backup selection file, pibackupfiles.bks, to
be backed up to PI_Backup.bkf. Since the /a flag is not on the command line, PI_Backup.bkf
is overwritten every time the backup is performed. The backup selection file is re-created in
the \pi\dat\ directory every time that the piartool backup identify command is run.
If you want to use different command line options for NTBackup.exe, or if you want to
execute a different backup command, create a pintbackup.bat file in the \pi\adm directory.
How to Perform a Non-VSS Backup on a System that Supports VSS
Follow this procedure to perform a non-VSS backup on Windows Server 2003 or Windows
XP.
1. Create a file called \pi\adm\pintbackup.bat.
2. Add a single line to the file:
"%AdmPath%\piartool" -backup "%BackupPath%" %NumArchives% %CutoffDate% -wait
When the pintbackup.bat file exists on a platform that supports VSS, the backup command in
the pintbackup.bat file is executed instead of the default backup command in pibackup.bat.
4.5.2
Perform a Test Backup

By default, the PI backup script will do a VSS backup on Windows XP or Windows 2003
Server and a non-VSS backup on Windows 2000.
Note: 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 to view messages that
are written to the message log during the course of the backup.
Page 36
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.exe being
launched and you will be able to monitor the progress of the backup via the
NTBackup.exe 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 target directory of the backup 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 \pi\adm\pigetmsg
and use piback* 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.exe
backup log for errors. The procedure for examining the NTBackup.exe log is
described in Troubleshooting Backups.
7. After backup is complete, verify that files are successfully backed up. Files are
backed up to the directory specified on the command line of pibackup.bat and
pibackuptask.bat. For VSS backups, files will be backed up into a file called
PI_Backup.bkf, which can only be opened by NTBackup.exe. For non-VSS backups,
the actual files will be copied to subdirectories of the target backup directory. For
example if the target directory is \PI\backup\ and 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 Waiting for completion. The Waiting
for completion status never changes back to Stable after a non-component mode VSS
backup has completed.
4.5.3
Perform a Test Restore

Special Considerations
The following files require special treatment during a restore.
File Name
Special Restoration Considerations
pisubsys.cfg
If you are doing a full disaster recovery, this file should not be restored. Typically, a
full disaster recovery involves re-installing your PI System and a new pisubsys.cfg
file is created during the install. In fact, restoring the file will prevent your PI Server
from starting if you installed PI to a different directory path than it was in originally.
The pisubsys.cfg file is included in the backup in case it is accidentally deleted.
PI Server 3.4.370
Page 37
File Name
Special Restoration Considerations

Unlike the executables of PI, the pisubsys.cfg file is not restored by repairing the PI
Server from the Windows Add or Remove Programs control panel.
piarstat.dat
The piarstat.dat file contains the full path names to all of the registered archives.
The piarstat.dat file also contains the PIARCADMIN and PIARCDATA database
security information (see Managing Security in the PI Server System
Management Guide).
You typically want to restore this file so that you do not need to re-register all of
your archives and re-configure your PIARCADMIN and PIARCDATA database
security information. However, if you restore the PI System to a different directory
path than it was in originally, the PI Archive Subsystem will not be able to find the
archives listed in piarstat.dat. For this reason, you should try to restore your PI
System to the same directory path that it had before.
If for some reason the PI System must be restored to a different directory path, you
can generate a new piarstat.dat file with the pidiag ar command (see
Finding and Fixing Problems: the pidiag Utility in the PI Server System
Management Guide). You will also need to re-register your archives with the
piartool ar command and re-configure the database security.
Restoring from NTBackup.exe

The NTBackup.exe application keeps track of the files that it has backed up via a catalog that
is stored under the following directory.
%ALLUSERSPROFILE%\Application Data\Microsoft\Windows NT\NTBackup\catalogs51.
The value of ALLUSERSPROFILE can be determined by running the set command from a
command prompt with no arguments. For example, one possible value for
ALLUSERSPROFILE is c:\Documents and Settings\All Users.WINDOWS.
When NTBackup.exe is run in advanced mode, these catalogs can be browsed from the
Restore and Manage Media tab.
Page 38
To test the restore, use the following procedure.

1. Change the Restore Files to location to Alternate Location. Specify 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. Double-click on the appropriate catalog entry under
the Backup Identification Label column header. Select all files for restore except
possibly those files discussed under Special Considerations above.
PI Server 3.4.370
Page 39
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 are restored successfully.
Restore from NTBackup.exe when a Catalog is Lost
All that is required to restore from NTBackup.exe is the original PI_Backup.bkf file that was
saved during the backup. The catalogs are not essential for restoring from backup.
6. Run NTBackup in advanced mode.
7. Select Restore and Manage Media.
8. Select Tools, and click Catalog a backup file.
9. Browse to the PI_Backup.bkf file that you had 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.6
Automate Backup in Windows with a Third Party Backup Application

If your PI Server is installed on Windows 2003 Server operating system, then you can do
your PI backups with third-party backup software that supports VSS. However, some backup
vendors require 3rd party VSS writers (such as the PI System) to be validated against their
software before they will enable backups for the writer.
On Windows 2003 Server, the PI Backup scripts use NTBackup.exe to launch a VSS backup.
The advantage of using NTBackup.exe 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 a
third party backup application, the backup application must support VSS backups.
One limitation of NTBackup.exe is that it only supports non-component mode VSS backups,
which means that NTBackup.exe cannot use the components of PI to select files for backup. A
list of file names must be provided to NTBackup.exe 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 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.
Page 40
Automate Backup in Windows with a Third Party Backup Application
4.6.1
Automate Backup in a Cluster Environment

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. Run the following command on each node:
PIbackup.bat <path> [number of archives] [archive cutoff date] [-install]
Installing the backup scripts as a scheduled task is discussed in detail under Automate
Backup in Windows. Only one of the scheduled backup tasks will succeed at any given time
because the pibackuptask.bat and pibackup.bat files are on the shared drive.
Other than the need to schedule the backups on both nodes, backups on clustered and nonclustered Windows nodes are the same.
4.6.2
Automate Backup in UNIX

The commands for scheduling a backup task on UNIX are analogous to scheduling a backup
task on Windows. However, the corresponding .bat files on Windows (pibackuptask.bat and
pibackup.bat) are .sh files on UNIX (pibackuptask.sh and pibackup.sh).
For example, the command
pibackup.sh /opt/PI/backup 3 -install
will schedule a backup with the following characteristics.
The backup will run every day at 3:15 AM.
Files will be backed up to /opt/PI/backup

A total of 3 archives will be backed up (the primary archive plus 2 additional).
Empty archives are never backed up.
As a second example, use the command:

pibackup.sh /opt/PI/backup 3 *-30d -install
will schedule a backup with the following characteristics.
The backup will run every day at 3:15 AM.
Files will be backed up to /opt/PI/backup

Either 3 archives will be backed up or any archive that contains data for the last
30 days, whichever criteria is more restrictive. For example, if the first archive
contains 30 days of data, then only the first archive will be backed up. Empty
archives are never backed up.
To verify proper installation, type crontab -l at a command prompt:

> crontab -l
15 3 * * * /opt/PI/adm/pibackuptask.sh
The scheduled task runs the script pibackuptask.sh at 3:15 AM. You can test your scheduled
backup simply by running the command pibackuptask.sh with no arguments from the
/opt/PI/adm directory.
PI Server 3.4.370
Page 41
If you look in the pibackuptask.sh, you will see that it calls pibackup.sh with the arguments
that were passed during the installation of the task. The following is the pibackuptask.sh file
that is created from running the second installation above.
fname="pibackup-`date +%d-%b-%y`.txt"
cd /opt/PI/adm
./pibackup.sh /opt/PI/backup 3 "*-30d" >>
/opt/PI/backup/$fname 2>&1
When the scheduled task is run, the standard output is redirected to a backup log. The backup
log will be written to the target directory of the backup, and the log file name will have the
form pibackup-dd-mmm-yy.txt, where dd, mmm, and yy are day, month, and year,
respectively.
4.7
How the PI Backup Subsystem Works

4.7.1
Principles of Operation
VSS Backup Overview
VSS backups are initiated by VSS requestors, which are backup applications such as
NTBackup.exe. 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.
After the Thaw 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.
Page 42
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
Non-VSS Backup Overview

Whereas VSS backups are initiated via a backup application, non-VSS backups are initiated
via 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 Backup (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 identified components. Typically, the PI Archive Subsystem identifies only a subset
of its archives, as determined by timeout parameters (see 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 Backup (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
PI Server 3.4.370
Page 43
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.exe, 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.
Page 44
Each entry in the above tree view is a friendly name of a component except OSIsoft PI
Server, which is the registered name of the PI VSS writer, and PI Archive Subsystem, which
is a component path. Typically, a backup application will use different icons to distinguish
between a registered writer, a component path, and a component, but this is dependent on the
particular backup application. Also, the component path PI Archive Subsystem may not be
selectable in some backup applications because there is no component at that point in the tree.
A user can select one or more components for backup. However, for a typical, automated
backup one should configure the backup application to backup the OSIsoft PI Server as a
whole because new archive components are added after each archive shift. These new
archives will not be selected for backup by default unless the OSIsoft PI Server is selected for
backup as a whole.
4.7.3
The Backup Components of PI

The following table summarizes the backup components of PI.
Component Name
Component
Path
Friendly Name
(Component Description)
SettingsAndTimeoutParameters
NULL
Settings and Timeout Parameters
Pilicmgr
NULL
PI License Manager
Pimsgss
NULL
PI Message Subsystem
Pibasess
NULL
PI Base Subsystem
Pisnapss
NULL
PI Snapshot Subsystem
Piarchss
PI Archive
Subsystem
Archive Registry and Archive Audit

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

Current
Piarchive_<UTCarch1>_<GUID>
PI Archive
Subsystem
Archive1 dd-mmm-yy hh:mm:ss to ddmmm-yy hh:mm:ss
...
Piarchive_<UTCarchN>_<GUID>
PI Archive
Subsystem
ArchiveN dd-mmm-yy hh:mm:ss to ddmmm-yy hh:mm:ss
Pibatch
NULL
PI Batch Subsystem
The Components in the Archive Subsystem

The archive subsystem has one component for each archive/annotation file pair. The name
has the form piarchive_<UTCTime>_<GUID>, where <UTCTime> is the start time of the
archive/annotation file in UTC seconds since midnight 01-Jan-70 and <GUID> is the GUID
that uniquely identifies each archive/annotation file pair. For example, the name of an archive
component with a start date of 5-Aug-05 17:56:08 might be:
piarchive_01123289768_{1a0fbff1-bfe4-45f3-82db-5cf5b64b088e}
PI Server 3.4.370
Page 45
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 will
become
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

PI Backup
The PI Backup 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:
Page 46
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.exe)
Plicmgr
The Pilicmgr subsystem has a single component called Pilicmgr. The files backed up with
this component are:
File Name
File Description
pilicense.dat
License Information
Pimsgss
The Pimsgss subsystem has a single component called Pimsgss.
The PI Message Subsystem component contains all message log files from the \pi\log
directory. The message file log names all begin with pimsg_ and end with .dat. The files
backed up with this component are:
File Name
File Description
Pimsg_*.dat
PI Message Log Files
Pibasess
The Pibasess subsystem has a single component called Pibasess. The files backed up with
this component are:
File Name
File Description
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
PI Server 3.4.370
Page 47
File Name
File Description
pibasessAudit.dat
Base Subsystem Audit Database
Pisnapss
The Pisnapss subsystem has a single component called pisnapss. The files backed up with
this component are:
File Name
File Description
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:
File Name
File Description
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 each archive component.

File Name
File Description
Archive and
Annotation (.ann) file
Archive file names can be anything. The annotation file name is the same
as the archive file name with .ann appended to it.
Each archive is contained in a separate component as described in The Components in the

Archive Subsystem.
PIBatch
The Pibatch subsystem has a single component called Pibatch. The files backed up with this
component are:
Page 48
File Name
File Description
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.
During the lifetime of a VSS backup, events typically occur in the order specified in the table
below. The two exceptions are the Identify event and the Abort event. The Identify event
always occurs immediately before the beginning of a backup, but the event can also occur
any time before, after, or during a backup. The Abort event can occur any time during a
backup to cancel the backup.
Backup Event
Description
Identify
Identify events can be received by the PI Backup Subsystem any time

before, after, or during a backup. The following list describes conditions
under which an identify event will be received.
An identify event is received by the PI Backup Subsystem at the beginning
of a backup. The backup subsystem has no way of distinguishing this
identify event from any other identify event.
For informational purposes, a component-mode VSS backup application
may request a list of files and components that need to be backed up. For
example, this list may be used by the backup application to display in a
GUI which components are available for backup. A user can then choose
which components they want to backup from the GUI.
During a backup, a component-mode VSS backup application may
periodically send identify events to make sure that the backup subsystem
is still responsive.
When the PI Backup Subsystem receives an identify event, the PI Backup
Subsystem forwards the event to each subsystem that participates in
backups. Each participating subsystem returns a list of files and
components to the Backup Subsystem. The backup subsystem combines
the list of files and components and sends the list to the VSS Provider. The
backup subsystem also uses the combined list to create a new backup
selection file (\pi\dat\pibackupfiles.bks).
If a non-component mode VSS backup is being performed, then the
backup application does not use the list of files and components that is
supplied to the VSS provider. Non-component mode VSS backup
applications must determine their list of files to backup by different means.
In the case of NTBackup.exe, the list of files to backup is determined from
the backup selection file.
PrepareBackup
PI Server 3.4.370
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.
Page 49
Backup Event
Description
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.
Page 50
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.
The snapshot is still updated in memory between the freeze and thaw
events. That is, the Snapshot Subsystem continues to process events.
Editing, creating, or deleting PI Points are disallowed between the freeze
and thaw events.
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. However, editing,
creating, or deleting PI Points fail immediately without regard to timeouts
between the freeze and thaw events.
The time period between the Freeze and Thaw events can be affected by a
3rd-party VSS writer that is being backed up 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 by 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 of 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 Event
Description
Backup completion may take hours if large files are being copied.
BackupComplete
Component-mode VSS backup applications can use this event to tell the PI
Backup Subsystem which components were successfully backed up and
which components failed to be backed up.
Non-component-mode VSS backup applications do not provide feedback
to the PI Backup Subsystem as to the actual success or failure of the
backup. No BackupComplete event is ever received by the PI Backup
Subsystem for non-Component mode VSS Backups. However, when the
PI Backup Subsystem receives a BackupShutdown event, the PI Backup
Subsystem internally generates a BackupComplete event for nonComponent mode backups so that the last backup time can be updated for
files as described below.
The PI Backup Subsystem forwards the received or artificially generated
BackupComplete event to each participating subsystem so that each
subsystem can update the last backup time for each file that was
successfully backed up. It is simply assumed that all files for a nonComponent mode VSS backup were successfully backed up.
Note that the last backup time is not tracked for some files. For all files for
which the last backup time is tracked, the last backup time can be
displayed with the piartool -backup -identify -verbose
command. You can also view the last backup time for archive files with the
piartool al command.
In addition to updating last backup times, which is done by all subsystems
participating in backups, the PI Archive subsystem also resets its archive
backup flag to 0. This means that the output of piartool as should
indicate that the archive backup flag has been reset to 0.
BackupShutdown
For component-mode VSS backups, if the PI Backup Subsystem gets the

BackupShutdown event without getting the BackupComplete event, then
this means that the backup did not complete successfully. Receiving the
BackupShutdown event without receiving a BackupComplete event is
equivalent to receiving an Abort event, and all cleanup operations
associated with the Abort event applies.
For non-component-mode VSS backups, the BackupShutdown event
always follows the PostSnapshot event and a BackupComplete event is
never received. As described under the BackupComplete event, the PI
Backup Subsystem internally generates a BackupComplete event
whenever it receives a BackupShutdown event for a non-component-mode
VSS backup.
Abort
If an abort event is received during a backup, the backup is aborted. An

Abort event can be received by the backup application or from the
piartool backup abort command.
If databases were frozen, all writes to databases are resumed. The archive
backup flag should be reset to zero, which means that the output of
piartool as should indicate that the archive backup flag has been
reset to 0.
PI Server 3.4.370
Page 51
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 from 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 archive is backed up. This is because
there is no way to tell which archive will receive the data before the data is processed. Time
is allotted for the queue to be emptied between each archive component that is backed up.
The PI Backup Subsystem sends the same backup events to each subsystem for a non-VSS
backup as for a VSS backup, except for the PrepareSnapshot and PostSnapshot events,
which the Backup Subsystem does not send. Another difference is that the Backup Subsystem
generates the events instead of responding to events from a VSS provider. Like a VSS
backup, the Identify, PrepareBackup, BackupComplete, and BackupShutdown events are
sent to each subsystem asynchronously. It is only the Freeze and Thaw events that are sent
one time for each component.
The backup events are summarized in the following table.
Page 52
Backup Event
Description
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
This event is generated by the PI Backup Subsystem in response to a

request for a non-VSS backup from a piartool backup command.
The PI Backup Subsystem sends the PrepareBackup event to each
subsystem that participates in backups.
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
Data writes resume to the files of the frozen component.. 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 to backup the next component follows the Thaw event. 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
Launching Non-VSS Backups
Backup Event
Description
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 the
piartool al command.
4.8
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
Like VSS component-mode backups, if the PI Backup Subsystem

generates a BackupShutdown event without generating a BackupComplete
event, then the backup did not complete successfully. A BackupShutdown
event without a BackupComplete event is equivalent to an Abort event.
Abort
If an abort event is received during a backup, the backup is aborted. Abort

event are issued with the piartool -backup -abort command for
non-VSS backups.
If databases were frozen, all writes to databases are resumed. The archive
backup flag should be reset to zero, which means that the output of
piartool as should indicate that the archive backup flag has been
reset to 0.
Launching Non-VSS Backups

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>
PI Server 3.4.370
The number of archives to backup. For example, "2" will backup the
primary archive and archive 1, provided that the primary archive and
Page 53
Argument
Description
archive 1 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.
If the -wait flag is used without specifying the optional [sec]
parameter, then the piartool -backup command will wait up to 1
day for the backup to complete.
If the -wait flag is not specified, then the piartool -backup
command will return immediately. In this case, the progress of the
backup can be monitored with the piartool -backup -query
command.
The -wait flag is used by the backup script for non-VSS backups
because it is important for the backup to complete before the sitespecific backup scripts are called.
4.9
Managing VSS and Non-VSS Backups

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 nonVSS backup. The pibackup.bat script, for example, uses the piartool -backup commands
to start non-VSS backups when the script is run on an operating system that does not support
VSS backups. The basic syntax for the piartool backup command is
piartool backup <Arg1> [Arg2] [Arg3]
where <> indicates a required parameter and [] indicates an optional parameter. If <Arg1>
does not begin with a hyphen (), then <Arg1> is assumed to be the destination directory for a
non-VSS backup. If <Arg1> begins with a hyphen (), then <Arg1> is assumed to be a backup
command. The following backup commands are valid.
Page 54
Backup Command
Description
-abort
Abort a current running backup.
Backup Command
Description
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 are reported.
Example:
piartool backup query

-identify [-numarch <number>]
[-cutoff <date>] [-verbose]
The identify command reports the list of files that PI

will backup. If the -verbose flag is specified, PI will
report a list of files and components.
A component is a logical grouping of files. For
example, all of the files for the base subsystem are
grouped under the pibasess component. The
purpose of a component is to identify a group of
files for backup.
The -numarch and -cutoff flags have the same
meaning as the backup command for non-VSS
backups, which is described below.
The identify command creates a
\pi\dat\pibackupfiles.bks file. This file is
used in the pibackup.bat backup script to
specify the list of files to backup using
NTBackup.exe. NTBackup.exe is used by the
backup script for performing VSS backups on
Windows 2003 Server.
Example:
piartool backup identify verbose

-trace <level>
Debug messages will be written to the log file when

the trace level is non-zero. The higher the trace
level, the more messages that will be written. The
maximum number of messages will be 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 nonzero, the trace level will be displayed be the
piartool backup query command.
Example:
piartool backup trace 1
PI Server 3.4.370
Page 55
4.9.2
Using piartool backup -query

When the PI System is 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
Page 56
PI License Manager
Registers for backup
PI Message Subsystem
PI Snapshot Subsystem
PI Archive Subsystem
PI Base Subsystem
PI Batch Subsystem
Registers for backup if you are licensed to use the old PI Batch
Subsystem
The other subsystems either do not have files that need to be backed up or they do not need to
be running for a backup to succeed. The above subsystems that register for backup should
appear in the list of registered subsystems in the output of the piartool backup query
command.
After doing a backup, the query will show information about the last backup. The following
shows an example of a query that was done after a successful non-VSS backup.
e:\pi\adm>piartool -backup -query
Backup in Progress: FALSE
Last Backup Start: 29-Jul-05 02:00:04
End: 29-Jul-05 02:01:11
Status: [0] Success
Last Backup Type: FULL, NON-VSS
Last Backup Event: BACKUPSHUTDOWN
Last Backup Event Time: 29-Jul-05 02:01:22
VSS Supported: TRUE
Subsystems Registered for Backup
Name, Registration Time, Version, Status
pibatch, 28-Jul-05 16:09:18, 3.4.370.38, [0] Success
pisnapss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
piarchss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
pilicmgr, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
pibasess, 28-Jul-05 16:09:52, 3.4.370.38, [0] Success
pimsgss, 28-Jul-05 16:09:53, 3.4.370.38, [0] Success
4.9.3
Using 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>
Unless the numarch <number> or cutoff <date> flags are specified on the command line
to the piartool backup identify command, the command will display the number of
archives according to the Backup_NumArchives and Backup_ArchiveCutoffDate timeout
parameters.
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.exe
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
PI Server 3.4.370
Page 57
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.
4.10
Timeout Parameters
The timeout parameters that are specifically related to backup operations are reproduced here
for convenience.
Subsystem(s)
Name
Default
Value
Min
Max
Read
Description
Archive
archive_back
upleadtime
1800 sec
86400
Before
every
backup
Archive
Archive_BSTi
meout
1800 sec
86400
Once a
minute
Backup
Backup_Num
Archives
10000
00
Before
every
backup
Backup
Backup_Archi
veCutoffDate
01-Jan-70
01Jan70
N/A
Before
every
backup
Number of seconds before the

predicted archive shift that a nonVSS archive backup may start.
The PI Backup Subsystem will
wait up to 30 minutes for the
archive shift to complete. This
timeout parameter has no effect
on VSS backups.
This timeout parameter is now
obsolete. It is now for internal use
only.
If the number of archives to be
backed up is not explicitly
specified in arguments to the
pibackup.bat backup script, then
this timeout parameter defines the
default number of archives to be
backed up.
If the cutoff date is not explicitly
specified in arguments to the
pibackup.bat backup script, then
this timeout parameter defines the
default cutoff date. Archives that
contain any data between
Backup_ArchiveCutoffDate and
current time will be backed up. For
example, if *-30d is specified,
then at least 30 days of data will
be backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict
the number of archives for backup.
Whichever timeout parameter is
Page 58
Timeout Parameters
Subsystem(s)
Name
Default
Value
Min
Max
Read
Backup
Backup_Trac
eLevel
1000
Startup
only
Description
most restrictive takes precedence.
This is the default backup trace
level. Non-zero backup trace
levels cause debug messages to
be written to the PI Message Log.
The default trace level can be
overridden while the PI Backup
Subsystem is running with the
piartool -backup -trace

<level> command.
All
<subsysname
>_WriteModT
imesToFilePe
riod
60 sec
10
900
Startup
only
PI internally keeps track of the last

modified date of most of the files
that it needs to back up. The last
modified times for each subsystem
are updated every
WriteModTimesToFilePeriod. The
smaller the period, the more
accurate the last modified time will
be.
A complete list of backed up files
along with their last modified dates
can be listed with the piartool
-backup -identify
-verbose command. For
All
<subsysname
>_BackupTim
eout
1800 sec
30
86400
Periodical
ly when
in system
backup
mode
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 with the
Archive_SecondsBetweenFlush
timeout parameter. After the cache
is flushed, the last modified time
will be updated within
WriteModTimesToFilePeriod
seconds.
This is the maximum number of
seconds to remain in system
backup mode. This timeout
parameter only pertains to the
piartool -systembackup
command, which is used to take
the audit databases offline. The
parameter has no effect for VSS
backups or non-VSS backups that
are started with the piartool
-backup command.
PI Server 3.4.370
Page 59
4.11
Troubleshooting Backups
4.11.1 Log Messages

The following log files should be examined for errors.
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.
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 piback* as a text mask for Message
Source.
NT Event Log. From the Application Log, look for messages from VSS, COM+, and
ntbackup sources.
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 will be 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 will be able to view the NTBackup.exe log from the Tools | Report menu of
NTBackup.exe when NTBackup.exe is run in advanced mode. To try this, launch
NTBackup.exe from a DOS command prompt. If you have not configured NTBackup.exe to
run in advanced mode, you will see the following screen.
Page 60
Uncheck Always start in wizard mode if you want NTBackup.exe to run in advanced
mode the next time that you run it. Click on the Advanced Mode hyperlink and you
will see the following dialog.
You can view the NTBackup.exe log files from the Tools | Report menu.
If the PI Server Backup scheduled task was run under the System account, then you must do
some detective work to figure out the directory to which the NTBackup.exe log is written.
One reason for this is that the log file is written to a hidden file system directory when
NTBackup.exe is run under the System account. Note that the log file name has the form
backupnn.log, where nn is a two-digit number.
Before you can browse to the log file, you must do the following.
Select Folder Options from the Tools menu of Windows Explorer. Select the View
tab and enable Show Hidden Files and Folders.
In order to search for the log file in Windows explorer, you must do the following.
Right-click on the Documents and Settings folder in Windows Explorer and select
Search
Select More Advanced Options and select Search hidden files and folders.
No matter which user account under which NTBackup.exe is run, the NTBackup.exe log is
written to the following directory.
%USERPROFILE%\Local Settings\Application Data\Microsoft\Windows
NT\NTBackup\data
USERPROFILE is an environment variable.
PI Server 3.4.370
Page 61
The logged in user can easily figure out what the USERPROFILE variable is for their account
by running the set command with no arguments from a command prompt. The trick,
however, is figuring out what USERPROFILE is set to for the System account. The
USERPROFILE variable is commonly set to C:\Documents and Settings\Default
User.WINDOWS for the System account, but there is no guarantee. Although it is possible
to determine the settings for USERPROFILE, it is easier to simply search for NTBackup
folders in the subdirectories of the Documents and Settings.
4.11.2 VSSADMIN
Vssadmin.exe is the Volume Shadow Copy Service administrative command-line tool. You
can use the tool to view the status of the VSS writers, VSS Providers, and VSS shadow
copies on the system.
Vssadmin List Shadows
A shadow copy is created during the freeze event. If a backup is not currently in progress, the
output of vssadmin list shadows should look like the following.
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 creating a shadow copy for a backup, there will be errors in the
NTBackup.exe log file indicating that shadow copy creation failed. When shadow copy
creation fails, NTBackup.exe will fall back to non-VSS mode, but NTBackup.exe cannot
backup the PI Server in this mode. The status listed by vssadmin list shadows may give
some indication as to why the shadow copy failed to be created.
Vssadmin List Providers
Windows XP and Windows 2003 Server come with a default VSS provider. Here is some
sample output from vssadmin list providers.
e:\pi\adm>vssadmin list providers
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. The name of the
writer for the PI System is OSISoft PI Writer. When a backup is not in progress, the status of
all writers should appear either as stable or Waiting for completion. The Waiting for
completion status never changes back to stable after a non-component mode VSS backup
has completed.
Page 62
e:\pi\adm>vssadmin list writers

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
If a non-component mode backup application such as NTBackup.exe is used to do the

backup, then you cannot rely on the status from vssadmin list writers to determine when
the backup is complete because BackupComplete events are never generated for noncomponent mode backups. This means that the status will remain Waiting for completion
even when the backup is already complete. Instead, you should used piartool backup
query to determine when a backup has completed. You can clear the Waiting for
completion status by stopping and restarting the backup subsystem, but this is completely
unnecessary.
PI Server 3.4.370
Page 63
Chapter 5.
LICENSE MANAGER
This PI Server release introduces licensing. The PI License Manager monitors and controls
the usage of PI system licensed resources. This is essentially a monitoring tool and we expect
a minimal impact for system users and managers. In this version, we only enforce resources
that were already enforced in previous versions through hard coded parameters.
5.1
How It Works
All the subsystems of the PI Server require authorization from the License Manager. The only
exceptions are the PInet Manager, the Message Subsystem, and the Update Manager.
The license manager needs a valid License File that specifies the licensed features and limits
for the system. If the License Manager is not running or the License File is expired or invalid,
no subsystem can run.
In addition to the permission to run, several licensed parameters such as point and module
counts that were previously hard coded are now retrieved from the license manager.
5.2
License File
The License File is in pi\dat\pilicense.dat. It is an encrypted binary file so there is no point
looking inside. If this file is missing or corrupted, the License Manager will not start.
5.3
License Manager
The startup script that comes with 3.4.370 starts the License Manager immediately after the
pinetmgr. If the License Manager is not running, check pisrvstart.bat. On reboot, the License
Manager should start if the system is installed for automatic startup of services. All the
subsystems will wait for the License Manager. If the License Manager is stopped after the
rest of the system started, some subsystems will degrade their activity level. Specifically, no
points or modules can be created. Once the License Manager is restarted, the system will
recover.
The License Manager reads the license file every 10 minutes. Placing a new license file in
pi\dat\pilicense.dat is sufficient. To get an immediate reading of a new license file, restart the
License Manager:
Net stop pilicmgr
Net start pilicmgr
PI Server 3.4.370
Page 65
Chapter 5 - License Manager
If license limits are exceeded, for example more points than allowed are created, the system
will produce an error message and no more points can be created. You can request a new
License File from Technical Support.
5.4
Monitoring
The license activity and usage can be monitored using
piartool lic <option>
There are several options:

Def - Show licenses and their current usage
Lic - All licenses and the user/subsystem using them
User All users and the licenses they are using
Usage Current general usage information.
In addition, there are two performance counters for every license showing amount used and
amount left. For each user there are counters counting calls to the License Manager. There are
also several general counters for the License Manager itself.
Page 66
PI POINT CLASS EDIT
Chapter 6.
6.1
Introduction
A PI point consists of a collection of attributes. What attributes a point has is uniquely
determined by the PI Point Class it belongs to. A PI Point Class, in turn, consists of a group
of PI point attribute sets, each of which consists of its own attributes. In other words, the
attributes of a point are built by grouping attributes into attribute sets, and then grouping the
attribute sets into a Point Class, and assigning the point to this Point Class. Note that a PI
Point Class cannot consist of attribute sets that have overlapping attributes.
Prior to PI Server 3.4.370, it was not possible to change the attributes of a point once it was
created and assigned to a Point Class. PI Server version 3.4.370 allows you to edit/delete
attribute sets and Point Classes.
The main motivations behind this new feature are to:
Allow users to upgrade uint16 type excmax and compmax attributes in the base
attribute (legacy attributes from earlier PI3 versions) to uint32.
Allow users who may have been using points in one Point Class to switch to a
different one (new or existing) so that the same points can continue to collect data
seamlessly but via a different mechanism. One example of this is to switch from a
totalizer point to a PE (classic Point Class) point or vice versa keeping the same tag.
Aside these specific cases, it may, however, still be desirable to change the attributes of a
point instead of creating a new point belonging to a different Point Class that contains the
desired attributes. This scenario can arise if the application that collects/retrieves data for a
point is to be changed to a different application that needs a different set of attributes, for
example. By allowing the attributes of a point to be changed, we can allow the same point to
retain its history and continue to collect/present new data using whatever applications that
need the new attributes.
PI Server 3.4.370
Page 67
Chapter 6 - PI Point Class Edit
6.2
Overview
Changing the attributes of a point can be accomplished in two ways:
Edit the ptclass attribute of the point to the ptclass that contains the desired attributes.
Edit the Point Class so that it contains the desired attributes. This will trigger implicit
edits of all points that belong to this Point Class, rebuilding their attributes.
Point Class Edits

A Point Class can be edited by changing the attribute sets that make up the Point Class. That
is, attribute sets can be added to or deleted from it.
Another way to edit a Point Class is to do so implicitly by editing one or more attribute sets
that form the Point Class. Editing an attribute set triggers edits of all Point Classes that use
the set. Editing a Point Class, implicit or direct, in turn, triggers edits of all points that use the
Point Class. In short, a points attributes can also be modified by editing an attribute set via
implicit edits of Point Classes and points.
Point Type Edits
Another type of edit disallowed prior to PI Server 3.4.370 but now allowed is point type edit.
Typical point type edits involves converting from float16 to float32 or float64, or from int16
or int32 to float32 or float64. Although a point type edit does not trigger a chain of edits that
affect the PI Base subsystem, it does have ramifications on how the archived data are treated
after the conversion. There are some restrictions on the type of feasible conversions as well.
These issues are discussed in detail in the PI Server Reference Guide.
PIADMIN for Attribute Set and Point Type Edits
Only piadmin is allowed to delete and/or edit attribute sets and Point Classes. This restriction
was imposed to prevent cases where implicit Point Class and point edits fail due to varying
ownership/permissions.
Attribute sets and Point Classes may be edited or deleted only in StandAlone mode in which
PINetmgr will close the TCP/IP listener and disallow any client connections. PI-SDK, PIAPI, Server Apps connections would be closed and reconnection attempts refused for the
duration of the standalone mode. Subsystems and locally-run utilities such as PIConfig and
PIartool can connect. Default-only attribute edits are supported in Normal mode as such
operations do not affect PINetmgrs cached ptclasses table.
Editing Restrictions
There are some restrictions on which attribute sets and Point Classes may be edited or
deleted. Below is a summary of the restrictions:
Page 68
Allow adding attribute(s) to any set except for the base attribute set. Note that any
attribute added to a predefined set cannot be removed due to rules #2 and #7
below: The predefined attribute sets are required by predefined Point Classes. So,
they are always in-use. It is recommended that the user create a new attribute set with
new attributes when expanding a Point Class rather than adding new attributes to a
predefined set.
Allow deleting attributes from a set except from

Predefined sets (those created by OSI) if they are required attributes1
In-use attribute sets
Disallow renaming attributes
Allow renaming attribute sets except

Predefined attribute sets
Allow deleting attribute sets except

Predefined attribute sets
In-use attribute sets
Allow adding attribute sets to any Point Class
Allow deleting attribute sets from a Point Class except from

Predefined classes (created by OSI) if they are required attribute sets2
In-use Point Classes
Allow renaming Point Classes except

Predefined Point Classes
Allow deleting Point Classes except

In-use Point Classes
These restrictions can limit the users ability to easily undo some actions3. Therefore, it is
CRUCIAL to make a backup of the point database before attempting to edit attribute sets or
Point Classes. One can delete attribute sets from a predefined Point Class as long as the class
is not in use and the set to be deleted is not a required set for that Point Class. Nevertheless, it
is a very good idea to keep a backup. The attribute set and Point Class edits should be done in
one PIConfig session only and should not be attempted concurrently via multiple PIConfig
sessions.
1 Predefined attribute sets and their required attributes are listed in the Appendix.
2
Predefined Point Classes and their required attribute sets are listed in the Appendix.
3
To give an example of how involved undoing some actions can be, to remedy a Point Class stuck with an
undesirable set as a member, edit the tags that belong to this class to another one so that it is no longer in-use. Edit
the stuck Point Class to remove the undesirable attribute set and have only the correct attribute sets, then edit the
points back to the original Point Class.
PI Server 3.4.370
Page 69
6.3
User Interface for PI Point Class and Attribute Set Edit

The only user interface available for editing and deleting attribute sets and Point Classes is
the PIConfig utility. PI server needs to be put in standalone mode for attribute set and Point
Class edits/deletes.4 It is not, however, necessary to place the system in standalone mode for
default-only edits.
6.4
Attribute Sets Database Edit

The following sections discuss three operations that modify the PI Attribute Set database:
6.4.1
Attribute Set Creation
Attribute Set Deletion
Attribute Set Edit
Attribute Set Creation

Once a new attribute set is created, it is ready to be used to build Point Classes. Point Classes
can be created/edited to use this attribute set.
An attribute set can be created by specifying the set name and the attribute names, types and
default values. If the type is not specified, float32 is assigned. If a default value is not
specified, it is set by PI. Allowed types and defaults (in parentheses) are listed below. Types
not listed below are not supported, and will either be rejected outright at attribute set creation
time or have unexpected behavior5.
String ()
Int16 (0)
Int32 (0)
BYTE (0)
UBYTE (0)
Uint16 (0)
Uint32 (0)
Timestamp (31-Dec-69 16:00:00)
Float32 (0)
Piartool standalone 1 puts the system in stand alone mode (no clients can connect), and piartool standalone 0
sets it in normal operating mode. Putting PI in stand alone mode actually disconnects currently connected clients and
reconnection attempts will be refused until the server is put back in the normal mode.
5
For example, a blob type will be accepted but will actually be set to string.
Page 70
Bool (0)6
Base Attribute Names (Non-Base Set)

The following attribute names are not allowed in attribute set creation.
Attribute name checks are case-insensitive.
Descriptor
exdesc
typicalvalue
engunits
zero
span
pointtype
pointsource
scan
excmin
excmax
excdev
shutdown
archiving
compressing
step
compmin
compmax
compdev
creationdate
creator
changedate
changer
displaydigits
Note that Boolean values will show as either 1 or 0 instead of true or false. All non-zeros are interpreted as true,
and 0 is interpreted as false. Known issue: an attribute of type Bool always has the default value of 0. A dependent
points attribute can be correctly set to 1 if edited.
PI Server 3.4.370
Page 71
Built-in Attribute Names

PointID
PtClassName
Recno
PtOwner
PtGroup
PtAccess
DataOwner
DataGroup
DataAccess
DigitalSet
Excdevpercent
Compdevpercent
SourceTag
expressstr
eventstr
filterstr
NEWtag
Reserved Names
NEWCLASS
NEWSET
set
class
6.4.2
Page 72
Attribute Set Deletion
An attribute set can be removed by just specifying the set name.
Predefined attribute sets are used as building blocks for PI Point Classes and may not
be removed from the database. When an attribute set deletion is requested, whether it
is a removable attribute set is checked. If not a removable set, an error is returned.
The following sets are predefined sets and may not be removed.
alarmparam
base
classic
sqcalm_parameters
totals
If the set to be removed is in use by any Point Class, an error is returned. The user
should make sure a set is not in use when trying to delete it.
Error Handling
If there is a failure during deletion of the set in the database, an error is returned. There are no
implicit edits that need to be undone since deletion is not allowed if there are dependent Point
Classes and points. The attribute set should still be both in memory and on disk.
6.4.3
Attribute Set Edit

An attribute set can be edited by adding/removing attributes and/or changing one or more
attribute types and default values.
Edits other than default-only edits require that the system be put in standalone mode by
running
PIartool StandAlone 1
PIartool StandAlone 0 puts the system back in Normal mode. Default-only edits do not
require standalone mode.

For reasons explained in the error handling section below, an attribute set edit (except for
default-only edits) is actually done in four steps:
1. Rename the original set to a temporary name (OriginalName~GUID).
2. Create a new set with desired attributes under the original name.
3. Trigger implicit Point Class edits (which in turn will trigger implicit point edits).
4. Remove the original set from the database after successful implicit edits.
Each of these steps are audited if auditing is enabled for the base subsystem.
Default-only edits directly modify the existing sets instead of following the
above steps. Therefore set id remains the same, and no implicit Point Class edits
are triggered. (Elsewhere in this guide, non default-only edits are implied unless
explicitly stated otherwise.)
Base attribute set edit is disallowed except to convert the compmax and excmax
attributes types from uint16 to uint32 (for earlier PI customers who had these
types as int16 and wish to increase the limit), and to change the default values of
any attributes in this set.
Name
(allowed type)
descriptor
(string)
exdesc
(string)
typicalvalue
(float32)
engunits
(string)
zero
(float32)
PI Server 3.4.370
Page 73
Name
(allowed type)
span
(float32)
pointtype
(ubyte)
pointsource
(string)
scan
(byte)
excmin
(uint16)
excmax
(uint16 or uint32)
excdev
(float32)
shutdown
(byte)
archiving
(byte)
compressing
(byte)
step
(byte)
compmin
(uint16)
compmax
(uint16 or uint32)
compdev
(float32)
creationdate
(timestamp)
creator
(uint16)
changedate
(timestamp)
changer
(uint16)
displaydigits
(byte)
Considerations
Page 74
Built-in attribute type and default value edits are not allowed. The types and default
values of built-in attributes, which are frequently mistaken as part of the base
attribute set, do not belong to any attribute set explicitly and therefore there is no
interface for changing them.
Attributes may be added to any attribute set (including the predefined sets) except for
the base attribute set.
Removing attributes in an attribute set that is in use is not allowed.
Removing required attributes in a predefined attribute set is not allowed.
If an attribute set is edited, its dependent Point Classes and, subsequently, dependent
points are edited internally by the PI Base subsystem. No explicit editing of the PI
Point Classes database by the user is necessary. Such indirect edits are henceforth
referred to as implicit edits.
When editing a set, attribute name, type and default should all be explicitly redefined.
If an attribute set is edited, and its pre-existing attribute name is specified, but not the
type and default, PIs default type of float32 and value 0.0 is assigned. If only the
type is specified by the user, a new default will be assigned even if the type is
identical to the previous one. There is no mechanism for editing the set by only
specifying the changes in the set.
Renaming an attribute set does not trigger any implicit edits of Point Classes or
points.
Renaming a predefined attribute set is not allowed.
Implicit point edits keep the existing attribute values if they are still in the edited
attribute set that triggered the implicit point edit and are compatible with the new
types. If the new attribute type is not compatible with the old one, the new default
takes precedence over the existing attributes value. This situation can arise if the old
attributes type changed, for example, from string to int32. If the original string value
of the attribute cannot be converted to an int32, the new default for this attribute type
will prevail. Another situation under which the attribute value will be reset to the new
default is the case the existing value no longer fits in the new type. For example, if
the type changed from float32 to BYTE, and the existing value was 128.0, then the
value will be set to 0.
Added attributes are assigned default values.
Implicit point edits do not validate the point configurations. That is, if a point with
improper configuration (e.g. a Totalizer point with no sourcetag) is implicitly edited,
the implicit edit will succeed although direct edit of the point would have failed
during attribute value validation.
Error Handling
When an attribute set is edited, unless it is a default-only edit, the original set is renamed to a
temporary one, and a new set is created under the original name with desired attributes and
added to the database. Disk commit is immediate. If successful, implicit Point Class edits are
triggered. If they all complete successfully, the old set is removed from the database. If the
edit and implicit edits are unsuccessful a rollback is attempted. Rollbacks are audited if the
base subsystem is enabled for auditing. Upon successful completion of the rollback, the user
should check the error message returned as well as PI Message Log and fix the source of the
error first before reattempting the edit.
PI Server 3.4.370
Page 75
If a fatal error7 occurs during implicit Point Class and point edits the remaining
implicit edits are aborted. Those edits that already succeeded are rolled back, and the
newly added attribute set is deleted. The original sets name is then restored.
In rollback, all implicitly edited Point Classes and points are reconstructed from the
original set still in the database. Since no attribute may be removed from its set if the
set is in use, most original attributes should have retained their values in implicit
point edits unless the new type and original type were incompatible. In this case, the
original values cannot be recovered. After the rollback is completed successfully, the
error that caused the rollback is returned to the user.
If rollback fails, the error is logged in PI Message log, and the rollback is aborted.
The database may end up with some points belonging to the original Point Class and
others to the temporary Point Class containing the new attribute set. In this case the
user needs to resolve the cause of the error and undo the changes manually. In
general, the following steps can be taken to restore the system to the original state:
Fix the cause of the rollback failure first (e.g., PISnap subsystem down, global
lock reacquisition failure, etc.)
If the set edit triggered implicit Point Class edits and point edits, start (recovery)
with point edits, then Point Class edits and then the attribute set edit.
Edit the points in the new Point Class to belong to the original Point Class.
Remove the new Point Class(es) created by the implicit Point Class edit process.
Remove the new attribute set.
Rename the original set to its rightful(!) name.
Determine the cause of the failure and fix it.
Re-edit the attribute set.
If a predefined set somehow gets stuck with undesirable attributes and has dependent
Point Classes which have dependent points, it cannot be removed. Even if all points
are edited to belong to some other Point Classes that do not depend on this set, it
cannot be deleted or renamed since it is predefined. It can only be edited, but must
have the required attributes at minimum.
Similarly, in-use classes cannot be deleted. Predefined classes cannot be deleted or
renamed. A predefined class can be edited as long as it is not in use and the new class
definition has all the required attribute sets.
To fix the stuck attribute set (not predefined):
A fatal error in this case is an error that requires the problem to be fixed before the implicit edits can continue. One
such error is the PI Snap subsystem not being available. Points that are being implicitly edited need their attributes
rebuilt and some changes must be sent to the PI Snapshot subsystem. PI Snapshot subsystem out of sync with the
Base subsystem may result in unexpected behavior.
Page 76
6.5
Create a new set with the desirable attributes.

Create new Point Classes that have the correct attribute sets, and edit the
dependent points to belong to these new classes so that the set and classes to be
fixed are not in use.
Edit the original set and its dependent classes (removing the undesirable
members) and then edit the points back to the correct classes, unless you want to
keep them with the new Point Classes.
If the dependent points are all converted back to the original classes in the
previous step, the interim Point Classes and sets created above can now be
deleted.
Point Class Database Edit

Point Classes database can be directly modified by a user via one of the following three
operations: Creation, Deletion and Edit.
6.5.1
Point Class Creation

Once a new Point Class is created, the user can start assigning points to this class.
A Point Class is created using either PIConfig or PI SDK by specifying which attribute sets
to include.
6.5.2
All Point Classes must include the base attribute set.
Point Class Deletion
Predefined Point Classes may not be deleted.
In-use Point Classes may not be deleted.
Error Handling
6.5.3
If a Point Class deletion fails, an error is returned. There are no implicit edits that
need to be undone since delete is not allowed if there are dependent points. The Point
Class should still be both in memory and on disk.
Point Class Edit

A Point Class can be explicitly edited by adding/removing attribute sets that form the Point
Class.
PIconfig can now display which attribute sets form a Point Class:
@table piptcls
@ostru class
@ostru set,
@select class=classname
@ends
PI Server 3.4.370
Page 77
If there are errors in getting the set names, errors will be returned. The RPC will still return as
many set names as it can get, with the failing set name replaced with question marks: ???
Internally, a Point Class edit is carried out in four steps:
1. Rename the original Point Class to a temporary name (constructed by concatenating
the original name with a GUID e.g., OriginalName~GUID.)
2. Create a new Point Class with desired attribute sets under the original name.
3. Edit the points that belong to the Point Class to belong to the new class.
4. Remove the original Point Class from the database after successful implicit point
edits.
These steps should be transparent to the user if all steps complete successfully. The classs ID
will change. This number is only used internally and is not accessible to users although
visible in Audit DB.
Edited Point Class should still contain the base attribute set.
Any attribute set may be added to a Point Class.
Attribute sets may not be deleted from in-use Point Classes.
Required attribute sets may not be deleted from predefined Point Classes even if they
are not in use.
Predefined classes may not be renamed.
If the sets passed to the Point Class edit routine are not different from the existing
ones, then no further action is taken and the routine returns success. If the attributes
of one or more attribute sets have changed, the attribute set edit itself should have
taken care of this via implicit edits.
Renaming a Point Class does not trigger any implicit edits of points.
Error Handling
As in the case of an attribute set edit, when a Point Class is edited, the original Point Class is
renamed to a temporary name and a new Point Class built from the specified attribute sets is
added to the database under the original name. Then implicit point edits are triggered. If all
point edits complete successfully, the old class (under temporary name) is removed from the
DB. If an implicit point edit fails, all previously successful implicit point edits are rolled
back, the new class is deleted, and the original classs name is restored.
Page 78
Recovery procedure: When more than one points is implicitly edited, if an implicit
point edit fails the rest of the implicit point edits are aborted. The old class is left in
the database under the temporary name, and the new class will remain also. The Point
Class edit routine will then return an error. This scheme ensures that if some implicit
point edits successfully finished and some didnt, both Point Classes will be in the
database and each set of the dependent points will uniquely refer to one of them and
attributes can be rebuilt by both at any time, instead of getting into a corrupted
database state. The user can take appropriate actions to remedy the situation and
attempt the Point Class edit again at a later time.
Now PIConfig can display the attribute sets that form a Point Class. Previously, it
had only been possible to display the attributes in a Point Class. The sets will be
listed by name. Note that the edit operation in PIconfig actually makes two calls, one
for listing the current set ids and a second call to do the edit. If something like below
is returned while editing, as long as there are no errors for edit itself, messages like
below just means this Point Classs original set ids contained a set id (110 in this
case) that refers to a set that does not exist anymore8, but the edit succeeded.
* (Ls - PIPTCLS) PIconfig> @mode edit
* (Ed - PIPTCLS) PIconfig> @istru class
* (Ed - PIPTCLS) PIconfig> @istru set,...
* (Ed - PIPTCLS) PIconfig> totalizer2
*> totalizer2
* (Ed - PIPTCLS) PIconfig> testatrset,base,totals
*> testatrset,base,totals
Error in Point Class' set list:
*** Start of PIvariant dump ***
setid 110 [-12002] Code Not Found in PInt
*** End of PIvariant dump ***
Messages that will not be directly returned to the client (PIConfig) are sent to the PI Message
Subsystem. Examples of these messages are information regarding the status (success or
failure) of four steps involved in Point Class edit (rename the original class, add a new class,
implicitly edit dependent points, remove the original class) and the number of dependent
points found, etc.
6.6
Editing a Point Class Attribute

Use PIConfig to edit the Point class of a point.
This scenario is unlikely (in fact only happened when the program was still in debug stage), but if it ever happens, it
can be rectified by editing the class.
PI Server 3.4.370
Page 79
In some cases, the points ptclass attribute value may be modified to another Point Class
rather then editing the Point Class it belongs to. A PI Points ptclass name attribute edit is
supported just as any other point attribute edit.
Internally, editing the points ptclass attribute works the same way as Point Class edit
induced implicit point edit: the attributes of the affected point are rebuilt. The only important
difference is, unlike in an implicit point edit, some existing attributes may be removed. The
reason is that a Point Class edit disallows removing any attributes if there are points that
belong to it. This effectively prevents points from losing existing attributes inadvertently
during implicit edit. However, if the user deliberately moves a point from one Point Class to
another, if the new Point Class does not contain some of this points current attributes, they
are deleted.
6.6.1
When a points ptclass attribute value is changed, the new classs attributes will be
compared against the existing points attributes, new attributes will be added (set to
default), old ones will be copied if they are in the new Point Class (compatible types
retain values and incompatible types set to new defaults), and attributes that do not
belong to the new Point Class will be removed.
When editing a point via PIConfig, other attributes can be modified simultaneously.
That is, it is ok to edit the ptclass attribute and include new attributes that only belong
to the new Point Class and did not previously belong to the points old class.
However, the target class needs to be set before such an edit is attempted. That is,
@ptclass target_classname needs to be specified first to edit the ptclass and new
attributes simultaneously rather than @ptclass current_classname.
Conversion of COM Connector Class to and from a Native PI Class

Special handling is required in case of a native PI points ptclass edit to a COM Connector
Point Class or vice versa. The difficulty arises from the fact that in order to allow transparent
retrieval of data for a point that has some data in a foreign DB and some in PI Archive, PI
needs to be aware of the cutoff times and go to the correct source. The possibility that the
conversion may occur multiple times adds to the complexity.
The history of the conversions will be ignored and data request will be directed to the
current data source.
Error Handling
An error during COM Connector to native point conversion or vice versa can occur either on
the PI side or on the COM Connector side.
Page 80
6.7
If the error occurred on the PI side during conversion, PI base will unwind and
restore all the original information and user can attempt the conversion after the
cause of the problem is identified and fixed. Since the COM Connector is only called
after the conversion is successfully completed on the PI side, if the error occurred on
the COM Connector side (e.g. could not map/unmap the point to/from the foreign
server), PI will have the intended point configuration, and if any data requests are
made for that point afterwards, they will be properly routed to the COM Connector
by PI and the COM Connector can return the appropriate errors.
Point Database Audit

Both Attribute Sets database and Point Classes database have been added to the Audit
database. EnableAudit bit9 2 will be used for Attribute Sets database and bit 4 for Point
Classes database. Note that audit records will cascade if underlying attribute sets or Point
Classes are edited.
A new attribute set create generates an audit record.
An attribute set delete generates an audit record.
Each step involved in editing an attribute set will be audited. That is, renaming the
original set to a temporary name, adding a new one under the original name, implicit
Point Class and point edits, and removing the original set will all be audited. In
default-only audit, however, only the set edit and implicit Point Class edits are
audited as the original set and classes are not renamed and no implicit point edits are
triggered.
A failed operation does not produce an audit record since the DB is not changed. This
means that if there is an error at any stage in the four steps involved in an edit, the
audit trail will stop at the audit of the previous successful step. Any changes to the
database during the rollback, however, will be audited.
9 Starts from 0.
PI Server 3.4.370
Page 81
6.7.1
A new Point Class create generates an audit record.
A Point Class delete generates an audit record.
Each step involved in editing a Point Class (renaming the original to a temporary
name, adding new class with the desired attribute sets, implicitly editing dependent
points, and then removing the old class) will be audited.
Just as in the attribute set edit, a failed operation does not produce an audit record
since the database is not changed.
Audit Records
EnableAudit Bits
Bits in the EnableAudit parameter in PItimeout table are set as follows.
Database
Bit
Value to Enable (decimal)
Point DB
Digital State DB
Attribute Sets DB
Point Classes
DB
16
User DB
32
Group DB
64
Trust DB
128
PIPtAttributeSetsDB
The following are Audit Record and Change Record Definitions for attribute sets database
edit.
Audit Record Definition
Page 82
Field
Description
PIUser
User who made change
PITime
Time and Date of change
Database
PIPtAttributeSetsDB
Action
Change action: Add, Remove, Edit
AuditRecordID
Unique ID assigned to audit record
Attribute set
Name of affected attribute set.
SetID
Affected record ID in database.

Changes
Table of specific changes.
Change Record Definition

Property
Before
After
New_attribute
NULL
New default
Deleted_attribute
Old default
NULL
Modified_attrib
Old default
New default
The name of the attribute set is treated as if it were an attribute.

The audit database exported in XML format also indicates what type the attributes value is.
PIPtClassesDB
The following are Audit Record and Change Record Definitions for Point Classes database
edit.
Field
Description
PIUser
PITime
Database
PIPtClassesDB
Action
AuditRecordID
Point class
Name of affected Point Class.
ID
Changes

Property
Before
After
New_attribute
NULL
New default
Deleted_attribute
Old default
NULL
Modified_attrib
Old default
New default
PI Server 3.4.370
Page 83
PIPointDB
The name of the Point Class is treated as if it were an attribute.
Field
Description
PIUser
PITime
Database
PIPoint database
Action
AuditRecordID
Point class
Name of affected point.
SetID
Changes
6.8
Property
Before
After
New_attrib_name
NULL
Default
Deleted_attrib_name
Old value
NULL
Edited_attrib_name
Old value
New value
Thread-safety
Attribute set and Point Class edits rely on the locking mechanism at RPC usher level for
thread safety. Both of these edits lock the entire points database, and it will not be accessible
to the user. That is, two users cannot simultaneously edit attribute sets and/or Point Classes.
Point edits, however, get the lock (same global lock as attribute set edits and Point Class
edits) on a per point basis. If an attribute set edit is initiated while the (explicit) point edit has
relinquished the lock to update the snapshot, it is possible that when snapshot update is
finished it is unable to re-acquire the (global) lock, and the edit fails. The point itself remains
locked (a separate flag specific to that point object is set) for the duration of the edit routine
and any new edit attempt for that point cannot modify that point until the first edit thread
resets the edit flag of the point and exits the routine. Therefore, it is possible that the explicit
point edit fails because it cant re-acquire the global lock after snap edit, and on the other
hand, the implicit point edit fails because that particular points edit flag is still set.
Page 84
Reversely, it is possible that an implicit point edit was in progress and the lock was released
to update the snapshot, and meanwhile an explicit point edit is initiated. The explicit edit
takes the lock, the implicit edit routine cannot re-acquire the lock, and the implicit edit fails.
The overall edit will abort, and the rollback will also fail.
An attempt will always be made to undo the points changes and, if applicable, snap edit as
well before returning from a failed point edit routine. The manual recovery procedure
mentioned in previous sections should be followed to put the points in the appropriated Point
Classes and re-attempt the attribute set or Point Class edit. However, it may be necessary to
restore manually from backup.
Both scenarios mentioned above require a piadmin simultaneously doing the explicit point
edits and the attribute set/Point Class edits locally using PIConfig in separate command
windows, and even then are not likely occur. They can (and should) be easily avoided.
PI Server 3.4.370
Page 85
PI POINT TYPE EDIT
Chapter 7.
7.1
Editing Point Types

Changing a points point type involves closing the current archive record and starting a new
one with the new type.
When a points pointtype attribute is changed, already archived history of the point
should remain intact. Upon archive record activation, the old type will be coerced to
the new point type if possible.
If the value does not fit in the new point type, Coercion Failed digital state will be
returned by default. If Archive_DataCoercionPolicy (see below) is defined in PI
timeout table, an appropriately translated digital state will be returned. PI Server does
not log a warning in PI Message subsystem upon point type edit.
If the current snapshot value cannot be coerced to the new type at the time of the
Point Type edit, the edit will fail even though the value will actually be archived in
the record of the old type. The point will remain the previous type, and the archived
data will look as before. However, piartool aw will show two new records since
the last archived events record. One will be for the attempted new type, and another
for the previous (i.e. current type). The first of these (the record created for the
attempted new type) will remain un-filled thereafter.
To illustrate, suppose a point named int16_typedit had the following archived values and was
of type int16. The data were back-filled.
6-Oct-2005
6-Oct-2005
6-Oct-2005
6-Oct-2005
13:51:53,2
14:21:54,32767
14:44:56,4
14:51:51,Pt Created
Then it was edited to type int32, and three new values were added.
6-Oct-2005 14:52:01,-10
6-Oct-2005 14:52:03,2147483647
6-Oct-2005 14:52:05,-16
The last value -16 is still in the snapshot. If this point is edited back to int16 type again, an
error will be returned since int16 type doesnt allow negative values.
[-10005] Subscript Under Range
Archive walk should show,

E:\PI\adm>piartool -aw
Enter Archive Number: 0
PI Server 3.4.370
Page 87
Chapter 7 - PI Point Type Edit
Enter Record Number: 130

Point ID: 1219 Record Number: 130
Chain Record Number - Next: 0 Prev: 0 Index: 0
Record Version: 3 Data type: 8
Flags - Index:1 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 29
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: e
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Event Count: 4
4 Event(s):
0: 29-Sep-05 14:00:03, S,O,A,S,Q [0,0,0,0,0]: 96688
1: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: 96730
2: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96687
3: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96686
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: 96688
Event Count: 4
4 Event(s):
0: 6-Oct-05 13:51:53, S,O,A,S,Q [0,0,0,0,0]: 2
1: 6-Oct-05 14:21:54, S,O,A,S,Q [0,0,0,0,0]: 32767
2: 6-Oct-05 14:44:56, S,O,A,S,Q [0,0,0,0,0]: 4
3: 6-Oct-05 14:51:51, S,O,A,S,Q [0,253,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Page 88

Event Count: 2
2 Event(s):
0: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: -10
1: 6-Oct-05 14:52:03, S,O,A,S,Q [0,0,0,0,0]: 2147483647
Event Count: 1
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
Event Count: 1
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
At this time, the point is of type int32.
PI Server 3.4.370
Page 89
Chapter 7 - PI Point Type Edit
A trickier situation arises if a value stays in a snapshot for a long time before a new
snapshot arrives and the point undergoes several point type conversions meanwhile.
This is very important: the snapshot undergoes a coercion process every time the
tags type is successfully edited. When a new value finally arrives at the snapshot, the
old snapshot is coerced back to the type it was originally sent as. Therefore if the
snapshot event went through several point type conversions and it cannot be coerced
from its latest type to the original type, the value will be rejected by the archive and
lost.
Out of order events that are sent to the archive after the point type change should go
into the archive for the point type that was in effect at the time of the events
timestamp.
The allowed coercion matrix looks as follows:

int16
int16
int32
float16
float32
float64
digital
string
blob
timestamp
ok
ok5
ok
ok
ok
ok
N/A
N/A
ok5
ok
ok
ok3
ok
N/A
ok
ok
ok
ok3
ok
N/A
N/A
ok
ok3
ok
N/A
ok
ok3
ok
N/A
ok
ok
N/A
N/A
N/A
ok
int32
ok1
float16
ok1
ok2
float32
ok1
ok2
ok5
float64
ok1
ok2
ok5
ok
digital
ok6
ok
ok
ok
ok
string
ok
ok
ok
ok
ok
ok4
blob
N/A
N/A
N/A
N/A
N/A
N/A
N/A
timestamp
N/A
ok
ok
ok
ok
N/A
ok
N/A
N/A
1. Assuming values in the range of 0 to 32767

2. Assuming values in the range of -2,147,450,880 to 2,147,483,647
3. Assuming positive, integer values (lower than number of digital states)
4. Assuming exact match (case insensitive) with a state string
5. Assuming the range of the source is compatible with the range of the target
6. Zero and span should be specified in the edit. Depending on whether all zero and span related
validation checks pass, the edit may or may not succeed. Normally, the validation is different for
digital tags and others. A normal digital tag configuration is likely to fail the validation test if it is
being edited to convert to a numerical tag. The best way to avoid problems is to specify zero, span
and typical value to suit the target numeric type at the time of the edit when converting from digital
to numeric.
Page 90
Off-line archive processing will actually convert the old type events to events of the
new type. In the future an option switch may be provided if the old type events are to
be preserved should it become necessary to off-line process the archive, e.g. to fix a
corruption, merge archives, etc.
Error Handling
If coercion is impossible from the stored type to the current point type, what is returned
or whether a value will be returned is determined by Archive_DataCoercionPolicy. This
PI timeout parameter can have one of the following values:
0 DTC_MarkBad
Failed)
Failed events are returned as DS -315 (Coercion
DTC_Leave
Original events are returned (mixed types)
DTC_Zero
Returned as 0 or blank depending on the type
DTC_Hide
Hidden (skip that event)
If a coercion fails during off-line archive processing, values will be replaced as dictated by
the above policy.
PI Server 3.4.370
Page 91
APPENDIX A PREDEFINED ATTRIBUTE SETS AND

POINT CLASSES
Predefined Attribute Sets
The following are pre-defined attribute sets for Attrib, Type, and Default.
alarmparam
action1
String
action2
String
action3
String
action4
String
action5
String
AutoAck
String
ControlAlg
String
ControlTag
String
Deadband
Float32
Options
String
ReferenceTag
String
srcptid
Int32
test1
String
test2
String
test3
String
test4
String
test5
String
txt1
String
txt2
String
txt3
String
PI Server 3.4.370
yes
0.
Page 93
Chapter 1 -
action1
String
txt4
String
txt5
String
base
Page 94
archiving
BYTE
changedate
TimeStamp
31-Dec-69 16:00:00
changer
Uint16
compdev
Float32
2.
compmax
Uint32
28800
compmin
Uint16
compressing
BYTE
creationdate
TimeStamp
31-Dec-69 16:00:00
creator
Uint16
descriptor
String
displaydigits
BYTE
engunits
String
excdev
Float32
1.
excmax
Uint32
600
excmin
Uint16
exdesc
String
pointsource
String
Lab
pointtype
UBYTE
12
scan
BYTE
shutdown
BYTE
span
Float32
100.
step
BYTE
typicalvalue
Float32
50.
zero
Float32
0.
-5
classic
convers
Float32
1.
filtercode
Int16
instrumenttag
String
location1
Int32
location2
Int32
location3
Int32
location4
Int32
location5
Int32
squareroot
Int16
srcptid
Int32
totalcode
Int16
userint1
Int32
userint2
Int32
userreal1
Float32
0.
userreal2
Float32
0.
AutoAck
String
yes
ChartType
Int32
ClearOnLimitChange
String
true
ClearOnStart
String
false
CLTag
String
CommentTag
String
LCLTag
String
LSLTag
String
Mixture
String
OneSideofCL
String
Options
String
OutsideControl
String
sqcalm_parameters
PI Server 3.4.370
Page 95
Chapter 1 -
AutoAck
String
yes
OutsideOneSigma
String
OutsideTwoSigma
String
PIProductLimits
String
ProductTag
String
ReferenceTag
String
ResetTag
String
SQCAlarmPriority
Int32
srcptid
Int32
Stratification
String
TestStatusTag
String
Trend
String
UCLTag
String
USLTag
String
WaitOnLimitChange
String
false
CalcMode
String
timeweighted
CompValue
String
ON
Conversion
Float32
1.
EventExpr
String
FilterExpr
String
Function
String
Total
MovingCount
Int16
Offset
String
+0m
Offset2
String
+0m
Options
String
PctGood
Float32
85.
Period
String
+1h
Period2
String
+2m
no
totals
Page 96
CalcMode
String
timeweighted
RateSampleMode
String
natural
ReportMode
String
Running
srcptid
Int32
TotalCloseMode
String
clock
zerobias
Float32
0.

Alarm
base
alarmparam
Base
base
Classic
base
classic
SQC_Alarm
base
sqcalm_parameters
Totalizer
base
totals
PI Server 3.4.370
Page 97
CONTACTING TECHNICAL SUPPORT

Technical Support Options
OSIsoft provides dedicated technical support internationally, twenty-four hours a day, seven
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 & Telephone Support
Telephone support is available twenty-four hours a day, seven days a week.*
USA and Canada - Call (510) 297-5828
Outside of North America - Call +01 510-297-5828
FAX: 1 (510) 352-2349
*Certain locations and hours may require a fast response call-back by a technical support engineer.
Email Support
Email technical support inquiries, including the problem description and message logs if
possible, to: techsupport@osisoft.com. You will receive a response within 24 hours.
Personalized Online Technical Support
Personalized online technical support, called the Online Call Center, allows you to create a
support call, and allows you to review support calls, software licenses, download history, and
Service Reliance Program (SRP) service agreements. Click My Support in the Technical
Support web site, or visit: http://techsupport.osisoft.com/mysupporthome.aspx.
Technical support engineers monitor online support calls, 24 hours a day, 7 days a week.
Online Knowledgebase Search and Documentation
OSIsoft provides registered users with an extensive online library of technical data and
documentation in the Download Center. Click Download Center in the Technical Support
web site, or visit: http://techsupport.osisoft.com/downloadindex.aspx.
The following knowledgebase resources are available for your use.
Support Solutions - Technical notes with answers to common questions

Bulletins - Alerts regarding newly-discovered issues
PI Server 3.4.370
Page 99
Support Pages - The web pages of support.osisoft.com

Known Issues - Documented issues and current resolution status
Enhancements - New features being considered for our products
Documentation - User Manuals, Release Notes, and White Papers
Applications - Install Kits and Utilities
Remote Server Access

Technical support engineers can remotely access your PI server to provide diagnostics,
hands-on troubleshooting, and assistance. Choose Contact Us > Remote Access Options in
the Technical Support web site, or visit: http://techsupport.osisoft.com/contactdetails.aspx.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. Search SRP
Terms in the Technical Support web site, visit http://techsupport.osisoft.com/srp.aspx, or
write for more information: ServiceUS@osisoft.com.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide the following:
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 the PI Version Number

To find the PI Server version number, change to the PI\adm directory and enter the
command: piversion -v
Find PI Build Numbers for Subsystems
If you have installed a patch for any PI subsystem, the build number(s) for individual
subsystems might be different. To view a subsystem build number, change to the PI\bin
directory. Invoke the subsystem executable with the v option. For example, for the Archive
subsystem: piarchss.exe -v
Note that this does not start or stop the subsystem. Repeat this step for each subsystem that
you have upgraded.
View Computer Platform Information
To view platform specifications:
Page 100
On Windows, right-click on My Computer, and choose Properties. For more detailed

information, choose Start > Run, and launch the msinfo32.exe utility.
On UNIX, use the command, uname -a.

PI 3.4.370 Install &amp; New Features

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PI 3.4.370 Install &amp; New Features

Uploaded by

Copyright:

Available Formats

PI Server 3.4.

Release: October 24, 2005

OSI Software GmbH

OSIsoft Canada ULC

OSIsoft, Inc. Representative Office

OSI Software Asia Pte Ltd.

Sales Outlets and Distributors

Installation and Upgrade Procedures .......................................................................9

New Installation Procedure ..............................................................................................9

New Installation Routine.......................................................................................10

Sample Installation ...............................................................................................12

Upgrade Installation Procedure .....................................................................................18

Upgrade Installation Routine ................................................................................19

Planning for Backups......................................................................................................29

Choose the Backup Platform (VSS vs. Non-VSS) ...............................................29

Choose a Backup Strategy...................................................................................30

Backup Guidelines ..........................................................................................................30

Guidelines for VSS Backups ................................................................................31

Guidelines for Non-VSS Backups ........................................................................32

Backup Prior to Upgrade ................................................................................................33

Automating PI Backups ..................................................................................................33

Automate Backup in Windows..............................................................................33

Perform a Test Backup.........................................................................................36

Perform a Test Restore ........................................................................................37

Automate Backup in Windows with a Third Party Backup Application.....................40

Automate Backup in a Cluster Environment.........................................................41

Automate Backup in UNIX....................................................................................41

How the PI Backup Subsystem Works..........................................................................42

Principles of Operation .........................................................................................42

Selecting Files or Components for Backup ..........................................................43

The Backup Components of PI ............................................................................45

The Files and Components for Each Subsystem.................................................46

Lifetime of a Backup .............................................................................................49

Launching Non-VSS Backups ........................................................................................53

Managing VSS and Non-VSS Backups..........................................................................54

Backup Command Summary ...............................................................................54

Using piartool backup -query..............................................................................56

Using piartool backup -identify ...........................................................................57

4.10 Timeout Parameters ........................................................................................................58

License Manager .......................................................................................................65

How It Works ....................................................................................................................65

License File ......................................................................................................................65

License Manager .............................................................................................................65

PI Point Class Edit ....................................................................................................67

User Interface for PI Point Class and Attribute Set Edit..............................................70

Attribute Sets Database Edit ..........................................................................................70

Attribute Set Creation ...........................................................................................70

Attribute Set Deletion............................................................................................72

Attribute Set Edit...................................................................................................73

Point Class Database Edit ..............................................................................................77

Point Class Creation.............................................................................................77

Point Class Deletion .............................................................................................77

Point Class Edit ....................................................................................................77

Editing a Point Class Attribute.......................................................................................79

Point Database Audit ......................................................................................................81

Audit Records .......................................................................................................82

Conversion of COM Connector Class to and from a Native PI Class ..................80

PI Point Type Edit......................................................................................................87

Editing Point Types .........................................................................................................87

Appendix A Predefined Attribute Sets and Point Classes .......................................................93

Introduction to PI System Management

PI Server Installation and Upgrade Guide

PI Server System Management Guide

PI Server Reference Guide

PI 3.4.370 Install & New Features

PI 3.4.370 Install & New Features