Documente Academic
Documente Profesional
Documente Cultură
370
Installation and New Feature Guide
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)
support@osisoft.com
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
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
Installation and New Feature Guide
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.
3.1
Overview.............................................................................................................................9
3.2
3.3
3.2.1
3.2.2
3.3.2
Sample Upgrade...................................................................................................21
Chapter 4.
PI Server Backup.......................................................................................................29
4.1
Introduction......................................................................................................................29
4.2
4.3
4.2.1
4.2.2
General Guidelines...............................................................................................30
4.3.2
4.3.3
4.4
4.5
4.6
Page iv
4.5.1
4.5.2
4.5.3
4.7
4.6.1
4.6.2
4.7.2
4.7.3
4.7.4
4.7.5
4.8
4.9
4.9.2
4.9.3
5.1
5.2
5.3
5.4
Monitoring ........................................................................................................................66
Chapter 6.
6.1
Introduction......................................................................................................................67
6.2
Overview...........................................................................................................................68
6.3
6.4
6.5
6.6
6.4.1
6.4.2
6.4.3
6.5.2
6.5.3
PI Server 3.4.370
Installation and New Feature Guide
Page v
6.6.1
6.7
6.8
Thread-safety ...................................................................................................................84
Chapter 7.
7.1
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:
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
Installation and New Feature Guide
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.
Key Considerations
Page 2
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.
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.
PI Server 3.4.370
Installation and New Feature Guide
Page 3
NEW FEATURES
Chapter 2.
License Manager A License File is now required for installation and upgrade.
Point Class and Point Type Editing System administrators now have the ability to
edit and delete Attribute Sets, Point Classes and Point Types.
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
Installation and New Feature Guide
Page 5
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
Installation and New Feature Guide
Page 7
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
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
Installation and New Feature Guide
Page 9
Installation Considerations
3.2.1
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
Installation and New Feature Guide
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.)
PI Server 3.4.370
Installation and New Feature Guide
Page 13
Page 14
6.)
Select the location of the license file, pilicense.dat. Click browse to change the location.
7.)
8.)
9.)
PI Server 3.4.370
Installation and New Feature Guide
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.
PI Server 3.4.370
Installation and New Feature Guide
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.
3.3
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.
Upgrade Considerations
3.3.1
PI Server 3.4.370
Installation and New Feature Guide
Page 19
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
Installation and New Feature Guide
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.
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
Installation and New Feature Guide
Page 23
24.) The user information from the previous installation is displayed. Optionally, change the
Name, Organization, Serial Number, and define user options.
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.
PI Server 3.4.370
Installation and New Feature Guide
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.
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.
PI Server 3.4.370
Installation and New Feature Guide
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.
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
PI Server 3.4.370
Installation and New Feature Guide
Page 29
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
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.
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.
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.
PI Server 3.4.370
Installation and New Feature Guide
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
Page 32
4.4
4.5
Make sure that your Interface Nodes are buffering your data.
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.
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 Backups in UNIX (Note: This topic is not included in this publication.)
Customize Backup
PI Server 3.4.370
Installation and New Feature Guide
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
[number of
archives]
[archive cutoff
date]
*-10d
[install]
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
Automating PI Backups
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
PI Server 3.4.370
Installation and New Feature Guide
Page 35
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
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
Automating PI Backups
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
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
Installation and New Feature Guide
Page 37
File Name
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.
Page 38
Automating PI Backups
PI Server 3.4.370
Installation and New Feature Guide
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
Page 40
4.6.1
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
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
Installation and New Feature Guide
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
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
PI Server 3.4.370
Installation and New Feature Guide
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.
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
Component
Path
Friendly Name
(Component Description)
SettingsAndTimeoutParameters
NULL
Pilicmgr
NULL
PI License Manager
Pimsgss
NULL
PI Message Subsystem
Pibasess
NULL
PI Base Subsystem
Pisnapss
NULL
PI Snapshot Subsystem
Piarchss
PI Archive
Subsystem
Piarchive_<UTCprimary>_<GUID>
PI Archive
Subsystem
Piarchive_<UTCarch1>_<GUID>
PI Archive
Subsystem
...
Piarchive_<UTCarchN>_<GUID>
PI Archive
Subsystem
Pibatch
NULL
PI Batch Subsystem
PI Server 3.4.370
Installation and New Feature Guide
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
Page 46
File Name
File Description
Pe314.dfa
Pe314.llr
Pifirewall.tbl
Firewall database
Pipeschd.bat
pisql.ini
pisql.res
Pisubsys.cfg
PISysID.dat
Pisystem.res
Pitimeout.tbl
Timeout database
Shutdown.dat
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
Pibasess
The Pibasess subsystem has a single component called Pibasess. The files backed up with
this component are:
File Name
File Description
pidbsec.dat
pidignam.dat
pidigst.dat
PIModuleDb.dat
PI Module Database
pipoints.dat
PI Point Database
piptalia.dat
piptattr.dat
piptclss.dat
piptsrcind.dat
piptunit.dat
pitrstrl.dat
PI Trust Table
piusr.dat
PI User Database
piusrctx.dat
piusrgrp.dat
PI Server 3.4.370
Installation and New Feature Guide
Page 47
File Name
File Description
pibasessAudit.dat
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
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
piarchssAudit.dat
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.
Page 48
File Name
File Description
pibaalias.nt
pibaunit1.nt
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
PrepareBackup
PI Server 3.4.370
Installation and New Feature Guide
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
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
PostSnapshot
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
Abort
PI Server 3.4.370
Installation and New Feature Guide
Page 51
Page 52
Backup Event
Description
Identify
PrepareBackup
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
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
Abort
Description
<path>
Path must be the complete drive letter and path to a directory with
sufficient space for the entire backup.
-component <comp>
-numarch <number>
PI Server 3.4.370
Installation and New Feature Guide
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>
-wait [sec]
-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
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
Backup Command
Description
Example:
PI Server 3.4.370
Installation and New Feature Guide
Page 55
4.9.2
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
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
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
PI Server 3.4.370
Installation and New Feature Guide
Page 57
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
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
<subsysname
>_WriteModT
imesToFilePe
riod
60 sec
10
900
Startup
only
-backup -identify
-verbose command. For
All
<subsysname
>_BackupTim
eout
1800 sec
30
86400
Periodical
ly when
in system
backup
mode
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
Installation and New Feature Guide
Page 59
4.11
Troubleshooting Backups
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
Troubleshooting Backups
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
PI Server 3.4.370
Installation and New Feature Guide
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
vssadmin 1.0 - Volume Shadow Copy Service administrative command-line
tool
(C) Copyright 2001 Microsoft Corp.
Provider name: 'MS Software Shadow Copy provider 1.0'
Provider type: System
Provider Id: {b5946137-7b9f-4925-af80-51abd60b20d5}
Version: 1.0.0.7
Page 62
Troubleshooting Backups
PI Server 3.4.370
Installation and New Feature Guide
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
Installation and New Feature Guide
Page 65
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>
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
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
Installation and New Feature Guide
Page 67
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.
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.
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
Installation and New Feature Guide
Page 69
6.3
6.4
6.4.1
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
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
Installation and New Feature Guide
Page 71
Page 72
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
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
Installation and New Feature Guide
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.
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.
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.
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
Installation and New Feature Guide
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.
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
6.5.2
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.
PI Server 3.4.370
Installation and New Feature Guide
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.
Required attribute sets may not be deleted from predefined Point Classes even if they
are not in use.
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
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
Installation and New Feature Guide
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.
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.
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
Installation and New Feature Guide
Page 81
6.7.1
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
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
PITime
Database
PIPtAttributeSetsDB
Action
AuditRecordID
Attribute set
SetID
Before
After
New_attribute
NULL
New default
Deleted_attribute
Old default
NULL
Modified_attrib
Old default
New default
Description
PIUser
PITime
Database
PIPtClassesDB
Action
AuditRecordID
Point class
ID
Changes
Before
After
New_attribute
NULL
New default
Deleted_attribute
Old default
NULL
Modified_attrib
Old default
New default
PI Server 3.4.370
Installation and New Feature Guide
Page 83
PIPointDB
The name of the Point Class is treated as if it were an attribute.
Audit Record Definition
Field
Description
PIUser
PITime
Database
PIPoint database
Action
AuditRecordID
Point class
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
Installation and New Feature Guide
Page 85
Chapter 7.
7.1
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
PI Server 3.4.370
Installation and New Feature Guide
Page 87
Page 88
PI Server 3.4.370
Installation and New Feature Guide
Page 89
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.
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
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)
DTC_Leave
DTC_Zero
DTC_Hide
If a coercion fails during off-line archive processing, values will be replaced as dictated by
the above policy.
PI Server 3.4.370
Installation and New Feature Guide
Page 91
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
Installation and New Feature Guide
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
Installation and New Feature Guide
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.
PI Server 3.4.370
Installation and New Feature Guide
Page 97
http://techsupport.osisoft.com
*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.
PI Server 3.4.370
Installation and New Feature Guide
Page 99
Page 100