PI Server System Management Guide

Version 3.4.380
OSIsoft, LLC International Offices
777 Davis St., Suite 250
San Leandro, CA 94577 USA OSIsoft Australia
Perth, Australia
Additional Offices
OSIsoft Germ any Gm bH
Houston, TX
Johnson City, TN Altenstadt, Ger many
Longview , TX OSIsoft Asia Pte Ltd.
Mayfield Heights, OH Singapore
Philadelphia, PA
OSIsoft Canada ULC
Phoenix, AZ
Savannah, GA Montreal, Canada
Calgary, Canada
Sales Outlets/Distributors OSIsoft, LLC Representative Office
Middle East/North Africa Shanghai, People’s Republic of China
Republic of South Africa OSIsoft Japan KK
Russia/Central Asia
South America/Car ibbean Tokyo, Japan
Southeast Asia OSIsoft Mexico S. De R.L. De C.V.
South Korea Taiw an Mexico City, Mexico
OSIsoft do Brasil Sistem as Ltda.
Sao Paulo, Brazil

Contact and Support:

Main phone: (01) 510-297-5800
Fax: (01) 510-357-8136
Support phone: (01) 510-297-5828

Web site: http://www.osisoft.com

Support w eb site: http://techsupport.osisoft.com

Support email: techsupport@os isoft.com

Copyright: © 1998-2009 OSIsoft, LLC. All rights reserved.

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical,
photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, IT
Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI
ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of
OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 11/11/2009
Table of Contents
About the PI Server........................................................................................................ 1
Tools for System Management.............................................................................. 1
PI Server Directory Structure ................................................................................ 2
PI Server Subsystems ......................................................................................... 2
Windows File System Concerns ............................................................................ 4
Time Specifications and Considerations ................................................................. 5

Start and Stop the PI Server ......................................................................................... 17

Start the PI Server ............................................................................................ 17
Stop the PI Server............................................................................................. 19
Shut Down or Restart Individual Subsystems ........................................................ 20
Shutdown Events .............................................................................................. 21

Manage Points............................................................................................................. 23
PI Point Classes and Attributes ........................................................................... 23
Exception Reporting and Compression Testing...................................................... 43
Change PI Point Type........................................................................................ 48
Create, Delete, or Edit PI Point Classes and Attribute Sets...................................... 51
Digital State Sets .............................................................................................. 65

Manage Archives......................................................................................................... 69
About Archives ................................................................................................. 69
Create a New Archive in SMT............................................................................. 74
Register and Unregister Archives ........................................................................ 78
Edit Archives .................................................................................................... 79
Delete an Archive ............................................................................................. 80
Display an Unregistered Archive ......................................................................... 80
Make Writeable/Read-only ................................................................................. 80
Move an Archive ............................................................................................... 80
Backup Archives ............................................................................................... 81
Note on Digital State Reprocessing ..................................................................... 81
Manage Archive Shifts ....................................................................................... 82
Backfilling Data................................................................................................. 83
Manage Archives of an Offline PI Server (piarchss)................................................ 85
List Archive Record Details (Archive Walk) ........................................................... 90

Back up the PI Server .................................................................................................. 97

Configure a Daily Backup Task ........................................................................... 97
How to Monitor and Maintain Your Scheduled Backups .........................................110

PI Server System Management Guide iii

Table of Contents

How to Restore a Backup to an Existing PI Server ................................................113

Restore a Server Backup to a New Computer ......................................................114
The PI Server Backup Scripts ............................................................................116
Troubleshooting Backups ..................................................................................118

Manage Interfaces ......................................................................................................121

About PI Interfaces...........................................................................................121
Interface Installation Checklist............................................................................124
Configure the PI Interface Status Utility ...............................................................126
Configure Auto Point Synchronization .................................................................126

Monitor the PI Server ..................................................................................................127

Schedule Monitoring Tasks ...............................................................................127
View System Messages ....................................................................................128
Windows Performance Counters ........................................................................133

Move or Merge PI Servers ...........................................................................................135

Move PI Servers ..............................................................................................135
Merge PI Servers .............................................................................................144

Tuning, Troubleshooting, and Repairs .........................................................................169

Tuning............................................................................................................169
Troubleshooting...............................................................................................187
Repairs ..........................................................................................................206

PI SQL Subsystem ......................................................................................................219

Architecture ....................................................................................................219
Configuration...................................................................................................220
Troubleshooting...............................................................................................223

PI Data Retrieval with Foreign Data Sources.................................................................227

Point Configuration...........................................................................................228
Retrieval of Snapshot Data................................................................................228
Retrieval of Archive Data...................................................................................229
Archive Files ...................................................................................................230
Snapshot Updates ...........................................................................................230
Compression...................................................................................................231
Point Security ..................................................................................................231

Technical Support and Resources ...............................................................................233

Before You Call or Write for Help........................................................................233
Help Desk and Telephone Support .....................................................................233
Search Support ...............................................................................................234
Email-based Technical Support..........................................................................234
Online Technical Support ..................................................................................234
Remote Access ...............................................................................................235

iv
 On-site service ................................................................................................235
Knowledge Center ...........................................................................................235
Upgrades........................................................................................................235

Index .........................................................................................................................237

PI Server System Management Guide v

About this Book
This book provides detailed instructions for configuring, maintaining, and troubleshooting a
PI Server. It also discusses other PI components that are relevant to PI Server system
management. These include PI Interfaces as well as client tools that can be used for system
management (PI SMT and the ICU, for example).
This guide assumes that you have a basic knowledge of the PI Server and how to perform
typical system administration tasks. See the Introduction to PI System Management guide for
this information.
PI Server security (authentication, access permissions) is fully documented in Configuring PI
Server Security. Please refer to that guide for more information.

Note: PI Server 3.4.380 allows you to manage your PI Server authentication through
Windows and Microsoft Active Directory (AD). This model improves PI Server
security, reduces your management workload, and provides users a single-sign on
experience. PI Server 3.4.380 also continues to support previous PI Server
security mechanisms.

PI Server System Management Guide vi

Chapter 1

About the PI Server

The PI System is a complete collection of OSIsoft software applications that run on one or
more computers to collect, store, retrieve, analyze, view, or manage process data. Examples
of these software applications include the PI Server, PI Interfaces, and client applications.
The PI Server typically runs on a separate computer from those that run PI Interfaces and
client applications . This distribut ed data collection architecture is scalable, robust, and
flexible. When the High Availability (HA) architecture is used, the PI Server runs on two or
more computers that are automatically synchronized and act as one logical PI Server. These
computers can be geographically dispersed.
A single PI Server include s:
• PI Server Subsystems (the processes that comprise the PI Server)
• Configuration and administrative utilities
• A set of default Interfaces
• PI API and PI SDK, software included with the PI Server that applications use internally
This chapter introduces these elements of the PI Server, and explains the structure of the PI
Server file system.

Tools for System Management

OSIsoft provides tools that make it easier to manage a PI System. These tools are included
with every new PI Server installation.
• The PI System Management Tool s (SMT) for performing all routine Server
administration tasks
• PI Tag Configurator for creating and editing tags in an Excel spreadsheet
• PI Module Database Builder for creating and editing modules in an Excel spreadsheet
• The PI Interface Configuration Utility (ICU) for configuring PI Interfaces
• Collective Manager for creating and managing PI Server Collectives for High
Availability (HA)
Check the OSIsoft Technical Support Web Site (http://techsupport.osisoft.com/) regularly for
updates to these tools.
OSIsoft also provides some powerful command-line utilities. This book discusses command-
line utilities only as they are needed for specific tasks. For more complete information on
command-line utilities, refer to the PI Server Reference Guide.

PI Server System Management Guide 1

About the PI Server

PI Server Directory Structure

When you install the PI Server, the installation kit prompts you for a location to store the PI
Server files. By default, PI Server ins talls its files in a folder called PI on the disk with the
most available space. Although you can rename the PI directory to whatever you like, we will
refer to the top PI Server directory as the PI directory.

Note: The PISERVER environment variable points to this directory.

Within the PI directory, the PI Server installs the following subdirectories:

Subdirectory Contents
Program Files\PI\adm Administrative tools

Program Files\PI\bin Subsystem or PI service executables

Program Files\PI\dat Databases and tables such as Point Database and Digital State
Table. This is also the default directory for Archive files and the
Event Queue.
Program Interfaces that w ere installed w ith previous versions of PI. This
Files\PI\interfaces directory is not present on new PI Server installations, but might
be present on Servers that are running upgrades.
Program Files\PI\log Log files
Program Files\PI\setup Files for install and uninstall

In addition to the PI directory, the PI Server installation creates the pipc directory, if it does
not exist. The pipc directory is actually created when you install the PI SDK, which is
included in the PI Server installation. The pipc directory contains files for the PI SDK, for
bundled PI Interfaces, and for a variety of other tools and utilities, including PI SMT, the
Collective Manager, and the ICU.

Note: The PIHOME environment variable points to this directory.

PI Server Subsystems
The PI Server Subsystems are a set of several interdependent processes, referred to as
subsystems. Some subsystems depend on other subsystems for proper behavior. All
subsystems wait at startup for any dependent subsystems. The executable for each of the PI
subsystems is installed in the PI\bin directory.

2
 PI Server Subsystems

Generally, the PI Server requires seven core subsystems to function to a minimum level:
Subsystem Executable Purpose Dependencies
Archive piarchss.exe Stores and serves the data after it Snapshot Subsystem,
comes out of the Snapshot Update Manager, and
Subsystem. Data consists of License Manager
multiple time-stamped
measurements for each data
point. Values represent on/off,
pressures, flows, temperatures,
setpoints, and so on.
Base pibasess.exe Maintains the Point Database, Update Manager and
Digital State Table, and License Manager
configuration databases for
authentication. Hosts the PI
Module Database.
License pilicmgr.exe Maintains license infor mation for
Manager the PI Server and all connected
applications.
Message pimsgss.exe Records status and error Messages are routed to
messages for the PI Server in a the Windows Event log
log file. if this subsystem is not
available
Netw ork pinetmgr.exe Manages communication
Manager betw een PI Server subsystems,
interfaces and client applications.
Also validates clients at time of
connection. Clients may be
standard products such as PI
Pr ocessBook, or they may be
custom PI A PI or PI SDK
programs.
Snapshot pisnapss.exe Stores the most recent event for Update Manager and
each point, applies compression, License Manager
sends data to the Event Queue,
serves Snapshot events, and
sends updates for client
applications to the Update
Manager.
Update piupdmgr.exe Queues notifications of changes Essential for proper
Manager in data values, point attributes, operation of a PI
modules, and so on to any Server; it is required by
interface or client application that most of the PI
is signed up for notification. Subsystems and most
client applications

PI Server System Management Guide 3

About the PI Server

In addition to the core PI Subsystems, the PI Server includes additional subsystems that are
not essential to run the PI Server. Some of these subsystems are licensed separately and might
not be installed on your PI Server:
Subsystem Executable Purpose

Alarm* pialarm.exe Pr ovides alar m capabilities for PI points.

Backup pibackup.exe Manages backups of the PI Server.

Batch* pibatch.exe Detects and records batch activity.

Performance pipeschd.exe Performs PI Perfor mance Equation ( PE) calculations for PI

Equations * PE points.

Recalculator pirecalc.exe Recalculates values of PE points after histor ical changes.

Redirector piudsrdr.exe Obtains data from external systems and sends it to the Base,
Archive, and Snapshot Subsystems. Used in connection w ith
COM Connectors*.
Shutdow n pishutev.exe Deter mines w hen the PI System w as stopped and w rites
shutdow n events to points configured to receive these
events; It runs only at startup and then stops.
SQL pisqlss.exe Pr epares and executes SQL statements directed at the PI
Server; The primary users of this subsystem are the PI
ODBC Driver and the PI SDK.

Totalizer * pitotal.exe Performs post-processing calculations on a point in the

snapshot and stores the results in a PI T otalizer point.

*
indicates a separately licensed subsystem

Windows File System Concerns

When running PI Server on Windows, OSIsoft recommends that you:
• Do not use Windows File System Compression on the PI Server.
• Disable virus scanning on the Archive and database folders.

Do Not Use Windows File Compression

OSIsoft recommends that you do not Windows File System Compression. Although
compression may save disk space, it requires more CPU resources each time data arrives at
the Archive and clients access database files.
You can slow access to Archive files and degrade performance of the entire PI System if you
use compressed files. This is especially true for files that change constantly, such as the
primary Archive and Event Queue files, and the current message log file.

4
 Time Specifications and Considerations

Configure Anti-Virus Software

OSIsoft recommends that you configure anti-virus software on production systems to exclude
scans of the PI\dat directory and any directories containing PI Server database and Archive
files. The PI\dat directory does not contain any executable programs or scripts.
Anti-virus software immediately scans files with contents that change. The contents of the PI
Server Archive files change constantly as Archive cache records are regularly flushed from
memory to disk. Archive files tend to be large, and thus the time required to scan can be quite
long. In addition, if any random bit pattern in an Archive file happens to match a known virus
signature, the anti-virus software can lock or otherwise quarantine the Archive file. Such a
corruption of the Archive file system would result in the unrecoverable loss of production
data. The same situation can occur for other PI Server database files.

Time Specifications and Considerations

The PI Server tracks time according to the Windows clock, including the time zone and
Daylight Savings Time (DST) settings. If the system clock is wrong, the PI Server data is not
correct. If you accidentally change the System Time, see Recover from Accidental System
Time Change (page 216).
OSIsoft recommends that you check the system clock regularly. If you need to make an
adjustment, adjust the clock only in small increments (for example, one second per minute).
Keep a record of all adjustments you make.

Note: Archive timestamps in PI Server are stored as the number of seconds past
January 1, 1970. Two-digit years from 00 through 69 are interpreted as 21st
century. Two-digit years from 70 through 99 are interpreted as the 20th century
(1900s). For example, 70 translates to 1970; 00 translates to 2000; and 37
translates to 2037.

PI Time Format

Many PI System utilities prompt for a date and time. The PI time formats are:
• Relative
• Absolute
• Combined

PI Server System Management Guide 5

About the PI Server

Absolute Time
Absolute times have one of the following formats:
Form at Description/Notes
DD- MMM-YY hh:mm:ss.ssss day-month-year hour:minute:second. If any of the date fields
are left out, they default to the current date. Time fields
default to 00.
* current time
T 00:00:00 on the current day ( TODAY)
Y 00:00:00 on the previous day (YESTERDAY)
Monday 00:00:00 on the most recent Monday
Sun,Mon,Tue,Wed,Thu,Fr i,Sat 00:00:00 on the most recent Sunday, Monday, ..., Saturday

You can specify a time zone in an absolute time string (Specifying Time Zones (page 9)). You
do not typically need to include a time zone in an absolute time because the PI Server can
determine the correct time zone. In this manual, a time string that does not specify a time
zone is called an unqualified time string. You should be aware of how the PI Server interprets
unqualified time strings during Daylight Savings Time (Daylight Savings Time
Considerations (page 8)).
The following tables show examples of absolute time strings.
Exam ple Description
25 00:00:00 on the 25th of the current month
25-Aug-86 00:00:00 on that date
8: 08:00:00 on the current date
25 8 08:00:00 on the 25th of the current month
21:30:01.02 9:30:01.0200 PM on the current date

Use caution with the default settings. Here are some examples of timestamps that may be
confusing.
8: 08:00:00 on the current date
:8 08:00:00 on the current date
::8 00:08:00 on the current date

:::8 00:00:08 on the current date

0:8 00:08:00 on the current date

The confusion comes from the ambiguity in the first two examples above. Following this
theme, when minutes are added to the next examples, the time stamps are still similar.
8:01 08:01:00 on the current date
:8:01 08:01:00 on the current date

6
 Time Specifications and Considerations

The difference in the two notations is evident when a date is added to the time. When a date
is added to the front of the time the default notation is hh:mm:ss.ssss not :hh:mm:ss.ssss.
2 8: 08:00:00 on the 2nd of the current month
2 :8 00:08:00 on the 2nd of the current month

2 ::8 00:00:08 on the 2nd of the current month

If extra colons and times are added that is greater than the given DD-MMM-YY
hh:mm:ss.ssss format the last part of the time is disregarded.
2 :::8 00:00:00 on the 2nd of the current month
2 8:01:30 08:01:30 on the 2nd of the current month

2 :8:01:30 00:08:01 on the 2nd of the current month

A value for the seconds must be used if sub-seconds are used. Hence use caution when
considering timestamps containing sub-seconds.
8::30.01 08:00:30.0100 on the current date

:8::30.01 08:00:30.0100 on the current date

14 :8::30.01 00:08:00 on the 14th of the current month

Following are examples of timestamps that do not work.

8:30.01 Ambiguous, 8 could be minutes or hours

:8:30.01 Ambiguous, 8 could be minutes or hours

Relative Time
Relative time is some number of days, hours, minutes, or seconds. The leading sign (+ or -)
is required.
+/- d | h | m | s
The default starting point for relative time is usually the current time. Therefore, a time of -8h
is eight hours before the current time. Fractional times may be entered. For example, use -
1.5d for one and one-half days. Only a single operator is supported, + or -. For example, this
is not supported:
-1d+1h

PI Server System Management Guide 7

About the PI Server

Combined Formats
Combined time scales use both an absolute and a relative time. The absolute part of the time
can be *, T, Y, or a day of the week. The following table shows examples.
Exam ple Description

T + 8h 08:00:00 AM on the current day (today)

Y - 8h 04:00:00 PM on the day before yesterday

Mon + 14.5h 02:30:00 PM on the most recent Monday
* - 1h One hour ago

Daylight Savings Time Considerations

For time zones that observe daylight savings time, there is a period (typically one hour) per
year in which an unqualified absolute time string is ambiguous. (An unqualified absolute time
string is a time string in which the time zone is not specified.) This always occurs during the
last hour of daylight savings time before the beginning of standard time. In the Northern
Hemisphere, this occurs in the fall. In the Southern Hemisphere, this occurs in the spring. The
above time string of 25-Oct-98 01:30 in North America is an example. PI cannot
determine from this time string alone whether standard time or daylight savings time is
intended.
If the unqualified time is passed, PI uses the current time to resolve the ambiguity. This
means that 25-Oct-98 01:30 is considered daylight savings if the translation takes place
before 25-Oct-98 02:00:00 Pacific Daylight Time, and is considered
standard time otherwise. If this is not your intent, suffix your time string with the appropriate
time zone name.

How to Determine if a Time String is Ambiguous

To determine if a specific time string is considered ambiguous, you can use pidiag -tz:
c:\pi\adm>pidiag -tz "25-oct-98 1:30:00"
# Time Zone name:
Pacific Time
# TZ environment variable: <not set>
# Bias (offset) from UTC (TAI) time:
28800
# January is standard / Northern hemisphere:
1
# Standard Time Name:
Pacific Standard Time
PST
# Daylight Time Name:
Pacific Daylight Time
PDT
# StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 3, 2, 1, 7200, -3600

8
 Time Specifications and Considerations

1970, 2038, 11, 1, 1, 7200, 0

Passed Time: 25-Oct-98 01:30:00* PST Local: 909279000 UTC:
909307800
The last line of the output reflects the passed time. It is marked with an asterisk (*) which
means that the time string would be ambiguous if specified without the time zone name.

How to Determine Your Time Zones

You can find the names of your time zones by using pidiag -tz.
This sample output was generated on Windows:
C:\PI\adm>pidiag -tz
# Time Zone name:
Pacific Time
# TZ environment variable: <not set>
# Bias (offset) from UTC (TAI) time:
28800
# January is standard / Northern hemisphere:
1
# Standard Time Name:
Pacific Standard Time
PST
# Daylight Time Name:
Pacific Daylight Time
PDT
# StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 3, 2, 1, 7200, -3600
1970, 2038, 11, 1, 1, 7200, 0

How to Specify Time Zones

In almos t all cases, PI can accurately determine whether daylight savings time is in effect. If
you wish to be specific, you may suffix the DD-MMM-YY hh:mm:ss.ssss absolute time
format with S for standard time, D for daylight time, or the appropriate time zone name.
Examples of time zone names include PST for Pacific Standard Time and MET for Middle
European Time.
The PI System supports both long time zone names (such as Pacific Standard Time) and short
time zone names (such as PST). You may specify either name. Comparisons are not case
sensitive. The following time strings are equivalent:
25-Oct-98 01:30 Pacific Daylight Time
25-Oct-98 01:30 pdt
25-Oct-98 01:30 D

How to Display Time Zone Information

To display time zone information, run:

pidiag -tz [time[TZ]] [-check | -dump [-brief] | -full]

PI Server System Management Guide 9

About the PI Server

Time Zone Information and Day Light Saving Time Transition Rules
Without the optional TZ parameter, pidiag -tz displays the time zone information and
Daylight Saving Time (DST) transition rules that are being used by the PI server. If the file
PI\dat\localhost.tz is resent and valid, then the time zone information is from the
file. Otherwise, the information is from the operating system.
C:\PI\adm>pidiag -tz
# Time Zone name:
Eastern Time
# TZ environment variable: <not set>
# Bias (offset) from UTC (TAI) time:
18000
# January is standard / Northern hemisphere:
1
# Standard Time Name:
Eastern Standard Time
EST
# Daylight Time Name:
Eastern Daylight Time
EDT
# StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 1973, 4, 5, 1, 7200, -3600
1974, 1974, 1, -1, 6, 7200, -3600
1975, 1975, 2, -1, 23, 7200, -3600
1976, 1986, 4, 5, 1, 7200, -3600
1987, 2006, 4, 1, 1, 7200, -3600
2007, 2037, 3, 2, 1, 7200, -3600
1970, 2006, 10, 5, 1, 7200, 0
2007, 2037, 11, 1, 1, 7200, 0
A StartYear, EndYear, Month, Week, Day, Time, and Offset define the daylight and standard
time trans ition rules.
The transition rules are:
• StartYear is the first year that the rule is in effect
• EndYear is the last year that the rule is in effect
• Month is the month (1-12) that the rule is applied.
• Week is the week (1-5) that the rule is applied. If Week is 5 and there are only four weeks
in the month, then 5 designates the last week in the month. If Week is -1, then Week is
ignored and day becomes absolute.
• If Week is greater than 0, then Day is the relative day (1-7) that the rule is applied. A Day
of 1 represents Sunday, a Day of 2 represents Monday, and so on. For example, a Week
of 1 and a Day of 1 means the first Sunday in April. If Week is -1, then Day is an absolute
day (1-31).
• Time is the time in seconds after midnight that the rule is applied.
• Offset is the time in seconds to subtract from standard time to get the local time. For
example, when daylight saving time is in effect, -3600 is subtracted from standard time.

10
 Time Specifications and Considerations

If your time zone does not observe daylight savings time, the output indicates this.
C:\PI\adm> pidiag -tz
TZ environment variable: <not set>
Standard Time Name: US Mountain Standard Time (UMST)
Daylight Savings Time: <not observed>
See Adjust Standard and Daylight Savings Times (page 12) to change this setting.

Display options
The -check option generates no output at all, unless the time zone settings on your system are
invalid.
The -dump option dumps the whole time zone table. This includes fall/spring changes in
every year. The dump is in comma-separated variable (CSV) format and can be loaded
directly into a spreadsheet, if all time-change information for the local time zone.
The -dump option can be combined with -brief. The output with this option includes the year
and spring and fall time changes, each marked with D or S to denote daylight or standard
time.
The -full option can be used to display additional information about the localhost.tz
file, such as the file’s UID, creator, creation time, and so on. The information is valid only if
localhost.tz was successfully loaded by the PI server.

Display Local and UTC Time

When the time parameter is provided, pidiag -tz displays the local and UTC times in seconds
corresponding to the provided time. It also indicates whether the passed time is in standard
(ST) or daylight saving time (DT). If the time string is ambiguous, it is marked with an
asterisk (*). Time strings are ambiguous if they specify a time in the last hour of daylight
savings time before the beginning of standard time. In the northern hemisphere, this occurs in
the fall. In the southern hemisphere, this occurs in the spring.
C:\PI\adm>pidiag -tz "31-Oct-2007 01:30:00"
# Time Zone name:
Mountain Time
# TZ environment variable: <not set>
# Bias (offset) from UTC (TAI) time:
25200
# January is standard / Northern hemisphere:
1
# Standard Time Name:
Mountain Standard Time
MST
# Daylight Time Name:
Mountain Daylight Time
MDT
# StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 1973, 4, 5, 1, 7200, -3600
1974, 1974, 1, -1, 6, 7200, -3600
1975, 1975, 2, -1, 23, 7200, -3600
1976, 1986, 4, 5, 1, 7200, -3600

PI Server System Management Guide 11

About the PI Server

1987, 2006, 4, 1, 1, 7200, -3600

2007, 2037, 3, 2, 1, 7200, -3600
1970, 2006, 10, 5, 1, 7200, 0
2007, 2037, 11, 1, 1, 7200, 0
Passed Time: 31-Oct-07 01:30:00 MDT Local: 1193790600
UTC: 1193815800

Display a Different Time Zone

If, in addition to time parameter, the TZ (time zone) parameter is specified, pidiag -tz
displays the time zone information of the provided time zone and converts the time as if the
provided time zone were in effect. Note that the TZ argument follows the time/year
argument, so you must provide a time string or year to use this feature. The specified time
zone can be different from the local time zone.
C:\PI\adm>pidiag -tz "*" GMT0BST
TZ environment variable: GMT0BST
Standard Time Name: GMT (GMT)
Daylight Time Name: BST (BST)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2037, 4, 1, 1, 7200, -3600
1970, 2037, 10, 5, 1, 7200, 0
Passed Time: 8-Oct-03 20:27:04 BST Local: 1065644824 UTC:
1065641224

Customize Standard and Daylight Savings Time Change Times

PI uses an internally constructed table to determine when changes between Standard Time
and Daylight Saving Time (DST) occur. When the file PI\dat\localhost.tz is present
and valid, this table is built using the change rules specified in the file. Otherwise, the table is
built using the single time change rule available from Windows.
A customized localhost.tz can be created following four steps:
Step 1: Create a Text File to Work on
You can create a text file that contains the DST start time and end time of each year by
running:
pidiag -tz -dump -brief > myzone.txt
Or you can create a text file that contains DST change rules by running:
pidiag -tz > editrules.txt
Step 2: Customize the Start Times and End Times or the Rules
Edit the text file to reflect the actual DST change times or rules for your time zone. If you are
working on the start times and end times, the file need not contain a record for every
supported year; years that are not specified use the operating system generated rule.

12
 Time Specifications and Considerations

Step 3: Convert the Text File into a Binary (.tz) File

To convert the text file containing the start times and end times into a binary file, run:
pidiag -tz -if myzone.txt -of test.tz
To convert the text file containing the change rules into a binary file, run:
pidiag -tz -ifrule editrules.txt -of test.tz
You can check the validity of test.tz by using pidiag with the -if option to read it again.
pidiag assumes that any file ending in .tz is a binary file; all other files are assumed to be
text. The -if option can be combined with any other options. For example, to test the date 31-
Oct-02 01:30 using the new binary file, enter:
pidiag -tz "31-oct-02 01:30" -if test.tz
To dump the contents of a binary file to text, enter:
pidiag -tz -if test.tz -dump > test.txt
Step 4: Put the New Binary File to Use
If the new binary file correctly represents the time transitions, copy the binary file to
PI\dat\localhost.tz and restart PI. Doing this does not affect the timestamps of data
already stored by PI, since these timestamps are stored as UTC. It affects only the translation
of these stored times to local times.

How to Translate Time Formats

pidiag -t time [U]

This provides translation between time string formats and internal formats:
• If time starts with 0 (zero) an integer format (seconds since 1-jan-70) is translated to
string representation. pidiag assumes local time, unless the third argument is U or UTC,
in which case the argument is taken to be universal time (GMT).
• If the first character is not 0, the time argument is treated as time string, absolute or
relative, and translated into an integer value. Both local time and UTC integer values are
displayed.

String to Integer Format Sample Output

C:\PI\adm>pidiag -t 1-sep
1-Sep-98 00:00:00 PDT - Local: 904608000 UTC: 904633200

C:\PI\adm>pidiag -t t+1h
21-Oct-98 01:00:00 PDT - Local: 908931600 UTC: 908956800

C:\PI\adm>pidiag -t "*"
21-Oct-98 20:00:10 PDT - Local: 909000010 UTC: 909025210

Integer Format to String Sample Output

C:\PI\adm>pidiag -t 0909000010
21-Oct-98 20:00:10 PDT - Local: 909000010 UTC: 909025210

PI Server System Management Guide 13

About the PI Server

C:\PI\adm>pidiag -t 0909025210 U
21-Oct-98 20:00:10 PDT - Local: 909000010 UTC: 909025210

Transforming Event Timestamps (-tfix)

Offsets, as a function of time, are defined in the time conversion file. This can be used to
apply corrections to times on some systems that had incorrect timestamps due to run-time
library problems, or non-standard DST setting.
This adds a given time offset to every event:
-tfix conversion_file

Time Conversion File Format

Lines starting with # are comments.
Empty lines and white spaces are ignored.
Data lines have the format:
StartTime, offset
StartTime may be expressed as UTC - seconds since 1/1/70 or as PI local timestamp string:
dd-mmm-yyy hh:mm:ss
*
*-1s
UTC timestamps and strings cannot be intermingled, the first format is assumed for all
entries.
Offset is a number of seconds added to the timestamp of every event within the time range.
Fractional seconds are not supported. Offset applies from timestamp up to, but not including
the next timestamp.

Time Conversion File Examples

Move entire archive ahead by 1 hour:
0,3600
2000000000,3600
Move entire archive ahead by 1 hour (another format):
01-Jan-70 00:00:00,3600
01-Jan-10 00:00:00,3600
Apply a missed DST conversion to an archive that covers the summer of 1997:
01-Jan-02 00:00:00,0
06-Apr-02 02:00:00,3600
26-Oct-02 02:00:00,0
31-Dec-02 23:59:59,0
Apply the time adjustments for each time period as a series of UTC values and offsets:
814953600,-61200

14
 Time Specifications and Considerations

828871200,-57600
846403200,-61200
860320800,-57600

PI Server System Management Guide 15

Chapter 2

Start and Stop the PI Server

The PI Server on Windows runs as a collection of services. These services are typically
configured to start automatically at computer startup. If you need to shut down or restart the
Windows operating system, always first stop the PI Server. Otherwise you could lose data
due to the service timeouts. You could also lose data that is still in memory and not flushed to
disk.

Note: If you use Microsoft clusters, always use the Microsoft Windows Cluster
Administrator to start and stop the PI Server. Do not start and stop PI Server with
the SMT PI Services tool or with the command-line scripts.

Start the PI Server

Note: If you use Microsoft clusters, do not use pisrvstart.bat, or PI Server Management
Tools (SMT) to stop the PI Server. Use the Microsoft Windows Cluster
Administrator instead.

Start Windows Services

To start the PI Server as Windows services:

1. Log on to a Windows account that has full access to the PI Server files and permission to
start PI services.
2. Open a Command Prompt window.
3. Change to the PI\adm directory.
4. Use the pisrvstart.bat script to start PI as Windows services:
pisrvstart.bat [-nosite] [-base]
To run PI Server without starting interfaces and other site-specific programs, use the optional
nos ite parameter.
If you are troubleshooting and want to start only the core subsystems, use the optional base
parameter. When you use this parameter, these subsystems will start in the following order:
Network Manager, Base, Message, License Manager, Snapshot, Archive, Backup, and
Update Manager.

PI Server System Management Guide 17

Start and Stop the PI Server

Configure Automatic Startup of Services

PI Server on Windows normally runs as a collection of services. When you install PI Server,
you can select the option for automatic startup at reboot. You can also set the PI Server
reboot startup behavior with the Windows Services dialog.
In order to control the services, you must be logged on with an account that has sufficient
privileges. If you are not, you get a message like this:
Error 5: Access Denied
For diagnostic purposes, you can also start the PI Server in interactive mode. For details, see
Start Interactively (page ).

Verify Startup

The PI Subsystems may take several minutes to start. The PI Subsystems that must start up
before interfaces and other applications can connect to the PI Server are Archive, Base,
License Manager, Network Manager, Snapshot, and Update Manager. When these
subsystems are ready to service requests, the TCP/IP listener is opened.
To verify that the PI Server has started, you can:
1. Determine that the PI Server port is open:
netstat -an
2. Or, review the PI Server log for the following message:
>> TCP/IP connection listener opened on port: 5450
Connection attempts will fail if the port is not open. Most interfaces and client applications
will retry automatically until a connection is established.

Start in Interactive (Troubleshooting) Mode

For troubleshooting purposes, you can start the PI Server interactively. Do this only if you
need to monitor, test, or troubleshoot the PI Server.
To start PI Server interactively:
1. Log on to a Windows account that has full access to the PI Server files and permission to
start PI services.
2. Open a Command Prompt window.
3. Change to the PI\adm directory and type:
pistart.bat [-nosite] [–stdout] [–base]
To run the server without starting the interfaces and other site-specific programs, use the
optional nosite parameter. To prevent the PI Message Subsystem from being started, use the
optional stdout parameter; all messages will be sent to the standard output instead of the PI
Server message log.

18
 Stop the PI Server

If you are troubleshooting and want to start only the core PI Server subsystems, use the
optional base parameter. When you use this parameter, these subsystems will start in the
following order: Network Manager, Base, Message, License Manager, Snapshot, Archive,
Backup, and Update Manager.

Note: Some Windows interfaces cannot be run as services. Refer to the interface
documentation for details.

Stop the PI Server

Note: If you use Microsoft clusters, do not use pisrvstop.bat, or PI Server Management
Tools (SMT) to stop the PI Server. Use the Microsoft Windows Cluster
Administrator instead.

Stop Services

To stop the PI Server if its processes are running as Windows services:

1. Log on to a Windows account that has full access to the PI Server files and permission to
start PI services.
2. Open a Command Prompt window.
3. Change to the PI\adm directory:
pisrvstop.bat
This stops all of the interfaces and programs listed in pisrvsitestop.bat, and then the PI
processes. To stop PI Server without shutting down interfaces and other site-specific
programs, enter the optional nosite parameter.
You may also enter a reason for shutting down the PI Server by entering:
[ - reason "Reason for shutting down PI Server" ]

Note: If you plan to completely start or stop a PI Server, it is important that you use the
startup and shutdown scripts; these files will start or stop services in the order
required by system dependencies.

Change the Shutdown Wait Time

Windows has a registry entry that defines the maximum wait time for a service to exit. On PI
Servers with large point counts, the maximum wait may need to be increased to allow the
services enough time to shut down properly. The PI Server installer sets the default value to
300,000 milliseconds, or 5 minutes. This is generally enough time for proper shutdown on
systems with fewer than 50,000 points. Larger servers may require more time.

PI Server System Management Guide 19

Start and Stop the PI Server

Failing to allow proper shutdown of the PI Server can result in lost data or corrupted data
files.
To determine if a longer wait time for shutdown is required:
1. Use pisrvstop.bat to stop the PI Server (page 19).
2. Record the time it takes the PI Server to shutdown.
3. If it takes more than 5 minutes for the server to shutdown, check the registry entry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WaitToKillSer
viceTimeout
If necessary, edit the WaitToKillServiceTimeout parameter to equal the time
required for shutdown.

Stop Interactive Mode

To shut down a PI Server that was started in interactive mode, type Ctrl+C in each of the
Command Prompt windows corresponding to the PI processes. You should shut down these
processes in the following order:
1. Utilities (such as piconfig)
2. Interfaces (such as RampSoak and Random)
3. pinetmgr (When you instruct pinetmgr to stop, the remaining processes are told to exit
in the proper order and, finally, pinetmgr stops.)

Shut Down or Restart Individual Subsystems

You can start or stop individual PI Server subsystem services using the Windows Services
administrative tool or using SMT. The PI Server System Management Tools (SMT) provides
a tool for managing the PI Server services. To see the tool, open SMT and select Operation
> PI Services. The PI Services tool allows you to start and stop individual services, or all the
services. You can also use the tool to configure PI Server reboot startup behavior.

Note: If you plan to completely start or stop a PI Server, it is important that you use the
startup and shutdown scripts; these files will start or stop services in the order
required by system dependencies.

Start an Individual Subsystem

To start an individual subsystem, enter:

net start subsystem
where subsystem is the PI Subsystem abbreviation derived from the executable name. For
example, pibasess, pibackup, pirecalc, pisqlss, pishutev, pisnapss,

20
 Shutdow n Events

piarchss, piupdmgr, pilicmgr, pismgss, pinetmgr, pitotal, pipeschd,

piudsrdr, pialarm, and pibatch.
For more information on the PI Server subsystems, see PI Server Subsystems (page 2).

Note: This procedure should not be done on a Microsoft Cluster. Use the Microsoft
Windows Cluster Administrator instead.

Shut Down an Individual Subsystem

To shut down an individual subsystem, enter:

net stop subsystem
where subsystem is the PI Subsystem abbreviation derived from the executable name. For
example, pibasess, pibackup, pirecalc, pisqlss, pishutev, pisnapss,
piarchss, piupdmgr, pilicmgr, pismgss, pinetmgr, pitotal, pipeschd,
piudsrdr, pialarm, and pibatch. For more information on the PI Server subsystems,
see PI Server Subsystems (page 2).

Note: This procedure should not be done on a Microsoft Cluster. Use the Microsoft
Windows Cluster Administrator instead.

Shutdown Events
PI Points have a configurable attribute to determine whether shutdown events are written.
The timestamp of the shutdown event normally represents the actual shutdown time of the PI
Server as recorded by the Snapshot Subsystem. If the PI Server is shutdown ungracefully, this
timestamp will be accurate to within 15 minutes by default.
The Shutdown attribute has two possible values: 1 (On) and 0 (Off). If the shutdown attribute
of a point is set to 1, the Shutdown Subsystem writes a shutdown event if the PI Server shuts
down. Beginning with PI Server PR1 SP1, unless you configure points to receive shutdown
events, only test points such as sinusoid and sinusoidu will receive shutdown events.
For details, see Set Shutdown Events for Specific Points.
OSIsoft recommends using the default setting of 0 (Off) for points collected by remote
interfaces that are configured for buffering or PI High Availability (PI HA). The reason: if
you run remote interfaces with buffering or PI Collectives, shutdown events are not an
accurate indicator of data loss when a PI Server is shut down.

PI Server System Management Guide 21

Start and Stop the PI Server

With properly configured buffering, data will simply be queued up for a PI Server while it is
shut down, provided the remote interfaces continue running. Also, if a PI Server is part of a
collective, shutting down one member has no effect on the other members' ability to continue
receiving and serving data.

Note: OSIsoft recommends that you do not run interfaces on the same machine as the
PI Server; however, if you do use such a configuration, these local interfaces
should be configured for shutdown events. Unlike most PI subsystems, the
Shutdown Subsystem exits after completion, except when running on Microsoft
Clusters.

Set Shutdown Events for Specific Points

Points that receive shutdown events are specified in the file PI\dat\shutdown.dat.

Note: If you have a new installation of PI Server version 3.4.375.38 (PR1) or later, the
default configuration of shutdown.dat targets only points with a point source of
R and a shutdown attribute set to 1. If you upgrade to PI Server 3.4.375.38 (PR1)
or later, the installer will not change the configuration of shutdown.dat.

You may edit shutdown.dat to restrict shutdown events to certain groups of tags. To
specify more than one tag name use a tag mask. Use the wildcards * and ?. An asterisk (*)
matches all possibilities with any number of characters. The question mark (?) matches a
single character and may be used any number of times.

Note: Do not specify additional tags by appending comma-separated tag masks or by

using additional lines. You can specify only one tag mask. You must specify at
least one tag mask to enable the shutdown system to operate without errors. To
prevent all shutdown events, specify a tag mask that does not match any tag.

You can use other point attributes and values in addition to, or instead of, the shutdown flag.
All conditions are logically ANDed together. If no point attributes are specified, all tags
specified by the tag mask are selected to receive shutdown events.
For example, this configuration file entry selects only tags that start with s, have the location1
attribute set to 0, and the point source set to H. No other tags receive shutdown events:
! tag mask
s*
! point attributes
location1,0
pointsource,H

22
Chapter 3

Manage Points
The Introduction to PI Server System Management provides the basics on working with PI
Points. This chapter does not repeat the information provided there. However, it does discuss
the following additional topics in detail:
• PI Point Classes and Attributes (page 23)
• Exception Reporting and Compression Testing (page 43)
• Change PI Point Type (page 48)
• Create, Delete, or Edit PI Point Classes and Attribute Sets (page 51)
• Digital State Sets (page 65)

PI Point Classes and Attributes

A point class represents the schema or template of a point. It determines what attributes you
can define for a point of that type. Essentially a point class is just a group of point attribute
sets. Each attribute set consists of a group of individual attributes. Point class is assigned
when the point is created. The default point class is Base point class.
No two attribute sets within a point class can contain the same attribute. The Point Database
has several different point classes, such as Base and Classic. The structure of the Classic
point class is depicted in the following figure.

PI Server System Management Guide 23

Manage Points

You can create point classes and attribute sets. You can also edit and delete both attribute sets
and point classes (PI Server version 3.4.370 and later) although this poses risks and it is rare
that you should need to do so.

Pre-defined Point Classes

The following table lists pre-defined point classes.

Point class Attribute sets that m ake up the point class

Alarm base
alar mparam
Base base

Classic base
classic
SQC_Alarm base
sqcalm_parameters
Totalizer base
totals

24
 PI Point Classes and Attributes

Predefined Attribute Sets

alarmparam
Attribute Type Default
action1 String
action2 String
action3 String
action4 String
action5 String
AutoAck String yes
ControlAlg String
ControlTag String
Deadband Float32 0
Options String
ReferenceTag String
Srcptid Int32 0
test1 String
test2 String
test3 String
test4 String
test5 String
txt1 String
txt2 String
txt3 String
txt4 String
txt5 String

PI Server System Management Guide 25

Manage Points

base
Attribute Type Default
Archiving BYTE 1
Changedate TimeStamp 31-Dec-69 16:00:00
Changer Uint32 for 3.4.380 0
and later
(Uint16 for earlier
versions)
Com pdev Float32 2.
Com pm ax Uint32 28800
Com pm in Uint16 0
Com pressing BYTE 1
Creationdate TimeStamp 31-Dec-69 16:00:00
Creator Uint32 for 3.4.380 0
and later
(Uint16 for earlier
versions)
Descriptor String
DisplayDigits BYTE -5
EngUnits String
Excdev Float32 1.
ExcMax Uint32 600
ExcMin Uint16 0
ExDesc String
PointSource String Lab
PointType UBYTE 12
Scan BYTE 1
Shutdow n BYTE 1
Span Float32 100.
Step BYTE 0
TypicalValue Float32 50.
Zero Float32 0.

26
 PI Point Classes and Attributes

classic
Attribute Type Default
Convers Float32 1.
Filtercode Int16 0
Instrum entTag String
location1 Int32 0
location2 Int32 0
location3 Int32 0
location4 Int32 0
location5 Int32 0
Squareroot Int16 0
Srcptid Int32 0
Totalcode Int16 0
userint1 Int32 0
userint2 Int32 0
userreal1 Float32 0.
userreal2 Float32 0.

PI Server System Management Guide 27

Manage Points

sqcalm_parameters
Attribute Type Default
AutoAck String yes
ChartType Int32 0
ClearOnLim itChange String true
ClearOnStart String false
CLTag String
CommentTag String
LCLTag String
LSLTag String
Mixture String
OneSideofCL String
Options String
OutsideControl String
OutsideOneSigm a String
OutsideTwoSigm a String
PIProductLim its String no
ProductTag String
ReferenceTag String
ResetTag String
SQCAlarm Priority Int32 0
Srcptid Int32 0
Stratification String
TestStatusTag String
Trend String
UCLTag String
USLTag String
WaitOnLim itChange String false

28
 PI Point Classes and Attributes

totals
Attribute Type Default

CalcMode String timeweighted

Com pValue String ON

Conversion Float32 1

EventExpr String

FilterExpr String

Function String Total

MovingCount Int16 2

Offset String +0m

Offset2 String +0m

Options String

PctGood Float32 85

Period String +1h

Period2 String +2m

RateSam pleMode String natural

ReportMode String Running

Srcptid Int32 0

TotalCloseMode String clock

Zerobias Float32 0

Base Class Point Attributes

The Base class is a common set of attributes that all other point classes include. Some of
these attributes can be changed only by the system. These attributes are described in System-
Assigned Attributes (page 42).

PI Server System Management Guide 29

Manage Points

Archiving
The Archiving flag mus t be set to ON (1) for a point to be archived. This flag can be set to
OFF (0) to stop archiving of a point.

Compressing Flag
Compression should be turned on for all real-time points in the system. Set compression OFF
for laboratory and manually entered tags so every value is recorded in the Archive. Even with
compression turned off, the number of events for these tags is usually small.
To turn compression on, set the Compressing attribute should be set to ON (1) for most
points. With compression off, every value sent to the Snapshot is saved in the Archive.
Compression affects digital points, since a new value is recorded only when the current value
changes. Points of types Blob and string have a similar behavior; new events pass
compression only when the value changes. String values are compared ignoring case.
(VaLuE and valUe are equal) For Blob events, any change is significant.

CompDev, CompMin, CompMax and CompDevPercent

When a new Snapshot arrives, the previous one is evaluated according to the compression
specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is
discarded. The result is that only significant data is written to the Archive. This process is
called compression.
The compression specifications consist of a deviation (CompDev), a minimum time
(Com pMin), and a maximum time (CompMax):
• Com pMin: An event that comes before CompMin time elapsed is discarded. For points
associated with interfaces that send exception reports, the Com pMin should be 0.
• CompMax: Events are archived if discarding them would cause a gap greater than
MaxTime. The recommended maximum time specification is one work shift (that is, 8
hours). Duplicate values are archived if the elapsed time exceeds CompMax. Under no
circumstances does this cause PI to generate events; it only filters events that are
externally generated.
• CompDev: The most important compression specification is the deviation, CompDev.
Setting this value too low causes too little data compression and wastes space in the
Archive. Setting this value too high causes loss of useful data. For most flows, pressures,
and levels, use a deviation specification of 1 or 2 percent of Span. For temperatures, the
deviation should usually be 1 or 2 degrees.
• CompDevPercent: This is similar to CompDev, but it specifies the compression
deviation in percent of Span rather than in engineering units. If one is changed by user,
the other is automatically changed to be compatible. If both are changed,
CompDevPercent overrides CompDev.
For non-numeric tags, CompDev and CompDevPercent are set to zero and ignored.
See Exception Reporting and Compression Testing (page 43).

30
 PI Point Classes and Attributes

Descriptor
The Descriptor is a text field that appears on various client application displays and can be
used in reports. It can be of any length up to 65,535 characters. When this value is read
through the PI API it is truncated to 26 characters.
Some interfaces use the descriptor for tag configuration on external system. Having quotes or
wild card characters might lead to confusion when these attributes are passed to other
applications.

DigitalSet
Only digital type tags use the DigitalSet attribute. It is ignored for any other type.
A collection of digital states is called a digital state set. For example, a digital state set can
consist of two states, OPEN and CLOSED. You might also define a digital state set that
consists of {RED, GREEN, BLUE, YELLOW, and ORANGE}. Typically there are many
digital state sets defined for a system.
For digital points, the DigitalSet attribute specifies the name of the digital state set associated
with the tag. All tags are associated with the system state set. The system state set contains a
collection of all the states that may be used for any point. Examples are Shutdown, Over
Range, and I/O Timeout.

DisplayDigits
The DisplayDigits attribute controls the format of numeric values on screens and in reports.
Zero or a positive number indicates the number of digits to display to the right of the decimal
point. A negative number indicates the number of significant digits to display. In this case,
the absolute value of DisplayDigits is the number of significant digits.
The following table shows how a value of 23.45 would appear on the screen for different
values of DisplayDigits:
DisplayDigits Form at
3 23.450
2 23.45
1 23.5
0 23
-1 2E+001
-2 23
-4 23.45

EngUnits
The Engineering Unit string describes the units of the measurement. You may use any
string, and the string may be of any length. However, the PI API retrieves only the first 12
characters. The PI SDK does not truncate the string.
Examples include:

PI Server System Management Guide 31

Manage Points

DEGF
Degrees Centigrade
Gal/Min
Gallons Per Minute
'"Hg
Engineering Unit strings are case preserving, but not case sensitive on search. The system
trims leading and trailing blanks are trimmed during input.

ExDesc
The extended descriptor is a text field of any length (although it is truncated to 80 characters
when reported through PI API). For most points, it is used only to provide additional
information for documentation. Several interfaces use the ExDesc attribute to encode
additional configuration information.

ExcDev, ExcMin, ExcMin and ExcDevPercent

Most interface programs use exception-reporting specifications to determine when to send
data to the snapshot. The exception reporting specifications consist of a deviation (ExcDev),
a minimum time (Exc Min), and a maximum time (Exc Min). ExcDevPercent is similar to
CompDev, but it specifies the compression deviation in percent of Span rather than in
engineering units. If one is changed by user, the other is automatically changed to be
compatible. If both ExcDev and ExcDevPercent are changed, ExcDevPercent overrides
ExcDev.
For digital, string and Blob tags, ExcDev and ExcDevPercent are set to zero and ignored.
See Exception Reporting and Compression Testing (page 43).

NewTag
The NewTag attribute is used for renaming tags.

Point Security
You can independently configure security for point attributes and point data. Use the Point
Security and Data Security attributes respectively (older versions of some client tools refer
to these as the Point Access and Data Access attributes).
Setting the values of security attributes is different for PI Server 3.4.380 and later than it is
for earlier versions of the PI Server. On PI Server versions 3.4.380 and later, you can set
point security access permissions for any PI Identities, PI Users, and PI Groups. Earlier
versions of the PI Server use the owner/group model.

32
 PI Point Classes and Attributes

In the owner/group model, you define an owner and a group for each security attribute. The
owner must be a PI User and the group must be a PI Group. You then set access permissions
for owner and for group, as well as world access.
See the Configuring PI Server Security for complete details on security.

PointSource
The PointSource attribut e is a string that associates a tag with an interface or PI application.
An interface uses the point source to retrieve all its points.
The default point source is Lab. Use this for points that are not associated with any interface
to specify lab-input points.
Avoid using the % (percent) character as a point source, as it has also special meaning for
SQL and other applications. Similarly, avoid using ? or * as point source characters.

PointType
There are many point types in the PI Server. PointType is assigned when the point is created.
Prior to PI Server version 3.4.370, this attribute could not be changed, but in versions 3.4.370
or later it can be edited. For details, see PI Point Class Edit (page 51).
Point Type Used for
Digital Points w hose value can only be one of several discrete states, such as ON/OFF or
Red/Green/Yellow . Nearest equivalent to the PI Server 2.x Digital type.
Int16 Points w hose values are 15-bit unsigned integers (0 to 32767). Nearest equivalent to
the PI 2.x Integer type.
Int32 Points w hose values are 32-bit signed integers (-2147450880 to 2147483647). PI
reserves the low est 32K values of the 32bit range for digital states.
Float16 Floating point values, scaled. The accuracy is one part in 32767. Nearest equivalent
to the PI 2.x Real type.
Float32 Single-precis ion floating-point values, not scaled.
Float64 Double-precision floating-point values, not scaled.
String Storing string data of up to 976 characters.
Blob Storing any type of binary data up to 976 bytes.
Timestamp Storing values of type Timestamp. Any Time/Date in the Range 1-jan-1970 to 1-Jan-
2038.

Choosing Point Type

For points collected by interfaces, use the point type that most closely matches the point type
in the source system. For example, if the point originates from a transmitter that supplies an
analog measurement with 14 bits of accuracy, use the float16 point type. This point type
provides 15 bits of precision.
For accumulators and other high precision values, use the higher precision point types: either
Float32 or Float64.

PI Server System Management Guide 33

Manage Points

The higher precision point types require more disk space for each stored value. Float16 points
use 16 bits or 2 bytes per value. Float32 and float64 use 4 and 8 bytes per value,
respectively. Int16 and int32 values use 2 and 4 bytes, respectively. Int16 is similar to a PI 2
integer type; it supports only 15-bit unsigned integers.
If you want to store negative integers, select the int32 point type. Note that PI reserves some
values in the negative range of a 32-bit integer. The smallest value that can be stored is
shown in the table above.
Interface manuals sometimes refer to point types R (real), I (integer), and D (digital).
• Use float16 or float32 for type R. If the data is coming from an analog-to-digital
converter (ADC), float16 is sufficient
• Use int16 or int32 for type I or integer values
• Use digital for type D or discrete values

FLOAT16 VS. FLOAT32

OSIsoft recommends that you use float32 as the default type for floating point data. The
space-saving of float16 can reduce the amount of I/O, but this is significant only on very
large data retrievals, such as yearly average calculations or long term trends.

Attributes that Depend on Point Type

Some point attributes are not relevant for some point types:
• Only Digital type tags use the DigitalSet attribute. It is irrelevant for other type tags and
can be ignored.
• For Digital, string and Blob type tags, the values of CompDev, CompDevPercent,
ExcDev and ExcDevPercent are not applicable. The value of these attributes is
automatically returned to applications as 0.
For Digital, string and Blob type tags, the Span and Zero attributes are not applicable. For
digital tags , Zero is automatically set to the digital set number. For PI Server version 3.4.380
and later, span is no longer relevant for digital points. On earlier versions of the PI Server,
Span is automatically set to the number of states minus 1 in the set.
Finally, for all non-numeric type the step flag is set to TRUE.

PtClassName
The point class must be defined before the point is created. PtClassName specifies the point
class. Prior to PI Server 3.4.370, the point class of a point could not be changed once the
point was created. In versions 3.4.370 or later, it can be edited. For details, see PI Point Class
Edit (page 51).

Scan Flag
Some interface programs use a Scan flag. Interfaces that honor this attribute do not update
points whose scan flag is set to OFF. See the documentation to find out if your interface
program uses it.

34
 PI Point Classes and Attributes

Shutdown Flag
In some cases it is useful to record, to PI points, when the Archive was shut down. That way
there is a clear indication of a gap in the data collection. Points may be configured so that PI
Server automatically records a time-stamped event to indicate when a shutdown occurs.
These are called shutdown events.
The shutdown flag for a point is set to ON (1) to indicate that shutdown events should be
recorded for this tag. The default is ON.
For points collected from interfaces on distributed collection nodes, set this flag to OFF (0)
because data buffering in PINet or PI API retains the data until the home node is running
again. Therefore, there are no data gaps to identify with shutdown events.
Many sites configure points that store laboratory test values so that the lab test points do not
receive shutdown events. Lab values are assumed to be constant between tests. Inserting
shutdown events for these points can be misleading.
The shutdown flag is used in conjunction with the configuration file dat\shutdown.dat.

SourceTag
For data output to other systems, the SourceTag is the PI tag of the data source. For example,
you can define a tag ABC to receive data using point source A, and then define another tag
DEF to send this information to another instrument system using point source B. The source
tag for tag DEF would be ABC. This attribute is used by some interfaces, while other
interfaces use the extended descriptor (ExDesc) for this information.
The SourceTag attribute is not stored in the Point Database. It is only a more readable
representation of the srcptid attribute which holds the source point ID. srcptid does not exist
in all point classes. For example, it is part of the classic point class but not of base.

Span
The Span is the difference between the top of the range and the bottom of the range. It is
required for all numeric data type points.
For float16 point types, the Span is used with the Zero for scaling values in the Archive. The
Span must be a positive value. If the value for a point type float16 point is greater than the
top of range, it is recorded in the Archive as Over Range. For other point types, Zero and
Span do not affect the values recorded in the Archive.
The Span is also used when defining a PI ProcessBook trend with a vertical scale of
database.
This attribut e is not used for non-numeric points.
The Span for a tag can be changed without affecting data already in the Archive. For points
of type float16, the old Span is used for retrieving the Archive data collected before the edit.
The new Span is used for data collected after the edit. When Span is changed, the exception
and compression deviation percents are preserved. This means that the ExcDev and

PI Server System Management Guide 35

Manage Points

CompDev fields, which are expressed in engineering units, are modified internally. If any of
the deviation fields is specified in the editing operation they take precedence.

Note: Some interfaces might use Span information to filter incoming data. These
interfaces often convert out- of-range data to digital states over range and under
range. However, interfaces might use Span configuration in other ways. The PI
Server itself does not change out of range data except for tags of type float16.

Step
The Step flag affects only numeric points. It defines how numeric archived values are
interpolated. The default behavior, step OFF (0), treats archived values as a continuous
signal. Adjacent archived values are linearly interpolated. For example, at 12:00:00, the value
101.0 is archived and at 12:01:00, the value 102.0 is archived. A request for the archive value
at 12:00:30 would return 101.5.
A step flag of ON (1) treats the archived values discretely. Adjacent archived values are not
interpolated; an archived value is assumed constant until the next archived value.
For example:
• At 12:00:00, the value 101.0 is archived
• At 12:01:00, the value 102.0 is archived
• A request for the value at 12:00:30 would return 101.0

Note: For points with non-numeric type (digital, string, and timestamp) set the Step
attribute to ON (1). Some plotting algorithms in user applications use the step
attribute to determine trend behavior. Setting Step to ON (1) prevents any
confusion about interpolating non-numeric values.

In general, data coming from continuous signals should be archived in points with the step
flag OFF. Examples might include signals from thermocouples and flow meters. Data
coming from discrete measurements should be archived in points with the step flag on.
Examples are sampled lab data, batch charge weight.
In addition, the step flag affects the compression calculation. When it is ON (1) a linear
change of value greater than or equal to CompDev passes compression. This is essentially the
same as the exception calculation explained above. When the step flag is OFF (0) the
complete swinging-door algorithm is applied.

Tag
The Tag attribute is the name of the point. Each Tag must be unique to a PI System. Since the
tag is the name that identifies the point to users, use a consistent tag-naming convention that
is meaningful to people in your organization. For example, you could reserve the first two
characters of a tag to indicate a unit name or an area of the plant. You could reserve another
six characters to match the standard instrument tag, and so on.
Tags may be any length and can include letters, numbers, and spaces. Tags are subject to the
following constraints:

36
 PI Point Classes and Attributes

• The first character must be alphanumeric, an underscore (_), or a percent sign (%)
• Control characters, such as linefeeds or tabs, are not allowed.
• The following characters are not allowed:
* ' ? ; { } [ ] | \ ` ' "
These characters are allowed, however, in other tag attributes, such as the descriptor.
Any tags that follow the above rules are, technically, allowed. However, be aware that some
legal characters are used by other applications in special ways. For example, SQL uses the
underscore (_) and percent sign (%) as wild cards. Using these characters in tags may cause
problems with these applications.

Note: The PI API functions pipt_tag and pipt_updates truncate the tag to 12
characters. Functions pipt_findpoint, pipt_wildcardsearch, pipt_taglong, and
pipt_tagpreferred report only the first 80 characters.

Case Sensitivity
The system preserves the case of all strings, including the tag, but searches are not case-
sensitive. For example, a string entered as BatchStart is stored exactly as entered. Subsequent
retrievals of this string retain the same capitalization. A search for this string does not require
that the capitalization match.

Changing Tag Names

To change the tag attribute, use the piconfig utility and the NewTag attribute in the
PIPoint table. Keep in mind that when you change a tag, certain programs that retrieve data
using that tag, such as PI DataLink spreadsheets, might also have to be updated. PI
ProcessBook displays automatically use the new tag name.

TypicalValue
The Typical Value is used only to document an example of a reasonable value for this point.
For a numeric tag, it must be greater than or equal to the Zero point attribute, and less than or
equal to the Zero plus the Span point attributes. Some interfaces us e this as an initial or
default value.

Zero
A Zero attribute is required for all numeric data type points to indicate the lowest value
possible. It does not have to be the same as the instrument Zero, but that is usually a logical
choice. Certain interfaces require that the Zero and Span match the instrument system range;
see the interface documentation for details.
The Zero is the bottom of the range used for scaling float16 values in the PI Archive. If the
value for a float16 type point is less than the bottom of range, the value is recorded in the
Archive as the Under range state when the Archive cache is flushed to disk. The Zero is also
used when defining a PI ProcessBook trend with a vertical scale of database.

PI Server System Management Guide 37

Manage Points

This attribut e is not used for non-numeric points.

A tag' s Zero attribute can be changed without affecting data already in the Archive. For
points of type float16, the old Zero is used for retrieving the Archive data collected before
the edit. The new Zero is used for data collected after the edit.

Note: Some interfaces might use Zero information to filter incoming data. These
interfaces often convert out- of-range data to digital states over range and under
range, however, interfaces might use Zero configuration in other ways. The PI
Server itself does not change out of range data except for tags of type float16.

Classic Point Class Attributes

Many OSIsoft interfaces rely on classic attributes. Use the Classic point class for all PI
Interface points if the interface uses the InstrumentTag or location code attributes.

Filtercode
The Filtercode indicates the time constant of a first-order filter used to smooth incoming
data. While it does impact the compressed data, it does not affect exception reporting.
We recommend not altering incoming data by leaving this code at its default value of 0. The
other options are:
Code Time Constant (Seconds)
1 10
2 60
3 120
4 600

Instrument Tag
When a value is retrieved from or sent to an external system such as a DCS, the instrument
tag is used by some interfaces as the tag in the external system. The InstrumentTag field can
be any length. However, most interfaces only use the first 32 characters of this attribute.
Some interfaces use the extended descriptor (ExDesc) instead.

Location1, Location2, Location3, Location4, and Location5

There are five integer location codes. Their meanings depend on the interface. For many PI
Interfaces, you use the Location1 attribute to specify the interface ID number and the
Location4 attribute to assign scan class. For instrument interfaces, the location codes often
describe a hardware or software address for reading or writing the value. See the interface
documentation for details on how to set these point attributes.

38
 PI Point Classes and Attributes

Ranges of ExcMin and CompMax

In early releases of PI Server 3, the values of these two point attributes were stored as
unsigned 16-bit integers, which meant that the maximum value of each was 65,535 seconds.
This continues to be true for existing systems upgraded from PI Server 3.3 or earlier, but
sinc e PI Server 3.4.370.x or later, these attributes can be edited to uint32 type. See Attribute
Sets Database Edit (page 53).
In new installations of PI Server 3.3 or greater releases, the values of these two point
attributes are stored as unsigned 32-bit integers, and the maximum value of each is
4,294,967,295 seconds.
The PI API protocol defines the Exc Min and CompMax attributes as a signed 16-bit integer.
If the PI Server stores a value that is larger than 32,767, the value returned by the PI API is
32,767.
PI SDK applications obtain from the PI Server a signed 32-bit integer values for Exc Min and
CompMax.

SquareRoot
Some interface programs use the square root code. Check the manual for your interface.

Srcptid
Srcptid is the PI point number corresponding to the tag specified in the SourceTag attribute.
If this attribute is edited, PI Server changes SourceTag to the corresponding tag. Do not
directly alter the Srcptid attribute; change SourceTag instead.

UserInt1, UserInt2, UserReal1 and UserReal2

PI reserves these four attributes for user applications. Most PI applications do not use these
attributes. UserInt1 and UserInt2 are 32-bit integers. UserReal1 and UserReal2 are 32-bit
floating-point numbers.

COM Connector Point Attributes

COM Connectors allow the PI Server to obtain data from foreign data systems. To do this,
you must create a special PI Server point whose attributes identify the location of the data in
the foreign system.
The term map is used throughout this manual to mean making a relationship between a point
on the foreign system and a point on the PI Server. During PI Server operation, clients make
requests for data by using PI Server point information. The PI Server then obtains data from
the foreign system point to which the PI Server point is mapped.
For mapped points you must define a point class that includes the following attributes:
Attribute Description
ctr_progid COM Program ID, as stored in the Window s registry. This name is used to
instantiate the COM Connector object.

PI Server System Management Guide 39

Manage Points

Attribute Description
ctr_lm ap Longw ord mapping parameter.
ctr_strm ap String mapping parameter.

A point is identified as a PI Server mapped point if it includes these three attributes.

The ctr_progid is used by the PI Server to load the COM Connector. The mapping
parameters ctr_lmap and ctr_strmap are passed to the COM Connector through a COM
method call so that it can locate the appropriate foreign system point. The usage of these two
attributes is always specified in the manual for any COM Connector.
The PI Server has a script file called classicctr.dif that can be processed by the
piconfig utility to define a point class called classicctr. This point class has all the attributes
of the classic point class plus the three attributes that define mapped points. The
classicctr.dif file can be used directly, or as a template for custom point class
definitions.

Default Values for Point Attributes

When you create a point you must, at a minimum, name the point with the tag attribute. If
you do not assign values to all other attributes, the PI Server uses the default value. The
default values for PI point attributes are:
Point Field Nam e Default Value Lim its
Class
Base Archiving ON ON, OFF, 1, or 0
Base ChangeDate System-assigned
Base Changer System-assigned

Base CompDev 2 eng units

Built-in CompDev Percent Comes from CompDev 0 ≤ x ≤ 100
Base CompMax 28800 sec see System-Assigned Attributes
(page 42)
Base CompMin 0 sec 0 ≤ x ≤ 65535
Base Compressing On ON, OFF, 1, or 0
Classic Convers 1
Base Creationdate System-assigned
Base Creator System-assigned

Built-in DataAccess O:rw g:r w :r Ow ner, group, and w orld may be

assigned read, w rite, or no access
(blank)
Built-in DataGroup piadm ins In PI Identity Database

Built-in DataOw ner piadm ins In PI Identity Database

40
 PI Point Classes and Attributes

Point Field Nam e Default Value Lim its

Class
Built-in DataSecurity piadm in: A(r,w ) | Each identity may be assigned
piadm ins: A(r) | read, w rite, or no access (blank)
PIWorld: A(r)
Base Descriptor blank

Built-in DigitalSet no default Used only for digital tags This must
be specified w hen the point is
created.
Base Display Digits -5 -20 ≤ x ≤ 10

Base EngUnits blank

Base Exc Dev 1 eng units

Built-in Exc Dev Percent Comes from ExcDev 0 ≤ x ≤ 100

Base Exc Max 600 sec see System-Assigned Attributes

(page 42)
Base Exc Min 0 sec 0 ≤ x ≤ 65535

Base Ex Desc blank

Classic Filtercode 0

Classic InstrumentTag blank

Classic Location1 0

Classic Location2 0

Classic Location3 0

Classic Location4 0

Classic Location5 0

Built-in NEWTag

Built-in PointID System-Assigned

Base PointSource Lab

Base PointType Float32

Built-in PtAccess o:rw g:r w :r Ow ner, group, and w orld may be

assigned read, w rite, or no access
(blank)
Built-in PtClassName Base Base, classic, Totalizer, alar m

Built-in PtGroup piadm ins In PI Identity Database

Built-in PtOw ner piadm in In PI Identity Database

PI Server System Management Guide 41

Manage Points

Point Field Nam e Default Value Lim its

Class
Built-in PtSecur ity piadm in: A(r,w ) | Each identity may be assigned
piadm ins: A(r) | read, w rite, or no access (blank)
PIWorld: A(r)
Built-in Rec No System-assigned

Base Scan On ON, OFF, 1, or 0

Base Shutdow n True

Built-in SourceTag blank

Base Span 100 x³0

Classic SquareRoot 0 On, Off, or 0 ≤ x ≤ 10

Classic Srcptid 0

Base Step  OFF for all numer ic

points
 ON for all non-numer ic
points
Base Tag no default This must be specified w hen the
point is created.
Classic Totalcode 0

Base TypicalValue 50 Zero ≤ x ≤ (Zero + Span)

Classic User Int1 0

Classic User Int2 0

Classic User Real1 0

Classic User Real2 0

Base Zero 0

Other The Totalizer Point class includes

other attr ibutes, w hich are
discussed in the PI Ser ver
Applications User Guide.

Note: Programmatic access to some of the attributes may be limited or unavailable from
the PI API.

42
 Exception Reporting and Compression Testing

System-Assigned Attributes

When you create a point, several attributes are assigned by the system. You cannot change
the values of these attributes.

ChangeDate
The date and time when the point was last edited.

Changer
The last user to edit the point.

CreationDate
The date and time when the point was created.

Creator
The user who created the point.

PointID
The Point Identifier is a unique number that identifies the point internally. PointID is never
reused, even when a point is deleted. This is the PI Point Identifier that is passed as a
parameter to most of the PI API functions. In the PI API Manual, this identifier is referred to
as the point number, or PtNum.

RecNo
The record number contains the point's primary record number in the Archive. This is useful
when using tools such as piartool -aw to examine the Archives. RecNo is not to be confused
with the PointID attribut e.

Exception Reporting and Compression Testing

You can tune your PI points for maximum efficiency with the configurable attributes that
specify compression and exception reporting. The configuration of these specifications
impacts the flow of data from the Interface Node to the Server for that point (exception
reporting) and the efficiency of data storage in the Archive for that point (compression
testing).

PI Server System Management Guide 43

Manage Points

In brief, these settings are defined as:

• Exception Reporting: This process filters out noise, and thereby reduces the
communication (I/O) burden between the PI Server and the Interface Node. As networks
have improved and I/O capacity has become less of an issue, some PI System Managers
have essentially turned off exception reporting, by setting the exception deviation to 0.
OSIsoft recommends that you set the exception deviation to slightly smaller than the
precision of the instrument. Exception reporting is a simple linear test that occurs on the
Interface Node.
• Compression Testing: The Snapshot Subsystem performs Compression Testing on the
PI Server to enhance data storage efficiency and thereby conserve disk space. The
Compression Test uses a sophisticated algorithm, called the swinging door compression
algorithm, to determine which events should be stored in the PI Archive. PI Server needs
to store only those events deemed significant by the Compression Test; it can essentially
recreate other events through extrapolation of surrounding events.

Exception Reporting

PI Interfaces use the exception reporting process to evaluate the significance of new events.
The interface sends significant events to the PI Server and discards events that are not
significant. The purpose of exception reporting is to avoid sending changes that are smaller
than the instrument can measure, from the interface to the PI Server.
The interface compares each new value to the previously sent value. The interface sends the
new value to the PI Server only if it is different from the previous value by an amount larger
than the value in the ExcDev attribute.
Exception reporting uses a simple dead band algorithm to determine whether to send events
to PI. For each point, you set exception reporting specifications (the ExcDev, Exc Min and
Exc Min attributes) to create the dead band. The interface ignores values that fall inside the
dead band.
Interface programs that do exception reporting apply the following algorithm rules whenever
a new value is received: A new value is compared to the last value reported; if the new value
does not fall within the dead band, an exception occurs; when an exception occurs, the
interface sends the event (both timestamp and value) that caused the exception and the
previous event to the Snapshot.
The new value is not reported:
• Unless the difference between the new value and the last value is greater than the
exception deviation specification, and the difference between the times of the new and
last values is greater than or equal to the exception minimum time specification.
• Or, the difference between the timestamp of the new value and the timestamp of the last
reported value is greater than or equal to the exception maximum time specification.

Note: The time between exception reports might be greater than the exception maximum
time if no new values are received by the interface for a point. Neither the PI
Server nor the interface will create data.

44
 Exception Reporting and Compression Testing

Some interfaces do not support exception reporting. See the documentation for your interface
to determine whether it supports this capability. Manually entered data is not normally
reported by exception so that every value can be retained.
Most OSIsoft interfaces report new events on exception. The exception algorithm relies on
the following parameters:
• Exception Maximum: Maximum time span between exceptions, expressed in seconds.
This value is configured for each point in the attribute Exc Min.
• Exception Minimum: Minimum time span between exceptions, expressed in seconds.
This value is configured for each point in the attribute Exc Min.
• ExcDev: Dead band when exceeded causes an exception. This is configured for each PI
Point in either the ExcDev or ExcDevPercent attribute.
• OldEvent: Value/status/timestamp of last event sent to the Snapshot; this is the last
event that passed exception report.
• PrevEvent: Value/status/timestamp of last event compared to determine whether or not
to send to the Snapshot.
• NewEvent: Value/status/timestamp of event to test for exception.
Exception reporting works by comparing the new event to the old event as follows.
• If the time new event timestamp and old event timestamp is greater than or equal the
Exc Min, the new event is sent to the Snapshot.
• For digital points, if the new value differs from the old value, the new event is sent to the
Snapshot regardless of Exc Min time.
• For numeric points, if the status changes from good to bad, or bad to good, the new event
is sent to the Snapshot.
• For numeric points, if the time between the old event and the new event is greater than or
equal to ExcMin and the absolute value of the difference between the new value and the
old value is greater than ExcDev, the value is sent to the Snapshot.
• If the new event was sent to the Snapshot, the old event is replaced by the new event.
The last step is a test to see if the PrevEvent should also be sent the Snapshot. If the
PrevEvent was not equivalent to the original OldEvent, the PrevEvent is sent to the
Snapshot. The only time the PrevEvent is not sent to the Snapshot is when two consecutive
exception reports send the new event to the Snapshot. The PrevEvent is used to accurately
indicate what really happened to the value; without it, a step change would look like a ramp
change. Basically, if a measurement holds steady for hours, then makes a step change, just
sending the new value to the Snapshot results in interpolating between the old value and the
new value. By also sending the PrevEvent, the step change is stored.

ExcDev and ExcDevPercent

The ExcDev attribute (Exception Deviation) specifies in engineering units how much a value
may differ from the previous value before it is considered to be a significant value. The
ExcDevPercent attribute specifies the same thing as a percentage of the Span attribute. A

PI Server System Management Guide 45

Manage Points

typical value is 1 percent of Span. The exception deviation should be less than the
compression deviation by at least a factor of 2.
You can set either the ExcDev or the ExcDevPercent attribute. If you change one, the other
is automatically changed to be compatible. If you try to change both at once, ExcDevPercent
takes precedence.

ExcMin
The Exception Minimum attribute, Exc Min, is a dead band after the previous value. This is
used to suppress noise. It is specified in seconds. A new data value that is received before the
end of the Exc Min interval is discarded.

ExcMin
The Exception Maximum attribute, Exc Min, puts a limit on the length of time that values can
be discarded due to exception testing. For example, it is possible for the incoming data to be a
single value for many days. If Exc Min is set to 28800 seconds (8 hours) then a value will
not be discarded due to exception if the previous event timestamp was more than 28800
seconds before that. Note that the interface does not manufacture data. If there are no
incoming values within 28800 seconds, then nothing is passed to the PI Server.

Turning Off Exception Reporting

To turn off exception reporting (that is, to generate an exception for every event), set Exc Min
= 0 and Excmin = 0.

Compression Testing

When a new Snapshot arrives, the previous one is evaluated according to the compression
specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is
discarded. This process is called compression . The point of compression testing is to store
just enough data to accurately reproduce the original signal.
PI uses a sophisticated compression algorithm to determine which events it needs to keep in
order to provide an accurate data history. The compression method used by PI allows PI to
keep orders of magnitude more data online than conventional scanned systems. The data is
also much more detailed than in an archiving system based on averages or periodic samples.
The compression method is called swinging door compression. Swinging door compression
discards values that fall on a line connecting values that are recorded in the Archive. When a
new value is received by the Snapshot Subsystem, a new archive value will be recorded and
the timestamp of that new value will be that of the last snapshot value received before the
latest snapshot value. This value is recorded only if any of the values since the last recorded
value do not fall within the compression deviation blanket. The deviation blanket is a
parallelogram extending between the last recorded value and the new value with a width
equal to twice the compression deviation specification.

46
 Exception Reporting and Compression Testing

Each point has three attributes that comprise the compression specifications : CompDev
(compression deviation), Com pMin (compression minimum time), and CompMax
(compression maximum time). CompDev is the half-width of the deviation blanket (as shown
in the illustration). CompDevPercent is similar to CompDev, but it specifies the
compression deviation in percent of Span rather than in engineering units.
Com pMin and CompMax are limits that refer to the time between events in the Archive. A
new event is not recorded if the time since the last recorded event is less than the compression
minimum time for the point. The Snapshot event is always recorded if the difference between
the time of the most recent Snapshot event is greater than or equal to the compression
maximum time.

Note: The maximum time specification does not guarantee that a value will be written to
the Archive within a certain time. The Archive waits for events to be sent to it. It
does not check to see if a point has timed out. It does not create new values.

You can adjust the compression parameters to produce efficient Archive storage without
losing significant data. The compression maximum time is usually set to one value for all
points in the system. It should be large enough that a point that does not change at all uses
very little Archive space. A compression maximum time of one work shift (for example, 8
hours) is often a good choice.
Use the compression minimum time (Com pMin) to prevent an extremely noisy point from
using a large amount of Archive space. This parameter should be set to 0 for any point
coming from an interface that does exception reporting. In this case, the exception minimum
time should be used to control particularly noisy points. For a data acquisition system with a
slow scan time, this parameter is not important. There are few cases where you want to use a
non-zero compression minimum time.

PI Server System Management Guide 47

Manage Points

The most significant compression parameter is the deviation specification, CompDev. This
parameter is often adjusted after the point is defined. A reasonable starting point is one or two
percent of Span for transmitters and 0.5 to 1.0 degrees for thermocouples. Look at trend
displays to find points for which the reproduction of the data is not acceptable. The goal is to
filter out instrument and process noise and still record significant process changes. The effect
of changing the compression deviation is not predictable.
For digital points, any change is a significant change. Only the compression maximum and
minimum time are important. The compression deviation specification is ignored for digital
points.
There are three instances where an event will bypass the compression process and be put in
the Event Queue:
• If the Compressing attribute for the point is set to OFF.
• If the timestamp is older than the timestamp of the current snapshot. Such an event is
considered out of order.
• If the Status attribute of the Point has changed.

Step Flag
The step attribute setting affects both display and compression.
Data for points with this attribut e set to 1 is assumed to remain fixed between events, whereas
for points with step=0 data is assumed to change linearly between valid numeric events.
The swinging-door compression, explained above, is not used when the step flag is set.
Instead, an exception calculation is applied using the CompDev value. If the absolute
difference between the current Snapshot and the last Archive value is greater than CompDev
then the Snapshot is sent to the Archive.
Compression maximum and minimum limits work the same as for tags with the step flag not
set.

Change PI Point Type

In PI Server 3.4.370 or later, you can edit the type attribute of a point, just as you change
other attributes.
You can use PI SMT, PI Tag Configurator, or piconfig to change point types.
To change a point type in PI SMT:
1. Stop the PI Interface that collects data for the point you plan to change.
2. Open PI SMT.
3. Navigate to Points > Point Builder.
4. Search for and select the point for which you would like to change the type attribute.
5. Use the Point type drop-down to select a point type.
6. Save your changes.

48
 Change PI Point Type

Allowable Point Type Coercions

In order for a point type attribute to be changed successfully, you must change between point
types that can be coerced.
Following is the matrix of allowed type coercions:
int16 int32 float16 float32 float64 digital string blob timestam p
int16 ok ok5 ok ok ok ok N/A N/A

int32 ok1 ok5 ok ok ok3 ok N/A ok

float16 ok1 ok2 ok ok ok3 ok N/A N/A

float32 ok1 ok2 ok5 ok ok3 ok N/A ok

float64 ok1 ok2 ok5 ok ok3 ok N/A ok

digital ok ok ok ok ok ok N/A N/A

string ok ok ok ok ok ok4 N/A ok

blob N/A 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

1.
Assuming values in the range of 0 to 32767
2.
Assuming values in the range of -2,147,450,880 to 2,147,483,647
3
Assuming positive, integer values that are lower than number of digital states
4
Assuming exact, case-insensitive match with a state string
5
Assuming the range of the source is compatible with the range of the target
Not e: When you change point types to int16 or digital, you must enter a value for the Zero
and Span attributes.

Effects on Archives

When you change a point type attribute, the current Archive record is closed and a new
record is open. The new record uses the changed point type attribute.
Point type edits affect how users will see both newly generated data and data that was
previously archived. For this reason, you should consider whether you want to:
• Preserve the original point type in the Archive history, or
• Convert all Archives to reflect the point type change.

Preserve Point Type in Archives

By default, the original point type is preserved in the Archives. That is, the events that were
created and archived prior to the point type edit will reflect the point type that was used
before the point type edit.

PI Server System Management Guide 49

Manage Points

Convert Archives to Reflect Point Type Change

If you want the previously archived data to reflect the new point type, you can reprocess your
Archives off-line to convert the stored events to the new point type. See Manage Archives of
an Offline PI Server (page 85).

Effects on Users

Data from the previous type(s) is coerced to the current type at retrieval time if possible. In
order for a point type attribute to be successfully coerced and subsequently changed, you
must make changes only between point types that are allowed. For details about point type
coercions that are allowed, see Allowable Point Type Coercions (page 49).
If an event in the Archive cannot be coerced to the edited point type, the digital state
Coercion Failed is returned by default. The Coercion Failed digital state acts as a
placeholder for an event that the Snapshot Subsystem failed to coerce. Out-of-order events
may also result in a Coercion Failed digital state.
You can use the parameter Archive_DataCoercionPolicy to translate a digital state, as
appropriate. For details, see Configure Error Handling (page 50).

Valid Point Type Edits

PI Server logs a message in the PI Message Log when you successfully edit a point type. To
successfully edit a point type, the point type must receive Snapshot values that are valid for
the new point type.
If the snapshot value cannot be coerced, the edit fails.
For example, if you change a point type to int16 and the current snapshot has a negative
value, the edit fails and the following error is returned because int16 does not translate
negative values:
[-10005] Subscript Under Range

Configure Error Handling

If the Archive Subsystem cannot coerce a stored point type to an edited point type, values are
replaced as specified by the Archive_DataCoercionPolicy tuning parameter. You can use
the PI SMT Tuning Parameters plug-in to configure this parameter, or use piconfig to
update this parameter in the PI Timeout Table.
An Archive_DataCoercionPolicy parameter can have one of these values:
0 DTC_MarkBad Failed events are returned as DS -315 (“Coercion Failed”)
1 DTC_Leave Original events are returned ( mixed types)

2 DTC_Zero Returned as 0 or blank depending on the type

3 DTC_Hide Hidden (skip that event)

50
 Create, Delete, or Edit PI Point Classes and Attribute Sets

Create, Delete, or Edit PI Point Classes and Attribute Sets

In PI Server version 3.4.370 or later, users can edit and delete both attribute sets and point
classes. The ability to edit point classes enables the following features:
• Attributes Exc Min and CompMax in base attribute set can be edited from uint16 to
uint32.
• It is possible to move a point from one class to another. Data collection can continue for
this point even though the method of collection may change. For example, one may
convert a Totalizer point, which belongs to the Totalizer point class and is populated by
the Totalizer Subsystem, to a Performance Equation point, which belongs to the Classic
point class and is populated by the performance equation scheduler.
• Users can change the attributes of a given point by modifying the attribute sets of the
parent point class. This type of modification applies to all points that belong to the same
point class.
• Adding, removing, editing attributes of a point class are generally motivated by changes
in the data collection methods. These operations have little or no effect on the retention of
history for individual points.
Point attributes can be changed in the following ways:
• Change the point class of a point to another point class that contains the desired
attributes. To do this, change the PtClassName attribute of the selected point.
• Change the point class explicitly by any combination of deleting and adding attribute
sets.
• Change the point class implicitly by modifying existing attribute sets. A modification of
an attribute set triggers a cascade of edits through all point classes that use the attribute
set.
• Both implicit and explicit point class modifications trigger edits of all points belonging to
the modified point class. If modification of all points in a point class is not the intended
effect, change the point classes of individual points instead.

Caution: The modification of attribute sets and point classes can trigger a cascade of
edits through a multitude of points and across a multitude of group and user
boundaries. Do this only if absolutely necessary. Do a backup before you begin.

Required Access Permissions and Other Restrictions

Only the piadmin user or the piadmins group can create, delete or edit attribute sets and
point classes. You must also have read and write permissions on the Point Database
(PIPOINT). The piadmin user always has read/write access to PIPOINT, but if you are using
piadmins, you might need to set the permissions explicitly.

PI Server System Management Guide 51

Manage Points

The following restrictions apply when editing and deleting attribute sets and point classes
(but not when creating them):
• Attribute sets and point classes may be edited or deleted only in standalone mode, in
which PI Net Manager closes the TCP/IP listener and disallows any client connections.
Existing PI SDK, PI API and PI Server Application connections close, and reconnection
attempts are refused for the duration of the standalone mode. Subsystems and locally run
utilities such as piconfig and piartool can connect. Default-only attribute edits are
supported in Normal mode.
The command piartool -standalone on puts the system in standalone mode,
that is, no clients can connect, and piartool -standalone off sets it in normal
operating mode. Use piartool -standalone query to query the system's
current mode.
• You may add attributes to any set, except the Base attribute set.

Note: Any attribute added to a predefined set cannot be removed. The predefined
attribute sets are required by predefined point classes, which cannot be
deleted, so they are always in use. When expanding a point class, we
recommend that you create a new attribute set with new attributes rather than
adding new attributes to a predefined set. For a list of predefined attribute sets
and point classes, see Predefined Point Classes.

• You may delete attributes from any set (only if not in use in any point class) except:
ο required attributes contained in sets predefined in PI Server
ο attributes contained within in-use attribute sets
• You may not rename attributes
• You may rename attribute sets, except predefined attribute sets
• You may delete any attributes sets except:
ο predefined attribute sets
ο in-use attribute sets
• You may add attribute sets to any point class
• You may delete attribute sets from a point class (only if not used by any point) except:
ο required attribute sets contained in predefined point classes; For a list, see Predefined
Point Classes.
ο in-use point classes
• You may rename any point classes, except predefined point classes
• You may delete any point classes, except:
ο predefined point classes
ο in-use point classes
These restrictions protect the attribute sets and point classes that PI system uses as building
blocks. These restrictions can limit the user's ability to easily undo some actions. Always
make a backup of the PI Point Database before attempting to edit attribute sets or point
classes. You can delete attribute sets from predefined point class as long as the class is not in

52
 Create, Delete, or Edit PI Point Classes and Attribute Sets

use and the set to be deleted is not a required set for that point class. Any attribute added to a
predefined attribute set can never be removed.
The piconfig utility can be used to perform these edits and deletes after placing the PI Server
in standalone mode using the piartool utility.

Attribute Sets Database Edit

The sections that follow discuss how to create, delete, and edit the PI Attribute Set database.

Note: Only the piadmin user or the piadmins group can create, delete or edit attribute
sets and point classes. You must also have read and write permissions on the
Point Database (PIPOINT). The piadmin user always has read/write access to
PIPOINT, but if you are using piadmins, you might need to set the permissions
explicitly.

Attribute Set Creation

To create an attribute set, specify the set name, attribute names, types, and default values. If
the type is not specified, float32 is assigned. If a default value is not specified, PI sets the
value. Supported Attribute Types and Defaults (page 53) lists allowed types and defaults.
Types not listed are not supported, and are either rejected at attribute set creation time or have
unexpected behavior.

Supported Attribute Types and Defaults

• String (“”)
• Int16 (0)
• Int32 (0)
• BYTE (0)
• UBYTE (0)
• Uint16 (0)
• Uint32 (0)
• Timestamp (“31-Dec-69 16:00:00”)
• Float32 (0)
• Bool (0)

Note: Boolean values show as either 1 or 0 instead of true or false. All non-zeros are
interpreted as true and 0 is interpreted as false.

PI Server System Management Guide 53

Manage Points

Disallowed Attribute Names

The following attribute names are not allowed in any user-defined attribute set:
Built-in attribute names:
DataAccess CompDev Percent PointID PtOw ner
DataGroup DigitalSet PtAccess PtSecur ity
DataOw ner Excdevpercent PtClassName Rec No
DataSecurity NEWtag PtGroup SourceTag

Reserved names:
Class NEWSET
NEWCLASS Set

Base attribute names:

Archiving Creationdate Exc Min Tag
ChangeDate Creator PointSource TypicalValue
Changer Descriptor PointType Zero
CompDev Display Digits Scan Exc Max
CompMax EngUnits Shutdow n

CompMin Ex Desc Span

Compressing Exc Dev Step

The built-in attributes are added to all points. Users cannot modify their types and defaults.
However, users can modify the default values of non system-assigned attributes, such as
PtSecurity, DataSecurity, PtOwner, PtGroup, PtAccess, DataOwner, DataGroup,
DataAccess, DigitalSet, ExcDevPercent, CompDevPercent, and SourceTag.
OSIsof t creates the base attribute set. See Attribute Set Edit (page 56) for details. Attribute
name checks are case-ins ensitive.

Example: Creating an Attribute Set

Following is an example of how to create an attribute set in piconfig utility. Standalone mode
is not required for creating an attribute set.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
@istru ...
MyAttributeSet
MyAttribute1,BYTE,
MyAttribute2,int32,2
MyAttribute3,string,"Default string"
MyAttribute4,,
@ends
MyAttribute4 is of type float32 and default of 0.0. To list the attribut e set jus t created:

54
 Create, Delete, or Edit PI Point Classes and Attribute Sets

@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttributeSet
@ends
The output will look like:
MyAttributeSet
MyAttribute1,BYTE,0
MyAttribute2,Int32,2
MyAttribute3,String,Default string
MyAttribute4,Float32,0.
* End Repeat...
*----------

Attribute Set Deletion

An attribute set can be removed by simply specifying the set name.
Predefined attribute sets are used as building blocks for PI point classes and may not be
removed from the database. When an attribute set deletion is requested, whether it is a
removable attribute set is checked. If not a removable set, an error is returned. The following
sets are predefined sets and may not be removed.
• Alarmparam
• Base
• Classic
• Sqcalm_parameters
• Totals
If the set to be removed is in use by any point class, an error is returned.

Example: Deleting an Attribute Set

1. Place the system in standalone mode using piartool in a command window.
piartool -standalone on
2. Start piconfig in a command window, and enter:
@table piatrset
@mode delete
@istru set
MyAttributeSet
@ends
3. When finished, place the system back in normal mode:
piartool -standalone off

PI Server System Management Guide 55

Manage Points

Attribute Set Edit

An attribute set can be edited by adding, removing attributes and/or changing attribute types
and default values. Be sure to make a backup before you edit an attribute set.
Edits other than default-only edits require that the system be put in standalone mode by
running piartool utility as follow s:
piartool -standalone on
Use piartool -standalone off to put the system back in Normal mode. Default-only edits do
not require standalone mode.
Default-only edits modify the existing sets directly instead of following the above steps.
Default edit trigge rs implicit point class edits but do not trigge r implicit point edits. This is
because the new defaults are applied only to new points. In the rest of this document, an edit
implies non-default-only edits unless stated otherwise.

Implicit Point Class and Point Edits

When an attribute set is edited, all dependent point classes and points are edited without user
intervention. These edits are known as implicit edits.
With implicit point edits, the existing attribute values are not changed if they 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 attribute's value. Additional attributes are assigned
default values.

Built-in Attributes
Built-in attributes are a part of every PI point, but do not belong to any particular attribute set.
The types and defaults of built-in attributes do not belong to any attribute set explicitly and
cannot be edited.

Base Attributes and Allowed Types

The only Base attribute set edits allowed are the conversion of types of CompMax, ExcMax,
Creator, and Changer attributes from uint16 to uint32 and changes to the default values of
any attributes in this set. All other edits to the Base attribute set are not allowed.

Note: In PI Server versions prior to 3.3, ExcMax and CompMax were type uint16.

Nam e Allowed type

Descriptor String
ExDesc String
TypicalValue float32
EngUnits string
Zero float32
Span float32
PointType ubyte

56
 Create, Delete, or Edit PI Point Classes and Attribute Sets

Nam e Allowed type

PointSource string
Scan byte
ExcMin uint16
ExcMax uint16 or uint32
Excdev float32
shutdow n byte
Archiving byte
Com pressing byte
Step byte
Com pm in uint16
Com pm ax uint16 or uint32
Com pdev float32
Creationdate timestamp
Creator uint16
Changedate timestamp
Changer uint16
DisplayDigits byte

Example: Editing an Attribute Set

If an attribute set is edited, the PI Base Subsystem edits its dependent point classes, and
subsequently dependent points, internally. No explicit editing of the PI point classes database
by a user is necessary. Such indirect edits are referred to as implicit edits.
To illustrate, suppose you want to change a set called MyAttributeSet. First place the sys tem
in standalone mode using piartool:
piartool -standalone on
Then list the existing attributes in the piconfig utility:
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttribSet
@ends
Suppose the attributes and their types and defaults of this attribute set appear as:
MyAttribSet
MyAttrib1,Int32,22
MyAttrib2,BYTE,0
MyAttrib3,Float32,5.

PI Server System Management Guide 57

Manage Points

To change the attribute MyAttrib2 to type String and add another attribute, MyAttrib4 of
type uint16 in piconfig:
@table piatrset
@mode edit
@istru set
@istru attrib,type,default
@istru ...
MyAttribSet
MyAttrib1,int32,22
MyAttrib2,String,default string
MyAttrib3,float32,
MyAttrib4,uint16,1
@ends
Now list the resulting set:
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttribSet
@ends
MyAttribSet
MyAttrib1,Int32,22
MyAttrib2,String,default string
MyAttrib3,Float32,0.
MyAttrib4,Uint16,1
When editing an attribute set, you must explicitly redefine the attribute name, type, and
default. If a pre-existing attribute is not specified in the new definition, it is permanently
removed from the set. If you had not wanted to edit the existing attributes, but only wanted to
add a new attribute MyAttrib4, you would still need to specify all attributes in his definition.
For example:
@table piatrset
@mode edit
@istru set
@istru attrib,type,default
@istru …
MyAttribSet
MyAttrib4,uint16,1
@ends
produces MyAttribSet containing only one attribute, MyAttrib4.
When you edit an attribute set, you must completely specify all the attributes, exactly as on
creation. If an attribute set is edited and its pre-existing attribute name (but not the type and
default) is specified, float32 and value 0.0 is assigned, overwriting the original type and
default. If the user specifies only the type, a new default is assigned even if the type is
identical to the previous one. The default of MyAttrib3 attribute was changed to 0.0 from the
origina l 5.0 because it was not explicitly specified in the edit.

58
 Create, Delete, or Edit PI Point Classes and Attribute Sets

When you are finished with the edit, place the system back in normal mode so that
applications can connect.
piartool -standalone off
Renaming an attribute set does not trigger any implicit edits of point classes or points and
does not require standalone mode.
See Overview (page 51) for attribute set edit restrictions.

Informational Messages
Some messages are not directly returned to the application that initiates the edit, such as
piconfig, but are instead sent to the PI Message subsystem. Examples of these messages are
information regarding the status (success or failure) of the edit steps (rename the old set, add
a new set, implicitly edit dependent point classes and points, and remove the old set) and the
number of dependent point classes found. These messages are useful in verifying that the
steps correctly followed during the edit.

Attribute Set Rename

An attribute set may be renamed via edit unless it is one of the predefined attribute sets. This
rename does not require standalone mode.

Example: Renaming an Attribute Set

In piconfig:
@table piatrset
@mode edit
@istru set,newset
MyAttribSet,MyNewAttribSet
@ends

Point Classes Database Edit

For details on indirect (that is, implicit) edit of PI Point Class Database, see Attribute Set Edit
(page 56). This section explains how to explicitly create, edit, or delete a point class.

Note: Only the piadmin user or the piadmins group can create, delete or edit attribute
sets and point classes. You must also have read and write permissions on the
Point Database (PIPOINT). The piadmin user always has read/write access to
PIPOINT, but if you are using piadmins, you might need to set the permissions
explicitly.

PI Server System Management Guide 59

Manage Points

Point Class Creation

Once a new point class is created, you can start assigning points to this class. Create a point
class using piconfig, specifying which attribute sets to include. This does not require
standalone mode. All point classes must include the base attribute set.

Example: Creating a Point Class

1. At a command prompt, enter:
piartool -standalone on
2. In piconfig:
@table piptcls
@mode delete
@istru class
MyPtClass
@ends
3. To go back to normal mode, enter:
piartool -standalone off

Point Class Deletion

Predefined point classes and in-use point classes cannot be deleted.

Example: Deleting a Point Class

In piconfig:
@table piptcls
@mode create
@istru class
@istru set,...
MyPtClass
Base,MyAttribSet
@ends

Point Class Edit

You can explicitly edit a point class by adding or removing attribute sets that form the point
class.
piconfig version 3.4.370.x or later can display which attribute sets form a point class:
@table piptcls
@ostru class
@ostru set,...
@select class=MyPtClass
@ends
This feature makes it easier to see what attribute sets are being used to form the point class.

60
 Create, Delete, or Edit PI Point Classes and Attribute Sets

Example: Editing a Point Class

A point class list in piconfig shows the following:
* (Ls - ) piconfig> @table piptcls
* (LS - PIPTCLS) piconfig> @mode list
* (Ls - PIPTCLS) piconfig> @ostru class
* (Ls - PIPTCLS) piconfig> @ostru set,...
* (Ls - PIPTCLS) piconfig> @select class=MyPtClass
* (Ls - PIPTCLS) piconfig> @ends
MyPtClass
base,classic
*----------
1. Add the attributes MyAttribute1 (string) and MyAttribute2 (int32) to this point class.
To do this, create an attribute set, MyAttributeSet, as follows.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
@istru ...
MyAttributeSet
MyAttribute1,string,my default string
MyAttribute2,int32,22
2. Check that the attribute was correctly created:
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttributeSet
@ends
You should see:
MyAttributeSet
MyAttribute1,String,my default string
MyAttribute2,Int32,22
* End Repeat...
*----------
3. Edit MyPtClass to include this attribute set. The system must be in standalone mode.
Enter at a command prompt:
piartool -standalone on
4. In piconfig, define the attribute sets that should belong to the point class:
@table piptcls
@mode edit
@istru class
@istru set,...
MyPtClass
base,classic,MyAttributeSet
5. Check that these attributes now form MyPtClass.
* (Ed - PIPTCLS) piconfig> @mode list

PI Server System Management Guide 61

Manage Points

* (Ls - PIPTCLS) piconfig> @ostru class

* (Ls - PIPTCLS) piconfig> @ostru set,...
* (Ls - PIPTCLS) piconfig> @select class=MyPtClass
* (Ls - PIPTCLS) piconfig> @ends
You should see:
MyPtClass
base,classic,MyAttributeSet
*----------
6. To see all attributes that are in this point class, enter:
@table pipoint
@ptclass MyPtClass
@?atr
The following list appears:
1 - Tag String D: !#!#!# C:
2 - NEWTag String D: C:
3 - archiving BYTE D: 1 C:
4 - changedate TimeSta D: 31-Dec-69 16:00:00 C:
5 - changer Uint16 D: 0 C:
6 - compdev Float32 D: 2. C:
7 - Compdevpercent Float32 D: 2 C:
8 - CompMax Uint32 D: 28800 C:
9 - CompMin Uint16 D: 0 C:
10 - compressing BYTE D: 1 C:
11 - convers Float32 D: 1. C:
12 - creationdate TimeSta D: 31-Dec-69 16:00:00 C:
13 - creator Uint16 D: 0 C:
14 - DataAccess String D: o:rw g:r w:r C:
15 - DataGroup String D: piadmin C:
16 - DataOwner String D: piadmin C:
17 - datasecurity String D: piadmin: A(r,w) | piadmins (r) |
PIWorld (r) C:
18 - descriptor String D: C:
19 - DigitalSet String D: system C:
20 - displaydigits BYTE D: -5 C:
21 - engunits String D: C:
22 - excdev Float32 D: 1. C:
23 - Excdevpercent Float32 D: 1 C:
24 - ExcMin Uint32 D: 600 C:
25 - excmin Uint16 D: 0 C:
26 - exdesc String D: C:
27 - filtercode Int16 D: 0 C:
28 - instrumenttag String D: C:
29 - location1 Int32 D: 0 C:
30 - location2 Int32 D: 0 C:
31 - location3 Int32 D: 0 C:
32 - location4 Int32 D: 0 C:
33 - location5 Int32 D: 0 C:
34 - myattribute1 String D: my default string C:
35 - myattribute2 Int32 D: 22 C:
36 - PointID Int32 D: 0 C:
37 - pointsource String D: Lab C:
38 - pointtype String D: Float32 C:

62
 Create, Delete, or Edit PI Point Classes and Attribute Sets

39 - PtAccess String D: o:rw g:r w:r C:

40 - PtClassName String D: MyPtClass C:
41 - PtGroup String D: piadmin C:
42 - PtOwner String D: piadmin C:
43 - ptsecurity String D: piadmin: A(r,w) | piadmins (r) |
PIWorld (r) C:
44 - Recno Int32 D: 1 C:
45 - scan BYTE D: 1 C:
46 - shutdown BYTE D: 1 C:
47 - SourceTag String D: C:
48 - span Float32 D: 100. C:
49 - squareroot Int16 D: 0 C:
50 - srcptid Int32 D: 0 C:
51 - step BYTE D: 0 C:
52 - totalcode Int16 D: 0 C:
53 - typicalvalue Float32 D: 50. C:
54 - userint1 Int32 D: 0 C:
55 - userint2 Int32 D: 0 C:
56 - userreal1 Float32 D: 0. C:
57 - userreal2 Float32 D: 0. C:
58 - zero Float32 D: 0. C:
7. Place the system back in normal mode:
piartool -standalone off

Restrictions on Attribute Set Edit

Some notes on point class edits are:
• All point classes contain the base attribute set.
• Any attribute set can be added to a point class.
• Attribute sets cannot be deleted from point classes that are in use.
• Required attribute sets cannot be deleted from predefined point classes even if they are
not in use.
• Predefined classes cannot be renamed.
• Renaming a point class does not trigger any implicit edits of points.

Informational Messages
Some messages are not directly returned to the user but are instead are sent to the PI Message
Subsystem. Examples of such messages are information regarding the status of the 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.

Point Class Rename

A point class may be renamed by an edit unless it is one of the pre-defined point classes. This
rename does not require standalone mode.

PI Server System Management Guide 63

Manage Points

Example: Renaming a Point Class

In piconfig:
@table piptcls
@mode edit
@istru class,newclass
MyPointClass,MyNewPointClass
@ends

Editing a Point's Point Class

You can change the point class of a PI point. As in the case of implicitly edited point, the
attributes of the point are rebuilt. The important difference is that unlike in an implicit point
edit, some existing attributes may be removed because a point class edit does not allow
removing any attributes if there are any dependent points. This prevents points from
inadvertently losing existing attributes. However, if a user deliberately moves a point from
one class to another and the new point class does not contain some of this point's current
attributes, they are deleted without prompting.
When you change a point's point class, any new attributes are added and set to default values.
Attributes that do not belong to the new point class are removed. Existing attributes are
copied if they are in the new point class. Compatible types retain their values and
incompatible types are set to new default values.
When editing a point with piconfig, new attributes can be modified simultaneously. That is, it
is acceptable to edit the PtClassName attribute and include new attributes that only belong to
the new point class and did not previously belong to the point's old class. However, the target
class must be set before such an edit is attempted.
To illustrate, try editing a point that belongs to Totalizer point class to Classic point class in
piconfig as follow s:
@table pinpoint
@ptclass Totalizer
@mode edit
@istru tag,ptclassname,location4,pointsource
The following error is returned:
*piconfig Err> Unknown parameter <location4> in structure
*@istru tag,ptclassname,location4,pointsource
*piconfig Err> Complete Structure line removed
*@istru tag,ptclassname,location4,pointsource
This is because @ptclass Totalizer sets the environment for this edit to Totalizer point
class, which does not have the location4 attribute. If you want to edit the PtClassName
attribute and new attributes unique to the target point class at the same time, set the
environment to the target point class, Classic, by using @ptclass Classic first:
@ptclass classic
@istru tag,ptclassname,location4,pointsource
tagname,classic,1,C
If it is not necessary to edit the PtClassName attribute and new attributes at the same time,
issuing:

64
 Digital State Sets

@ptclass classic
is not necessary since PtClassName is a built-in attribute and every point has this attribute.
Point class of a point can be edited using piconfig in PI Server 3.4.370 or later.

Converting Com Connector Classes to and from Native PI Classes

Special handling is required in case of a native PI point's PtClassName edit to a COM
Connector point class or vice versa. The difficulty arises from the fact that in order to allow
transparent retrieval of data for a point that has some data in a foreign database and some in
PI Archive, the PI System must be aware of the cutoff times and go to the correct source. The
possibility that the conversion may occur multiple times adds to the complexity.
History of the conversions is ignored and a data request is directed to the current data source.

Point Database Audit

Both Attribute Sets and Point Classes are included in the Audit Database. The EnableAudit
parameter in the PI Timeout Table bit (which starts from 0) is used for Attribute Sets Audit
Database and bit 4 for Point Classes Audit Database.
Datab ase Bit Value to Enable (decim al)
Point DB 0 1
Attribute Sets DB 2 4
Point Classes DB 4 16

Use the AuditViewer tool to work with the Audit Database. See the AuditViewer help and
Audit the PI Server for more details.

Digital State Sets

A digital state set has a name and consists of a list of states, sometimes called digital state
strings. For example, we can define the digital state set Valve-state-set as containing the two
states OPEN and CLOSE. You can use the default set or you can define your own digital
state.

Digital State Name Conventions

When you use or define digital states, it is important to know that:

• Digital state names are not case-sensitive. If you define a state with all capital letters,
such as OFF, any later references to that state are not case-sensitive. That is, either off or
Off are valid references to the state named OFF.
• Leading and trailing blanks are removed from state names.

PI Server System Management Guide 65

Manage Points

Default Set: Syste m State Set

The default set is called the System digital state set and contains over 300 digital states that
may apply to any point. A sample of pre-defined digital states that represent typical system
states are as follows:
State Description

I/O Tim eout Interfaces use this state to indicate that communication w ith a remote device has
failed.
No Data Data-retrieval functions use this state for time per iods w here no archive values
for a tag can exist 10 m inutes into the future or before the oldest mounted
archive.
Under For float16 point types, this state indicates a value that is less than the zero for
Range the tag.
Over Range For float16 point types, this state indicates a value that is greater than the top of
range ( Zero+Span) for that tag.
Pt Created This state is assigned to a tag w hen it is created. This is a tag's value before any
value is entered into the system.
Shutdow n All tags that are configured to receive shutdow n events are set to this state on
system shutdow n.
Arc Off-line Used by data-retrieval functions to indicate a period of time not covered by any
mounted archive.
Bad Input Interfaces use this state to indicate that a device is reporting bad status.

Note: The last possible state in the System digital state set is number 16383. It is
reserved for internal PI Server use. OSIsoft recommends that you keep changes
to the System digital state set to a minimum. At most, you can translate the states
into another language without changing their meaning. Digital points should use a
user-defined digital set, not the System digital state set.

Define a Digital State Set

You can define digital state sets with the PI System Management Tools (PI SMT) or
piconfig. For digital points, there are typically only a small number of valid states. Before
you can configure a digital point, you need to define the digital state set that it will use.
For example, you can configure a point to use an instrument system that reports a valve
position as having a digital code value of 0 or 1 and assigns the value 0 to a state of
CLOSED and the value 1 to a state of OPEN.
Before you configure this point, you must first establish a digital state set with two strings,
CLOSED and OPEN. You might name it Valve Position. You could also define other points
that also have CLOSED and OPEN states to use the same Valve Position digital state set.
Points that have states of ON and OFF would use a different digital state set, which you
could call Switch Position.

66
 Digital State Sets

The digital code value, that is 0 or 1, is determined by the PI Server according to the position
of the digital state string in the Digital State Table. The first value is 0, the second is 1; the
third is 2, and so on. The position in the set is termed digcode in PI API.
When retrieving state strings, PI API returns a maximum of 79 characters.

Note: There is no need to include system states in custom digital sets because the
system states contained in the System State Set is used where needed by the PI
Server. You may define up to 16383 state sets with up to 16383 states in each
set. For details, see System State Set for All Points (page 66).

PI Server System Management Guide 67

Chapter 4

Manage Archives
PI Archive management includes significant tasks. Most of these tasks can be performed in
SMT, however there are still a few tasks (such as performing an archive walk or backfilling
data) that require command-line utilities. This chapter explains how to perform tasks in SMT,
wherever possible and provides command-line instructions where necessary. For complete
information on using command-line tools for managing archives, see the PI Server Reference
Guide.

About Archives
PI Archives are the files that the PI System uses to store PI Data. Each Archive file contains
events for a time period specified by the Archive start time and end time. Archive files range
in size from 2 MB to 2 terabytes (2,048 GB).
Archive files can be either fixed or dynamic. Fixed Archive files are always the same size,
regardless of how much data they contain. Dynamic Archive files grow in size as they get
data. See About Fixed and Dynamic Archives (page 72) for details.

Tools to Manage Archives

SMT provides two tools for working with Archives:

• The Archive Editor: This tool is for working with the data in PI Archives. Use the
Archive Editor to view, edit, insert, and delete values for PI point events in a PI Archive.
To open the Archive Editor, select Data > Archive Editor in SMT.
• The Archives tool: The Archives tool allows users to administer PI Archive files and
manage how the PI Server uses Archive files. To edit the data contained in the Archive
files, use the Archives tool (Archive Editor). To open the Archives tool, select Operation
> Archives in SMT.
The three command-line tools you will use most often to manage PI Archives are:
• piartool: Use this utility for most archive management tasks including: create, register
and unregister archives; force archive shifts; list details of archive files; and much more.
You can use piartool only when the PI Server is running. For a complete list of the
parameters for piartool, enter piartool ? in the PI\adm directory to refer to the
piartool Help, or see Use Other PI Archive Utility Parameters.
• piarcreate: Use the piarcreate utility to create new archives.
•

PI Server System Management Guide 69

Manage Archives

piarchss: The Archive Subsystem, piarchss, includes an Offline Archive Utility. You
use this utility to process existing offline archives. Among the tasks you use piarchss for
are: to combine multiple archives into one; to divide large archives into multiple
archives; to recover corrupted archives, and so on.

About Archive Shifts

The Archive receiving current data is called the primary Archive. When the primary Archive
becomes full, an Archive shift occurs and the next available Archive becomes the new
primary Archive.
PI performs an Archive shift before the primary Archive is completely full. As a result, the
Archive contains some extra space so that, if necessary, you may add data later. For an
Archive file to be eligible to be the new primary Archive, it must be registered, writable, and
large enough to handle the current size of the Point Database. When an Archive file is
registered, it is visible to the PI Server and indirectly to its client applications. See Register an
Archive and Choose an Archive Size (page 76) for more details.

If no eligible Archives are available for an Archive shift, PI us es the oldest available filled
Archive as the new primary Archive and, in the process, overwrites the data in the old
archive. For example, in the preceding illustration there are no empty registered Archives left
on the Server after the shift from piarch.003 to piarch.004. If the system manager
does not create new Archives on this PI Server, Filled Archive: piarch.001 becomes the
next primary Archive and the PI Server overwrites the existing data in that Archive.
It takes PI a few minutes to complete an Archive shift. During that time, you are not allowed
to add, edit or delete points. PI stores incoming data in the event queue until the shift is
complete and then writes the queued events into the new primary Archive.

70
 About Archives

About Archive Gaps

Archive gaps are times for which no Archive file is registered. If an event is sent to the
Archive and no Archive file is registered within the appropriate time range, the event is
discarded and an error is logged. If data retrieval is attempted for a time range that overlaps
with a gap, the returned data inc lude s a digital state Arc Offline that indicates the
beginning of the gap. This prevents values from being interpolated when data is missing.

About Archive Records

PI Archives store events as data records. Data records are either primary records or overflow
records. Each point in the Point Database has one primary record allocated in every archive
file. Primary records are stored at the very beginning of the Archive file. When the primary
record for a point fills up, the data for that event goes to an overflow record in the Archive
file. Overflow records start at the end of the Archive file and are filled backwards. Each
record is one kilobyte.

A point can have as many overflow records as needed. Points that receive events at a slow
rate might never need to allocate an overflow record, whereas points that receive events at a
fast rate might need to allocate many overflow records. The PI System uses index records to
keep track of multiple overflow data records for a point.

Note: When the Archive allocates a new overflow record for a point, it immediately writes
to disk both the new record and any existing records that reference the new
record.

About Index Records

Index records are records that index the overflow data of a point by time. After one overflow
record for a point is full, PI creates an index record for that point and a new overflow record.
An index record can hold between 150 and 160 record points. When the index record is full,
PI creates a second index record and these index records are linked. Archive data retrieval for
points with chains of index records are marginally slower than for points with zero or one
index records.

PI Server System Management Guide 71

Manage Archives

About Primary Archives

The primary Archive is the Archive file that covers the current time range. For the duration of
time that its state is the primary Archive, it has a defined start time but no defined end time.
The end time is always assumed to be now.
The end time for the primary Archive is redefined when an Archive shift occurs. An Archive
shift is the process of replacing the primary Archive with a new or cleared Archive. The time
of the shift becomes the end time and that archive is no longer the primary Archive.
If registered, an empty Archive is selected to be the new primary Archive. If no empty
archive is registered, then the oldest archive becomes the primary Archive and its existing
data is overwritten.
You may also set up automatic Archive creation using the
Archive_AutoArchiveFileRoot Tuning parameter; if this is in effect, a new Archive
with the same characteristics as the current primary Archive is created during the shift. For
details on how to set up automatic Archive creation, see the SMT help files or Intro to PI
Server System Management.
The PI Server ensures that some space is still available at the time of the shift. This way, out-
of-order events can still be stored in the Archive after it is no longer the primary Archive. For
more information, see Manage Archive Shifts (page 82).

About Fixed and Dynamic Archives

There are two types of Archive files, fixed and dynamic.

Fixed Archives
Use fixed Archives for all normal operations. Fixed Archives:
• Have all of their disk space allocated at creation time. An empty Archive and a full
Archive take the same amount of disk space.
• May or may not participate in Archive shifts, depending on the point count-to-Archive
size ratio and the state of the shift and write flags.
• May have new points added, if the fixed archive is the primary archive.

Note: As of version 3.4.375, fixed-sized archives will become dynamic whenever they
are full if there is sufficient disk space. A fixed-sized archive that has become
dynamic will remain shiftable. When the changed archive becomes primary, it will
convert back to fixed-sized. The allocated disk space for archives will not be
modified. For details, see If Fixed Archives Are Full (page 73).

The default Archives that are installed with a PI Server are fixed Archives.

72
 About Archives

Dynamic Archives
Dynamic Archives:
• Cover a specific time range.
• Are not eligible for Archive shift if they already contain data. Newly created dynamic
Archives participate in the standard shift algorithm.
• Do not contain unallocated space waiting to be used for overflow records. Rather, the file
grows as overflow records are added. You must specify a maximum Archive size when
you create a dynamic Archive. Dynamic Archives grow as they are filled, up to the
specified maximum size, or maxsize, but no larger than 2 terabytes.
• Are initialized with a fixed number of primary point records. Once a dynamic Archive is
created, the number of primary records cannot grow beyond the initial allocation, even if
there is space in the file.

Note: You can create dynamic Archives with a number of primary records higher than
the current number of points. This allows users to create additional points in a
dynamic primary Archive. Users can add new points as long as the number of
points does not exceed the number of primary records allocated when you created
the dynamic Archive. See Example: Create a Dynamic Archive for details.

When to Use Dynamic Archives

Dynamic Archives make archive sizes flexible, thereby enabling disk space to be allocated
only as needed. For example, if you want to combine data from two old Archives into a single
archive file, you would run the Offline Archive Utility twice: once to copy data from the
earlier Archive and again to add data from the second Archive. The resulting dynamic
Archive contains data from the two input Archives and has no free records. As a result, the
new Archive is potentially smaller than the combined size of the input archives and able to
accommodate additional data as long as the maximum growth size is not exceeded. For
details on this example, see Combine and Divide Archives (page 88).

Caution: You must consistently monitor disk space usage to ensure that you have
adequate disk space for new Archives. If you run out of disk space, you risk data
loss.

If Fixed Archives Are Full

It is possible for a fixed Archive to get completely filled up. Once an Archive is full,
incoming data events for that time range have nowhere to go. This can occur if a much larger
than usual quantity of data is sent to the primary Archive and confuses the attempt to predict
the shift based on event rates. It can also happen when old data is sent to an Archive that is
already full.
If such a condition occurs, the Archive subsystem attempts to convert this fixed archive into a
dynamic Archive to prevent data loss. This means that the file size is extended and additional

PI Server System Management Guide 73

Manage Archives

overflow records are appended at the end. If the Archive that was filled is the primary, an
Archive shift is also scheduled immediately. This arrangement allows all the incoming events
to be stored so there is no data loss. The fixed Archive that was converted is marked as non-
shiftable, like all non -empty dynamic Archives. As a result, some additional management
may be required. For example, you may need to register a new empty Archive for the next
shift or reprocess the converted Archive to fit a certain size. Converted Archives are clearly
marked as a different type on Archive displays such as piartool -al.

Note: To prevent the automatic conversion of full fixed archives to dynamic archives, set
the Archive_Enable_AutoDynamic parameter to 0. To update this the parameter in
SMT, use the Archive Tab in the Tuning Parameters tool.

About Read-Only Archives

Archive files that have a read-only file-system attribute, or files on a read-only device (CD
ROM) are mounted as read-only. Their status will show up on the piartool -al display as not
writable. Read-only files cannot participate in Archive shifts.
New events in the time range of such an Archive go into the Archive cache, but when flushed
to disk, an error message is logged for each event. This includes attempts to edit, delete or
annotate events in a read-only archive.

About Annotations

Every value in the Snapshot or the Archive may be annotated. An annotation can be of any
data type. Annotations are stored in an Annotation file. Each Archive file has a single
associated Annotation file, with an .ann extension. The Annotation file is created if it does
not exist. It is important the Archive and Annotation files remain together, especially when a
backed up Archive file is restored.
You can view, add, and edit annotations using the SMT Archive Editor. To open the
Archive Editor, select Data > Archive Editor in the PI Server System Management Tools
pane.

Note: Any operation on annotation translates into an actual I/O, bypassing Archive
caching. Thus it is much less efficient than non-annotated events. Be aware of this
when using annotations.

Create a New Archive in SMT

To create a new Archive file in SMT, use the Archives tool (Operation > Archives):
1. Select an Archive from the target PI Server from the list and click the Create Archive
button , or right-click the Archive and choose Create New.
The Create a New Archive dialog box appears.

74
 Create a New Archive in SMT

2. Click the browse button to change the Archive path, if desired.

You can store an Archive in any local or network directory accessible by the PI Server.
Local storage with other Archives provides the most reliable option for using and
managing Archives.
3. Enter a name for the file in the Archive name field, or accept the chronologically-
numbered default name.
If the text field is yellow, then the Archive name is already in use by another file,
possibly an unregistered Archive. You may want to cancel the procedure and use the
existing Archive, if empty.
4. Select a source option to create the Archive:
ο Select Clone primary Archive fixed size to create a new, empty Archive of Fixed
type, based on the size of the current primary Archive. A Dynamic Archive may also
be used, but is not recommended.
This option is not available if the current primary Archive is not of Fixed type.
ο Select Create Archive larger than current primary to create a new, empty Archive
larger than the current primary Archive, and use the accompanying filed to specify
the desired size in megabytes (MB).
The size must be equal to or greater than the size of the current primary Archive, up
to a maximum of 2 terabytes (TB) for PI Servers 3.4 and later, and 1 GB (1024 MB)
for PI Servers prior to 3.4.
ο Select Create Archive with fixed start and end time to create a new, empty
Archive to be used only for a specified time period.
Choose the Type of Archive to create, either a Fixed Archive with size equal to the
current primary Archive, or a Dynamic Archive.
Enter Start time and End time in the provided fields using PI time format. A yellow
background indicates that a timestamp was entered in a format that is not recognized
by PI Server.

Note: Start and end times must not overlap an existing Archive.

5. Click OK to close the dialog box and create the Archive.

The Archives tool attempts to register the newly created Archive automatically. If the
register succeeds, the new Archive appears in the Archive list.

Archive Names

To name PI Archives, you must use a naming convention that is valid for the underlying
operating system and the file location must have sufficient disk space. There are no other
limitations to name PI Archives.
The default archive file names are piarch.xxx, where xxx is 001, 002, 003 and so on.
The associated annotation file has the same full path name as its archive file with .ann
appended. For example, the annotation file for the piarch.001 archive file would be
piarch.001.ann.

PI Server System Management Guide 75

Manage Archives

Choose an Archive Size

Archive files can have a fixed size or can be configured to grow dynamically as they receive
more data. The archive size affects backups, frequency of shifting, and total number of points
allowed.
Apply these guidelines to determine the minimum and maximum size for your PI Archives:
• Minimum Archive Size: Double the number of points and divide the result by 1000 to
calculate the minimum Archive size, in MB. For example, to allow for 20,000 configured
points, the minimum archive size is:
(20,000 x 2) / 1000 = 40 MB
• Maximum archive size: 2 terabytes (2000 GB).
The minimum file size is 1 MB or the current point count multiplied by 1024, whichever is
highe st. The maximum file size is 2,096,128 MB, that is, approximately 2 terabytes.

Archive Size and Shift Frequency

The larger the PI Server archive files, the less frequently Archive shifts will occur. To decide
what archive size is optimal for your system, consider that the following factors will
determine shift frequency:
• the backup device
• available disk space
• average incoming data rate

Archive Size and Point Count Limits

It is important to note that the archive size limits the number of points that may be created.
No more than half of the archive records of a fixed archive can be primary records. If the
allotment of primary records is used and you try to create an additional point, although the
primary archive is not full, you will get the error:
PI_AR_ARCHIVEFULL = -11053, /* no more available records in this archive */
To resolve this, use the command piartool -fs to force the archives to shift into a larger
archive before creating additional points. See Force Archive Shifts for details.

Set the Maximum Archive Size

A dynamic archive will not grow larger than maxsize. In most cases, the parameter
maxsize is set to equal the maximum size of the Primary Archive in MB; but such a
maxsize setting is not required.

76
 Create a New Archive in SMT

To set the maximum Archive size, use piarcreate or piartool. For example:
piarcreate -acd D:\PI\dat\piarch.115 2000 20000
Attempting to create a 0 Mbyte fixed archive file: -acd
Initializing archive file: -acd
Archive -acd is prepared to be registered.

Set the Number of Points in the Archive

This number, specified by the maxpoints parameter, determines the maximum number of
points that can be created. To find the current number of points, enter piartool -ss to list the
snapshot status. The maximum number of archive points should be at least the current
number and greater if you expect to create new points.
Use the piarcreate tool to change the maxpoints parameter:
G:\pi\adm>piarcreate -?
Usage: piarcreate -v
piarcreate -d path maxpoints maxsize(Mb)
piarcreate path size(Mb)
The following listing is for a 2048 MB archive; the maximum number of configurable points
for the archive is 1,048,576 (half the total number of records).
D:\PI\adm>piartool -al
Archive shift prediction:
Shift Time: 5-Oct-05 19:42:01
Target Archive: e:\pi\arc\piarch-2GB.1
Archive[0]: e:\pi\arc\piarch-2GB.3 (Used: 53.4%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: e:\pi\arc\piarch-2GB.3
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2097152 Add Rate/Hour: 154207.3
Offsets: Primary: 253063/1048576 Overflow: 1231270/2097152
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 5-Oct-05 06:11:09
End Time: Current Time
Backup Time: Never
Last Modified: 5-Oct-05 13:26:21

Estimate Archive Utilization

You must allocate the space to be used by a fixed archive when you create it. Use piartool -al
to list the registered archives. For each archive an estimate of the used space is displayed. See
the entry Record Size: in each Archive record. For details, see List Registered
Archives.

Note: The default archives are sized at the time of installation when the installer answers
prompts from the installation wizard.

PI Server System Management Guide 77

Manage Archives

Register and Unregister Archives

The PI Server Archive Registry contains the name, location, size, count of records, and
record size for each archive file. This information is stored in the binary file,
PI\dat\piarstat.dat. In order to for an archive to be shiftable, it must be registered.
Once an archive is registered it is available to the system and participates in shifts and storage
and retrieval of event data.

Register an Archive

To register an existing Archive for use with a particular server, use the Archives tool
(Operation > Archives):
1. Select the Archive in list view and click the Register Archive button on the toolbar, or
right-click and choose Register Archive.
2. Browse to the Archive file you want to register and click Open. The list of Archives is
refreshed. Be sure to verify that the register succeeded and that the Archive is in the list.

Unregister an Archive

To un-register an Archive from a particular server, taking it out of the queue, use the
Archives tool (Operation > Archives):
1. Select the Archive in the list and click the Unregister Archive button on the toolbar, or
right-click and choose Unregister Archive.
A dialog box prompts you to confirm before un-registering the Archive.
2. Click Yes to un-register the Archive, or No to cancel the operation.

Note: If the PI Server is not on the local machine, this feature requires the PI Server's
piadmin password.

Bulk Operations

To register or unregister archives in bulk, you need to use the piartool utility. With this
utility, you can use the wildcard characters * and ? to perform bulk operations. The symbol *
matches all possibilities with any number of characters. The symbol ? matches a single
character and may be used any number of times.

78
 Edit Archives

Register in Bulk
To register archives, you use the piartool -ar command. The syntax is:
piartool -ar path
For example, the following command registers the archive called piarch.006 in the
PI\dat directory on the D drive:
piartool -ar D:\PI\dat\piarch.006
The specified path must be a complete, not relative, path of an existing archive file. You can
use the wildcard characters * and ? to register archives in bulk. The symbol * matches all
possibilities with any number of characters. The symbol ? matches a single character and may
be used any number of times.
For example, the following command registers all archive files in the PI\dat directory that
begin with the piarch.0 prefix:
piartool -ar D:\PI\dat\piarch.0*

Unregister in Bulk
To unregister an archive, use the piartool -au command. The syntax is:
piartool -au path
where path specifies a complete, not relative, pathname. For example, the following
command unregisters the archive called piarch.006 in the PI\dat directory on the D
drive:
piartool -au D:\PI\dat\piarch.006
You can use the wildcard characters * and ? to unregister archives in bulk. The symbol *
matches all possibilities with any number of characters. The symbol ? matches a single
character and may be used any number of times. For example, the following command
unregisters all archive files that begin with the piarch.0 prefix and are located in the
PI\dat directory:
piartool -au D:\PI\dat\piarch.0*

Edit Archives

Note: All archive edits are first handled by the Snapshot Subsystem. The Snapshot
Subsystem performs some security and data checks then, if appropriate, forwards
the edit events to the Archive Subsystem.

For large scale changes and repair use the Offline Archive Utility (piarchss). For example,
inadvertently moving the computer system clock ahead may cause considerable problems.
You can configure a time limit on insertion and editing of events. The Snapshot rejects events
with timestamps earlier than the limit. By default there is no limit, which is consistent with
earlier versions of PI.

PI Server System Management Guide 79

Manage Archives

To configure a time limit on insertions and event edits, add an entry to the PITimeout table:
EditDays, nnn
where nnn is the number of days (prior to current time) in which changes and additions are
allowed. The Snapshot Subsystem must be restarted for the changes to take effect. To add the
Tuning parameter, you can use the SMT Tuning Parameters tool (Operation > Tuning
Parameters).

Delete an Archive
You must first unregister an archive before you can delete it. Use the Archives tool
(Operation > Archives) in SMT to delete the archive. Then delete the related annotation file.

Display an Unregistered Archive

To display an un-registered Archive in the list, so that it can be registered and used:
1. Select an Archive from that server in the list and click the Unregistered Archive button
on the toolbar, or right-click and choose Display Unregistered Archive.
2. Browse to and select the unregistered Archive file on the server, and click Open. The
unregistered Archive is added to list view with an unregistered Archive icon and State
Dismounted.

Make Writeable/Read-only
To change the protective Write flag for an Archive, right-click the Archive in list view, and:
• choose Make Read-Only to make a writable Archive read-only.
• choose Make Writeable to make a read-only Archive writeable.

Note: Primary Archives may not be set to read only.

Move an Archive
To move an archive you must unregister it, move it to a new directory, and then re-register it.
Remember to move the associated annotation file as well. Moving the primary archive
requires some additional steps, since you cannot unregister it while the PI archive process is
running.
To move the primary archive:
1. Unregister it.

80
 Backup Archives

2. If any empty archives exist in the original directory, move them to the new directory and
register them there. One of these archives will become the new primary archive.
3. Verify that there is at least one empty archive registered in the new directory. Create one
if it does not exist. See Create a New Primary Archive for details.
4. Force an archive shift. This results in a new primary archive, which is one of the empty
archives in the new directory.
5. Move the previous primary archive to the new directory by the usual method: unregister
it, copy it to the new directory, and then reregister it.

Note: It is not generally necessary to rename archive files. If you do, remember to
rename the annotation file as well. Check the release notes for a description of
issues associated with archive file renaming.

Backup Archives
You can use the SMT Archive tool to backup an Archive and its corresponding annotation
file for PI Server versions 3.4.370, or earlier:
1. Select the Archive to back up in the list, and click the Backup button , or right-click
and choose Backup.
2. Browse to the desired backup directory, and enter a new file name or select an existing
backup file, then click Save.

Note: Backups may be created only for local PI Servers, version 3.4.370 or earlier. The
backup process differs for later versions. See Back up the PI Server (page 97).

Note on Digital State Reprocessing

Digital states are stored in the archives as offsets in a digital state set. The digital state set
number is registered in every archive record of a digital point. System digital states can
appear in any record.
When an archive is reprocessed these offsets are preserved, but the digital set becomes the
current digital set of the point. This can cause confusion when the digital state of a point was
changed. For example, if data is stored for a point with a set of On, Off this data amounts to 0
and 1. Later the point is changed to use a set with Open, Close. When reprocessed, the old
data displays as Open and Close. This might be a desired behavior in some cases and
confusing in others. One possible solution is to create a new set with both old and new states,
but that works only if new data sent corresponds to the new offsets, in this case 2 and 3.

PI Server System Management Guide 81

Manage Archives

Manage Archive Shifts

An archive shift normally begins when the Archive Subsystem detects that the primary
archive is almost full. It dismounts the last empty archive, or oldest shiftable archive if no
empty archives are available. It then initializes this archive. This can take some time,
depending on the current point count. Messages are written to the log during the initialization
to indicate progress.
After the new archive clears, it is initialized to start at the current time and is mounted as the
primary archive. The start time of this archive is set to the end time of the archive file that
just became full. The end time corresponds to the timestamp of the most recent event that was
stored in the archive.

Note: The oldest shiftable archive is the oldest writable archive large enough for the
current point count. Also, dynamic archives containing data are not shiftable.

The process of clearing the oldest archive and preparing it to be the new primary archive is
called an archive shift. It is important that all eligible archives are backed up prior to the
archive shift to ensure that no data is lost.
When an archive is assigned a start time, it is initialized. Archives are only initialized during
an archive shift, or when registered with pre-defined start and/or end times.
The archive shift process takes a few minutes to initialize a new archive file. You cannot add,
edit, or delete points during an archive shift. Events sent to the Archive during an archive
shift are queued. When the shift is complete, the queued events are written to the Archive.

Note: Dynamic archives that contain data do not participate in archive shifts. That is,
newly created dynamic archives may be shifted into, but they are shift disabled
after the first overflow record is allocated.

Archives Eligible for Archive Shifts

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

Predict Next Archive Shift Time

The SMT Archives tool (Operation > Archives) has a shift prediction column that predicts
the time for the next archive shift, based on the average number of archive records cons umed
per hour, plus the rate of consumption. If the primary archive is less than 20 percent full, the
prediction is based on the previous archive rates.

82
 Backfilling Data

Resolve Failed Archive Shifts

If an archive shift fails for any reason, all further shifts are disabled and a message is sent to
the log. When the cause of the failure is resolved, restart the Archive Subsystem to enable
archive shifts. If the cause of failure was a lack of available archive to shift into, then register
a new empty archive to automatically resolve the situation and enable a shift into the new
archive.
Failed shifts do not cause any data loss since the archive goes into read-only mode and
prevents data from being written to the archive file. All incoming data is queued in the Event
Queue by the Snapshot Subsystem.

Make Shiftable/Non-shiftable

To change the Shift flag for an Archive, right-click the Archive in list view, and:
• choose Make Non-shiftable to make the Archive non-shiftable
• choose Make Shiftable to make the Archive shiftable.

Force an Archive Shift

To force a selected server to shift from one Archive file to another, select the server's primary
Archive in the list and click the Force Shift button . A dialog prompts for confirmation
before forcing the shift.

Backfilling Data
At times it may be useful to make data available in PI that was collected prior to the PI
installation. Several applications can be used for this procedure, known as backfilling. You
may use a PI API or PI SDK application, piconfig, or the batch file interface. Your choice
depends mainly on how the data that will be entered into PI is currently stored.

Backfill Data with Compression

The installation procedure is:

1. Ins tall PI, start PI, create all points, stop PI.
2. Isolate the PI Server from all incoming process data. This means shutting down PI
interfaces on all PI API and PINet nodes. Another way to do this is to disallow all PI API
connections at the server. To do this, start piconfig without starting PI. Disregard
messages about failure to connect and enter:
@table pifirewall
@mode edit,t
@istr hostmask,value
"*.*.*.*",DISALLOW

PI Server System Management Guide 83

Manage Archives

Note: Entries that allow access to specific names or addresses override the
DISALLOW. Edit all other entries to DISALLOW. Local connections are not
affected by PIFirewall table entries; verify that applications that may
write data are not running.

3. Start PI with the -base parameter. This ensures that PI starts up with only the minimum
required subsystems. Enter the command:
pisrvstart.bat -base
4. Use piartool -ac or -acd to create and register archive files for the backfilling period.
5. Use piconfig or other tools to insert one event for every point at the earliest time on-line.
6. Delete all the PointCreated events from the snapshot. This will bring into the
snapshot the old events. This can be done with a PI API or PI SDK program or with the
piconfig utility. Verify that the old event is in the snapshot.
7. Backfill the archives by reading in the data in Time Sequential Order. This way the data
is compressed.

Caution: The Archive Subsystem assumes the snapshot time is the most recent
time stamp written to any point. To enable compression, it is important to keep
all current data sources from writing to the PI Server. This is why Random,
Ramp Soak, Performance Equations, PI Total, PI Alarm, or any other
interfaces cannot be running.

8. If you used the technique of modifying the PIFirewall table in Step 2 above, run piconfig
to either change the hostmask value to Allow or delete the above hostmask altogether.
9. Start the interfaces using pisrvsitestart.bat.

Backfill Data without Compression

1. Install PI Server and create all points. The points that you want to backfill must be
created prior to the archive initialization, otherwise the archive has no primary records for
these points.

Note: You can backfill data using an archive created with a start time prior to point
creation time, provided the point data exists when that archive is created.
Reprocessing an old archive with the offline utility adds to that archive all
existing points, while preserving all the old data.

2. Use piartool -ac to create and initialize back fill archives. The start and end times must
be specified. The start time should be the timestamp of the oldest data to be backfilled;
the end time should be just prior to the oldest archive time specified using piartool -al.
3. Backfill the data. The data that you backfill is not compressed, since it is prior to the
snapshot time.

84
 Manage Archives of an Offline PI Server (piarchss)

4. If the backfill archive is filled before all of the backfill data is entered, you must delete
the backfill archive, and create two backfill archives. Next, divide the target time range
between the two, or create a single larger archive, and then retry the data backfilling.

Manage Archives of an Offline PI Server (piarchss)

The Offline Archive Utility is actually the same Archive subsystem executable, piarchss that
is a part of a running PI system. To use the archive utility functions of piarchss, you run it in
console mode using special command-line arguments. The offline archive utility can be used
even while PI is running.
You typically use the piarchss utility to work with archive files outside the context of a
running PI Server. This enables you to continue archiving current data on your PI Server,
while manipulating other archives offline. Typical applications of the offline tool include:
• Combine a number of archives together
• Divide a large archive file into smaller archives
• Extract a specific time period from an archive
• Recover a corrupted archive

Note: The archives that are created by the Offline Archive Utility may be either fixed or
dynamic. Their format is not different from any other archives created by piartool -
ac.

Running the piarchss Utilities

When you run piarchss as the offline archive utility, indicate an input archive file and an
output archive file, along with relevant command parameters. The basic format is:
piarchss -if inputPath -of outputPath
where inputPath is the full path and file name of the input archive file and outputPath is the
full path and file name of output archive file.
The piarchss utility takes the input file, processes it according to the command parameters,
and then outputs the processed file to whatever location you specified. The piarchss utility
does not modify the input file under any circumstances.

Tips for Using the Offline Archive Utility

If you're working with the piarchss offline archive utility, note the following:
• The full path name of the input archive must be specified.

Note: piartool -al lists only registered archives.

PI Server System Management Guide 85

Manage Archives

• If the input file is registered, the Offline Archive Utility unregisters it when processing
begins.
• If the input archive is the primary Archive, it cannot be unregistered. To work around
this, force an archive shift using piartool -fs or temporarily shut down the Archive
Subsystem.
• If the output file does not exist, the utility creates it.
• If a full path name is not specified for the output archive, the utility places the output
archive in the current directory.
• At the end of processing, neither the input nor the output archives are registered.
• By default, the piarchss offline archive utility creates dynamic archives. Use the -f
argument to specify a fixed archive.

Note: Dynamic archives become non-shiftable once a single overflow record is

generated, but remain shiftable if no overflow records are generated.

• You can run the piarchss offline archive utility while the PI System, including piarchss
itself, is running. At a minimum, the pinetmgr, pibasess, and pisnapss
subsystems must be running, because the utility needs to access the Point Database
during off-line operations.

The piarchss Utility Command-Line Parameters

There are several command-line parameters for the piarchss offline archive utility. Some of
these options are discussed in more detail in the following sections. The parameters may be
entered in any order.
Param eter Nam e Notes

-dup Duplicate Allow input archive records w ith duplicate times. By

records default duplicates are ignored.
-f size Make output Specify size in MB. If size = 0, the input file size is
archive a fixed used. Default is dynamic archive.
archive
-filter start end Filter Pr ocess events only w ithin the time range (inclusive)
specified. Both timestamps must be provided. See
Time Filtering (-filter) (page 87).
-id pathname Specify ID Specify the ID conversion binary path and filename.
conversion file See Specifying an ID Conversion File (-id).
-if pathname Input archive Required. The full path, including drive letter is
file required. This is true for all file arguments passed.
-oet option Output file end Options: Input, Ev ent, time, NFE, Primary, NoChange.
time See Specifying an End Time for the Output File (-oet)
(page 88).
-of pathname Output Archive Required.
File
-ost option Output file Options: Input, Ev ent, time, NFE. See Specifying a
start time Start Time for the Output File (-ost) (page 87).

86
 Manage Archives of an Offline PI Server (piarchss)

Param eter Nam e Notes

-silent Silent mode Suppress w arning messages.

-tfix Time fix Apply a specified time transformation to input data. See
Transforming Event Timestamps (-tfix) (page 14).
-tzf pathname Time zone Use w hen input is different from standard DST.
specification
file
-vah Validate Apply a validation algorithm. Multiple events
annotation referencing a single annotation are detected and fixed.
handles Batch Database annotations are checked for
consistency.

Piarchss Offline Archive Utility Exit Codes

To facilitate batch file processing, the offline utility returns an exit code to the operating
system:
Code Definition
0 No errors—at least one input record processed
1 Errors dur ing input phase
2 No processing errors—0 records processed possibly an empty input file
<0 An error returned from the output processing chec k log messages

Time Ranges

Filter a Time Range

The -filter flag specifies a time range (inclusive) beyond which events are discarded. The
usage is:
-filter starttime endtime
Start time must be before end time.

Specify a Start Time for the Output File

The -ost flag specifies the start time for the output file. The us age is:
-ost option
Where option is one of the following:
input Sets the start time to the start time of input. This is the default behavior.
event Sets the start time to time of first event in input.
time Sets the start time to the specified time string. Times are specified in absolute PI
(w here time is time for mat. Relative times are not supported. Times must be enclosed in double
specified in quotes w hen containing spaces. If only date is specified the time defaults to
absolute PI time 00:00:00 ( midnight)
format) For example:

PI Server System Management Guide 87

Manage Archives

"22-JA N-02 23:59:59"

23-JA N-02
21-Feb
Output file start and end times must differ by at least one second.
NFE Sets the start time to time of first event w hich passes the time filter.

Specify an End Time for the Output File

The -oet flag specifies the end time for the output file. The usage is as follows:
-oet option
Where option is one of the following:
input Sets the end time to the end time of input file. This is the default behavior.

event Sets the end time to the time of last event in input file.
time Sets the end time to the specified time string. Times are specified in absolute PI
(w here time is time for mat. Relative times are not supported. Times must be enclosed in double
specified in quotes w hen containing spaces. If only date is specified the time defaults to
absolute PI time 00:00:00 ( midnight).
format) For example:
“22-JAN-02 23:59:59”
23-JA N-02
21-Feb
Output file start and end times must differ by at least one second.

NFE Sets the end time to time of last event w hich passes the time filter.
primary Sets the end time to indicate the archive is a primary archive.
NoChange End time is not altered.

Combine and Divide Archives

From a user perspective, archive files are organized according to the time ranges that they
span. It is sometimes useful to change the initial file organization of the archive. The Offline
Archive Utility can be used to accomplish each of the following tasks:
• Combining archives with overlapping dates into one archive
• Combining archives with adjacent time ranges into one archive
• Dividing an archive into smaller archives, each covering a portion of the original time
span

Divide an Archive into Smaller Archives

To break a single archive into smaller archives, invoke piarchss once for each output file and
use the same input file for all the outputs. Each time, a different start and end time is
specified. These times are specified in absolute PI time format.

88
 Manage Archives of an Offline PI Server (piarchss)

This is an example of dividing an archive into two smaller archives:

piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat -filter "1-
jan"
"31-jan-02 23:59:59" -ost "1-jan" -oet "31-jan-02 23:59:59"
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\february.dat -filter "1-
feb" "28-feb-02 23:59:59" -ost "1-feb" -oet "28-feb-02 23:59:59"

In this example, january.dat and february.dat do not exist prior to the operation.
They are created as dynamic archives by default. After they are created, they may be
registered using piartool -ar, and then events may be added to the archive files in the usual
way. Both output archives are not shiftable because they were created by the Offline Archive
Utility as dynamic archives.
The filter start time of january.dat is specified as 1-jan. This defaults to 1-jan, of the
current year, at 00:00:00. The filter end time is enclosed in double quotes because of the
embedded space character. The output archive start and end times are explicitly specified.
Excluding the -ost and -oet flags results in the default behavior. For more details, see Specify
a Start Time for the Output File (page 87) and Specify an End Time for the Output File (page
88).
If the input file was registered prior to the operation, it will be unregistered during the
operation. When the operation is complete, you can use piartool -ar to register it again.

Combine Multiple Archives into a Single Archive

To combine several archives, invoke piarchss once for each input file, using the same output
file for all these inputs. Start from the oldest input and continue in ascending time order.

Note: The Offline Archive Utility will not work in descending or random time order.

The end-time of the output file can be moved forward as required, but the start-time cannot be
changed after creation.
Archives with an unknown end time should be processed into a new archive to determine the
actual end time. The resulting archive can then be merged chronologically. Merging a series
of archives with overlapping dates requires processing the archive with the oldest start time
first, then process the remaining in chronological order based on the archive end times.
This example demonstrates how to combine archives:
piarchss -if D:\pi\dat\oldest.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newer.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newest.dat -of D:\pi\dat\bigfile.dat
In this example, bigfile.dat does not exist prior to the operation. It is created in the first
session and events are added to it in the second and third session. It is created as a dynamic
archive by default. After it is created, it may be registered, and then events may be added to
the archive through the Snapshot Subsystem.
Any of the three input files that were registered prior to the operation are unregistered during
the operation. When the operation is complete, you can register them again. Dynamic
archives, which is the default type created by the offline utility, are not shiftable.

PI Server System Management Guide 89

Manage Archives

List Archive Record Details (Archive Walk)

Use piartool -aw to read the contents of an Archive directly from the file. Use this command
primarily for troubleshooting.
When a new archive is created, data for each point flows into its own separate primary
record. When this primary record fills up, then an overflow record is reserved for the new
data. The primary record points to the first overflow record, which can point to a second, and
so forth. Following this chain of records is referred to as an Archive Walk. When the number
of free unused overflow records in an archive gets below a configurable level, an archive shift
initiates.
The key to reading archive data this way is to understand that every PI point has a unique
Record Number (RecNo) which corresponds to a primary record in the Archive. This can be
found using piconfig or PI SMT tools.

Example : Perform an Archive Walk

To view a detailed listing of archive records, use piartool -aw. After issuing this command,
you are prompted for the target archive number and the target record.
Use piartool -al to determine the archive sequence number. See Determine Archive Sequence
Numbers (page 90) for more details. After you determine the archive sequence number, you
can display archive records, view record details and examine broken pointers.

Determine Archive Sequence Numbers

Some piartool commands require an archive sequence number; for example, archive backup
(piartool -backup) and archive walk (piartool -aw). Use the archive list command piartool -
al to determine the archive sequence number. The archive sequence number is
chronologically assigned with zero being the primary archive.
To view the Archive sequence number, look for the number in the brackets immediately
following Archive:
Archive shift prediction:
Shift Time: 27-Sep-05 14:46:56
Target Archive: g:\pi\arc\piarc.144
Archive[0]: g:\PI\arc\piarc.045 (Used: 72.2%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: g:\PI\arc\piarc.045
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 116.0
Offsets: Primary: 19273/98304 Overflow: 55751/131072
Annotations: 10/65535 Annotation File Size: 1623
Start Time: 11-Aug-05 12:59:35
End Time: Current Time
Backup Time: Never
Last Modified: 9-Sep-05 22:26:55
Archive[1]: g:\pi\arc\piarc144.arc (Used: 16.2%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: g:\pi\arc\piarc144.arc
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1

90
 List Archive Record Details (Archive Walk)

Record Size: 1024 Count: 131072 Add Rate/Hour: 3337.3

Offsets: Primary: 19273/65536 Overflow: 129079/131072
Annotations: 1/65535 Annotation File Size: 1552
Start Time: 11-Aug-05 09:12:35
End Time: 11-Aug-05 12:59:35
Backup Time: Never
Last Modified: 16-Aug-05 19:08:48
Archive[2]: g:\pi\arc\piarc145.arc (Used: 99.8%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: g:\pi\arc\piarc145.arc
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 77.9
Offsets: Primary: 19273/65536 Overflow: 19511/131072
Annotations: 1/65535 Annotation File Size: 1552
Start Time: 2-Jun-05 09:21:00
End Time: 11-Aug-05 09:12:35
Backup Time: Never
Last Modified: 7-Sep-05 09:41:50
Archive[3]: g:\pi\arc\piarch.011 (Used: 99.8%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: g:\pi\arc\piarch.011
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 36.8
Offsets: Primary: 19473/98304 Overflow: 19740/131072
Annotations: 1/65535 Annotation File Size: 1552
Start Time: 5-Jan-05 08:15:06
End Time: 2-Jun-05 09:21:00
Backup Time: Never
Last Modified: 7-Sep-05 09:41:50
Archive[4]: g:\pi\arc\piarc.144 (Used: 99.3%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: g:\pi\arc\piarc.144
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 1871.1
Offsets: Primary: 18472/65536 Overflow: 19440/131072
Annotations: 1/65535 Annotation File Size: 1552
Start Time: 2-Jan-05 10:43:06
End Time: 5-Jan-05 08:15:06
Backup Time: Never
Last Modified: 7-Sep-05 09:41:50
Archive sequence numbers are arbitrarily assigned to unused archives. Unused archives can
be recognized by both start and end time set to “Current Time.” When unused archives are
unregistered or specified for a backup, the assigned number will likely change on subsequent
reregister or backup end. Generally, there is no reason to back up unused archives.

Display Archive Records

View Record Headers Only

To display archive records with record headers only:
C:\pi\adm>piartool -aw
Enter Archive Number: 0
Enter Record Number: 40

PI Server System Management Guide 91

Manage Archives

Point ID: 18 Record Number: 40

Chain Record Number - Next: 80531 Prev: 0 Index: 0
Record Version: 3 Data type: 11 Zero: 600 Span: 500
Flags - Index:0 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 214
Storage (bytes) - Available: 990 Used: 987
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
The last line in the record is a toggle to display event data for the record you viewed. To view
event data about this record, see View Archive Record Event Data (page 92).
To toggle off the display, enter h at the Enter Record # <CR> next rec (p)rev
(e)vents (a)rchive # (q)uit: prompt.

View Archive Record Event Data

By default, the piartool -aw command displays only the record header. To view the data
in the record, enter e when prompted for the next record ID.
Event data is displayed as shown in this example. Every archive record must contain at least
one event.
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
e
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 75 $]::
Point ID: 4 Record Number: 59421
Chain Record Number - Next: 0 Prev: 71411 Index: 4
Record Version: 3 Data type: 101 Digital State Set: 3
Flags - Index:0 Step:1 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 121
Storage (bytes) - Available: 994 Used: 288
121 Event(s):
0: 9-Sep-05 18:57:04, S,O,A,S,Q [3,1,0,0,0]:
1: 9-Sep-05 18:58:14, S,O,A,S,Q [3,2,0,0,0]:
2: 9-Sep-05 18:59:24, S,O,A,S,Q [3,3,0,0,0]:
3: 9-Sep-05 19:00:34, S,O,A,S,Q [3,2,0,0,0]:
4: 9-Sep-05 19:01:44, S,O,A,S,Q [3,1,0,0,0]:
5: 9-Sep-05 19:05:14, S,O,A,S,Q [3,2,0,0,0]:
6: 9-Sep-05 19:06:24, S,O,A,S,Q [3,3,0,0,0]:
etc.
The S,O,A,S,Q array in the Event Record output indicates these values:
Event Type Definition
Coding
S StateSet
O Offset in StateSet; 248 corresponds to "No Data"
A Annotated (0=no, 1=yes)
S Substitute (0=no, 1=yes)
Q Questionable (0=no, 1=yes)

92
 List Archive Record Details (Archive Walk)

EVENT RECORD DE TAILS

Index shows whether the values in the records are data values or pointers to data records,
where 0 indicates that it is not an index record. If they are pointers, the pointers are actually
record numbers corresponding to the start time. When events for a point exceed two records
in a single archive, an index record is created. An index record holds about 150 pointers to
data records.
RecNo (Record Number) is a read-only point attribute which indicates the position of the
point's primary record in the archive. This is useful when using tools such as piartool -aw to
examine the archives. Do not confuse RecNo with the PointID attribute. If the point is
deleted, the RecNo can be reused but the PointID cannot.
This table shows commonly used data types:
Data Type Definition
8 Int32
(index records are also of data type 8=, as they contain record
numbers)
12 Float32
101 digital
102 Blob

Examine Broken Pointers

In rare cases of hardware failure, record chains can become inconsistent. You can use the
following archive check utility to examine archive integrity:
pidiag -archk path
See Verify the Integrity of Archive Files (page 93) for more details.
The archive offline utility repairs any record chaining problem. See Manage Archives of
Offline PI Server (page 85) for details.

PI Server System Management Guide 93

Manage Archives

Verify the Integrity of Archive Files

pidiag -archk path [complete]
To perform integrity checks or extract statistics from archive files that are not registered, use
the -archk command. Run the command on an archive file to get a report that displays:
• a list of points sorted by record number or RecNo
• the number of index records (indices)
• the number of data records
• the count of events in all records and the average fill ratio (fr)
When the complete option is specified, the report also includes details about each record,
including the start time, number of events, and fill ratio of the data record.
For example:
D:pidiag -archk D:\PI\dat\piarch.001
Analyzing archive: D:\PI\dat\piarch.001
-----------------------------------------------------------------
------
recno: 1 id: 1 indices: 1 records: 5 events: 636 fr:
89.4%
recno: 2 id: 2 indices: 1 records: 5 events: 631 fr:
88.6%
recno: 3 id: 3 indices: 2 records: 278 events: 54437 fr:
99.5%
recno: 4 id: 4 indices: 7 records: 866 events: 428465 fr:
99.6%
recno: 5 id: 5 indices: 1 records: 23 events: 3202 fr:
97.3%
recno: 6 id: 6 indices: 1 records: 31 events: 4355 fr:
96.6%
recno: 7 id: 7 indices: 1 records: 39 events: 5534 fr:
98.4%
recno: 8 id: 8 indices: 1 records: 27 events: 3981 fr:
98.7%
recno: 9 id: 9 indices: 1 records: 6 events: 1340 fr:
89.7%
recno: 10 id: 10 indices: 1 records: 19 events: 4646 fr:
98.3%
recno: 11 id: 17 indices: 6 records: 1092 events: 86402 fr:
48.0%
recno: 12 id: 18 indices: 0 records: 1 events: 69 fr:
48.4%
recno: 13 id: 14 indices: 0 records: 1 events: 1 fr:
0.8%
recno: 14 id: 15 indices: 0 records: 1 events: 1 fr:
0.8%
recno: 15 id: 16 indices: 0 records: 1 events: 1 fr:
0.8%
recno: 16 id: 19 indices: 0 records: 1 events: 0 fr:
0.0%

94
 List Archive Record Details (Archive Walk)

recno: 17 id: 24 indices: 0 records: 1 events: 0 fr:

0.0%
recno: 18 id: 0 indices: 0 records: 1 events: 0 fr:
0.0%
recno: 19 id: 0 indices: 0 records: 1 events: 0 fr:
0.0%
-----------------------------------------------------------------
-----
0 errors detected
23 total index records
2399 total data records
593701 total events
247.5 events per record
10800 total annotations
Consistency check status: [0] Success
Points receiving events in order with no edits or remove events typically have a fill ratio close
to 100%.

Note: Since the last record in a chain is rarely full, the fill ratio is almost never exactly at
100%.

In this example, points 4 and 17 (RecNos 4 and 11, respectively) clearly have an excessive
number of index records. See Maximize PI Server Performance.

PI Server System Management Guide 95

Chapter 5

Back up the PI Server

This chapter describes the important concepts related to PI Server backups. The most
important concept to grasp is the recommended procured for backing up the PI Server. This
procedure can be summarized as follows.
• Step 1: Configure a Daily Backup Task. This daily task will back up the PI Server to a
single PI Server backup directory. Files are overwritten and accumulate in this directory.
Ideally the accumulated files in this directory correspond to a full backup of the PI
Server.
It is important to realize that this backup directory corresponds only to the latest state of
the PI Server. If you need to restore a backup from two days ago, this backup directory
will not help you. You must also implement step 2.
• Step 2: Back up the Backup Directory. The backup of the backup directory will allow
you to restore the backup directory at a point in time in the past. It is recommended that
you use a third-party backup application for this purpose.
Although other solutions that do not require third-party backup software are described in this
chapter, third-party software will significantly reduce your backup administrative tasks. For
example, typical third-party backup software will automatically discard old backups after a
configurable expiration period. Also, third-party backup software can typically be managed
by IT so that the PI System manager can attend to other tasks.

Note: The Backup tool in SMT only allows you to evaluate the success or failure of Step
1. The tool gives no indication as to the success or failure of Step 2.

Configure a Daily Backup Task

The PI Server includes a script to configure a daily backup that runs as a Windows task. In
this document, we refer to this backup task as the scheduled backup task. The scheduled
backup task performs an incremental, verified backup each day. It places the backup files in
the directory specified by the Windows task, which we refer to as the scheduled backup
directory. The scheduled backup directory holds only the most recent verified backup. You
need to back up each day's verified backup to a safe location.
You can access the PI Server as usual while the scheduled backup task is running. You can
create points, push data to the archives, and so on. To minimize performance impact during
backups, use the recommended disk configuration (Recommended Disk Configuration (page
99)).

PI Server System Management Guide 97

Back up the PI Server

Note: By default, the backup task uses Microsoft's Volume Shadow Copy Services
(VSS) to enable access to the PI Server during backups. If VSS is not supported
on the PI Server computer, then there are some limitations to access during
backups. See VSS and non-VSS Backups (page 106) for more information.

About the Daily Backup Task

The recommended strategy for automating backups of the PI Server is as follows:

1. Establish a baseline backup in the scheduled backup directory. The scheduled backup
directory is the directory that contains the backup files generated by the scheduled
backups. (You do not need to perform this step for new installations.) See Establish a
Baseline Backup (page 103).
2. Set up a PI Server backup to run as a Windows automatic task. The PI Server includes
scripts for creating the task and performing the backups. The task backs up files and
copies them to the scheduled backup directory. The name and location of the backup
directory is configurable, as is the time of the backup. See Create the Backup Task (page
104).
3. Use a third-party backup tool to automate a regular backup of the files in the backup
directory. This backup should store the files on a different computer from the PI Server.
The PI Server includes a script that you can use for this, if a third-party tool is not an
option. SeeBack up the Scheduled Backup Directory (page 108 ).
4. Run a test backup to make sure that the scheduled backup task is working correctly. See
Run a Test Backup (page 109).
The following diagram illustrates the two steps that should occur each day: the backup of the
running PI Server, and the backup of the scheduled backup directory.

98
 Configure a Daily Backup Task

Recommended Disk Configuration

VSS backups require at least one NTFS partition on the machine where the PI Server is
installed. For optimum performance during backups the following files should be on separate
drives:
• The PI data archives and event queue
• The paging file of the operating system
• The scheduled backup directory (this drive can be a remote network drive or NAS)
For example, the PI Server may be installed on the C: drive, which is usually where the
paging file is located, while the archives and event queue are configured to be on the D: drive
and the intermediate backup directory is on the E: drive or a remote network drive.
All archives to be backed up must be on the PI Server Node. The backup will fail if the
archive to be backed up is on a remote drive, such as a mapped network drive. (This is true
for all VSS backups.)

Upgrade Considerations
If you had the 3.4.370 or 3.4.375 backup scheme in effect before the upgrade, your backup
will continue to work in the same or similar manner as it did before the upgrade. If you are
upgrading from any PI Server version prior to 3.4.370 or if you are moving your PI Server to
a different machine, your scheduled backups will cease to function and you need to convert to
the 3.4.380 backup scheme.
• How can I tell if the 3.4.380 Backup Scheme is in effect? (page 99)
• How do I convert to the 3.4.380 Backup Scheme? (page 100)
• What archives are backed up after converting to the 3.4.380 Backup Scheme? (page 100)
• Why should I convert from the 3.4.375 Backups Scheme to 3.4.3.380 Backup Scheme?
(page 101)
• How will the 3.4.375 Backup Scheme change after upgrading to 3.4.380? (page 100)
• Why should I convert from the 3.4.370 Backups Scheme to 3.4.3.380 Backup Scheme?
(page 101)
• What is the pibackup_3.4.370.bat script? (page 102)
• What are there "Unknown" Last Modified Times listed in piartool –al? (page 102)

How can I tell if the 3.4.380 Backup Scheme is in effect?

To see whether the 3.4.380 backup scheme is in effect, follow these steps:
1. Open the Backups tool in the PI System Management Tools (select Operation >
Backups).
2. Select the Server from the PI Server drop-down menu. The backup history for the
selected PI Server appears.
3. Double-click on any of the scheduled backups in the list. The Details dialog appears.

PI Server System Management Guide 99

Back up the PI Server

4. On the Summary tab, look at the Method Field. If this field says INCREMENTAL, then
the 3.4.380 backup scheme is in effect.

What archives are backed up in the 3.4.380 Backup Scheme?

In the 3.4.380 backup scheme, the scheduled backup task backs up only those archives that
have been modified since the last backup. subsequent to the 3.4.380 upgrade are backed up.
To see which archives will be included in the next backup, use the command:
piartool -backup -identify -type incremental

How do I convert to the 3.4.380 Backup Scheme?

1. In the Task Scheduler Windows control panel, delete the existing PI Server Backup
scheduled task or rename the task and disable it.
2. Delete or rename the \PI\adm\pintbackup.bat script if it exists. See The pintbackup.bat
Script (page 117) for more information on the pintbackup.bat script.
3. Delete or rename the \pi\adm\pibackup_3.4.370.bat script if it exists.
4. Create a new scheduled backup task (Create the Scheduled Backup Task (page 104)).
5. Establish a baseline backup (Establish a Baseline Backup (page 103)).

How will the 3.4.375 Backup Scheme change after upgrading to 3.4.380?
If you configured your backups in 3.4.375, the 3.4.375 backup scheme will still be in effect
after you upgrade to 3.4.380. This means that archives will still be selected for backup
according to the number of archives and/or the archive cutoff date that is configured in the PI
Server Backup scheduled task.
However, there will be a slight difference in the file copy behavior of the PI Backup
Subsystem. In 3.4.380, the PI Backup Subsystem always skips file copies for any archive that
has the same file size and last modified date in the source and target directories. Previously,
in 3.4.375, such file copies were skipped only on Mondays and this functionality was referred
to as incremental backups. In 3.4.380, the meaning of incremental backups has changed.
Another change is that backup verification will start occurring automatically without any
need to reconfigure your backups.

100
 Configure a Daily Backup Task

Why should I convert from the 3.4.375 Backups Scheme to 3.4.3.380 Backup
Scheme?
The 3.4.380 backup scheme offers true incremental backups. With this scheme, the scheduled
backup task backs up all archives that have changed since the last scheduled backup. In the
3.4.375 backup scheme, you cannot back up all files that have changed; you can only specify
a particular number of archives or an archive cut-off date as the selection criteria for the
backup. This means you might miss some modified archive files in the backup.
It is possible to configure a 3.4.375-style backup to be effectively the same as a the new
3.4.380 backup scheme. However, the 3.4.380 backup scheme is easier to manage and
guarantees that any archives that have been modified are included in the backup.
To configure a 3.4.375-style backup to be a true incremental backup, you need to keep a full
PI Server backup in your scheduled backup directory and you need to select all archives for
backup. Because of the changes to the backup tools in 3.4.380, file copies are always skipped
for any file that has the same last modified date and file size in the source and target
directories.

How will the 3.4.370 Backup Scheme change after upgrading to 3.4.380?
If you configured your backups in 3.4.370, the 3.4.370 backup scheme will still be in effect
after you upgrade to 3.4.380. If PI is installed on Windows Server 2003 and you are using
NtBackup.exe to backup the PI Server, your backups should behave in exactly the same
manner as they did before the upgrade.
If PI is installed on Windows 2000, the non-VSS backups will behave in a similar fashion as
they did before the upgrade. Archives will still be selected for backup according to the
number of archives and/or the archive cutoff date that is configured in the PI Server Backup
scheduled task. There will, however, be a slight difference in the file copy behavior of the PI
Backup Subsystem. In 3.4.380, the PI Backup Subsystem will always skip file copies for any
archive that has the same file size and last modified date in the source and target directories.
In 3.4.370, file copies would never be skipped. Another change to the non-VSS backups is
that backup verification will start occurring automatically without any need to reconfigure
your backups.

Why should I convert from the 3.4.370 Backups Scheme to 3.4.3.380 Backup
Scheme?
The 3.4.370 backup scheme has a number of limitations:
• VSS backups in 3.4.370 used NtBackup.exe. NtBackup.exe is no longer delivered with
Windows beginning with Windows Vista/Windows Server 2008. Further, NtBackup.exe
creates a single backup file called PI_Backup.bkf. Unlike the new backup scheme, files
do not accumulate in the backup directory. A backup of the single PI_Backup.bkf file
typically does not correspond to a full backup of the PI Server.
• You cannot back up all files that have changed as you can with the new incremental
backups in 3.4.380. You can specify only a particular number of archives or an archive
cut-off date as the selection criteria for the backup; this means you might miss some
modified archive files in the backup.

PI Server System Management Guide 101

Back up the PI Server

What is the pibackup_3.4.370.bat script?

When upgrading from 3.4.370, the installer renames the 3.4.370 pibackup.bat script to
pibackup_3.4.370.bat. This script is called instead of the new pibackup.bat script that is
installed with 3.4.380. This is the manner with which the 3.4.370 backup scheme is preserved
after upgrading to 3.4.380.

What are there "Unknown" Last Modified Times listed in piartool -al?
After upgrading, the last modified times of some archive files may appear to have Unknown
last modified times as displayed by piartool -al. These archives have had their last modified
time reset to a universal coordinated time of 1-Jan-70 because their last modified time was
more recent than their last backup time before the upgrade. Prior to 3.4.380, the last modified
time could not be used as a reliable mechanism for incremental backups. As a conseque nce of
resetting the last modified time, only those archives that have been modified subsequent to
the 3.4.380 upgrade are backed up for incremental backups.

Backups on Replicated Server Nodes

PI Server Replication is not a substitute for backing up your PI Server. Replication provides
users with alternate sources to the same time-series data. Backups provide a means of
recovery after unintended configuration changes and database corruption. Also, by default,
backup performs a nightly validation of the snapshot and base subsystem databases and the
primary archive. If properly configured, backups allow you to roll back a PI Server to a given
point in time.
An example of an unintentional configuration change is an accidental point deletion.
Replication will propagate this mistake to all nodes in the collective. Depending on when the
mistake is detected, the only means to recover the deleted point may be to restore a backup
that was taken prior to the deletion of the point.
• At a minimum, backup the primary node in a PI Server Collective. However, as
enumerated below, there are several good reasons to backup secondary nodes as well.
Not all configuration information is replicated. Non-replicated data include, for example,
tuning parameters and PI Server Message logs. In part, these files can be enumerated by
the piartool -backup -identify -verbos e command; the non-replicated components
where the data may differ between the primary and secondary nodes include the
SettingsAndTimeoutParameters, pimsgss, and pibatch components. However, non-
replicated data also includes customized batch scripts, ini files, logs, etc., that can be
backed up with the pisitebackup.bat script.
• Database corruption can occur independently on primary and secondary nodes. The
validation step at the end of the backup may, for example, detect corruption on a
secondary node that did not occur on the primary node.
• If the secondary and primary are geographically separated across a slow network, then it
might be more expedient to restore the secondary from a backup, rather than re-
initializing from the primary.
• The start and end time of archives are not the same on primary and secondary nodes. Re-
initializing a secondary typically requires manual steps to eliminate data gaps. If a
secondary is restored from backup, there will be no data gaps.

102
 Configure a Daily Backup Task

If you decide to backup the secondary node, keep in mind that the files used to create
customized backups, pintbackup.bat and pisitebackup.bat, are copied to the secondary
node when the secondary node is synchronized to the primary. For this reason, these files
should be written so that they will work on both nodes of the collective. The
pisitebackup.bat.example was written with this in mind.
When restoring a secondary node from backup, keep in mind that the data that will be
restored in the primary and secondary nodes will not be identical due to slight differences in
timing as to when the backups are taken and due to slight differences in timing as to when
data arrives to the primary and secondary nodes. You can use the archive editor Plug-In from
the PI System Manager tools to independently examine the data the in the various nodes in
the collective.

Backing up the PI Server on a Windows Cluster

Backups must be scheduled to run on both nodes of the cluster. Although the backup task is
scheduled on both nodes, the backup task will start only on the currently active node. This is
because the pibackuptask.bat and pibackup.bat files are on the shared drive, which is only
visible to the currently active node.
Other than the need to schedule the backups on both nodes, backups on clustered and non-
clustered Windows nodes are the same.

Establish a Baseline Backup

After you upgrade a PI Server, you need to establish a baseline backup (new installations do
not require a baseline backup). You have two basic configurations to choose from:
• If you plan to keep a full backup of the PI Server in the backup directory itself, then you
use the following command (from the PI\adm directory) to establish the baseline
backup:
piartool.exe –backup backupdir –type full –arcdir -wait
where backupdir is the full path to the backup directory. The path can be a UNC path.
Here are a few examples of valid paths:
C:\pibackup\
\\myserver\c$\pibackup\
\\myserver\share\pibackup\

Note: The UNC path can be a path to a shared directory on a remote computer, but
mapped network drives cannot be used in the full path.

For example, to establish a baseline backup with D:\PI\backups as the backup

directory, you would change to the PI\adm directory and type the following command:
piartool -backup D:\PI\backups -type full -arcdir -wait
• If you don't have the disk space to maintain a full backup of the PI Server in the backup
directory, then you can keep a backup of some number of the most current archives in the
backup directory. You can keep the remaining archives backed up to a separate safe

PI Server System Management Guide 103

Back up the PI Server

location. In this case you use the following command (from the PI\adm directory) to
establish the baseline backup:
piartool -backup backupdir -numarch num -arcdir -wait
where backupdir is the full path to the backup directory, as above and num is the number
of archives you want to keep in the backup directory. For example, specifying -
numarch 2 backs up the primary archive and archive 1, provided that the primary
archive and archive 1 contain data. Empty archives are not identified for backup. So, to
establish a baseline backup with four archives and D:\PI\backups as the backup
directory, you would change to the PI\adm directory and type the following command:
piartool -backup D:\PI\backups -numarch 4 -arcdir -wait

Create the Scheduled Backup Task

To set up a scheduled backup task, follow these steps:

1. On the PI Server computer, log in with a Windows account that has administrator
privileges.
2. Open a Windows command prompt.
3. Change to the PI\adm directory. For example, if the PI Server is installed on the D
drive, you would type:
cd /d "%piserver%adm"
4. Select a target directory for your backups. We will use e:\pibackup in this
example. Ideally, the e: drive does not correspond to the system drive or the drive where
your archives are stored.
pibackup e:\pibackup -install
This command creates a Windows Scheduled Task called PI Server Backup.

Note: On Windows 2000 Server, the task name will be of the form Atn, where n is
the next available task number when the task was created. If you have
installed the scheduled task on Windows 2000, rename the scheduled task to
PI Server Backup by right-clicking the task name and choosing Rename.

5. Open the scheduled task to verify that it got created. On Windows 2000 Server and
Windows Server 2008, open the Scheduled Tasks Windows Control Panel. On Windows
Server 2008 and Windows Server 2008 R2, open the Task Scheduler Windows Control
Panel under Administrative Tools.
6. Optional: Configure site-specific files for backup. See Configuring Site-Specific Files
for Backup (page 107).
7. Optional: Customize the scheduled backup task. You can change the time the task runs,
the name and location of the scheduled backup directory, and so on. See Customize the
Default Backup (page 108).
8. Configure step 2 of the Two-Step backup.

104
 Configure a Daily Backup Task

Backup Verification
By default the PI Server Backup task performs an incremental backup of PI Server files.
The PI Backup Subsystem attempts to maintain a consistent backup without corrupt or
partially copied files in the PI Backup directory. It does this by temporarily copying files to a
precommit directory before moving the files to their final destination. This precommit
directory is a subdirectory under the PI Server backup directory. If the backup is aborted, if
the PI Backup Subsystem crashes, or if the files in the precommit directory do not pass
verification, the files in the precommit directory are not moved to their final destination.
Therefore, unless some corruption was not detected, the last good backup should always be
available.
The following illustration represents a simplified view of a typical backup. First, the
components represented by the yellow blocks are selected for backup. Second, the files
corresponding to these components are copied to a precommit directory. Third, the primary
archive and the files that correspond to the base and snapshot subsystems are verified in the
precommit directory. Finally, if verification passes, the files are moved to the backup
directory. Any files with the same name that already exist in the backup directory are
renamed before the move operation. If all move operations are successful, the renamed files
are deleted.

If the backup fails verification, the files are left in the precommit directory, and the reason for
the failed backup id s logged in a pibackupverify_*.log file written to the PI Server
backup directory. If successive backups fail verification, files will start accumulating in the
precommit directory. After the next successful backup, all files are copied to their final
destination.
The following table shows commands that the PI Backup Subsystem spawns to perform the
verification.
Com ponent Verification Comm and
Archive components pidiag -archk
pibasess pibasess -verifydb
pibasess pidiag -fb

PI Server System Management Guide 105

Back up the PI Server

Although only the primary archive is verified by default, the number of archives to be
verified can be set with the BackupVerification_NumArch tuning parameter. Alternatively,
all verification can be suppressed by setting the BackupVerification tuning parameter to 0.
Although the last good backup should not be corrupt, it is still imperative to backup the PI
Server backup directory, preferably with third-party backup software. For example, if you
accidentally delete a PI Point and subsequently perform a backup, the PI Point is deleted in
the last good backup as well. To retrieve the deleted PI Point, you might need to restore a
previous backup. If you are not keeping multiple backups of your PI Server backup directory,
there will be no means to do this restore.

VSS and non-VSS Backups

The PI Server performs Volume Shadow Copy Services (VSS) backups as the default on
Windows Server 2003 and later. The PI Server performs non-VSS backups on Windows
2000. Although Windows XP supports VSS backups, the PI Server performs non-VSS
backups on this platform (unless you use NtBackup).
VSS provides fast volume capture of the state of a disk at one instant in time. This volume
capture is called a snapshot or shadow copy. When the snapshot is taken, disk writes are
suspended for a brief period of time, typically on the order of milliseconds. After the
snapshot, disk writes can resume, but the original state of the files are maintained by a
difference file. The difference file allows the state of the original file at the time of the
snapshot to be reconstructed. This behavior allows files to be backed up while new data is
being written to files.
With VSS the PI Server works completely as usual during backups. You can create points,
push data to the archives, and so on. (While possible, it is not recommended to make
configuration changes during a backup.)
If your operating system does not support VSS, then the PI Server still provides online
backup functionality by doing non-VSS backups. Non-VSS backups are still online backups,
so you do not need to take the Server or archives offline. However, non-VSS backups have
the follow ing limitations :
ο files are read-only while they are being backed up
ο you can't create new points during the backup
ο you can't push new data into the archives while the archives are being backed up
The following table compares the PI Server impact for VSS and non-VSS backups.
Datab ase Operation Applies to Im pact
Snapshot Read and VSS and Non- The snapshot remains available for read and w rite
Database Write VSS operations. For example, a Pr ocessBook trend
that remains open during the course of a backup
w ill continue to receive data w ithout interruption.
How ever, if the revert button is pressed, data that
arrived during the course of the bac kup may not
be available from the archive depending on
whether the data can be w ritten during the
backup. See "Archive Databases / Write" below .
Message Read and VSS The message logs are unavailable for a br ief time,
Logs Write typically less than a second.

106
 Configure a Daily Backup Task

Non-VSS The message logs are unavailable during the

entire time period that it takes for the message log
files to be backed up.
Archive Read VSS and Non- All data that is in the archive remains available for
Databases VSS read w ithout interruption.
Write VSS Archiving is turned off only for a brief time,
typically less than 1 second.
non-VSS While each archive is backed up, archiving is
turned off. The total amount of time that archiving
is turned off depends on the total size of all
archive files that are included in the backup and
the speed at w hich the PI Backup Subsystem can
be copy the archives to the destination directory
for the backup.
Base Read VSS and Non- Configuration data remains available for read
Databases VSS w ithout interruption during the entire backup. For
(for example, example, a tag search can be done at any point
point and during the backup.
Module Write VSS The base databases are unavailable for
configuration configuration changes only for a brief period of
data) time, typically less than a second. For example, PI
Points and PI Modules can be created or edited
during the course of a bac kup. Although database
changes are possible, it is not recommended to
make large-scale configuration changes during a
backup.

Non-VSS The Point Database cannot be altered w hen the

snapshot, archive, or base databases are backed
up. Other base databases cannot be altered
when the database itself is backed up.

Configuring Site-Specific Files for Backup

By default, the scheduled backup task does not back up the files under the 32-bit and 64-bit
pipc directories. If, in the PI\adm directory, you rename pisitebackup.bat.example to
pisitebackup.bat then, pisitebackup.bat is run at the end of the pibackup.bat script
(provided that the backup of the PI Server itself was successful). By default, the
pisitebackup.bat script will copy all .bat, .log, .ini, .txt, and .sql files from the
32-bit and 64-bit pipc directories to the sitebackup directory under the PI Server backup
directory. To change which files are backed up, edit pisitebackup.bat.
If you do not have third-party backup software, you can configure the pisitebackup.bat
script to copy the backup directory to a remote computer. Instructions for doing this are in the
pisitebackup.bat.example itself. This step is imperative if you are not using third-party
backup software to backup the backup directory.
If you are following the recommended approach and you are using third-party backup
software to backup your backup directory, you can manually trigger the third-party backup
from the pisitebackup.bat script. However, it is usually sufficient to schedule the third-party
backup at a time when the PI Server backup should be completed.

PI Server System Management Guide 107

Back up the PI Server

Customize the Default Backup

After installing the PI Server backup as a scheduled task, you can customize the task as
follow s:
• Change backup time. The default time is 3:15 AM.
• Change the Windows user under which the task runs. By default, the task runs under the
System account. If you are using the pisitebackup.bat script to backup files to a remote
computer, then you will need to run the scheduled task as a user that has sufficient
privileges to write to the target directory on the remote computer.
• Change the path to the scheduled backup directory.
To make any of these changes, open the Windows Task Scheduler, and double-click on the PI
Server Backup entry.

Back up the Scheduled Backup Directory

Backing up the files in your backup directory is a crucial step to safeguarding your PI Server.
The backup directory contains only the most recent backup. As new backup files are copied
into the backup directory, the old backup files are overwritten. This means that the backup
directory contains only the most current verified backup. This does not help you if you need
to restore to an older backup.
For example, suppose you discover that two days ago you accidentally deleted a point. You
cannot recover the deleted point from the files in the backup directory because the last backup
occurred after the point was deleted. You need to recover the point from an earlier backup.
Your backups of the PI Server backup directory will provide the backup history that allows
you to restore the point.

The recommended method of backing up the PI Server backup directory is to use a third-
party backup program. You can use any backup strategy that is available with the third-party
backup program. For example, you might choose to do a combination of full and incremental
backups, full and differential backups, a combination of full, incremental, and differential

108
 Configure a Daily Backup Task

backups, and so on. The exact terminology and strategies vary from backup program to
backup program.
If third-party backup software is not available, you can use the pisitebackup.bat script to
automatically copy the backup directory to a remote computer. The
pisitebackup.bat.example file contains instructions for setting this up.

Run a Test Backup

Next, follow the procedure below to run a couple of test backups. In this example, the backup
directory is assumed to be E:\pibackup\ and the PI Server directory is assumed to be
C:\pi\.
1. Run the pige tmsg -f command to monitor messages that are written to the PI Message
log during the backup.
2. In the Windows Task Scheduler, start a test backup by right-clicking on the PI Server
Backup scheduled task and selecting Run. Files will be backed up to the following
directories.
ο Archives will be backed up to E:\pibackup\arc\.
ο Files from C:\pi\dat, C:\pi\adm, C:\pi\log, and C:\pi\bin are
backed up to E:\pibackup\dat, E:\pibackup\adm, E:\pibackup\log,
and E:\pibackup\bin, respectively.
3. Monitor the PI Message Log messages from the pige tmsg -f command. At the beginning
of the backup, you should see the message Backup operation started. You
may see -15033 errors because the PI Message Subsystem is briefly unavailable for
logging during the backup. Because of this, you may not see the Backup operation
completed successfully message in the pige tmsg -f output, even though the
message does eventually get written to the message log. You can tell when the backup is
complete by examining the task status in the Windows Task Scheduler or from the output
of the piartool -backup -query command.
4. After the backup is complete, examine the backup log in E:\pibackup\. The log will
have a name of the form pibackup_dd-MMM-yy_hh.mm.ss.txt.
ο Near the beginning of the log you will see the list of the currently registered archives.
This archive list can be helpful during restore operations. For example, when
restoring the PI Server, it is helpful to know at the time of the backup which archive
was the primary and which directories the archives were in.
ο At the very end of the log you should see the message pibackup.bat script
completed successfully if the backup was successful.
ο The log contains a Verbose File Backup Report indicating which files were copied to
the backup directory.
ο The log displays the list of subsystems that were registered for backup and the
subsystem version numbers.

PI Server System Management Guide 109

Back up the PI Server

ο The log also contains a summary of the backup that looks similar to the following.
Backup in Progress: FALSE
Files Copied: 24
Files Skipped: 36
File Copy Failures: 0
Total File Count: 60
Last Backup Start Pending: 1-Nov-09 03:15:05
Last Backup Start: 1-Nov-09 03:15:26
End: 1-Nov-09 03:15:42
Status: [0] Success
Last Backup Type: INCREMENTAL, VSS, Component
Mode
Last Backup Event: BACKUPSHUTDOWN
Last Backup Event Time: 1-Nov-09 03:15:43
Verification Start Time: 1-Nov-09 03:15:42
VSS Supported: TRUE
The type of the backup should be INCREMENTAL, which is true for all newly ins talled
backup tasks in 3.4.380. The first incremental backup of a newly installed PI Server should
be equivalent to a full backup. A backup type of NUMARCH/CUTOFF is possible only if the
backup task is left over from an upgrade.

How to Monitor and Maintain Your Scheduled Backups

Periodically Restore a Backup

Fundamentally, the only way to know for sure whether your backup is working correctly is to
periodically restore a backup. It is not sufficient to restore the latest backup from your
scheduled backup. Instead you should restore one of the backups taken from your third-party
backup software or from pisitebackup.bat.

Monitor Backup Performance Counters

OSIsoft recommends that you monitor the following Windows performance counters for the
PI Backup Subsystem:
• Last Backup Failed will be 1 if the last backup failed; otherwise it will be 0.
• Backups Started should increase by 1 every night if you have a nightly backup
task installed.
• Failed Backups will inc rease by 1 for every failed backup.
All of these counters are reset to 0 when the PI Backup Subsystem is restarted. The values for
these performance counters can be stored into PI Points with the PI Performance Monitor
interface, the basic version of which is installed by default on the PI Server node.
If you have PI Notifications, you can configure e-mail alerts based on Last Backup
Failed or Failed Backups. Otherwise, you can view the values of these performance
counters with PI ProcessBook.

110
 How to Monitor and Maintain Your Scheduled Bac kups

If the pisitebackup.bat fails or if a third-party backup of your backup directory fails, this is
not reflected in Last Backup Failed or Failed Backups.

Monitor Backup History in the SMT Backup Tool

Although you can perform on-demand backups in SMT by clicking the Backup Now icon ,
the main purpose of the backup plug-in is to monitor your backup history. On-demand
backups with SMT should be used only for troubleshooting purposes. They are not a
substitute for regularly scheduled backups.
To do check the backup history for a PI Server, use the SMT Backup tool. Follow these steps:
1. Open PI SMT.
2. Check the check box for the PI Server in the Collectives and Servers panel.
3. Select Operation > Backups.
4. Select the Server from the PI Server drop-down menu. The menu includes all of the
servers that are selected in the Collectives and Servers panel. The backup history for
that Server appears.
5. Right-click on the column headings to see a complete list of columns you can display in
this table.

6. Double-click on a backup entry to see the details for that particular backup. You can
choose to view a backup summary or the entire list files that were backed up.
By default, you can view reports for the last 100 PI Server backups. These reports only tell
you whether or not the backup of the PI Server itself was successful. The reports do not tell
you whether or not your pisitebackup.bat script ran successfully or whether or not a third-
party backup of the backup directory was successful.
The history tells you the Type of backups that are being performed. If the Type column is not
shown, you can right-click on the column header and add it from the drop down menu. The
following backup types are possible.

PI Server System Management Guide 111

Back up the PI Server

Backup Type Description

INCREMENTA L Any new backup task that is installed w ill perform incremental
backups.
NUMA RCH/CUTOFF If you have upgraded you PI server from 3.4.375 and you have
not re-installed your bac kup task, you w ill see back types of
NUMA RCH/CUTOFF. Backups of this type use as selection
criteria either a particular hard-coded number of archives or an
archive cutoff date. All modified archives are not guaranteed to be
included in the backup.
COPY When the PI Collective Manager or the PI SMT bac kup Plug- In
performs a bac kup, they do COPY backups. The distinguishing
feature of a COPY backup is that the last backup time is not
updated for archive files.
Backups w ith the SMT Backup plug-in are not a substitute for
your regular ly scheduled backups.
FULL If you have upgraded from 3.4.370 and you are still using
NtBackup.exe to backup your PI Server, you w ill see FULL
backups reported. How ever backups w ith NtBackup.exe should
really be considered bac kups of type NUMA RCH/CUTOFF.
DIFFERENTIAL This backup type w ill typically not appear in the list.

Examine the PI Backup Log

Periodically examine the backup logs in the PI Server backup directory. These logs have a
name of the form pibackup_DD-MMM-YY_hh:mm:ss. You can determine whether the PI
Server backup and the pisitebackup.bat script ran successfully by examining this log.

Check the Message Logs

PI SMT allows you to search the message logs for messages from the backup subsystem. If
you think there might be a problem with your automated backups, or with the backup
subsystem, this is a good place to look. Follow these steps:
1. Open PI SMT.
2. Select Operation > Message Logs. From here you can look at all the message logs
produced by PI.
3. Under Time, select the time period that concerns you.

112
 How to Restore a Backup to an Existing PI Server

4. Under Filter, type the following into the Source field:

pibackup

5. Click the Retrieve Messages icon on the tool bar. The log messages appear. Check the
log messages for errors. You can select a message to see more details about it.

How to Restore a Backup to an Existing PI Server

This section explains how to restore your PI Server from a backup. These instructions are for
restoring the PI Server on the same computer that it was running on:
1. Isolate the PI Server from the network.
2. Stop the PI Server.
\pi\adm\pisrvrstop.bat
3. Restore the backup to a temporary directory, such as C:\TempRestoreDir. For
example, if you have been backing up your backup directory with a third-party backup
application, restore the desired backup to C:\TempRestoreDir. Alternatively, if you
are restoring the latest backup, you can restore the PI Server directly from the latest
backup directory. This procedure assumes that you have restored a previous backup to a
folder of the name C:\TempRestoreDir.
4. Copy the files from C:\TempRestoreDir\dat to PI\dat.
5. Copy the files from C:\TempRestoreDir\adm to PI\adm.
6. Copy the files from C:\TempRestoreDir\bin to PI\bin.
7. Copy the files from C:\TempRestoreDir\log to PI\log.
8. Copy the archive files from the C:\TempRestoreDir\arc directory in your backup
folder to their original location on the PI Server. If you are not sure where your archive
files were located on the PI Server, look in the backup log file in
C:\TempRestoreDir\. The log contains the archive list at the time of the backup.
Since you’re restoring to an existing server, you don’t have to restore all archives. At a
minimum you must restore primary archive. Restore other archives as needed.
9. If a site backup was performed (if, for example,
C:\TempRestoreDir\sitebackup exists ), then copy the files from the site
backup directories to the corresponding 32-bit and 64-bit pipc directories. For more
information on site backups, see Configuring Site-Specific Files for Backup (page 107).
10. Restart the PI Server.

PI Server System Management Guide 113

Back up the PI Server

11. Restore the PI Server's connection to the network.

Restore a Server Backup to a New Computer

The following procedure guides you through restoration of a complete PI Server from backup
and the original installation disk. This is suitable for cases of disk crashes or disasters of
similar magnitude. This procedure assumes that you are restoring the PI Server on a node
where the PI Server was never previously installed.
1. Change the computer name of the new node to the name of the old PI Server node.
Restart the computer.
2. Restore the backup to a temporary directory, such as C:\TempRestoreDir. For
example, if you have been backing up your backup directory with a third-party backup
application, restore the desired backup to C:\TempRestoreDir. Alternatively, if you
are restoring the latest backup, you can restore the PI Server directly from the latest
backup directory. This procedure assumes that you have restored a previous backup to a
folder of the name C:\TempRestoreDir.
3. Copy the installation kit to the computer and then disconnect the computer from the
network. Disconnecting from the network is important so that data is not lost from
buffered interface nodes in subsequent steps.
4. Install the PI Server. The same PI Server version should be installed as on the old PI
Server node, and the PI Server should be installed to the same drive letter and directory
path as on the old PI Server node. If you are restoring an old backup, use the PI Server
version that was installed at the time that the backup was taken. The PI Server version
can typically be found in the backup log, which should have been restored to
C:\TempRestoreDir.
5. Verify that the PI Server is disconnected from the network before proceeding to the next
step.
6. Start PI, and then stop PI after proper startup is observed. This accomplishes the "run
once" functions performed after an installation. Since the PI Server is disconnected from
the network at this point, data will not be lost from buffered server nodes.
7. Restore (using Windows Explorer or the copy command) all files from the
C:\TempRestoreDir\dat\ directory to the new PI\dat\ directory.
8. Restore all the message log files (pimsg_xxxxxxx.dat) from the
C:\TempRestoreDir\log\ to the PI\log directory.
9. Restore all files from the C:\TempRestoreDir\adm\ directory to the new PI\adm\
directory.
10. Restore all files from the C:\TempRestoreDir\bin\ directory to the new PI\bin\
directory.
11. Restore the archives from the C:\TempRestoreDir\arc\ directory to the same
directory that they were installed on the old PI Server node. You can determine the
directories from the archive list in the restored backup log. If you restore the archives to a
different directory, then you will need to do the following additional steps a through b.

114
 Restore a Server Backup to a New Computer

a. Register the primary archive in the new location with the following command from
the PI\adm directory:
pidiag –ar
After this command completes, only the primary archive will be registered.
If you are uncertain which of the backed up archives is the Primary Archive (archive
0), use pidiag -ahd and examine the archive dates. The primary should have the
latest start date and an end date of "Current time." The syntax of the command is:
pidiag -ahd C:\TempRestoreDir\arc\piarch001.dat
After you start the PI Server in a later step, register additional archives with the
piartool -ar command. For example:
piartool -ar path_and_archive_file_name
12. If the backup was performed using PI Version 3.4.370 or greater, then skip this step
because the snapshot is backed up as of 3.4.370. Otherwise, follow steps a – b below.
a. Rename the PI\dat\piarcmem.dat to PI\dat\piarcmem.dat.old.
b. Re-create the snapshot file with the command:
\pi\bin\pibasess -snapfix
13. Start the PI Server.
14. If you had to run pidiag -ar earlier in the procedure, register additional archives with the
piartool -ar command now.
15. Use piartool -al and the client tools (PI ProcessBook and PI DataLink) to verify that all
the data has been recovered. If the data is intact, you are done. Run the clients locally,
since the PI Server should be isolated from the network. It is very important to confirm
correct PI Server recovery before exposing the PI System to buffered data. Failing to do
so may cause data loss.
16. Connect the PI Server to the network. Verify the PI Server is reachable from clients on
the network. Monitor all buffered interface nodes.

Restore Archives from Backup

To restore an archive from backup:

1. Copy the archive file to disk.
2. Unregister any archives whose dates overlap the archive to be restored. For details, see
Unregistering an Archive.
3. Use piartool -ar path to register the restored archive.
4. Use piartool -al to list the registered archives and their dates. The archive just registered
should be displayed.

Note: The PI Server will not allow registering archives with overlapping dates. If you find
overlapping dates, you can use pidiag -ahd to check the exact start and end
times.

PI Server System Management Guide 115

Back up the PI Server

Restore Subsyste m Databases from Backup

Many databases are interconnected. For example, the Point Database must be synchronized
with the Snapshot and Primary Archive. Generally, if one database must be restored from
backup, all databases must be restored from backup, as well as the primary archive. Partial
backup restoration should be done under the advice of OSIsoft Technical Support.
To restore a database, shut down the PI Server. Replace the existing database files and the
Primary Archive from the most recent backup. Restart the PI Server.

The PI Server Backup Scripts

The PI Server Backup scripts are all located in the PI\adm directory:
• pibackup.bat: used to launch a backup or it can be used to install a backup as a
scheduled task..
• pibackuptask.bat: calls pibackup.bat and redirects the standard output to a log file.
• pisitebackup.bat: a custom backup script. This script does not exist by default.
• pintbackup.bat: a custom backup script. This script does not exist by default and
typically should not be implemented unless you have upgraded your PI Server.
• pibackup_3.4.370.bat: created by the PI Server installation only when upgrading from
3.4.370 to 3.4.375 or greater.
If you want to launch your regularly scheduled backup prior to its scheduled time, you should
open the Scheduled Tasks Windows control panel and run the PI Server Backup scheduled
task from there. With the exception of installing a backup task with pibackup.bat, you
should not need to run any of these backup scripts directly.
If you want to run an unscheduled backup (one that does not change the last backup time for
your scheduled backups) use the Backups tool in PI SMT (Run an Unscheduled Backup).

The pibackuptask.bat Script

The scheduled backup task calls the pibackuptask.bat script to launch the backup. The script
calls pibackup.bat and redirects the standard output to a backup log. The backup 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
For example:
pibackup_5-Aug-05_14.16.22.txt

The pibackup.bat Script

This script can be used to install a backup as described in Create the Scheduled Backup Task
(page 104). The pibackup.bat script performs the actual backup of the PI Server and calls the

116
 The PI Server Bac kup Scripts

pisitebackup.bat script after backing up the PI Server. When the backup task runs, the
pibackuptask.bat script is called directly, which itself then calls pibackup.bat.
The pibackup.bat scripts starts the backup of the PI Server by running a single piartool -
backup command.

Note: Do not directly customize the pibackup.bat script. This script is overwritten on PI
Server upgrades.

The pisitebackup.bat Script

After the backup of the PI Server has completed, pibackup.bat calls pisitebackup.bat,
provided that pisitebackup.bat exists.
The pisitebackup.bat script can be used to::
• Backup site-specific files. See Include Site-Specific Files from PIPC Directory (page
107) for instructions.
• Copy files from the backup directory to a safe location. This should be done only if a
3rd-party backup program is not available.
• Trigger a backup of the backup directory with a third-party backup program.
The pisitebackup.bat does not exist by default. However, the PI Server installs the
pisitebackup.bat.example file to the PI\adm\ folder. By simply removing the .example
extension, the script backs up all files ending in .bat, .log, .ini, .txt, and .sql under
the 32-bit and 64-bit PIPC home directories. If you want to backup any other files or do any
other task, you must customize the script. Customization instructions are in the
pisitebackup.bat.example file itself.

Note: The pisitebackup.bat script is not overwritten when the PI Server is upgraded.

The pintbackup.bat Script

The pibackup_3.4.370.bat script is created by the PI Server installation only when upgrading
from 3.4.370 to 3.4.375 or greater. The purpose of the pibackup_3.4.370.bat script is to
maintain the behavior of the backups from 3.4.370 so that a user’s site-specific backup is not
broken by the upgrade.

The pibackup_3.4.370.bat Script

The pibackup_3.4.370.bat script is created by the PI Server installation only when upgrading
from 3.4.370 to 3.4.375 or greater. The purpose of the pibackup_3.4.370.bat script is to
maintain the behavior the backups from 3.4.370 so that a user’s site-specific backup is not
broken by the upgrade.

PI Server System Management Guide 117

Back up the PI Server

Troubleshooting Backups
This section explains how to identify common backup problems.
• Log Messages (page 118 )
• Performance During Backups (page 118)
• Common Problems with VSS Backups (page 119)
• Failure Due to Offline Subsystem (page 119)

Log Messages

The following log files should be examined for errors.

• The backup script log
The backup script log is written to the target directory of the backup with a name of the
form pibackup_dd-mmm-yy_hh.mm.ss.txt. For example:
pibackup_5-Aug-05_14.16.22.txt.
• The PI Message Log
To display all error messages between the start and end time of a backup, use a command
of the form:
pigetmsg -sl E –st starttime –et endtime
If any errors occur during a backup, the output of this command is automatically dumped
to the backup script log.
To display all messages related to backup, use a command of the following form:
pigetmsg -src pibackup –st starttime –et endtime
To display only those messages from the PI Backup Subsystem itself, use a command of
the following form:
pigetmsg -pr pibackup –st starttime –et endtime
• The Windows Application Event Log.
Look for messages from VSS and COM+ event sources.
• The Windows System Event Log
Look for messages from VOLSNAP, NTFS event sources.

Performance During Backups

Any backup on the PI Server node has the potential to impact PI Server performance. You
can largely avoid this impact by using the recommended disk configuration (Recommended
Disk Configuration (page 99)). However some impact is unavoidable because CPU resources
and file system cache resources are consumed.
Monitor your PI Server during a backup to determine how the backup affects archiving rate,
archive reads, and the CPU usage of the PI Server. Also monitor the Windows Performance

118
 Troubleshooting Backups

counters Avg Disk Write Queue Length and Avg Disk Read Queue Length for the
Physical Disk performance object. If the disk queue length is greater than one, then the disk is
falling behind.

Common Proble ms with VSS Backups

The following are common reasons why VSS backups fail:

• Service Pack 1 or greater of Windows Server 2003 is not installed. There were many bug
fixes with regard to VSS in Service Pack 1 of Windows Server 2003. VSS backups are
not reliable in Windows Server 2003 without service pack 1.
• Ole32.dll is not registered. Sometimes the system can get into a state where the
ole32.dll becomes unregistered. If ole32.dll becomes unregistered then VSS
backups will not work. This problem can be solved by re-registering ole32.dll with
the following command:
regsvr32 ole32.dll
• VSS backups fail if either of the following services is disabled:
ο Microsoft Software Shadow Copy Provider
ο Volume Shadow Copy
• Typically, the Volume Shadow Copy service should not be running. It is started on
demand whenever it is needed. If the service is running, this could mean that the service
is stuck in a bad state. You can stop the service with the following command:
net stop "Volume Shadow Copy"
If this command does not work, you might need to kill VSSVC.exe from task manager.
• Third-party VSS providers can cause VSS backups to fail. VSS backups of the PI Server
have been known to fail if the OfmProvider from St. Bernard software is installed on the
PI Server machine. You can determine whether this software provider is installed by
running the vssadmin list providers command and looking for the OfmProvider in
the output. There are no other known problems with third-party VSS providers.
• For VSS backups, all archives to be backed up must be on the PI Server Node. The VSS
backup will fail if the archive to be backed up is on a remote drive, such as a mapped
network drive.
• VSS backups require at least one NTFS partition on the machine where the PI Server is
ins talled.

Failure Due to Offline Subsyste m

Once a subsystem registers for backup, the subsystem must remain online during the next
backup or else the backup will fail with the following error:
Backup start failed, Status: [-16896] RPC Resolver offline for a
subsystem to which the backup subsystem is communicating. Find
-10733 error in message log to identify problematic RPC

PI Server System Management Guide 119

Back up the PI Server

Two messages will appear in the PI Server Message log with the -10733 error similar to the
follow ing:
E 19-Oct-09 13:54:57 pibackup (5059)
>> Callback failed for <pibatch> for the IDENTIFY event. Error
[-10733] PINET: RPC Resolver is Off-Line.
E 19-Oct-09 13:54:57 pibackup (5061)
>> Error [-10733] PINET: RPC Resolver is Off-Line., failed to
send the IDENTIFY backup event to pibatch
To fix the problem, you can either start the subsystem that is not running, or you can do the
following, if the subsystem was purposefully stopped:
1. Run the command piartool -backup -query and make note of the subsystems that are
currently registered for backup.
2. Restart the PI Backup Subsystem.
3. Wait for the previously registered subsystems to register for backup again, with the
exception of the problematic subsystem. Subsystems may take up to 5 minutes to re-
register for backup after the backup subsystem has been restarted.

120
Chapter 6

Manage Interfaces

About PI Interfaces
PI interfaces are software modules for collecting data from any computing device with
measurements that change over time. Typical data sources are Distributed Control Systems
(DCSs), Programmable Logic Controllers (PLCs), OPC Servers, lab systems, and process
models. However, the data source could be as simple as a text file. Most interfaces can also
send data in the reverse direction, from PI to the foreign system.
We refer to a computer running one or more PI Interfaces as a PI Interface Node. In most
cases, you should not run interfaces on the PI Server computer. Running interfaces on a
separate node allows the PI Server to be taken down for maintenance while data is still
collected and buffered on the Interface Node. Also, you do not want interfaces competing for
computer resources with the PI Server.
For most interfaces, it is important to configure buffering on the Interface Node. This
prevents loss of data when the PI Server is not available for some reason (such as an upgrade
on the Server). The exceptions are:
• Some interfaces do not require buffering because the data source itself is buffered. For
example, the UFL Interface and batch interfaces such as the Emerson DeltaV Batch
Interface do not require buffering.
• There are a very few interfaces that should not be run with buffering. Consult the
documentation for your interface.
The majority of OSIsoft interfaces use the PI Application Programming Interface (PI API) to
retrieve configuration information from the PI Server and to write data to the PI Server. A
few non-batch interfaces also use the PI Software Development Kit (PI SDK) to retrieve
configuration information from the PI Server and to create PI Points, Digital States, and so
on. Almost all batch interfaces use the PI SDK to write batch data to PI. The PI API and the
PI SDK are described in more detail below.
There are hundreds of different PI interfaces and each interface is fully documented in its
own dedicated manual. However, most interfaces are based on UniInt therefore share a
common set of features.

About UniInt

Most interfaces written by OSIsoft are written using UniInt, UniInt stands for Universal
Interface. UniInt is an OSIsoft-developed template used by the OSIsoft developers that is
integrated into many interfaces. The purpose of UniInt is to keep a consistent feature set and
behavior across as many of our interfaces as possible.

PI Server System Management Guide 121

Manage Interfaces

UniInt performs many tasks that need to be performed by most interfaces: such as loading
points, parsing command line, arguments, and scheduling scans for data. UniInt-based
interfaces use some of the UniInt supplied configuration parameters and some interface-
specific parameters. UniInt uses the standard PI API to write and read data from the PI
Server.

About the PI API

The PI Application Programming Interface (PI API) is a library of functions that allow you to
read and write values from the PI Server, and also let you retrieve point configuration
information. OSIsoft has used the API to create interfaces that run on a variety of platforms.
The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to
be taken offline for software or hardware upgrades without compromising data collection.
When PI becomes available again, the buffered data are then forwarded to PI.
API Nodes are workstations that run programs such as interfaces that are based on the PI API.
In practice, the term API Node is sometimes used as a synonym for Interface Node, because
historically, most interfaces are API based.
You can call PI API from C, C++, Visual Basic, or other languages. For more information on
the PI API, refer to the PI API Programmer's Help. You can access this from the PI SDK help
file.

About the PI SDK

The PI Software Development Kit, (PI SDK), is an ActiveX in-process server that provides
COM access to OSIsoft historians. The product provides an object-oriented approach to
interacting with PI systems in contrast to the procedural methods used in the PI API.
The PI SDK can only be installed on Windows. Only interfaces that run on Windows can take
advantage of the functionality provided by the PI SDK. All interfaces written for UNIX or
VMS must use the PI API exclusively for all communication with the PI Server.
Some interfaces use the PI SDK because certain functionality is not provided via the PI API.
For example, the PI SDK allows interfaces to create points, digital sets. Also, any interface
that writes batch data to PI, such as the PI Batch Generator Interface (PIBaGen), must use the
PI SDK to write its data.
Any data that is written to PI via the PI SDK is not buffered via the BufServ service. For this
reason all interfaces write time-series data to the PI Server via the PI API.
Interfaces that connect to the PI Server with both the PI SDK and the PI API must maintain
two separate connections to the PI Server.

Interfaces Installed with the PI Server

Each PI Server includes several interfaces. These interfaces are installed in the
pipc\Interfaces directory. Each interface is installed in its own subdirectory, and each
has an accompanying user manual. This section briefly lists the interfaces included in the PI

122
 About PI Interfaces

Server installation, grouped according to function. For more information, see the user manual
for the relevant interface.
The following interfaces are useful to monitor the health of your system and network. The
basic version of each interface is installed. These basic versions must be run on the PI Server
and have limited point counts and other restrictions. Full versions of these interfaces are
available. See the interface user manuals for more information.
• PerfMon reads Windows Performance Counters and stores the values in PI points. This
interface is located in pipc\Interfaces\PIPerfMon_Basic.
• SNMP collects performance data from computer systems and network routers using the
Simple Network Management Protocol, and stores the values in PI points. This interface
is loc ated in pipc\Interfaces\SNMP_Basic.
• Ping monitors the network availability of computer systems by pinging them and stores
the response times in PI points. This interface is loc ated in
pipc\Interfaces\PING_Basic.
The PI Interface Status Interface is a utility that determines whether an interface program is
writing new values to its points. PI Interface Status periodically checks whether a particular
PI point, known as the watchdog tag, is receiving new values. This interface is located in
pipc\Interfaces\PIIntStatus.
Random and Ramp Soak are simulator interfaces that can be configured to simulate random,
sinusoidal, and batch data. By default they are installed on the PI Server, but you can run
them remotely. These interfaces are located in pipc\Interfaces\Random and
pipc\Interfaces\rmp_sk respectively.
The PI Batch Generator Interface (PIBaGen) collects data from the PI Server, generates
batch data and writes the batch data to the PI Server in the PI Batch Database. PIBaGen is
used when there is no native interface to generate and store batch data in the PI System.
PIBaGen should be run directly on the PI Server. This interface is located in
pipc\Interfaces\PIBaGen.

Additional Documentation on Interfaces

In addition to this document, the following OSIsoft manuals provide general information with
regard to interface configuration and management. They are available on the OSIsoft
Technical Support Web site: http://techsupport.osisoft.com (http://techsupport.osisoft.com)
Manual Nam e Notes
PI API Installation On Window s, this manual is installed into the pipc\bin directory
Instructions by the PI SDK installation kit. The manual provides several
important post-installation details for configuring the PI A PI and
buffering.
PI Buffer Subsystem User On Window s, the PI Buffer Subsystem provides an enhanced
Guide buffering solution designed specifically for High Availability ( HA).
This manual describes how to install and configure the Buffer
Subsystem.

PI Server System Management Guide 123

Manage Interfaces

Manual Nam e Notes

UniInt Interface User Most interfaces are based on the OSIsoft Universal Interface
Manual (UniInt) and therefore share a common set of features. Certain
UniInt features may be described in more detail in the UniInt
Interface User Manual document than in interface-specific
documentation. How ever, not all features that are described in
UniInt Interface User Manual are supported by all UniInt interfaces.
PI Interface Configuration The Interface Configuration Utility provides a graphical user
Utility User Manual interface for configuring the interface command line, interface
services, and various PI points that are useful for monitoring
interface performance.
PI Performance Monitor The PI Performance Monitor interface, PIPerfMon, obtains
Interface to the PI System Microsoft Windows performance counter data and sends it to the PI
System.
Interface Status Interface to The PI Interface Status Utility is an interface that runs on the PI
the PI System Server node. The utility w rites events such as “ISU Saw No Data” to
PI Points that have not received values for a configurable period of
time from a particular interface.
PI AutoPointSync for Some interfaces (such as the OPC Interface) support auto-point
Interfaces and PI COM synchronization. PI AutoPointSync ( PI A PS) is a utility that
Connectors synchronizes PI Server points for an interface using tag definitions
on the interface's data source.

Interface Installation Checklist

This section provides some general information for installing interfaces. It does not include
interface-specific information. Consult the documentation for your interface for specific
information.
These steps rely on the PI Interface Configuration Utility (ICU). The ICU provides a
graphical user interface for configuring PI interfaces. If the interface is configured by the PI
ICU, then the batch file of the interface is maintained by the PI ICU and all configuration
changes are kept in that file and the module database. The PI ICU must be installed on an
interface node in order to use it to configure an interface.
If you are familiar with running PI data collection interface programs, this checklist helps you
get the Interface running. The Data Collection Steps (page 124) below are required. Interface
Diagnostics (page 125) and Advanced Interface Features (page 126) are optional.

Data Collection Steps

1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI SMT
on the same computer on which you run this Interface.
2. If you are running the Interface on an Interface Node, edit the PI Server’s Trust Table to
allow the Interface to write data.
3. Run the installation kit for PI Interface Configuration Utility (ICU) on the interface node
if the ICU will be used to configure the interface. This kit runs the PI SDK installation
kit, which installs both the PI API and the PI SDK.

124
 Interface Installation Chec klist

4. Run the installation kit for this Interface. This kit also runs the PI SDK installation kit
which installs both the PI API and the PI SDK if necessary.
5. If you are running the Interface on an Interface Node, check the computer’s time zone
properties. An improper time zone configuration can cause the PI Server to reject the data
that this Interface writes.
6. Run the ICU and configure a new instance of this Interface. Essential startup parameters
for this Interface are:
ο Point Source
ο Interface ID
ο PI Server
ο Scan Class
7. Use the Connection Tool to confirm connection between the Interface Node and the
device.
8. If you will use digital points, define the appropriate digital state sets.
9. Add the X, Y, and Z states to the System State Set.
10. Build input tags and, if desired, output tags for this Interface.
11. Start the Interface interactively and confirm its successful connection to the PI Server
without buffering.
12. Confirm that the Interface collects data successfully.
13. Stop the Interface and configure a buffering application (either Bufserv or PIBufss).
14. Start the buffering application and the Interface. Confirm that the Interface works
together with the buffering application by either physically removing the connection
between the Interface Node and the PI Server Node or by stopping the PI Server.
15. Configure the Interface to run as a Service. Confirm that the Interface runs properly as a
Service.
16. Restart the Interface Node and confirm that the Interface and the buffering application
restart.

Interface Diagnostics

1. Configure Scan Class Performance points.

2. Install the PI Performance Monitor Interface (Full Version only) on the Interface Node.
3. Configure Performance Counter points.
4. Configure UniInt Health Monitoring points.
5. Configure the I/O Rate point.
6. Install and configure the Interface Status Utility on the PI Server Node.
7. Configure the Interface Status point.

PI Server System Management Guide 125

Manage Interfaces

Advanced Interface Features

1. Configure the Interface for Disconnected Startup. Refer to the UniInt Interface User
Manual for more details on UniInt Disconnect startup.
2. Configure UniInt Failover, see that section in this document for details related to
configuring the interface for failover.

Configure the PI Interface Status Utility

The PI Interface Status Utility provides a convenient means to distinguish true flatlines in
data from disruptions in data collection. That is, the utility provides a means of indicating to a
user that data from a given interface is stale. Data becomes stale when no fresh data is sent
from the interface to the PI Server. For example, stale data can occur under the following
scenarios.
• The interface is running but the PI API node cannot send data to the PI Server.
• The interface is not running and a system digital state was not written to indicate that the
interface has been shut down. This could happen if the interface crashes.
• One PI Interface Status tag is configured per monitored interface, each tag monitors a
watchdog tag collecting data from the interface. If the watchdog tag's value on the PI
server hasn't updated after a user specified amount of time, the PI Interface Status tag's
status changes to a bad digital state status.
If you decide to configure the PI Interface Status Utility, then the utility is always configured
to run on the PI server Node. For more information see the PI Interface Status Utility
documentation.

Configure Auto Point Synchronization

Many interfaces, such as the PI OPC Interface, support Automatic Point Synchronization
(APS). For example, PI Points on the PI Server can be automatically created based on the
points in the OPC server using a configurable set of rules. You must consult your interface
specific documentation to determine whether your interface supports APS.
If the interface of interest has an APS Connector then consult the PI AutoPointSync
Connector Manual for the interface for configuration steps. You can also refer to the PI
AutoPointSync for Interfaces and PI COM Connectors Manual for additional information.

126
Chapter 7

Monitor the PI Server

Basic PI Server monitoring is discussed in the Introduction to PI Server System Management.
This chapter does not include those basics.

Schedule Monitoring Tasks

OSIsoft recommends that you regularly review key elements of your PI Server to ensure it
operates correctly and efficiently. Through daily monitoring, you become familiar with the
normal operation of your PI Server. You can therefore anticipate disk space and license
requirements, find abnormal messages, and thus identify and resolve potential problems
before they become serious. You can also determine how your PI Server operates under
normal conditions, and establish a baseline to use when you set up automatic monitoring.
OSIsoft recommends that you schedule the tasks listed here to monitor PI Server:
Frequency Com ponent Task Tools Autom ation
Method
Daily:
Archives Verify daily that the expected PI SMT, piartool See Set up
archives are registered and -al Automatic Archive
that you have prepared for the Creation
next archive shift.
Backups Verify daily that PI System PI SMT, piartool See Backing up the
backups w ere run for the -al PI Server (page 97)
previous day and that you
have sufficient disk space for
future backups.

Weekly, or m ore often:

PI System Rev iew the System message PI SMT, N/A
Messages log and interface logs at least pigetmsg
Log once a w eek to deter mine if
unusual events occurred.

PI Server System Management Guide 127

Monitor the PI Server

Frequency Com ponent Task Tools Autom ation

Method

Interface Check logs to see w hether PI SMT N/A

Logs unusual events have occurred
Snapshot Deter mine if Snapshot data PI SMT, piartool
data flow flow is normal. -ss
IO Rate View or Trend IO rate points PI Datalink or
Counters then review rations of PI ProcessBook
interfaces support writing
snapshot rates to PI Points;
Rev iew IO rate values and
timestamps.
Monthly:
License Perform monthly usage PI SMT, piartool N/A
limits and statistics and point count -lic
usage checks for your PI System to
anticipate license increase
needs.
Upon initial setup:
Performance Use key Windows Window s
Counters performance counters to Performance
(Windows) review statistics about all Monitor, PI
subsystems. Performance
Monitor
(Perfmon)
Interface
As needed:
Tag Data Rev iew Archive data reference PI SMT,
tags. pisnap.bat or
pisnap.sh
Update Verify client connections to the pilistupd
Manager PI Server.

View System Messages

All PI processes send messages to the PI Message Subsystem process, which writes messages
to the PI Message Log. The message source is generally a PI Server subsystem. However, the
message may originate from a source within a subsystem, such as the PI Point Database.
In PI Server versions earlier than 3.4.380, these messages are plain text. PI Server 3.4.380
introduces the PI Message Definition file, which contains message IDs and definitions.
At PI System startup, there is a short time when the PI Message Subsystem is not yet running.
During this time, and at any other time when the PI Message Subsystem is not functioning, PI
Systems running on Windows direct messages to the system event log. You can read these
messages using the Windows Event Viewer application in the Administrative Tools group.
When the PI Message Subsystem starts, it merges messages from the Windows Event Log
into the PI Server Message Log.

128
 View System Messages

View Syste m Messages with PI SMT

To view messages in SMT, select Operation > Message Logs. To narrow your message
search in PI SMT, you can use the Source, Message and Count menus. By default, Message
Filter Options are set to display messages from connected PI servers:
• over the past 5 minutes, and
• without filtering for content.
To use the message filter options you may:
• Select the Refresh Automatically check box if you need to review more than 25 log
messages.
• Select a message source from the Source menu, which lists all source programs found in
the list of displayed messages.
• Enter contents from the Message column or diagnostic information of the message.
• Indicate the maximum number of messages you would like to retrieve.
• Enter a Start time in a PI time format; the value may be either a relative time or an
absolute time.
• Enter an End time in a PI time format; the value may be either a relative time, or an
absolute time.

Note: The end time is not used when navigating forward or backward with the
toolbar. To reset the end date and time to current time, right-click anywhere in
the End frame and select the Set to Current Time menu item. The wildcard
character is asterisk (*).

Interpret a Message

To see how a message is structured, look at the following example message:

C 23-Jul-08 09:27:46.243
piarchss:piarcmgr (2050)
>> Primary archive file failed to load or has invalid dates.
Archiving will be turned off.
The first character is a letter representing the severity of a message. In this case it is C,
meaning Critical. The possible severity levels, from most severe to least severe, are Critical,
Error, Warning, Information and Debug. The severity character is followed by a time stamp
(23-Jul-08 09:27:46.243). Next is the source of the message and the message ID. Here the
message ID is 2050. The message text comes at the end.

PI Server System Management Guide 129

Monitor the PI Server

Severity Levels

There are 5 severity levels defined (in order of greater to lesser severity): Critical, Error,
Warning, Information and Debug. The leading character indicates the severity level.
• Critical: Loss of System Functionality. Requires immediate attention. Here is an example
of a critical message:
C 23-Jul-08 09:27:46.243
piarchss:piarcmgr (2050)
>> Primary archive file failed to load or has invalid dates.
Archiving will be turned off.
Note the first character, C, which indicates that this is a critical error.
• Error: Action failed. Here is an example of an error message:
E 23-Jul-08 09:27:46.243
piarchss:piarcmgr (2049)
>> Failed to load archive file F:\PI Archives\8-Sep-04_14-
Sep-04: [3] The system cannot find the path specified.
• Warning: An anomaly has occurred that does not impact the user (yet). Here is an
example of a warning message:
W 23-Jul-08 09:41:32.733 piarchss:pievqreader
(6012)
>> Invalid queue creation path "E:\PI\dat\", using default
location
• Information: Action succeeded. Here is an example of an information message:
I 29-Jul-08 18:31:53.211
pinetmgr (7039)
>> Connection accepted: Process name: pigetmsg(6260) ID:
3
• Debug: Debug/Tracing message. Here is an example of a debug message:
D 29-Jul-08 15:22:59.421
pibackup (5136)
>> PIvsswriter::OnFreeze. succeeded

PI Message Definition File

The message definition file stores information about the messages. This database associates a
message ID with each message, along with the message text, parameters, severity, and other
information. The message definition file is called pimdf.dat and it is stored in the
PI\dat directory.

130
 View System Messages

Every product installation may update the definition with new messages. If the message
definition file is not present, or is an old version, then some messages may not be able to be
rendered into readable text. In this case the message will read something like:
E 29-Jul-08 17:44:17
pibasess (8020)
>> Unknown Message # 8020
To see what version of the message definition file is ins talled, type :
pidiag -mdfv
Messages with an ID of 0-5 are considered free form. This means that they don't require a
definition in the message definition file to be read. All messages generated prior to the
introduction of the message database have an ID 0. With the introduction of the message
database, five new IDs for free-form messages (1-5) are introduced, one for each severity
leve l.
ID Severity Level
1 critical

2 error

3 warning

4 information

5 debug

View Messages if the Message Subsyste m is Unavailable

Messages are written to the Windows event log if the Message Subsystem is not available.
On Windows, use the Event Viewer to see messages when PI is running as Services, or check
the command windows if running interactively. The PI Server messages that went to the
event log messages are stored back to the PI message log on system startup and on regular
time intervals.

Note: Some startup messages may be written to the Windows event log before the PI
Message Subsystem is active.

Translate Error Codes

Use the pidiag utility to interpret any error codes that are included in the message logs. To
display the error message, enter:
pidiag -e errorcode
where errorcode is the error number displayed in the message log. Error code values may
be positive or negative.

PI Server System Management Guide 131

Monitor the PI Server

For example, if the error code is -10722, enter:

pidiag -e -10722
[-10722] PINET: Timeout on PI RPC or System Call
You can also use the pidiag utility to translate operating system error codes, which are
always positive numbers.

Subsyste m Health Checks (RPC Resolver Error Messages)

Every few minutes, the pinetmgr sends a health check message to each of the PI
subsystems. If pinetmgr does not receive a response within a given amount of time, it
generates the following message and the subsystem (RPC resolver) is marked off-line:
>> Deleting connection: pisnapss, Subsystem Healthcheck failed.
If an RPC is made to a subsystem that is marked off-line, you will see this message:
[–10733] PINET: RPC Resolver is Off–Line
The output will include details if only the first part of a message was retrieved. In this
example, the message contains the message length. However, a timeout occurred when the
pinetmgr attempted to retrieve the rest of the message:
>> Deleting connection: pisnapss, Connection lost(1),
[-10731] PINET: incomplete message

Log Files

During normal operation, the PI Message Subsystem maintains central log files for messages
from all PI Server subsystems. PI Server creates a new log file every day, on universal time
coordinate (UTC) time, puts the log files in the PI\log directory and names each log
according to the date. The file names use the format, pimsg_YYYMMDD.dat, where:
• YYY is years since 1900. For example, if the year is 2007, YYY is 107.
• MM is the month. For example, if the month is January, MM is 01.
• DD is the day. For example, if it is the fifth of the month, DD is 05.
For example, the log file for January 5, 2007 is named pimsg_1070105.dat.
You can use the PI SMT Message Logs tool or the pige tmsg utility to view these PI Message
Log files and search for messages by time, subsystem, source, severity, or message ID. PI
Server must be running to view messages.
The PI Server creates a new log file every day and stores them for 35 days, before it
automatically purges log files. To keep log files beyond 35 days, you must back up the log
files before the PI Server deletes them. Then, if necessary, you may restore and investigate
the backed up files later.

132
 Window s Performance Counters

Windows Performance Counters

You can use key Windows performance counters to review statistics about all PI subsystems.
These counters may be viewed with the Windows Performance Monitor or recorded to PI
Server with the OSIsoft Performance Monitor Interfaces.

PI Server System Management Guide 133

Chapter 8

Move or Merge PI Servers

Move PI Servers
PI Servers are designed for platform independence. All the databases and tables are stored in
a format that allows you to:
• move a PI Server to a different computer, or
• move a PI Server to a different location on the same computer, or
• migrate a 32-bit PI Server that is running on Windows x64 to a 64-bit PI Server on the
same computer.
These instructions describe how to move a Windows- or UNIX-based PI Server that is release
3.2.332 or greater. If your PI System is an earlier release, upgrade it before continuing.

Note: To move a VMS-based PI Server, you must first migrate your PI Server version
2.x to PI Server version 3.x. See the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com/) for details on migrating VMS Servers.

Definitions

Term Definition
Source The original location of the PI Server before the move
Target The destination of the PI Server after the move
Buffering process Buffering of data occurs on the interface nodes w hile the PI Server is being
moved. Buffering processes include the PI Buffer Subsystem (pibufss) or the
API Buffer Server (bufserv).

Note: Some interface nodes can recover historical data from their data sources and
require neither the PI Buffer Subsystem nor the API Buffer Server. See
documentation specific to each interface to determine if an interface requires
buffering.

PI Server System Management Guide 135

Move or Merge PI Servers

Before You Begin

To minimize the amount of data buffered by interfaces, it is important to spend as little time
as possible completing the steps required to move a PI Server. OSIsoft recommends that you
review and become familiar with the procedure to move a PI Server before you begin.
To prevent data loss while moving a PI Server, take the following precautions:
• If the interface node uses buffering, verify that the buffering process is working properly.
To test buffering, remove the interface node from the network for a few minutes then
reconnect it. When the node is reconnected to the network, buffered data should be sent
to the PI Server and you should see a continuous flow of data in the application you use
to view PI Server data.
• If an interface node does not use buffering, verify that its history recovery process is
working properly. Remove the interface node from the network for a few minutes and
then reconnect it. When the node is reconnected to the network, the interface should
historically recover data from its data source and you should see a continuous flow of
data in the application you use to view PI Server data.
• If you plan on changing the IP Address or FQDN of the PI Server node during the move,
determine whether your interfaces connect by IP Address or by host name.
• Create a license activation file. The PI Server Installation and Upgrade Guide contains
instructions for this.

Basic Procedure: Move a PI Server to a Different Computer

You can use the procedures in this section to move a standalone PI Server, or tomove either a
primary or secondary PI Server in a collective. The basic procedure in this section can be
followed without alteration if the following conditions are met:
• The archive directory corresponds to the same drive letter and directory paths on the
source and target servers. Otherwise, alter the procedure according to Different Archive
Directory (page 139).
• The event queue directory corresponds to the same drive letter and directory paths on the
source and target servers. Otherwise, alter the procedure according to Different Event
Queue Directory (page 140), which also describes how to determine the event queue
directory.
• The fully qualified domain name (FQDN) for the source and target servers are the same.
Otherwise, alter the procedure according to Different FQDN (page 140).
• The IP Address for the source and target servers is the same. Otherwise, alter the
procedure according to Different IP Address (page 141).
• The basic procedure assumes the operating system for the source and target servers is
Windows. Otherwise, alter the procedure according to Moving from UNIX to Windows
(page 142).
If your PI Server Setup is not reflected in any of these scenarios, contact OSIsoft Technical
Support (page 233) before you begin.

136
 Move PI Servers

Step 1: Prepare the Target Server for the Move

Note: Install the same PI Server version on the target node that is installed on the
source node.

To prepare the target node:

1. Choose a target server for the install. At this point, the target node has a temporary name
and IP address.
2. Run the Machine Signature File (MSF) utility on the target computer to generate a license
activation file (pilicense.dat) for the target. You cannot use the license activation
file from the source computer.
3. Install the PI Server on the target computer. Observe the following when you prepare for
the ins tallation:
ο Specify a small archive size (such as 32 MB); you will delete these files later in this
procedure (step 5).
ο Specify the default directories for the archives and the event queue; these defaults
will be overridden when you copy the database files from the source PI Server.
4. Start the PI Server on the target node and perform some quick tests, such as running
PI\adm\pisnap.bat to verify that the PI Server installation was successful.
5. Stop the target PI Server.
6. Delete the three temporary archive files and the associated annotation files that are
created during the installation.

Step 2: Prepare the Source Server for the Move

After completing Step 1, prepare to move and then decommission the source node:
1. Verify that there are some empty archives registered on the source PI Server. Build and
register a few new archives if necessary. Some empty archives will be moved to the
target PI Server later in the procedure.
2. Force an archive shift on the source node. You can use the SMT Archives tool
(Operation > Archives) to do this.

Note: Forcing a shift ensures that the primary archive is nearly empty. When the
target node is eventually brought online, a flood of events will come in from
the buffered interface nodes, which can cause a nearly-full archive to shift. It is
better to force a shift ahead of time under controlled conditions.

3. Run the piartool -al command on the source PI Server and redirect the output to a file.
Record this file location; you will use the output later in the procedure to determine
which archive to move to the target node first.
4. Determine the directory where the PI Server writes its event queues. This directory is
determined by the Snapshot_EventQueuePath tuning parameter.

PI Server System Management Guide 137

Move or Merge PI Servers

You can dump all tuning parameters with the following command:
piconfig table pitimeout ostru name,value ends exit
If Snapshot_EventQueuePath does not appear in the output, the event queue
directory is PI\dat.
5. Stop the source PI Server.
6. On the source server, use the Windows Control Panel to disable the PI Network Manager
Service. Disabling PI Network Manager ensures that the PI Server on the source
computer is not restarted accidentally.
7. Assign a new IP Address to the source node and rename it.
8. Restart the source node so that the new IP Address and source server name take effect.
The PI Server will not start again after the restart, provided you disabled the PI Network
Manager Service on the source server.

Step 3: Move Files from Source to Target

After you have prepared both servers for the move, use these guidelines to copy the server
files from the source PI Server to the target PI Server:
• Copy all script files, that is, .bat files, from PI\bin and PI\adm to the
corresponding directory on the target.
• Copy all files in the PI\log directory from the source computer to the corresponding
directory on the target.
• Use the following guidelines to determine which Archive files to copy to the target PI
Server. Copying selected archive files reduces the time required for the move, so that less
data is buffered on the interface nodes.
ο Copy the primary archive, the previous archive, and one or two empty archives to the
target PI Server. You can move and register additional archives when the target PI
Server is up and running. To decide how many archives to copy to the target PI
Server, note if there are any points with Snapshot values earlier than the start time of
the oldest archive that you copy. If so, set the shutdown attribute to 0 for these points.
This setting will prevent -11043 errors when the target PI system is first started.
ο It is important to copy empty archives to the target PI Server because buffered data
from interface nodes will be dumped to the target PI Server when it is finally brought
online. The data from the buffered nodes may cause an archive shift.
ο When moving an archive, make sure that you also move the corresponding
annotation file. Annotation files have the same full path names as the archive files but
end with the .ann extension.
• Copy the files in the PI\dat directory to the target, except for the archives and the
licens e activation file, pilicense.dat. You cannot use the license activation file
from the source computer on the target. You generated the license activation file for the
target computer in Step 1.
• If event queue files are not in the PI\dat directory, copy all files from the event queue
directory to the corresponding directory on the target node.

138
 Move PI Servers

Step 4: Bring the Target PI Server Online

Complete the following steps to finalize the move to the target PI Server and ensure that it
functions correctly:
1. Change the IP Address and node name of the target node to that of the source PI Server
node and reboot the target PI Server.

Note: If you configured the target PI Server to restart services automatically, the PI
Server starts and collects data after the reboot. If you want to prevent the PI
Server from starting after a reboot, disable the PI Network Subsystem Service
before rebooting, and then enable it after the reboot.

2. If the PI Server is not started after the reboot, start it manually with the
PI\adm\pisrvstart.bat command. The server should begin collecting data from
the buffered interface nodes.
3. Examine the PI Message Log. If you have intentionally not copied all archives to the
target PI Server node, you will see archive files not found errors, which can be ignored.
4. Copy the remaining archives from the source node. Restart the PI Archive Subsystem on
the target node to bring the remaining archives online.
5. Verify that the target node PI Server is functioning correctly. For example, verify that PI
Performance Equations, PI Totalizer, and PI Alarm perform as expected.
6. Configure backups on the target node. See Back up the PI Server (page 97).
7. Verify that the full path names in site-specific files, such as pisitebackup.bat, are
still valid.

Exceptions to the Basic Procedure

Different PI Installation Directory

If the target PI Server installation directory (%PIServer%) uses a different drive letter or
directory path than the source nodes, alter the basic procedure as follows:
• Change to Step 3: When copying the %PIServer%\dat\ directory, do not copy the
pisubsys.cfg file. The PI Server on the target node will not start if the
pisubsys.cfg file contains a path that does not correspond to the installation
directory.

Different Archive Directory

If the archives on the source node and target node use different drive letter or directory paths,
or you prefer to store your archives in a different location, alter the basic procedure as
follow s:
• Change to Step 3: Copy the primary archive, the previous archive, and one or two empty
archives to the desired archive directory on the target PI Server node, rather than to the
corresponding directory. Unlike the basic procedure, only the Primary Archive will be
registered when you initially bring the PI Server online in step 4. If there are any points
with a Snapshot values set before the start time of the Primary Archive, set the shutdown

PI Server System Management Guide 139

Move or Merge PI Servers

attribute to 0 for these points. This setting will prevent -11043 errors when the target PI
system is first started.
• Change to Step 4: Register a new primary archive when the target PI Server is not
running before you reboot and continue with the remaining Step 4 tasks.

Note: The primary archive on the target server must be available and have enough
free space to handle a potential flood of buffered events from interface nodes,
because no empty archives will be available on the target server for an
archive shift. In this case, archives are stored in a new location and the PI
Server does not register them automatically when started on the target node.

ο To register the primary archive in a new location, run the pidiag -ar command.
When prompted, enter the full path name of the primary archive file copied to the
new archive location on the target PI Server. This creates a new
PI\dat\piarstat.dat file with only the primary archive registered.
ο As an additional precaution, you may want to disconnect the target server from the
network while initially bringing the target PI Server online. This allows you to
register the remaining archives before the flood of events from buffered nodes.
• Change to Step 4: After the target PI Server is bought online, only the primary archive
will be registered. Register the remaining archives with the piartool -ar command. You
can use wildcard characters to specify archive names to register archives in bulk.

Different Event Queue Directory

If the event queue directory on the target node uses a different drive letter or directory path,
you will need to change the basic procedure.
The event queue directory is determined by the Snapshot_EventQueuePath timeout
parameter. You can dump all timeout parameters with the following command:
PI\adm\piconfig table pitimeout ostru name,value ends exit
If Snapshot_EventQueuePath does not appear in the output, the event queue directory
is \PI\dat.
Alter the basic procedure as follow s:
• Change to Step 2: Before stopping the source PI Server, edit the
Snapshot_EventQueuePath timeout parameter to point to the desired event queue
path on the target PI Server.
You may make this change on the source PI Server because changes to
Snapshot_EventQueuePath do not take effect until the PI Snapshot Subsystem is
restarted.
• Change to Step 3: Copy the event queue files to the newly specified event queue
directory on the target node.

Different FQDN
The following considerations apply to the basic procedure if the target node has a fully
qualified domain name (FQDN) different from the source node:

140
 Move PI Servers

Note: Although this section describes many complicating factors that can arise from
changing the FQDN, it is not an exhaustive list. Contact OSIsoft technical support
if you have questions about changing the FQDN of the PI Server.

• While the source and target PI Servers are down, shut down the buffering process and
interfaces on all interface nodes. Configure the buffering process to point to the target PI
Server using the new FQDN. Change the startup command file for each interface to point
to the new server node.

Note: A consequence of changing the FQDN is that data cannot be collected or

buffered during the time period between stopping the source server and
starting the target server.

• Bring the target server online and export the PI Module Database from the source node PI
Server, using the PI Module Database Builder add-in for Excel. Search for and replace all
references to the old server name with the new target server name. Then import the PI
Module Database contents into the target PI Server.
• Edit the PI SDK Known Servers Table (KST) on computers where SDK client
applications, such as PI ProcessBook and PI DataLink, are used. Leave the old entry in
the KST and change the pointer to the network node to reflect the new target server.
• All PI Servers are identified by the server hostname that is stored as ServerID in the
PIServer database table. When the PI Server is moved to a machine with a different
hostname, it is automatically given a new entry in the PIServer table the first time it runs.
To transfer the ServerID use piconfig to copy the ServerID of the target server from the
existing server. This approach allows you to transfer the ServerID without creating a new
entry and thereby avoid client application connection problems. For example, if
oldname is the previous name of the server and newname is the new name of the
server:
* (Ls - ) PIconfig> @tabl piserver
* (Ls - PISERVER) PIconfig> @ostr name,ServerID
* (Ls - PISERVER) PIconfig> @sele name=oldname
* (Ls - PISERVER) PIconfig> @ends
oldname,9166a4b4-7600-4fd8-8557-f20693fff729
* (Ls - PISERVER) PIconfig> @mode ed
* (Ed - PISERVER) PIconfig> @istr name,ServerID
* (Ed - PISERVER) PIconfig> oldname,0
*> oldname,0
* (Ed - PISERVER) PIconfig> newname,9166a4b4-7600-4fd8-
8557-f20693fff729
*> newname,9166a4b4-7600-4fd8-8557-f20693fff729

Different IP Address
If the target node has a different IP address, alter the basic procedure as described in this
section:

PI Server System Management Guide 141

Move or Merge PI Servers

• As long as interfaces connect via the PI Server name rather than IP address, no corrective
action need be taken on interface nodes. If interfaces connect by IP address, the
procedures used to move the server using a different FQDN apply also to interface nodes.
• Change to Step 2: If PI Trusts are configured for the old server IP address, add a trust for
the new IP Address before stopping the source server.
You can remove a trust for an old IP address at any time after a move is complete. The IP
address of the server node is not required in the TRUST table unless there are interfaces
that run on the same machine as the PI Server and that connect by IP address.

Different Time Zone

If you are moving a PI Server to a different time zone, alter the basic procedure as described
in this section:
Change to Step 3: Do not include the file localhost.tz when you copy files from the
PI\dat directory.

Moving from UNIX to Windows

The following exceptions to the basic procedure apply when moving the PI system from a
UNIX server to Windows:
• Substitute UNIX path names for all Windows path names. For example, PI\dat\
might correspond to /opt/pi/dat on UNIX.
• Change to Step 2: The basic procedure calls for disabling the PI Network Manager
Service on the source node. Since there are no services on UNIX, rename the pinetmgr
executable in the /opt/pi/bin directory instead.
• Change to Step 3: UNIX script files us e an .sh rather than a .bat extension, and it
generally does not make sense to copy .sh files to Windows. Manually reconfigure all
script files on the target Windows server node when moving from UNIX. Most of the
time the only script that needs to be configured is pisitebackup.bat.

Move the PI Server to a Different Directory on the Same Computer

To move a PI Server to a different directory on the same computer, follow these steps:
1. Move Archives
2. Move the PI Installation Directory
If you prefer not to move the directory where your archives are registered, skip to Move the
PI Installation Directory (page 143).

Move Archives
1. Create a new directory for the archives.

142
 Move PI Servers

2. In the new archive directory, create a new archive and force an archive shift. You can use
the SMT Archives tool (Operation > Archives) to do this. After the shift, the new
primary archive will be the archive that you created.
3. Move each archive to the new archive directory, as follows:
a. Unregister the archive (you can use the SMT Archives tool).
b. Move the archive and the associated annotation file to the desired location.
c. Reregister the archive (you can use the SMT Archives tool).

Move the PI Installation Directory

1. Back up your PI Server with the following command:
piartool -backup backupdir -numarch 1 -arcdir –wait
where backupdir is a temporary backup directory that does not correspond to your normal
backup directory. Although the primary archive is backed up with this command, the
purpose of this step is to back up non-archive files. The non-archive files are copied from
backupdir in a later step.
2. Isolate your PI Server from the network. This forces buffering of data on the interface
nodes.
3. Run piartool -qs and monitor the output until the Event Queue is empty.
4. Shut down the PI Server with the pisrvstop.bat command.
5. Uninstall the PI Server. The uninstall process does not delete your archive files or the
other PI Server databases.
6. Install the PI Server in the newly desired PI Server installation directory. The version of
the PI Server that you choose for the installation should be the same version as was
previously installed. When you install PI Server:
a. Choose a temporary archive directory for use during the installation; the archive files
are deleted in a later step.
b. Select a small archive size (such as 32 MB).
c. Select the final destination for your event queues during the installation.
7. Before starting the PI Server, verify that the PI Server is isolated from the network.
Otherwise, the buffered data on the interface nodes will be lost.
8. Start the PI Server. Verify that the PI Server was installed successfully by running
pisnap.bat and spot-checking the values of a few PI points.
9. Shut down the PI Server with the pisrvstop.bat command.
10. Delete the temporary archive files and the temporary archive directory that were created
during the installation.
11. From the backup performed in step 1, use the following guidelines when you copy the
files from backupdir to the new PI Server directories:
a. Do not copy the archive (or archives) that were backed up to backupdir\arc. All
archives should already be in their final destination.

PI Server System Management Guide 143

Move or Merge PI Servers

b. Copy all files from backupdir\dat to PI\dat.

c. Copy all files from backupdir\log to PI\log.
d. Copy all files from backupdir\bin to PI\bin.
e. Copy all files from backupdir\adm to PI\adm.
12. Start the PI Server.
13. Verify that the archives in the new archive directory are still registered by using the
piartool -al command.
14. Reconnect your PI Server to the network. Data collection should resume from the
buffered server nodes.

Merge PI Servers
You can merge data from multiple PI Servers if would like to retire a PI Server yet preserve
its data. Use the merge process to stop using two or more PI Servers and transfer all data onto
another PI Server.

Summary of Merge Process

Complete these steps to prepare for a merge of two servers:

1. Determine if the servers you will merge contain batch data stored in either the PI Batch
Subsystem or the PI Batch Database.
2. Create a complete list of points and archives. For details, see List Points and Archives to
be Merged (page 146).
3. Compare the list of points from the retired system to the points on the destination server;
rename any points that have identical names. See Modify Points on the Destination
Server (page 146) for details.
4. Create a Point ID Conversion table on the retired system. For details, see Create a Point
ID Conversion Table (page 147).
5. Update the Digital State Table, for servers containing digital PI points. For details, see
Update the Digital State Table and Digital Tags (page 147).
Use these steps to complete the merge of two servers:
1. Install the PI points you want to preserve from the retired system to the destination
system, see Create Points on Destination Server (page 149) for details.
2. If your PI Server includes PI Batches stored in the PI Batch Database, see PI Batch
Database Considerations (page 145). If your PI Server includes batch data stored in the
PI Batch Subsystem, see PI Batch Subsystem Considerations (page 145 ).
3. Stop all interfaces that are sending data to the PI Server if they haven't been stopped yet.
For details, see Stop Cutover Interfaces (page 149).

144
 Merge PI Servers

4. Force an archive shift on the PI Server to be retired. See Force a Shift on the Retired
System (page 149) for details.
5. Shut down the retired PI Server. For instructions on how to stop a server, see Start and
Stop the PI Server (page 17).
6. Transfer Archives from the retired server to the destination server. See Manage Archives
(page 69) for instructions on how to transfer archives.
7. Create a Binary ID Conversion table on the destination server. See Create Binary ID
Conversion Table on Destination System (page 149) for details.
8. Convert the Retired Archives. See Reprocess the Archives on the Destination Server
(page 150) for details.
9. Verify that the merge is complete.

Determine if You Will Merge Batch Data

You must follow special steps to merge systems containing batch data. There are two types of
data stores for batch data in the PI Server; you must use different procedures to maintain and
process each of these distinct data stores. Batch data may be stored in either the PI Batch
Subsystem, or the PI Batch Database. To ensure you successfully merge batch data from your
PI Servers you must follow the procedures for each type of batch data stored on your PI
Server. For more information, see PI Batch Database Considerations (page 145) and PI
Batch Subsystem Considerations (page 145 ).

Note: If you are merging two PI Servers and only one server has Batch data, replicate
the PI Server that has the Batch data to the destination PI Server, as described in
Move PI Servers. Then follow the instructions in Merge the PI Servers (page 149)
and Merge Batch Data (page 151).

PI Batch Database Considerations

If your PI Server stores Modules created in SMT, or you have PI Batches, UnitBatches, or
SubBatches, PI Batches and Modules must be moved independently of points.
For details, see Merge Batch Data (page 151).

PI Batch Subsystem Considerations

The PI Batch Subsystem stores batches in automatically created points. To merge batches
stored in the PI Batch Subsystem, it is critical that you:
• Identity the points stored in the PI Batch Subsystem; look for the format pibaN, where N
is an integer unique to the unit.
• Do not convert these points to the destination system when you Create a Point ID
Conversion Table (page 147).
• Move batches independently of the points.

PI Server System Management Guide 145

Move or Merge PI Servers

For details, see Merge Batch Data (page 151).

Prepare the PI Servers

List Points and Archives to be Merged

To prepare for the merge of PI Servers, list all points and point attributes and all archives on
both the server to be retired and on the destination server.
Use these lists when you Modify Points on the Destination Server (page 146 ) to compare the
data on both servers and decide if any points and archives need to be renamed.

Note: You can also use these lists at the end of the merge process to verify the merge is
complete.

Modify Points on the Destination Server

1. Compare the list of points from the retired system to the list of points from the destination
server.
2. Determine if there are any points that have the identical names on both systems.
3. Rename any such points to ensure that duplicate point names do not exist on the retired
and destination servers.
Remember: point attributes depend on the point class; not all points have the same
attributes. Therefore:
ο Required point attributes are specific to each interface. If you do not know which
point attributes apply to each interface, dump all point attributes for all points, except
the PointID and RecNo attributes.
ο If a point name is the same on both systems and both have the same attributes, no
special steps are required. When you merge the retired point, the events for that point
are perceived as out-of-order events and are merged into the history of the point on
the destination server.
ο If the point name is the same on both systems and the points are not identical, you
must rename of one of the points. Normally the conflicting retired point is renamed;
although either point may be renamed.
ο Before you start the merge process, you should complete renames of points.

Note: All points do not need to be merged; just the points with a history that you
want to preserve.

4. Default points such as sinusoid have identical names on both servers. If you want to
preserve the history of default points on the retired server, rename the points. Otherwise,
delete the default points from the retired server.

146
 Merge PI Servers

Create a Point ID Conversion File

To convert the retired archives to the destination system, you must map the retired record
numbers to the record numbers of the destination system. The mapping is established with a
text file, which links the retired system PointIDs, RecNos, and tags to those on the
destination system.
To create the text file:
1. Use the following piconfig script to create the input for the conversion table:
@table pipoint
@ostr pointid,recno,tag
@select tag=*
@output output.txt
@ends
@exit

Note: This example assumes all tags are being merged. If all tags are not merged,
edit the output file or use a tag selection of other than "tag=*".

The ID conversion input file must only have entries of the format:
pointid,recno,tag
2. If your server has data stored in the PI Batch Subsystem, delete pibaN tags from the
input file, where N is an integer, from the input file you created for the Point ID
Conversion Table. You will move these points separately when you follow the
procedures in Merge Batch Data.
3. If your PI server stores data from the Batch Database or Module Database, delete storage
points for the Batch Database. To recognize storage points, look for these characteristics:
ο A point class of Base
ο Long GUIDs
ο A description that indicates the points are storage points for campaign, Batch,
UnitBatch or transfer records.

Note: Ensure that a new line follows the last entry of the input file.

PI Server System Management Guide 147

Move or Merge PI Servers

Update the Digital State Table and Digital Tags

1. Review the Digital State tables on the old server and the destination server; compare the
tables and determine which digital state sets exist on the server that will be retired but do
not exist on the destination server. Then, use PI Server Management Tools (SMT) to
complete these steps:
a. Export digital state sets that exist on the server that will be retired but do not exist on
the destination server.
b. Import these digital states sets to the destination system.
2. To use piconfig to add a digital state set, see Add a Digital State Set (page 148).

Caution: If a digital set from the retired system already exists in the target system, verify
that the digital state sets names are identical for both servers before you complete
the merge. If the names are not identical, rename the digital state set before
transferring it to the new server.

Digital points created on the target system are assigned a digital set by name. During archive
conversion, only the offset is preserved, thus the data is interpreted according to the point's
current digital-set.

Add a Digital State Set

To add a digital state set to the Digital State table, use piconfig as shown in this example:
1. Select the Digital State table
(Ls - PIDS) piconfig> @table pids
2. Prepare to write to the table
(Ls - PIDS) piconfig> @mode create
3. Specify an input data format of a digital state set name followed by any number of states
in the set. Follow this with a data line.
(Cr - PIDS) piconfig> @istructure set, state, ...
(Cr - PIDS) piconfig> ValveStateSet, Open, Closed
4. Next, list the new state set in order to verify that it was properly created. Select only
those sets that start with “V.” Use an endsection command to force processing:
(Cr - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set, state, ...
(Ls - PIDS) piconfig> @select set=V*
(Ls - PIDS) piconfig> @endsection
VALVESTATESET,Open,Closed
(Ls - PIDS) piconfig>

Note: The endsection command is not needed when creating the state set because
data lines are processed as they are entered.

148
 Merge PI Servers

Merge the PI Servers

Create Points on Destination Server

Install on the destination system all points from the retired system that you want to include on
the destination system. Use piconfig or Tag Configurator and the point list from the retired
system to create the points on the destination server.

Note: If your server includes PI Batches, Module Database data, or data created by the
PI Batch Subsystem, see Merge Batch Data (page 151).

Stop Cutover Interfaces

At this time, interfaces feeding data to the retired system should be stopped. If appropriate,
restart the interfaces pointing to the destination system. If the interfaces are restarted against
the destination system, check interface output for errors and address any problems before
proceeding.
On the retired system run pishutev to put shutdown events into the Snapshot. This will
force the Snapshot value into the Archive.

Force a Shift on the Retired System

Force a shift on the retired system. This makes the archives' end time consistent on the retired
system, and makes management of the Archive merge easier.
Run piartool -al to get a list of all archives. Save this list for reference when converting the
archives.

Shut Down the Retired System

At this point the retired system is no longer needed. Shut down the retired system. For details,
see Shutting Down a Retired System (page 161).

Create Binary ID Conversion Table on Destination System

The input file that is generated when you Create a Point ID Conversion Table (page 147) is
the source for creating the ID conversion table. This table maps the tags from the old system
into the new one. The piartool utility creates the ID conversion table; the syntax is:
piartool -idci text_file_path -idco binary_file_path.bin
where text_file_path is the full path to the text file, including the text file name and
binary_file_path is the full pathname for the binary file to create.
This command is run on the destination system.

PI Server System Management Guide 149

Move or Merge PI Servers

Reprocess the Archives on the Destination Server

The offline archive features of piarchss are used to reprocess the non-primary archives on the
destination server. This is done to create record numbers for the points that will be transferred
later from the old server. To do this, use the following syntax on the non-primary archives on
the destination system:
Piarchss -if arhive1 -of newarchive
After the non-primary archives are reprocessed, you can start adding data to the archives for
the points transferred. To transfer tag data from the archives of the system to be retired to the
archives in the destination system, use the offline archive utility, the Binary ID conversion
table file, and the retired archives which contain the data. The syntax is:
piarchss -id ID
-if retired_archive_path
-of converted_archive_path
Where ID is the full path to and filename of the binary ID conversion file. The
converted_archive_path should be either the primary archive, which did not need the first
reprocessing, or the most recently reprocessed non-primary archive. This
converted_archive_path will then include the data for the time range in the destination system
and the data of the system to be retired within the time range of the retired_archive_path.
Before you register the reprocessed archives on the destination system, you must check to see
if there are any time overlaps between the archives on the destination system and the
reprocessed archives. The solution is to force a shift and combine the converted archive with
the destination archive.
There are a few things to consider when converting archives. By default, the offline archive
utility creates dynamic type archives. That is, they are not shiftable. When you convert to a
fixed size archive, there must be enough disk space for all used records in both archives being
combined. The -f argument may be used to force output archives to a fixed size. If you are
unsure about the disk space, use dynamic archives, as they can always be moved into a fixed
size archive later.
One strategy to convert the retired archives is as follows:
1. Reprocess the oldest archive in the destination server to create record numbers for the
points transferred from the old server.
2. Reprocess this converted archive using the binary ID conversion file to map record
numbers from the old archives to the new archives.

Note: This step will add data to the points transferred from the old server in the new
server archives; the output archive time range of the converted_archive_path
will be adjusted to that of the retired_archive_path.

3. Compare the data with the retired system to ensure correct conversion before proceeding
with other archives.
4. Proceed with the archive processing from oldest to newest and observe the changes in the
archive time ranges. If there are any overlapping archives in the converted archives, you
will need to use the offline archive utility to further process and combine these archives.
This may be time consuming, especially if there are many overlapping archives.
5. Register and view archives as they are completed.

150
 Merge PI Servers

For a detailed example of the archive conversion process, see Reprocess the Archives (page
162).

Merge Batch Data

Note: Complete the steps explained in Prepare the PI Servers (page 146) and Create
Points on Destination Server (page 149) before you start the steps explained in
this section.

Merge Batches from PI Batch Subsystem

To merge batches from the PI Batch Subsystem, you must complete these steps:
1. Use the piconfig utility to dump all existing batches and unit configuration.
2. Rename unit names that conflict between the two systems; to do so, rename the
references to the conflicting units in the piconfig dumps.
3. Create the PI Batch Database units on the destination system.
Use the PIBatch Unit table listing to create the units on the destination system. The
batches are created after the archives you Reprocess the Archives on the Destination
Server (page 150). All pertinent unit configuration information must be listed.
4. Use piconfig to install the input file from the PI Batch dump into the system. If all
archives were merged, there should be an archive on line to receive the batch. If not all
archives were migrated, batches for those dates will not be created.
For a detailed example, see Point and PI Batch Configuration on Retired Server.

Regenerate Data from the PI Batch Database

PI Unit Batches have references to the PI Modules from which they were generated. These
references are stored inside the annotation files that contain the PI Unit Batch data. When you
move annotations to another PI Server, they will have references to the PI Module annotation
files from the server from which you want to transfer data.
To explain how to merge Batch Unit data, here are two potential scenarios: you have two
existing PI Servers with data and one new destination PI Server. Either one PI Server has
Batch data or both PI Servers have Batch data.
If only one PI Server has Batch data, you must simply replicate the PI Server that has the
Batch data on it to the destination PI Server, as described in Move PI Servers. Then, follow
the instructions to Merge the PI Servers (page 149) to copy over data from the other PI
Server.
If both PI Servers have Batch data, you must re-generate the Batch data from one of the PI
Servers, move one of the PI servers to the destination server and then follow steps in Merge
the PI Servers (page 149).

PI Server System Management Guide 151

Move or Merge PI Servers

MERGE PI BATCHES
1. Identify all the active tags (for UnitBatches, SubBatches) and all batch property tags
(BatchID, ProductName, PIBatch Index, etc).
2. Verify that all these tags exist on the destination PI Server. If you have not yet copied
tags to the destination system, see Prepare the Destination Server.
3. Using Module Database (MDB) Builder, import all the PI Units and PI Modules and
export them to the destination PI Server. Include the full module path when importing
and edit all server name entries to the correct value before exporting. For details, see
Merge Module Database Servers (page 153).
4. If the destination server already has the PIBaGen module, then edit the Properties to
match the property settings on the retired system. If there is no PIBaGen module on the
destination server then you must import the module from the old server by either using
the Module Database Builder or by dragging and dropping using System Management
Tools (SMT) as follows:
a. Under the %OSI module on the retiring system, find the module called PIBaGen.
Import this module and all its PIProperties. It should not have PIAliases.
b. If you are using the Module Database Builder, export these properties to the
destination server.
5. If there are PIHeadings on the retired server, then re-create all the PIHeadingSets and
their PIHeadings with the same name and level number on the destination server. You
can copy and paste PIHeadingsSets from one PI Server to another with the PI SMT
Module Database Plug-in.
6. If the destination server is a PI 3.4 or later server, then go to step 8. If the destination
server is PI 3.3 Server, then using MDB Editor on the destination server, add a dummy
PIUnitBatch (start time and end time do not matter), and then delete it. This action will
create the necessary header/tags for the PIUnitBatch storage. Also, add a dummy PIBatch
and delete it. This action will create the PIBatch storage. On a PI 3.4 server, the unit
batch storage tag is created as soon as the PIUnit is created and the PIBatch storage tag is
created during installation.
7. Stop all interfaces that are sending data to the PI Server. For details, see Stop Cutover
Interfaces (page 149). Then, continue with the remaining steps in Merge the PI Servers
(page 149).

Verify the Merge of Batch Data

To verify that the merge of batch data was successful:
1. Select the MDB View tab on the Batch Generator plug-in of SMT. For each unit that is
registered for PIBaGen, check the configuration for the UnitBatches, SubBatches and PI
Batches to verify that the migration is successful.
2. Set the Recovery Time as far back as you want to recover data. There is no restriction on
how far back in time you want to recover data. For more details on how recovery works,
see the PIBaBen 2.0 manual.
3. Ensure that you select the correct setting for Recovery Options.

152
 Merge PI Servers

If you would like to make any changes to the SubBatch Hierarchy, do it after you have
verified the batch data was successfully merged. PIBaGen 1.x had only one level of
SubBatches. PIBaGen 2.x can create configuration for hierarchical subbatches. In order to
achieve that, the configuration must be modified after migrating. See the help files for the PI
SMT Batch Generator plug-in for details about how to configure SubBatch hierarchy.
Save the configuration if any changes are made. If the unit is not Registered (the Register
button is disabled and the Unregister button is enabled), then Register it if you want PIBaGen
to recover batches on that unit. Registering a PIUnit is equivalent to turning the SCAN ON
for a traditional PIPoint.
Start the PIBaGen Interface. Please note that the interface might take up considerable amount
of resources and time to recover all the batches for all these units. It really depends on how
many events need to be recovered. If you think there would be a lot of events, you can try
registering one unit at a time.

Merge Module Database Servers

To merge data from a Module Database Server, you can copy and paste PI Modules, their
hierarchies and their history to another PI Server using the Module Database add-in of the
Tag Configurator. If you do not have this add-in, you may need to download it from the
OSIsoft Technical Support Web site at http://techsupport.osisoft.com
(http://techsupport.osisoft.com).
A typical situation for this scenario is when you want to retire a server that contains a Module
Database and transfer its data onto a new server.
The steps to merge data from a Module Database server onto another server are:
1. Run PI SMT 3.x and open the Module Database plug-in.
2. Use SMT to connect to both PI Servers, that is, the server you want to retire and the
destination server.
3. Select and copy the parent module on the source server that contains the entire hierarchy
to copy.
4. Open the destination PI Server and right-click in the location where you want to paste the
module hierarchy.
5. You will see three paste options:
Paste Value
Paste Hierarchy
Paste Value Hierarchy
6. Select Paste Value Hierarchy to get the module, the children of the module, and
all the values and history associated with the modules. Choose Paste Hierarchy if
you want to paste just the Module Hierarchy, but have no values associated with it.

Note: You cannot merge Batch data this way. For details on how to merge data from a
batch database, see Merge Batch Data (page 151).

PI Server System Management Guide 153

Move or Merge PI Servers

Server Merging Examples

The following example retires a small PI System and merges it with an existing larger PI
System. Both systems consist of example points provided with installation. The tags on the
retired system were edited to create unique tags.
Here is the archive list and point list of each system before starting the merge:

Retired Server
This list indicates the points that will be merged from the retired system to the destination
system. Point names have been modified.

BA:Active.1
BA:CONC.1Retired
BA:LEVEL.1Retired
BA:PHASE.1Retired
BA:TEMP.1Retired
batchid-1Retired
CDEP158Retired
CDM158Retired
CDT158Retired
piba1
pipe:sine2Retired
pipe:sine2tRetired
pipe:sine3Retired
pipe:sine4Retired
pipe:sine5Retired
pipe:sineRetired
pitot1Retired
pitot2Retired
pitot3Retired
pitot4Retired
pitot5estRetired
pitot5rampRetired
pitot5Retired
pitot5runRetired
pitot6countRetired
pitot6timeNERetired
pitot6timeRetired
pitot_1Retired
pitot_avgRetired
pitot_maxRetired
pitot_minRetired
productid-1Retired
sin:h2Retired
sin:hourRetired
SINUSOIDRetired
SINUSOIDURetired
t_minRetired
t_state1Retired
Archive: D:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.002
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1

154
 Merge PI Servers

Record Size: 1024 Count: 2048

Offsets: Primary: 39/512 Overflow: 2025/2048
Start Time: 2-Mar-05 12:51:41
End Time: Current Time
Backup Time: Never
Archive: D:\PI\dat\piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.003
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 2047/2048
Start Time: 2-Mar-05 12:50:27
End Time: 2-Mar-05 12:51:41
Backup Time: Never
Archive: D:\PI\dat\piarch.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 1901/2048
Start Time: 25-Feb-98 14:16:40
End Time: 2-Mar-05 12:50:27
Backup Time: Never

Destination Server
This list reflects all of the points and archives that are currently on the destination system.
Use this list to compare points to ensure that duplicate point names do not exist.

BA:ACTIVE.1
BA:CONC.1
BA:LEVEL.1
BA:PHASE.1
BA:TEMP.1
batchid-1
CDEP158
CDM158
CDT158
piba2
pipe:sine
pipe:sine2
pipe:sine2t
pipe:sine3
pipe:sine4
pipe:sine5
pitot1
pitot2
pitot3
pitot4
pitot5
pitot5est
pitot5ramp
pitot5run
pitot6count
pitot6time

PI Server System Management Guide 155

Move or Merge PI Servers

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

156
 Merge PI Servers

Start Time: Current Time

End Time: Current Time
Backup Time: Never

Point and PI Batch Configuration on Retired Server

Notice that the tag BA:Active.1 on the retired system conflicts with destination system.
This tag must be renamed before proceeding. This tag is also used as the batch active tag for
Reactor1. When adding the unit Reactor1 to the destination system, this change must be
accounted for. Here's the dialog of the tag rename:
D:\PI\adm>piconfig
* (Ls - ) PIconfig> @table pipoint
* (Ls - PIPOINT) PIconfig> @mode edit
* (Ed - PIPOINT) PIconfig> @istr tag,newtag
* (Ed - PIPOINT) PIconfig> ba:active.1,ba:active.1Retired
*> ba:active.1,ba:active.1Retired
Also, the tag piba1 exists on both systems. This is a PI Batch point and must not be
migrated.
The retired server has one PI batch unit that is merged. The unit is a demo unit, but is treated
as a unique unit in this case; it will require some modification to prevent conflicts with the
demo unit on the destination system.
The first step is to dump the unit configuration to a text file:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @?atr
1 - UnitName (D) (C)
2 - NEWUnitName (D) (C)
3 - ActiveTag (D) (C)
4 - ActiveType (D) pulse (C)
5 - BIDExpr (D) (C)
6 - DataAccess (D) o:rw g:r w:r (C)
7 - DataGroup (D) piadmin (C)
8 - DataOwner (D) piadmin (C)
9 - Description (D) (C)
10 - EvalDelay (D) 0 (C)
11 - ProdExpr (D) (C)
12 - UnitAccess (D) o:rw g:r w:r (C)
13 - UnitGroup (D) piadmin (C)
14 - UnitOwner (D) piadmin (C)
* (Ls - PIBAUNIT) PIconfig> @Ostr
unitname,activetag,bidexpr,description,prodexpr
* (Ls - PIBAUNIT) PIconfig> @ends
*piconfig Err> Wild-card specs. missing, default to '*'...
Reactor1,ba:active.1,'batchid-1',Reactor 1,'productid-1'
For this unit, several attributes are set to default values; only attributes unique to this unit are
dumped. Since this unit's configuration conflicts with a unit on the destination system the
attributes require editing before input. Here's the content of the input file after editing:
@table pibaunit
@mode create
@istr unitname,activetag,bidexpr,description,prodexpr

PI Server System Management Guide 157

Move or Merge PI Servers

Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'", "Retired
Reactor 1","'productid-1Retired'"

Create ID Conversion File

The ID conversion text file is created on the retired system by running the following piconfig
script:
@table pipoint
@ostr pointid,recno,tag
@select tag=*
@output retiredidconv.txt
@ends
@exit
D:\PI\adm>type retiredidconv.txt
9,9,ba:active.1Retired
8,8,BA:CONC.1Retired
7,7,BA:LEVEL.1Retired
10,10,BA:PHASE.1Retired
6,6,BA:TEMP.1Retired
11,11,batchid-1Retired
5,5,CDEP158Retired
4,4,CDM158Retired
3,3,CDT158Retired
13,13,piba1
34,34,pipe:sine2Retired
35,35,pipe:sine2tRetired
36,36,pipe:sine3Retired
37,37,pipe:sine4Retired
38,38,pipe:sine5Retired
33,33,pipe:sineRetired
18,18,pitot1Retired
19,19,pitot2Retired
20,20,pitot3Retired
21,21,pitot4Retired
25,25,pitot5estRetired
24,24,pitot5rampRetired
22,22,pitot5Retired
23,23,pitot5runRetired
29,29,pitot6countRetired
31,31,pitot6timeNERetired
30,30,pitot6timeRetired
32,32,pitot_1Retired
26,26,pitot_avgRetired
27,27,pitot_maxRetired
28,28,pitot_minRetired
12,12,productid-1Retired
16,16,sin:h2Retired
14,14,sin:hourRetired
1,1,SINUSOIDRetired
2,2,SINUSOIDURetired
15,15,t_minRetired
17,17,t_state1Retired

158
 Merge PI Servers

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

Dump the PI Batch Subsystem

As mentioned previously, batches stored in the PI Batch Subsystem must be merged with
piconfig scripts. Start by dumping all batches to be merged. To do this, first dump all the
units to a text file, then use this text file to dump all desired batches. In this example, all
batches are merged. The script and procedure for dumping the units are:
@table pibaunit
@ostr unitname
@sele unitname=*
@output unitlist.txt
@ends
@exit

PI Server System Management Guide 159

Move or Merge PI Servers

Edit the text file to include the start time and end time for each unit and add an exit command
to the end. In this example, there is only one unit, and all the batches are merged; therefore
setting a very wide start and end time ensures that all batches are dumped. Here is the file
after editing:
D:\PI\adm>type unitlist.txt
Reactor1,*-1000d,*
@exit
The script and procedure for dumping the batches are:
D:\PI\adm>type pibatchlist.dif
@table pibatch
@mode list
@ostr unitname,bid,prodid,starttime,stoptime
@ostr ...
@istr unitname,searchstart,searchstop
D:\PI\adm>piconfig input pibatchlist.dif input unitlist.txt >
pibatchlist.txt
@exit
D:\PI\adm>type pibatchlist.txt
*> Reactor1,*-1000d,*
Reactor1,XYZ3,Green,2-Mar-05 11:58:20,2-Mar-05 13:09:20
Reactor1,XYZ25,Yellow,2-Mar-05 13:19:20,2-Mar-05 14:30:20
Reactor1,XYZ3,Green,3-Mar-05 12:24:23,12:44:00
* End Repeat...
* (Ls - PIBATCH) PIconfig> PIconfig 1 Data lines
8 Command lines
0 Records in error...
3 Records Listed
Pibatchlist.txt requires editing before input to the destination system. The unit name,
Reactor1 must be changed to the migrated name Reactor1Retired. Also, the piconfig creation
commands can be added to the top of the file. Here is the file after the edits:
@table pibatch
@mode create
@istr unitname,bid,prodid,starttime,stoptime
Reactor1Retired,XYZ3,Green,2-Mar-05 11:58:20,2-Mar-05 13:09:20
Reactor1Retired,XYZ25,Yellow,2-Mar-05 13:19:20,2-Mar-05 14:30:20
Reactor1Retired,XYZ3,Green,3-Mar-05 12:24:23,12:44:00

ADD PI BATCH UNI T CONFIGURATION TO DESTINATION SERVER

The example has unit configuration in the text file retiredunit.dif. Use piconfig to
input this file:
$ piconfig < retiredunit.dif
*> Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'",
Retired Reactor 1,"'
productid-1Retired'"
PIconfig 1 Data lines
3 Command lines
0 Records in error...
1 Records Created

160
 Merge PI Servers

Shutting Down a Retired System

At this point we have piconfig text files of the point and batch databases and the ID
conversion text file. This is required to reproduce the point and batch configuration on the
destination system. Before shutting down the retired system, stop the interfaces and other data
sources, write shutdown events to all the points, and force a shift.
In this example, all interfaces are on the local host rather than a remote node. On your
system, make sure any API node and PINet node interfaces are shut down. Also shut down
PI Totalizer, PI PE Scheduler, and PI Batch Subsystems.
Before forcing the shift, make sure an empty archive is available for the shift.
Here is the dialog from these steps:
D:\PI\adm>pisrvsitestop
D:\PI\adm>echo Stopping Site Specific PI System Services...
Stopping Site Specific PI System Services...
D:\PI\adm>..\interfaces\rmp_sk\rmp_sk -stop
Stopping service rmp_sk
rmp_sk Stopped Successfully.
D:\PI\adm>..\interfaces\random\random -stop
Stopping service random
.
random Stopped Successfully.
D:\PI\adm>net stop pibatch
The PI Batch Subsystem service is stopping....
The PI Batch Subsystem service was stopped successfully.
D:\PI\adm>net stop pitotal
The PI Totalizer service is stopping...
The PI Totalizer service was stopped successfully.
D:\PI\adm>net stop pipeschd
The PI Performance Equation Scheduler service is stopping..
The PI Performance Equation Scheduler service was stopped
successfully.
D:\PI\adm>..\bin\pishutev -verbose
Shutdown input file: D:\PI\dat\shutdown.dat.
Shutdown events will be written for tag mask *
Point attributes:
shutdown, 1
Shutdown Events at 3-Mar-05 11:04:09 sent for 37 Points
Service Manager requested shutdown of pishutev
D:\PI\adm>piartool -fs
Attempting to force an archive shift...
An archive shift has been initiated on the server.
Completion time will vary from a few minutes to hours,
depending on the machine and archive size. During this
time the archive subsystem will be unavailable and the
PI System should not be stopped until the shift is
complete.
The status of the shift can be found in the message
log using pigetmsg.
The current primary archive is D:\PI\dat\piarch.002
and the target archive for shift is d:\pi\dat\piarch.004
The current primary archive has 2048 records
and the target archive for shift has 2048 records.
D:\PI\adm>pisrvstop

PI Server System Management Guide 161

Move or Merge PI Servers

At this point the retired system is no longer required. All of the text files must be copied to
the destination system. The archives to be merged must be copied to the destination system in
binary mode. In this example, the following archives are merged:
Archive: D:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.002
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 2025/2048
Start Time: 2-Mar-05 12:51:41
End Time: 3-Mar-05 11:15:03
Backup Time: Never
Archive: D:\PI\dat\piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.003
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 2047/2048
Start Time: 2-Mar-05 12:50:27
End Time: 2-Mar-05 12:51:41
Backup Time: Never
Archive: D:\PI\dat\piarch.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 1901/2048
Start Time: 25-Feb-05 14:16:40
End Time: 2-Mar-05 12:50:27
Backup Time: Never

Add Retired Point Configuration to Destination Server

This is just a matter of inputting the scripts into piconfig. In this example, all tag
configuration is in one file called retired.dif. The following command executes this
script, only a portion of the output is shown:
$ piconfig < retired.dif
*> SINUSOIDRetired, 12 Hour Sine Wave, , float32, 0.0, 100.0,
50.0, 0, R, 2, 1, 0,
*> SINUSOIDURetired, UTC 12 Hour Sine Wave, , float32, 0.0,
100.0, 50.0, 0, R, -2, 1, 0,
*> CDT158Retired, Atmospheric Tower OH Vapor, DEG. C, float32,
50.0, 200.0, 140.0, 0, R,30 , 1, 1,
*> CDM158Retired, Light Naphtha End Point Control, STATE,
digital,3.0, 4.0, 3.0, 1, R, 3, 1, 1,
*> CDEP158Retired, Light Naphtha End Point, ,int32,0.0, 400.0,
290.0, 0, R, 5, 1

Reprocess the Archives

The binary ID conversion file is required to reprocess the retired systems archives on the
destination server. This is created from the ID conversion text file created on the retired
system - retiredidconv.txt:

162
 Merge PI Servers

$ piartool -idci E:\PI\adm\retiredidconv.txt -idco

E:\PI\adm\retiredidconv.bin
Creating new conversion table: E:\PI\adm\retiredidconv.bin...
37 input lines processed
37 names in table
The offline archive utility is used to convert the archives from the retired system. For this
example, one archive is converted and registered. Other archives are handled in a similar
manner. Here is the dialog from the conversion:
$ ../bin/piarchss -id E:\PI\adm\retiredidconv.bin -if
E:\PI\dat\piarchretired.002 -of E:\PI\dat\piarchconv.002
PIarchss offline archive utility
Input file type: PI 3
Archive input file: piarchretired.002
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-05 12:51:41
Archive indicated end time: 3-Mar-05 11:09:30
Archive indicated recordcount: 2048
Processing record 1 ...
Invalid ID Conversion on input Point ID 13 . Record not
processed.
Primary record load completed.
Records processed: 38
Records with data: 21
Empty records: 17
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Overflow record load completed.
Records processed: 157
Records with data: 155
Empty records: 0
Records with errors: 0
Records out of time range: 2
Records with duplicate time range: 0
Begining Output pass. Output archive: piarchconv.002
Processing record 1 ...
Invalid ID Conversion on input Point ID 13 . Record not
processed.
22722 Loaded in 3( 1 + 2 ) Seconds 7574 Event/Sec.
80269 Archive Total seconds - ratio: 26756
Service Manager requested shutdown of piarchss
Records for points not merged are not processed. The previous output shows a message
indicating records for PointID 13 are not processed—this is the PI Batch point that was
intentionally not merged.
Note the times on the archive converted. The times overlap the primary archive on the
destination system. This problem must be addressed before the converted archive can be
registered. The solution is to force a shift, and combine the converted archive with the
destination archive. After the shift, the destination system's archives are as follows:
$ piartool -al
Archive shift prediction:
Shift Time: 18-Jan-38 19:14:07.7930
Target Archive: E:\PI\dat\piarch.002

PI Server System Management Guide 163

Move or Merge PI Servers

Archive: E:\PI\dat\piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarch.003
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 98/512 Overflow: 2047/2048
Start Time: 3-Mar-05 16:32:27
End Time: Current Time
Backup Time: Never
Archive: E:\PI\dat\piarch.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 98/512 Overflow: 1948/2048
Start Time: 2-Mar-05 12:21:11
End Time: 3-Mar-05 16:32:27
Backup Time: Never
Archive: E:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarch.002
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 1/512 Overflow: 2047/2048
Start Time: Current Time
End Time: Current Time
Backup Time: Never
The converted archive and piarch.001 must be combined. For this example the
conversion is made into a dynamic size. If converting into a fixed size archive, there must be
enough space for all used records in both archives being combined. If in doubt use dynamic
archives, as they can always be moved into a fixed size archive later.
In the following dialogs, the ID conversion file is not required:
$ ../bin/piarchss -if E:\PI\dat\piarch.001 -of
E:\PI\dat\piarchcomb.001
PIarchss offline archive utility
Input file type: PI 3
Archive input file: E:\PI\dat\piarch.001
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-05 12:21:11
Archive indicated end time: 3-Mar-05 16:32:27
Archive indicated recordcount: 2048
Processing record 1 ...
Primary record load completed.
Records processed: 97
Records with data: 86
Empty records: 11
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Overflow record load completed.
Records processed: 101
Records with data: 101
Empty records: 0

164
 Merge PI Servers

Records with errors: 0

Records out of time range: 0
Records with duplicate time range: 0
Begining Output pass. Output archive: E:\PI\dat\piarchcomb.001
Processing record 1 ...
19260 Loaded in 1( 0 + 1 ) Seconds 19260 Event/Sec.
101476 Archive Total seconds - ratio: 101476
Service Manager requested shutdown of piarchss
Now combine the converted archive.
$ ../bin/piarchss -if E:\PI\dat\piarchconv.002 -of
E:\PI\dat\piarchcomb.001
PIarchss offline archive utility
Input file type: PI 3
Archive input file: E:\PI\dat\piarchconv.002
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-05 12:51:41
Archive indicated end time: 3-Mar-05 11:09:30
Archive indicated recordcount: 395
Processing record 1 ...
Primary record load completed.
Records processed: 97
Records with data: 26
Empty records: 71
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Processing record 200 ...
Overflow record load completed.
Records processed: 139
Records with data: 139
Empty records: 0
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Begining Output pass. Output archive: E:\PI\dat\piarchcomb.001
Processing record 1 ...
21870 Loaded in 20( 1 + 19 ) Seconds 1093 Event/Sec.
80269 Archive Total seconds - ratio: 4013
Service Manager requested shutdown of piarchss
The combined archive is now ready for registration. Register it and have a look at some data
from a merged point:
$ piartool -ar E:\PI\dat\piarchcomb.001
Attempting to register archive file: E:\PI\dat\piarchcomb.001
Successfully registered archive file: E:\PI\dat\piarchcomb.001
peach piadmin$ piartool -al
Archive shift prediction:
Shift Time: 18-Jan-38 19:14:07.7930
Target Archive: E:\PI\dat\piarch.002
Archive: E:\PI\dat\piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarch.003
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048

PI Server System Management Guide 165

Move or Merge PI Servers

Offsets: Primary: 98/512 Overflow: 2047/2048

Start Time: 3-Mar-05 16:32:27
End Time: Current Time
Backup Time: Never
Archive: E:\PI\dat\piarchcomb.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarchcomb.001
State: 4 Type: 1 Write Flag: 1 Shift Flag: 0
Record Size: 1024 Count: 499
Offsets: Primary: 98/256 Overflow: 499/1048576
Start Time: 2-Mar-05 12:21:11
End Time: 3-Mar-05 16:32:27
Backup Time: Never
Archive: E:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: E:\PI\dat\piarch.002
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2048
Offsets: Primary: 1/512 Overflow: 2047/2048
Start Time: Current Time
End Time: Current Time
Backup Time: Never
$ piconfig
* (Ls - ) PIconfig>
* (Ls - ) PIconfig> @Input piarc.dif
* (Ls - PIARC) PIconfig> sinusoidRetired,2-Mar-05,*,
*> sinusoidRetired,2-Mar-05,*,
87.71619,GOOD,2-Mar-05 13:37:56
99.23527,GOOD,2-Mar-05 14:39:56
96.20524,GOOD,2-Mar-05 15:44:56
75.77717,GOOD,2-Mar-05 16:57:56
14.20552,GOOD,2-Mar-05 19:31:26
1.545739,GOOD,2-Mar-05 20:31:26
1.869217,GOOD,2-Mar-05 21:31:26
18.17325,GOOD,2-Mar-05 22:40:56
86.39859,GOOD,3-Mar-05 01:33:26
99.15742,GOOD,3-Mar-05 02:38:56
96.37012,GOOD,3-Mar-05 03:43:56
75.96362,GOOD,3-Mar-05 04:57:26
14.35799,GOOD,3-Mar-05 07:30:56
0.7647065,GOOD,3-Mar-05 08:39:56
3.794814,GOOD,3-Mar-05 09:44:56
24.22295,GOOD,3-Mar-05 10:57:56
Digital State,Shutdown,3-Mar-05 11:04:09
Digital State,Pt Created,3-Mar-05 14:29:48
98.3448,GOOD,3-Mar-05 14:30:26
98.2471,GOOD,3-Mar-05 15:30:26
82.16194,GOOD,3-Mar-05 16:39:56
79.05913,GOOD,3-Mar-05 16:48:56
End Repeat...
Look carefully at several points before proceeding.

166
 Merge PI Servers

Add the PI Batches

Batches are stored in the Archive; therefore, all archives should be converted before
processing the batch text files. Once again, piconfig is used to add the batches:
$ piconfig
* (Ls - ) PIconfig> @input pibatchlist.dif
*>Reactor1Retired,XYZ3,Green,2-Mar-05 11:58:20,2-Mar-05 13:09:20
*>Reactor1Retired,XYZ25,Yellow,2-Mar-05 13:19:20,2-Mar-05
14:30:20
*>Reactor1Retired,XYZ3,Green,3-Mar-05 12:24:23,12:44:00
This completes the merge.

PI Server System Management Guide 167

Chapter 9

Tuning, Troubleshooting, and Repairs

This chapter gives tips for tuning, troubleshooting, and repairing a PI Server.

Tuning
Most PI Servers require no tuning and work well with the default settings. In some instances,
you may need to make adjustments to the parameters contained in the Timeout Table (these
are called Tuning Parameters).

Configurable Tuning Parameters

To edit PI Server configuration and tuning parameters use the PI System Management
Tool s (PI SMT). In PI SMT, use the Tuning Parameters tool (select Operations > Tuning
Parameters).
Changes to tuning parameters do not take effect until you stop and restart the PI Server or the
subsystem associated with the updated parameter.
Also, applications that were already connected to the PI Server will not reflect tuning
parameter edits until you reconnect.
All Subsystems

Param eter Description Min - Max/ Default Read

<subsysname>_Max Specifies the maximum number of 1 – ThreadCount – Startup

ThreadsPerClientQuery threads that can be used ThreadCount -1/
concurrently for each client. 0
Pr otects PI Server subsystems
from exhausting all w orker
threads by one client application.

PI Server System Management Guide 169

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Default Read

<subsysname>_Thread Size of the subsystem message 1 – N/A/ Startup

Count thread pool. Message threads are 4
dedicated to RPC request
processing. Depending on the
number of processors on the
machine, this value may be
increased so more RPC requests
can be handled simultaneously. If
all the threads are busy, RPCs
are queued up and processed in
chronological order. Note: The
default for the Archive
Subsystem,
piarchss_ThreadCount, is 8
worker threads instead of 4 for all
other subsystems. The subsystem
limits COM Connector RPC
request processing threads,
called pending CC threads, to
maximum of half of this number.
<subsysname>_Authz The authorization cache saves 0 – 1024/ Startup
CacheLimit authorizations results for one 32 entries
RPC execution. For example,
putsnapshot for multiple points
w ill use previous authorizations, in
case multiple points have s imilar
security setting.
_QueuedMessageTimeout If all RPC threads are busy, any 10 – 3600/ Startup
RPC commands received by a 600 seconds
subsystem w ill be placed in a
queue. If running RPCs take a
long time to complete, the queue
w ill grow , increasing the chance
that the client has already timed
out the request by the time an
RPC thread executes it. When an
RPC thread picks up a request,
the subsystem sees how long it
has been in the queue. If it is
longer than
_QueuedMessageTimeout
seconds, the RPC thread w ill
send a message indicating that
the RPC has timed out rather than
executing it.
SBHThreshold Threshold for CRT library small 0 – 1016/ Startup
block heap memory allocation. 128 bytes

170
 Tuning

Archive Subsystem

Param eter Description Min - Max/ Read

Default

Archiv e_AutoArchiv eFile File name extension of automatic N/A/ Before every
Ext Archives. See also shift
.arc
Archive_AutoArchiveFileRoot
and
Archive_AutoArchiveFileForm a
t.
Archiv e_AutoArchiv eFile File name format of automatic 0 – 2/ Before every
Format Archives w hen shift
1
Archive_AutoArchiveFileRoot
parameter is used to create
automatic Archive files. The
formats are:
0:<root>._D_Mon_YYYY_H_M_S.<ext
>
1:<root>._YYYY-MM-DD_HH-MM-
SS.<ext>
2: <root>._UTCSECONDS.<ext>
Archiv e_AutoArchiv eFile Automatic archive file creation on N/A/ Before every
Root shifts. If present, this parameter shift
N/A
defines the path and file name
prefix to be used for new
archives.
For example, C:\PI\arc\auto_
Archiv e_BSTimeout The maximum number of seconds 1 – 86400/ Once a
an archive is allow ed to remain 1800 sec minute
offline w ith the piartool -bs utility.
Archiv e_CacheCleanCycle Frequency at w hich read-only 1 – Flush Startup
cache cleanup operations are Cycle/
performed. Setting this limit too 10 seconds
low may affect the performance of
the Archive Subsystem.
Archiv e_CacheHighPct High cache c leanup threshold, in 100 – 200/ Startup
Limit percentage of the 110 percent
Archive_CacheRecordPool
value. Oldest cache records are
deleted w hen the read-only cache
pool is above this limit, regardless
of
Archive_MaxIdleCleanCycles.
Archiv e_CacheLow PctLimit Low cache cleanup threshold, in 20 – 100/ Startup
percentage of the 80 percent
Archive_CacheRecordPool
value. Oldest cache records stop
being deleted w hen the read-only
cache pool is below this limit.
Archiv e_CacheRecordPool Maximum number of archive 10000 – Startup and
cache records for read access 500000/ end of each
queries. The actual size of the Point count flush cycle
read-only cache pool may low er m ultiplied by
due to low physical memory 4
resources.

PI Server System Management Guide 171

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Read

Default

Archiv e_CacheRecordsPer Maximum number of archive 4 – cache Startup and

Point cache records per point. In the end of
pool divided by
default configuration, up to half 2/ each flush
the cache record pool may be cycle
512
allocated to a single point.
Archiv e_CacheTrimPercent Percentage to tr im the read and 1 – 75/ Startup
write cache w hen low physical 40 percent
memory resources are detected.
Archiv e_COMConnector Configures the timeout for w aiting 1– On the first
SemaphoreWait for pending CC thread semaphore 2147483647/ data request
per subsystem. This pending CC 10 m sec for a COM
thread semaphore must be Connector
acquired by the w orker threads point
before they can call COM
Connectors. The value of -1 sets
it to default.
Archiv e_DataCoercion Data type coercion on old archive 0 – 3/ Startup
Policy record access: 0
0 – mar k value as bad (default
behavior)
1 – leave as is, w ith
heterogeneous point type
2 – replace by 0 value
3 – hide (value is not returned to
user queries)

Archiv e_EnableAuto Enable or disable automatic 0 – 1/ Startup

Dynamic conversion of fixed size archives 1
to dynamic w hen they become
full.
Archiv e_EventQueue Number of w orker threads that 1 – 255/ Startup
ThreadCount move events out of the Snapshot 1
Event Queue to the w rite cache.
Archiv e_FlushQueueSize Maximum number of flush tasks, 16 – 8192/ Startup
shared betw een the EventQueue 256
threads and the Flush threads.
Archiv e_FlushThreadCount Number of w orker threads that 1 – 128/ Startup
flush events from the write cache 4
to the archive files, according to
the
Archive_MaxWriteCachePerPoi
nt parameter.
Archiv e_LogArchive Log a message w hen percentage 0 – 50/ Startup
PercentFull of archive files fill up in the 10 percent
specified increment.

172
 Tuning

Param eter Description Min - Max/ Read

Default

Archiv e_Low DiskSpaceMB Minimum amount of free disk N/A/ Once a

space to leave on archive file 256 MB minute w ith a
volumes. A dynamic primary dynamic
archive w ill stop grow ing if this primary
limit is reached and a shift w ill be archive, and
triggered. on shifts
when Archive
AutoArchiveF
ileRoot is set
Archiv e_MaxAnnotations Maximum number of event 128 – Startup
annotations per archive file. 134217728/
Note: Annotations are stored in 65535
the parallel file w ith the .ann
extension.
Archiv e_MaxIdleClean Maximum idle time of archive 1 – 60/ Startup
Cycles cache records before being 2
discarded. This number is
expressed in number of flush
cycles that is specified by
Archive_SecondsBetw eenFlush
.
Archiv e_MaxWriteCache Maximum number of w rite cache 0 – 16384/ Startup and
PerPoint events per point. Ev ents of a end of each
256
given point w ill be flushed to disk flush cycle
when this limit is exceeded. The
default value may be scaled back
based on system point count and
available memory.
Archiv e_MinCacheRecord Minimum size of the record pool 1024 – 102400/ Startup
Pool when doing cache trimming due 2048
to low -memory conditions.
Archiv e_MinMemAv ail Minimum amount of free physical 0 – 1024/ Startup
memory to leave for OS and other 96 MB
subsystems. The Archive
Subsystem w ill start trimming its
cache w hen physical memory
resources go below this or the
Archive_MinPercentMem Avail
percentage.
Archiv e_MinPercentMem Minimum percentage of free 0 – 50/ Startup
Avail physical memory to leave for OS 10 percent
and other subsystems. The
Archive Subsystem w ill start
trimming its cache w hen physical
memory resources go below this
or the Archive_MinMem Avail
value.
Archiv e_MinWriteCachePer Minimum number of write cache 1 – 1024/ Startup
Point events per points w hen doing 8
cache trimming due to low-
memory conditions.

PI Server System Management Guide 173

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Read

Default

Archiv e_PointLockLogging Minimum lock timeout that 0 – 900000/ Startup

triggers a message in the PI 5000 m sec
Server log.
Archiv e_PointLockTimeout Maximum w ait time for archive 1000 – 270000/ Startup
read quer ies 120000 m sec
Archiv e_SecondsBetween Archive cache flush cycle or 1 – 86400/ Startup
Flush maximum time betw een 900 sec
consecutive dis k flushes for a
given point.
Archiv e_ShiftFreeTime Number of seconds to subtract 0 – 86400/ Startup
from the predicted time to 1800 sec
deter mine the actual shift time.
Setting this parameter to
something greater than 0 w ill
leave the corresponding free
archive space. Default is 30
m inutes. This parameter and/or
the Archive_ShiftRatio are
useful on systems w here
backfilling or out-of-order events
are expected.
Archiv e_ShiftRatio Ratio of total records to free 4 – 2048/ Startup
records at w hich archive shifts are 50
triggered. The inverse of this
parameter defines the percentage
of free records to leave in archive
files. Default is 1/50 = 2 percent.
This parameter and/or the
Archive_ShiftFreeTim e are
useful on systems w here
backfilling or out-of-order events
are expected.
Archiv e_ShiftRecordCount Number of records to process in 256 – 16384/ Before every
one chuck during archive file 2048 shift
initializations. When shifting or
initializing new archives, this
parameter partly defines the
speed of archive initializations.
How ever, setting this parameter
higher than the default may
impact system performance as
more memory w ill be consumed.
Archiv e_WriteLockTimeout Maximum w ait time for archive 5000 – 900000/ Startup
writes or flushes. 270000 m sec

174
 Tuning

Param eter Description Min - Max/ Read

Default

ArcInsertRecOnOOO Break the chain and insert new 0 – 1/ Startup

records w hen out-of-order events 1
need to be inserted into full
overflow records. When set to 0
(false), this parameter makes the
Archive Subsystem to revert bac k
to the event cascading algorithm
of PI Server versions 3.3 and
earlier.
ArcMaxCollect Maximum number of compressed N/A/ Startup
events that can be retrieved by a 150000
single query. This number does
not affect interpolated event
retrieval or archive summary calls.
BatchDb_MaxSearch Limits the number of batch -1 – 1000000/ Startup
Records records returned by a single -1
query. The limit, w hen set applies
to PIUnit Batches, PIBatches
and PICam paigns. The default (-
1) is no limits.
BatchDb_SearchLookBack Controls the batch search look 1 – 365/ Startup
Days back per iod. The start time in a 31 days
search is moved back in time
based on this number of days.
BreakCrossRefOnDelete Break reference betw een 0 – 1/ Startup
Unit Batch and PIBatch on 1
deletion of Unit Batch.
Cache_FreelistSize Size of the list of reusable cache 1000 – 100000/ Startup
records that w ere discarded from 10000
the read-only record pool. This
parameter should only be
changed upon recommendation
from a technical support engineer.
MarkArchiveGaps Return special Arc Off-line 0 – 1/ Startup
events w hen archive files are 1
taken offline or w hen time gaps
are detected in mounted archives.
The archive offline markers are
primarily useful to prevent any
mis-interpolation of data across
missing archives.
piarchss Subsystem w ait time after every 1 – 10000000/ Startup
main loop iteration. 100000 µsec

PI Server System Management Guide 175

Tuning, Troubleshooting, and Repairs

Backup Subsystem

Param eter Description Min – Max/ Default Read

Archiv e_BackupLeadTime Number of seconds before the 5 – 86400/ At start of

predicted archive shift that a non- 1800 sec each
VSS backup may start. The PI backup
Backup Subsystem w aits
Archive_BackupLeadTim e
seconds for the archive shift to
complete. If the shift does not
occur w ithin this time period, the
backup request is aborted w ith a
status of -30150. This timeout
parameter has no effect on VSS
backups.
Backup_TraceLevel The default backup trace level. 0 – 1000/ Startup
Non-0 bac kup trace levels cause 0
debug messages to be w ritten to
the PI Message Log for
troubleshooting PI Server backups.
The default trace level can be
overridden w hile the PI Bac kup
Subsystem is running w ith the
piartool –backup –trace <level>
command.
Backup_Low DiskSpaceMB Defines the minimum amount of 0 – N/A/ At start of
disk space that must remain after a 256 MB each
successful backup. If there is backup
insufficient disk space on the disk
drive corresponding to the backup
directory, the backup w ill not start.
Backup_MaxHistory Maximum number of backups for 0 – 1000/ At the end
which to save history. 100 of each
backup

BackupVerification Set this parameter to 0 to disable 0 – 1/ At the start

backup ver ification. 1 of each
backup

BackupVerfication_Num Number of archives to verify. Set -1 – 1000000/ At the start

Arch this parameter to -1 to verify all of each
1
modified archives that are bac ked backup
up (archives that have not been
modified since the last backup are
never verified). This parameter is
ignored if all bac kup verification
has been disabled by setting the
BackupVerification timeout
parameter to 0.

176
 Tuning

Base Subsystem

Param eter Description Min - Max/ Read

Default

Server_Authentication The timeout parameter represents 0 – 14/ Startup

Policy a bit mask, w ith the follow ing 0
values and meanings:
0 – enable all authentication
methods
1 – disable explicit logins
2 – disable explicit logins w ith
blank passw ords (1 implies 2, but 2
does not imply 1)
4 – disable trusts
8 – disable mappings
AutoTrustConfig Bitmask w hich controls automatic 0 – 255/ Once a
trust configuration 17 minute
0 – NONE
1 – Loopbac k
2 – Localhost
4 – IPaddr
8 – Hostname
16 – FQDN
127 – v3.4.370 Compatible
255 – All
17 – LoopBack + FQDN
BatchDbEditLogging Logging of Batch Database edits 0 – 1/ Startup
and deletions to the message log. 0
This parameter does not apply to
PI Batch Subsystem and is
superseded by the Audit feature of
the PI Server.
EnableHostnameForFQDN Allow a hostname instead of a fully 0 – 1/ Once a
qualified domain name in the PI 0 minute
Server configuration, FQDN field.
This should be set only w hen
clients are unable to resolve the
fully qualified domain name of the
server due to having limited access
to name resolution services such
as DNS, or otherw ise the server's
address is not published v ia these
services to all clients.
Module_MessageOnWrite Pr int message on modifications of 0 – 1/ Startup
the module database. 0

ModuleDb_CleanPeriodSec Frequency at w hich checks for idle 30 – 3600/ Startup

modules are performed. Setting 300 seconds
this limit too low may affect the
performance of the Base
Subsystem.

PI Server System Management Guide 177

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Read

Default

ModuleDb_MaxIdleClean Maximum idle time of MDB 0 – 604800/ Startup

Sec modules before being unloaded 3600 seconds
from memory. Checks are
performed every
ModuleDb_CleanPeriodSec
seconds.

pibasess Subsystem w ait time after every 1 – 10000000/ Startup

main loop iteration. 10000 µsec

PointDb_CleanPeriodSec Frequency at w hich checks for idle 30 – 3600/ Startup

points are performed. Setting this 300 seconds
limit too low may affect the
performance of the Base
Subsystem.
PointDb_COMConnector Configures the timeout for w aiting 1 – 2147483647/ On startup
SemaphoreWait for pending CC thread semaphore w ith COM
10 m sec
per subsystem. This pending CC Connector
thread semaphore must be points, or
acquired by the w orker threads upon the
before they can call COM first COM
Connectors. The value of -1 sets it Connector
to default. point
creation
PointDb_MaxIdleCleanSec Maximum idle time of PI Points 0 – 604800/ Startup
before being unloaded from 3600 seconds
memory. Checks are perfor med
every PointDb_CleanPeriodSec
seconds.
RecreateServerTrust Recreate missing trust entries for 0 – 1/ Startup
local machine access. These trust 1
settings are used by SDK or A PI
applications or interfaces running
on the server node.
Replication_ClockDiffLimit A secondary member of a PI 10 – 600/ Once a
Collective allow s this difference in 300 seconds minute
server clocks before raising sync
failure.
Replication_CommFailure Amount of time that the primary 0 – 10000/ Once a
GracePeriod server allow s a secondary member minute
300 seconds
of a PI Collective to be late in
communicating before mar king the
server as unavailable.
Replication_EnableBDB 0 or missing: secondary computers 0 – 1/ Once a
Access respond to Batch RPCs w ith error. minute
0
1 enables Batch RPCs on
secondary computers.

178
 Tuning

Param eter Description Min - Max/ Read

Default

Replication_EnableSDK 0 or missing on secondary 0 – 1/ Once a

WriteValues computers prevents the PI SDK minute
0
1.3.4 or later from w riting data. 1
allows the PI SDK 1.3.4 or later to
write data. The PI SDK 1.3.3 or
earlier is not affected by this
parameter.
Replication_SyncFailure Amount of time a secondary is 0 – 10000000/ Once a
GracePeriod allow ed to have a sync failure minute
0 seconds
before it makes itself unavailable.

Replication_SyncTimeout Timeout w hen reading 0 – 100000/ Once a

Period configuration changes from the minute
300 seconds
primary.

Base_LookupSIDForTrust Perform w indows user 0 – 1/ Startup

(only in 3.4.380.28 and later; authentication against a domain 1
previously controller. This feature should only
Window sAuthentication)
be disabled upon recommendation
from a technical support engineer.

Base, Snapshot and Archive Subsystems

Param eter Description Min - Max/ Default Read

AuditMaxKBytes Maximum size of one audit file in 0 – 16000000/ Startup

kilobytes. When the size of the 256000 KB
audit file in bytes exceeds 1,000
times this parameter, the audit file
w ill be closed and renamed w ith
the date and time appended. Then
a new audit file w ill be opened w ith
the audit file name. If this
parameter is 0, the check on audit
file size is omitted.
AuditMaxRecords Maximum number of records in 0 – 10000000/ Startup
one audit file. When the number of 0
records in the audit file exceeds
this parameter, the audit file w ill be
closed and renamed w ith the date
and time appended. Then a new
audit file w ill be opened w ith the
audit file name. If this parameter is
0, the chec k on number of records
is omitted.
EnableAudit Auditing mas k, -1 (or 0 – 0x FFFFFFFF/ Startup
0xFFFFFFFF) enable the audit of 0
all databases. See the Audit the PI
Server for details on acceptable
values.

PI Server System Management Guide 179

Tuning, Troubleshooting, and Repairs

Batch Subsystem

Param eter Description Min - Max/ Default Read

pibatch Subsystem w ait time after every 1 – 10000000/ Startup

main loop iteration. 12000 µsec

Message Subsystem

Param eter Description Min - Max/ Default Read

pimsgss Subsystem w ait time after every 1 – 10000000/ Startup

main loop iteration. 12000 µsec

Netw ork Manager Subsystem

Param eter Description Min - Max/ Default Read

APITreatLocalAdapters When making a trust for a PI-A PI 0 – 1/ Startup

As127.0.0.1 application, if the connection 1
originates from an address ow ned
by the server, use 127.0.0.1 as the
IP address passed to PIbasess.
APIProcessing Allow API connections. 0 – 1/ Startup
Note: This w ill not allow any API 1
interfaces to connect.

backlog Maximum number of pending 5 – 1000/ Startup

TCP/IP connections. 5

connectionlocktimeout Amount of time to w ait for a 1 – 1000/ Startup

connection loc ked by another 90 seconds
thread.

connectionw ait Amount of time for a new TCP/IP 1000 – 1000000/ Startup
connection to become w ritable. 30000 m sec

DefaultUserAccess Enable guest (or "w orld") access to 0 – 1/ Startup

the PI Server. 1

DoRDNSForMessaging Have Pinetmgr to perform a 0 – 1/ Startup

reverse name lookup w hen printing 0
out messages to the log involving
an IP address associated w ith a
connection. This is expensive on
some systems.

180
 Tuning

Param eter Description Min - Max/ Default Read

HealthCheckInterval Frequency at w hich health checks 60 – 1000000/ Startup

are performed betw een 1800 seconds
NetManager and the PI
Subsystems. NetManager w ill
close connections if subsystems
don't respond to health chec ks.
keepalive TCP/IP keepalive option. A value -1 – 1/ Startup
of -1 means system default, 0 is -1 seconds
disabled.

linger_on Socket closure behavior. See also 0 – 1/ Startup

linger_time. 0

linger_time Time in seconds to linger on socket 0 – N/A/ Startup

closure, if linger_on is set. 0 seconds

MaxAuthAttempts Configures the maximum allow ed 0 – 10/ Startup

number of subsequent 3
authentication attempts w hen none
is accepted.
MaxConnIdleTime Closes idle connections after the 300 – 2147483647/ Startup
specified number of seconds. By 0 seconds
default, PI NetManager w ill not
close connections regardless of
idle time.
MaxMessageLength Maximum size of messages 10 – 512/ Startup
handled by NetManager, PI3 256 MB
Subsystems and PI-SDK
applications.
maxzerobytereads Assume a connection close w hen 0 – 1000/ Startup
receiving a series of zero-byte 100
messages.

pinetmgr Subsystem w ait time after every 1 – 10000000/ Startup

main loop iteration. 10000 µsec

ReadCompletionTimeout Amount of time to bloc k for read 120 – Startup

completion. 0xFFFFFFFF/
300 seconds
readretry Maximum retry attempts on read 1 – 10000000/ Startup
stream errors; externally 250
configurable on UNIX systems
only.
readretrytimeout Aggregate time limit for retried read 0 – 1000/ Startup
operations, in addition to retry 2.5 seconds
count.

readtimeout Read timeout on netw ork I/Os; 1 – 50000000/ Startup

externally configurable on UNIX 50000 µsec
systems only.

PI Server System Management Guide 181

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Default Read

rev ersenamelookupflag Translate IP addresses to IP host 0 – 1/ Startup

names on new connections. 1

ThreadStackSize Stack of Netw ork Manager w orker 0 – 10/ Startup

thread. A value of 0 means the 0 MB
same as NetManager's main
thread.
w riteretry Maximum retry attempts on w rite 1 – 10000000/ Startup
stream errors; externally 250
configurable on UNIX systems
only.
w ritetimeout Write timeout on netw ork I/Os; 1 – 10000000/ Startup
externally configurable on UNIX 50000 µsec
systems only.

Perform ance Scheduler

Param eter Description Min - Max/ Default Read

pipeschd Subsystem w ait time after every 1 – 10000000/ Startup

main loop iteration. 50000 µsec

Snapshot Subsystem

Param eter Description Min - Max/ Read

Default

EditDays Number of past days w here 0 – N/A/ Startup

events can be modified in the 0 days
Snapshot or Archive
databases. A value of zero
means no time check is done.
pisnapss Subsystem w ait time after 1 – 10000000/ Startup
every main loop iteration. 1000 µsec

Snapshot_BufferStatistics Log statistics about point 0 – 60/ Once a

ow nership changes betw een 1 m inute minute
PI Buffer Subsystem
instances. A value above 0
indicates the minimum time
interval betw een log
messages (in minutes).

182
 Tuning

Param eter Description Min - Max/ Read

Default

Snapshot_BufPointLogFiles Troubleshooting only: dump 0 – 60/ Once a

the list of points that are 0 file minute
moving betw een Pibufss
instances into text file under
PI\log. Files are named
"snap_bfptX-#.log", w here X is
the Buffer Subsystem
registration ID.
Snapshot_COMConnector Configures the timeout for 1 – 2147483647/ On the first
SemaphoreWait waiting for pending CC thread data request
10 m sec
semaphore per subsystem. for a COM
This pending CC thread Connector
semaphore must be acquired point
by the w orker threads before
they can call COM
Connectors. The value of -1
sets it to default.
Snapshot_EventQueuePage Size of the memory pages 64 – 8192/ Startup
Size from the memory mapped 1024 KB
Event Queue. This number
must be a multiple of 64.
Snapshot_EventQueuePath Path w here the memory- NA/ Startup
mapped queues are created; PI\dat
default is PI\dat. The
primary queue name is alw ays
pimapevq.dat and overflow
queues are pimq0000.dat,
pimq0001.dat ...
pimqFFFF.dat.
Snapshot_EventQueueSize Size of the primary and 8 – 131072/ Startup
overflow Event Queues on 64 MB
disk. This parameter should be
adjusted according to archive
event rate to avoid the
creation of overflow queues.
Snapshot_ReleaseBuffered Release buffered points 0 – 1/ Startup
PointsAfterCompmax automatically w hen the PI 1
Buffer Subsystem is
connected and Com pMax
time is exceeded.
Snapshot_SecondsBetween Snapshot table flush cycle or 60 – 3600/ Startup
Flush maximum time betw een 900 seconds
consecutive flushes for a given
point.

PI Server System Management Guide 183

Tuning, Troubleshooting, and Repairs

Snapshot and Archive Subsystems

Param eter Description Min - Max/ Default- Read

Max (Default)

Archiv eEditLogging Logging of event edits and 0 – 1/ Startup

deletions to the message log. 0
This parameter is superseded
by the Audit feature of the PI
Server.
Snapshot_EventQueueFlush Frequency at w hich the 0 – 3600000/ Startup
Period memory- mapped queue is 30000 m sec
flushed to disk by the
Snapshot and Archive
Subsystems.

Snapshot and Update Manager Subsystems

Param eter Description Min - Max/ Read

Default

MMQ_Low DiskSpaceMB Minimum amount of free disk NA/ When

space to leave w hen creating 256 MB overflow
overflow event queues. This event
parameter replaces queues are
Snapshot_Low DiskSpaceM created
B.

SQL Subsystem

Param eter Description Min - Max/ Default Read

pisqlss Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 12000 µsec

Totalizer Subsystem

Param eter Description Min - Max/ Default Read

pitotal Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 12000 µsec

Update Manager Subsystem

Param eter Description Min - Max/ Read

Default

MaxUpdateQueue Maximum number of events N/A/ Startup

per consumer held in the 50000
Update Manager, excluding
memory- mapped queue
consumers.

184
 Tuning

Param eter Description Min - Max/ Read

Default

PIUPD_MaxConsTimeout Maximum value of client- 0 – 7200/ The first time a

supplied cleanup time for 0 seconds consumer is
inactive consumer signups. added

PIUPD_MinConsTimeout Minimum value of client- 0 – 7200/ The first time a

supplied cleanup time for 600 seconds consumer is
inactive consumer signups. added

PIUPD_TimeoutKillCons Remove timed out consumers 0 – 1/ Startup

in addition to removing all 0
pending events.

piupdmgr Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 12000 µsec

TotalUpdateQueue Maximum number of events in N/A/ Startup

Update Manager for all 1000000
consumers, excluding
memory- mapped queue
consumers.
Update_EventQueueFlush Frequency at w hich the 1 – 3600000/ When the
Period memory- mapped queue is memory-
30000 m sec
flushed to disk by the Update mapped queue
Manager. consumer
registers w ith
the Update
Manager
Update_EventQueuePageSize Size of the memory pages 64 – 32768/ When the
from the memory-mapped 16384 KB memory-
Event Queue. This number mapped queue
must be a multiple of 64. consumer
registers w ith
the Update
Manager

Update_EventQueuePath Path w here the memory- N/A/ When the

mapped queues are created PI\dat memory-
(default is PI\dat). The primary mapped queue
queue name is alw ays consumer
piupd_<consumer>_evq.d registers w ith
at and overflow queues are the Update
piupd_<consumer>_evq00 Manager
00.dat,
piupd_<consumer>_evq00
01.dat, ...,
piupd_<consumer>_evqFF
F.dat w here <consumer> is
the name of the memory-
mapped queue consumer.

PI Server System Management Guide 185

Tuning, Troubleshooting, and Repairs

Param eter Description Min - Max/ Read

Default

Update_EventQueueSize Size of the primary and 8 – 131072/ When the

overflow Event Queues on 256 MB memory-
disk. This parameter should be mapped queue
adjusted according to the consumer
memory- mapped queue registers w ith
consumer event rate and the Update
pending events to avoid the Manager
creation of overflow queues.
Update_GetEventsSize Size limit threshold for 1024 – Startup
Threshold memory- mapped queue 33554432/
consumer get events request. 16777216
bytes
Update_PersistentConsumer Cleanup time for inactive 0 – N/A/ Startup
Timeout persistent consumer signups. 86400
seconds

Utilities

Param eter Description Min - Max/ Default Read

CheckUtilityLogin Force an interactive login from 0 – N/A/ Startup

console utilities like piconfig 86400 seconds
and pisetpass.
Arguments for local login w hen
this is set
piartool Subsystem w ait time after 1 – 10000000/ Startup
every main loop iteration. 1000 µsec

piconfig Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 1000 µsec

pigetmsg Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 1000 µsec

pilistupd Subsystem w ait time after 1 – 10000000/ Startup

every main loop iteration. 1000 µsec

Adjust the Pending Update Limit

By default, the PI Update Manager maintains up to 4,095 pending updates per cons umer.
Similarly, the TotalUpdateQueue parameter sets the maximum events queued in the entire
Update Manager database. The default number of maximum events is 100,000.
If either of these limits is reached, a message is sent to the PI Message Log. Another message
is sent when the level goes back below 99 percent of the limit and queuing is resumed.

186
 Troubleshooting

Messages for consumers using less than 0.1 percent of the TotalUpdateQueue limit (100 for
the default) are still queued even when the total limit is reached.

When to Change the Pending Update Limit

The default is suitable for most systems, with the following exceptions:
• The number should be increased on systems with one or more of the following:
ο very large physical memory
ο high frequency of updates (normally snapshots)
ο applications that might retrieve update limits slowly
Changes to the Max UpdateQueue parameter takes effect only after the PI Server
restarts.
• If a PINet node or PItoPI interface is connected to the PI Server, the default
Max UpdateQueue value is too small. It should be increased to at least the point count of
the PI Server. This value ensures that all point updates requested by PINet can be queued
on the PI Server if a system manager performs an edit operation on every point.

Maximum Number of Events in the Queue

It is possible to change the Maximum number of events queued in the entire update-manager
database by adding a TotalUpdateQueue tuning parameter. The default maximum number is
100,000.

Troubleshooting
Data passes through many steps on the way into and out of the Archive. When
troubleshooting, it is important to identify both data path malfunctions, and data paths that
function correctly.
OSIsoft recommends a three-step approach to troubleshooting a PI System:
1. Isolate the problem to a single computer, either client or server, or to the network. You
may follow the steps in the Troubleshooting Checklist to isolate the problem area. See PI
Messages, to review a list of error messages.
2. Further isolate the problem to a particular client program or PI subsystem. See Verifying
PI Processes (page 190) and PI Server Data Files for details.
3. Determine the exact cause of the problem.
This approach is intended to reveal what is needed to fix the problem, repair the damage, and
prevent a recurrence. If needed, see Repairs to repair data files such as Archives or Point
Database.
If you have worked through the Troubleshooting Checklist and have not yet resolved your
problem, call OSIsoft Technical Support for assistance. The technical support engineer will
ask for key information and may also ask to connect remotely to your system for hands-on
troubleshooting.

PI Server System Management Guide 187

Tuning, Troubleshooting, and Repairs

Troubleshooting Checklist

OSIsoft recommends that you complete the steps in this checklist to troubleshoot PI Server
problems. If you have not resolved the problem when you finish these steps, contact OSIsoft
Technical Support (page 233).
1. Look for Error Messages. If you know the specific error message, search the Technical
Support site for that error. If you do not yet have a specific error message, look at the
message logs on the Server and on the client node. For Server messages, you can use the
Message Log tool in PI SMT. Filter messages for a severity of Error and greater (Severity
Levels (page 129)).
You can't look at a client node message log remotely. You can run PI SMT directly on
the client node or you can use pige tmsg. For Interface problems, you can examine the
\pipc\dat\pipc.log files directly on the Interface Node. If this is a setup problem,
look at the setup logs in the 32bit pipc\dat directory.
To get a text description for an error number, use:
pidiag -e errornumber
For more information on error messages, see View System Messages (page 128). For
information about pige tmsg, see the PI Server Reference Guide.
2. Determine which computers exhibit the problem:
ο Client computer(s)
ο Server computer(s)
ο Interface computer(s)
To isolate the computers, run the questionable system against a system that is functioning
correctly and review the results.
ο A network problem is likely if all computers exhibit the malfunction.
ο A server problem is indicated if the malfunction occurs on all clients.
ο A hardware or networking problem is likely if the applications that malfunction do
not use PI Server. Run telnet to further isolate the problem. If telnet works, then the
network is not likely the problem.
3. If this is a client problem:
ο Check security. Log onto Windows using an account that has a Mapping to piadmin.
ο Check the Update Manager to make sure that the client is signed up for and receiving
updates.
ο If a trend in PI ProcessBook flatlines, see Flatline in a PI ProcessBook Trend (page
198).
4. If this is a server problem:
ο Verify that all PI processes are running. You can use the PI Services tool in PI SMT
to see the status of all processes running as Services.

Note: PI Systems may take several minutes to start; loading of the Point Database,
Snapshot and Archives takes most of the time. Utilities, such as piartool and
piconfig, are not fully operational until startup has completed.

188
 Troubleshooting

ο Even if a process is listed as running, it might be in a state where it is not

communicating with the PI Network Manager Subsystem (PINet Manager). Here are
some things to check:
− You can use the PI Services tool to check the Thread Details. Look at the State
column and the CurTime (milliseconds) column. If the State is InUse and the
CurTime is unexpectedly large, the thread might be hung.
− You can also use the SMT Network Manager Statistics tool to get more
information (Check Connections (page 193)).
− You can also use the utilities listed in Verifying PI Processes (page 190 ) to verify
that individual PI Server processes are communicating. For information about
connections, look at the Network Manager statistics.
− You can use piartool -block <subsystem> -verbose to check whether a
subsystem is responsive.
ο Try running PI Server with pistart.bat, rather than as services. The interactive
command windows may display additional status messages.
5. If a subs ys tem crashes, there may be additional information that can be useful to our
developers. Configure Dr. Watson (Configuring Dr. Watson (page 195)) or another
application debugger to generate a crash dump file.
6. Use netstat -a to verify whether other processes are communicating on port 5450; if so,
PINet Manager communicated successfully at one time.
7. If you have an Archive or Snapshot problem, use the piartool -as and piartool -ss
utilities to gather more information about the data flow (Verify PI Processes (page 190)).
ο Try retrieving a Snapshot three different ways; the combined results of all three tests
helps pinpoint the source of the problem:
− apisnap from a remote node (uses API + network)
− apisnap from the home node (uses API)
− piconfig < pisnap.dif from the home node (uses internal communication)
ο Do a Snapshot dump with piartool -sd. Run this a few times to determine if the
Snapshot is changing for the tags you're interested in.
ο To determine if the Archive has been corrupted, use piartool -aw (List Archive
Record Details (Archive Walk) (page 90)).
ο If this is an Update Manager problem, use the pilistupd utility to see which processes
are signed up for events.
8. Each PI System is distributed with a standard set of points including SINUSOID,
CDEP158, and CDM158. Verify that the points work properly.
9. For troubleshooting backups, see Back up the PI Server (page 97).

PI Server System Management Guide 189

Tuning, Troubleshooting, and Repairs

10. For troubleshooting Collectives, first use Collective Manager to check the status of all
members. Next use piconfig < pisysdump.dif:
− isavailable should be 1 for all members
− lastsynctime indicates the last successful communication
− role should be 1 for a primary and 2 for a secondary
11. If the problem is with Interfaces, typical tricks include:
ο Try running an Interface with only one point.
ο Run the Interface interactively.
ο Run the Interface without buffering.
ο Determine if the problem is with all points on all interfaces or just a few points on
some interfaces.
ο Verify that a PI Trust exists for that node or specifically for that interface.
ο Check the Firewall database.
ο Check the individual Interface log files, if any; also check the PI Message Log on the
Interface Node.
ο If an API Interface is not able to connect, try to connect with apisnap.
ο Try running as Administrator. If the problem goes away when you run as the System
Administrator, then you have a permission problem.
ο If this is the OPC Interface , check DCOM settings.

General Troubleshooting Tasks

Verify PI Processes
When PI Server is running, all its processes should be running. When PI Server is stopped, all
PI Server processes should be stopped. The exception is pishutev, which only runs briefly
at PI Server startup. The PI SMT PI Services tool shows the status of PI Services.
In PI SMT, the PI Services tool
piartool -thread <subsystem> -info
Even if a process is listed as running, it may be in a state where it is not communicating with
PINet Manager. There are several utilities you may use to verify that each PI process is
communicating properly.
To list all processes that are started as Services, enter at the command prompt:
net start
Each PI Server process or interface that is running interactively will have a separate
command window labeled with the process name.

190
 Troubleshooting

Archive Subsystem
Run the piartool -al, piartool -as, and pisnap utilities to test piarchss. If piarchss is
not working correctly, you will see:
C:\PI\adm>piartool -al
Getarchivefilelist Failed: [-10733] PINET: RPC Resolver is Off-
Line.
C:\PI\adm>piartool -as
Getarcmemtablestatistics Failed: [-10733] PINET: RPC Resolver is
Off-Line.
C:\PI\adm>pisnap
C:\PI\adm>apisnap localhost:5450

PI-API version 1.6.1.5

Attempting connection to localhost:5450

Enter tagname: sinusoid

Error: piar_getarcvaluex -10733

Error: piar_getarcvaluesx 100

Tag = SINUSOID Point Number = 1 Type = Real-32

12 Hour Sine Wave

Snapshot value
Value = ERROR ERROR
Status = ERROR

Latest archive value

Value = ERROR ERROR
Status = ERROR
Archive events are queued when the Archive Subsystem is not operating correctly. Use
piartool -qs to view the Event Queue count.

PI Base Subsystem
Run the pisnap and piconfig utilities to test the PI Base Subsystem. If the PI Base Subsystem
is not working correctly, you will see:
C:\PI\adm>apisnap localhost:5450

PI-API version 1.6.1.5

Attempting connection to localhost:5450
Error -994, connecting to localhost:5450
C:\PI\adm> piconfig
* (Ls - ) PIconfig> @tabl pipoint
*PIconfig Err> Table initialization error (PIPOINT
*@tabl pipoint
*[-10733] PINET: RPC Resolver is Off-Line.

PI Server System Management Guide 191

Tuning, Troubleshooting, and Repairs

PI License Manager
The PI License Manager, pilicmgr, provides license services for PI programs including
subsystems, client applications and interfaces. For example, PI Archive Subsystem registers
with the PI License Manager to obtain a valid license. If it fails to get its licens e, it may not
operate properly.
Run the piartool utility to test the PI License Manager. If pilicmgr is not working
correctly, you will see:
C:\PI\adm>piartool -lic usage
Continue after failure to register with License Manager. [-10733]
PINET: RPC Resolver is Off-Line.

PI Snapshot Subsystem
Run the piartool -ss and pisnap utilities to test the Snapshot Subsystem. If the Snapshot
Subsystem is not working correctly, you will see:
C:\PI\adm>piartool -ss
Getsnaptablestatistics Failed: [-10733] PINET: RPC Resolver is
Off-Line.
C:\PI\adm>pisnap

C:\PI\adm>apisnap localhost:5450

PI-API version 1.6.1.5

Attempting connection to localhost:5450

Enter tagname: sinusoid

Error: pisn_getsnapshotsx -10733

Error: piar_getarcvaluex -10733
Error: piar_getarcvaluesx 100

Tag = SINUSOID Point Number = 1 Type = Real-32

12 Hour Sine Wave

Snapshot value
Value = ERROR ERROR
Status = ERROR

Latest archive value

Value = ERROR ERROR
Status = ERROR

PI Update Manager
Run the pilistupd utility to test piupdmgr. If piupdmgr is not working correctly, you will
see:
C:\PI\adm>pilistupd
pilistupd -h for help
[-10727] PINET: RPC is Non-Existent
Producer Consumer Qual. Flags Pending
--------- --------- ------ ------ --------
status: [-12150] not registered in updmgr

192
 Troubleshooting

Running PI Processes Independently

Under normal operation, all of the PI Server processes are started up together using the
pisrvstart script, and are stopped together using the pisrvstop script. It is sometimes useful
in troubleshooting to run a subset of the PI Server processes. On Windows, pisrvstart.bat
starts each subsystem interactively in its own command window.
There are inter-process dependencies with the PI System. For example, all PI Server
subsystems rely on PINet Manager. Most subsystems require the PI License Manager, which
provides license services, and the PI Update Manager, which provides key services, to be
running. Also, the Archive Subsystem requires the Snapshot Subsystem for normal startup.
When troubleshooting, the following subsystems should generally be started in the order
listed:
• pinetmgr
• pimsgss
• pilicmgr
• piupdmgr
• pibasess
• pisnapss
• piarchss

STOPPING A W INDOWS PROCESS

To stop and start processes on Windows, use the Services dialog box in the Control Panel.
You may also use net stop to start and stop individual processes from a command
prompt. For example, to stop the PI Message Subsystem, enter:
net stop pimsgss

Check Connections
For information about connections, look at the Network Manager statistics. You can see these
in the PI SMT Network Manager Statistics tool (select Operation > Network Manager
Statistics). The pinetmgr process manages the Remote Procedure Calls (RPCs) that PI
Server subsystems and processes use to communicate with each other.
For example, if the Snapshot Subsystem (pisnapss) sends an event to the Archive
Subsystem (piarchss) for storage, the communication flows from pisnapss to
pinetmgr to piarchss. If the Archive Subsystem writes a message to the System
Message Log, the communication flows from piarchss to pinetmgr to pimsgss.
The Network Manager Statistics tool shows a lot of information. Some things to check for:
• BytesSent and BytesRecv can be helpful in identifying applications that are requesting or
sending unusual amounts of data. If the value for an application or interface is large
compared to other applications or interfaces of that type, then that might point to the
problem connection. (BytesSent and BytesRecv from PINetMgr will always be the
highest.)
• What client processes are connected from which nodes.

PI Server System Management Guide 193

Tuning, Troubleshooting, and Repairs

• How long clients have been connected.

• You can tell what type of application is connecting by looking at the RegAppType
column.
ο OSISDKApp indicates an SDK application.
ο OSIInterface indicates an Interface.
• ProtocolVersion can tell you whether the connection is from an SDK or API application.
A version number of 1.x indicates an API application. A version number of 3.x indicates
an SDK application.

Check Update Manager

The Update Manager keeps track of producers of updates (such as the Snapshot, the Archive,
and so on) and consumers of updates (such as Interfaces, ProcessBook, or ACE). It lets
clients and other consumers know when a value that they are interested in is updated.
If a client is not getting updates, check the Update Manager statistics for consumer and
producer statistics with the pilistupd utility. pilistupd -cs gives consumer statistics and
pilistupd -ps gives producer statistics. pilistupd -h gives information on usage. For more
information on pilistupd, see the PI Server Reference Guide.
Consumers. Look for the following:
• Is it the consumer registered?
• is the consumer timed out?
• Is the consumer signed up?
• When was the last time the consumer retrieved an update?
Producers. Look for the following:
• Is the producer connected?
• Is the producer sending updates?
• When is the last time it sent an update?
• How many signups does it have?
For more on a specific producer, you can use piartool -upd. The syntax is:
piartool -upd subsystem producer

194
 Troubleshooting

See PI Producers and Associated Subsystems (page 195) for a list of producers and
associated subsystems. Look for:
• send failures
• retrying
• is the producer responsive?
If all the consumers and producers are communicating correctly, but no events are coming
through, check the producer of the data (for example, Snapshot, Archive, or MDB).

PI Producers and Associated Subsystems

The following table lists the possible producers and what subsystem they belong to.
Producer Description Subsystem

snapshots snapshot Snapshot

archive archive Archive

ptupdates point updates Base

MDBUpdates module database Base

PIChangeRecordUpdates Configuration changes for PI Base

Server replication
DigitalSets digital sets Base

BDBUpdates batch database updates Archive

PIBatchUpdates batch updates Archive

PIUnitBatchUpdates unit batches Archive

PIUnitBatchOnUnitUpdates Unit batch updates for a Archive

specific unit
PICampaignUpdates campaigns Archive

PITr ansferRecordUpdates transfer records Archive

Configuring Dr. Watson

Dr. Watson is an application debugger included with some Microsoft operating systems. If
your operating system includes Dr. Watson, you can configure it to be the default debugger
and have it generate a crash file dump if your system experiences an error causing a computer
crash. This file can provide useful data to OSIsoft Technical Support.

Note: Dr. Watson is not included in Windows 2008 or Vista.

PI Server System Management Guide 195

Tuning, Troubleshooting, and Repairs

To set Dr. Watson as the default debugger, follow these steps:

1. Open a command window and enter:
drwtsn32.exe -i
2. Enter drwtsn32.exe again, without the -i parameter:

3. Use the dialog box to specify these recommended settings as shown in the Dr. Watson
for Windows dialog :
ο Log File Path: Use the default location.
ο Crash Dump: Use the default name. This file may be overwritten; after a process
crash, copy this file to a safe location.
ο Number of Instructions: 25
ο Number of errors to save: 25
ο Crash dump type: Full
4. Ensure that the checkboxes next to these Options are selected in the Dr. Watson for
Windows dialog box:
ο Dump symbol table

196
 Troubleshooting

ο Dump all thread contacts

ο Append to existing log file
ο No visual notification
ο No sound notification
ο Create crash dump file
5. Click OK to close the dialog box.
To test your selections, enter pidiag -crash in the command window and examine the log
files that are created.

Specific Proble ms

Slow Connections; Failure to Connect

The PI Network Manager looks up the host name of all computers connecting with PI API.
The name lookup is used to identify the connecting computer for trust login and PI Firewall
access. A Reverse Name Lookup requests the Domain Name Server (DNS) to translate an IP
address to host name. This request must complete in a reasonable amount of time for PI
Server to function correctly.
Network systems with malfunctioning Reverse Name Lookup will experience slow
connections or failure to connect to PI Server. Often the symptoms may be isolated to a
subnet or computers connecting from outside the LAN. The standard TCP/IP utility,
nslookup, can be used to check Reverse Name Lookup. If nslookup reports a delay when
resolving an IP address to name, the network has DNS problems that should be addressed.
Resolving this problem is a system network configuration task and beyond the scope of this
document.
If the problem cannot be resolved in a timely manner, you can temporarily disable the reverse
name lookup feature. To do this, set the ReverseNameLookupFlag tuning parameter to zero
(0). You can do this in SMT:
1. Select Operation > Tuning Parameters.
2. Click the New Parameter button .
3. In the Parameter Name field, type:
ReverseNameLookupFlag
4. In the Value field, type:
0
5. Click OK.
6. Restart the Base subsystem.

Note: This setting (like any tuning parameter) is not replicated.

To re-enable reverse name lookup, set the value to a non-zero entry.

PI Server System Management Guide 197

Tuning, Troubleshooting, and Repairs

Flatline in a PI ProcessBook Trend

If a PI ProcessBook trend flatlines, you may have a problem with PI ProcessBook, with the
PI Server, with network performance/connectivity/configuration, or with the data source.
Here are some possible diagnostic steps to take:
1. Determine whether only one tag is affected or several are affected. Check another trend
in ProcessBook to see if the problem is limited to only some points. If the problem
involves multiple points, go to step 2. If the problem involves only one point, go to step
4.
2. Try retrieving the data from the PI Archive by closing and reopening the trend window. If
the trends appear normal, the problem may be in the update signup. Go to step 3. If the
trends still show no data, go to step 4.
3. If no tags are producing trends, run pilistupd on the PI Server to see if the flatline is due
to ProcessBook not being signed up for updates. See Check Update Manager (page 194).
4. To determine whether the problem is with the PI Server or with the client application,
view the pending numbers in the results. Pending numbers represent the number of events
queued and not yet retrieved by the client such as PI ProcessBook. If data is not arriving
from the data source, the pending number remains at 0. If the client PI ProcessBook is not
retrieving the updates, the pending number continually grows and does not shrink.
5. If the pending updates are growing, try restarting the PI System. If this does not fix the
problem, contact OSIsoft Technical Support (page 233) for additional assistance. If the
pending updates remain zero, go to step 4.
6. If all the points are signed up for updates, and refreshing the data from the archive still
yields a flatline trend, the problem could be in the archive, in the data source, or in
communications to the data source.
7. To determine if the Server is working, create a trend for a point with data generated on
the Server, such as sinusoid, which is generated by the Random Interface on the
Server.
8. If the trend for sinusoid appears correctly, it means that the archive is working and
communication between Server and client is working. Then go to step 6.
9. If the trend for sinusoid does not appear correctly, go to step 5.
10. Use piartool -as or piartool -al to verify that the Archive is functioning properly.
11. Use piconfig or PI DataLink to try inserting data into a test point trend the point. If this is
successful, go to step 6. If not, contact OSIsoft Technical Support (page 233) for
additiona l assistance.
12. If all these tests are successful, the data source for the flatlined points may not be
working. Examine the Source point attribute of the point to find out which interface is
feeding data for the point in question.
13. Check the OSIsoft Technical Support (page 233) to verify that the interface program is
running and connected to the Server.
14. Verify that the interface program is communicating with the external data source (DCS
system, RDB system, and so on). See the documentation for the specific interface for
details.

198
 Troubleshooting

15. If the data source is running successfully, go to step 16.

16. Security may be preventing the process at some point. Examine the interface log files and
the PI Server Message Log files. Verify that both the data source interface and PI
ProcessBook have the correct access to the system. Examine all messages about trusts
granted or refused.
17. If the points in question have some access restrictions, there must be established trust
logins. The interface must have access as a PI user with WRITE access to the points. PI
ProcessBook must have read access to all these points.
If none of the above steps have resolved the problem, contact OSIsoft Technical Support
(page 233) for additional assistance.

Abusive Usage
If the PI Server uses most of the CPU needed to pinpoint a problem, it may be due to
improper sizing; that is, the configuration may be set too large for available hardware
compone nts, such as CPU, memory or disk.
The introduction of threading in release 3.4 solves many past performance issues; however,
very large Archive queries can still affect performance. The total number and size of queries
can be monitored with piartool -as.
If the amount of read access and number of events retrieved seem excessive, use the activity
grid (page 199).
Also, the PINetMgrStats table in piconfig can help identify network connections with the
highest traffic.

Activity Grid
The Archive Subsystem provides a tool to monitor the rate of read-access to the Archive.
This tool creates, over a finite time period, a grid of activity. The grid provides an account of
connections and point activity. Start the activity grid to temporarily identify the connections
that present the greatest load on the system and the points that are being queried most often.

Note: This monitoring requires significant computing resources and therefore is normally
turned off. Once the load on the system is identified, OSIsoft recommends that
you turn off the activity grid.

To start the activity grid:

piartool -aag start
To stop it, and remove all its memory:
piartool -aag stop
To temporarily stop the accounting yet allow querying of the current statistics:
piartool -aag pause
Each query requests the number of events retrieved or the number of retrieval calls made.
These can be arranged by points or by users. A yearly average might go through thousands of
events for a specified point, yet counts as a single call.

PI Server System Management Guide 199

Tuning, Troubleshooting, and Repairs

The following gets the number of events retrieved by point, from the time the activity grid
was started:
d:\pi\adm>piartool -aag point event
Name - Count - ID
SINUSOID 35 - 1
CDT158 100 - 3
CDM158 110 - 4
The following gets the number of event-retrieval calls, arranged by Connection ID:
d:\pi\adm>piartool -aag cnxn event access
Name Count ID
pidemo 3320 2

Problems with COM Connectors

Occasionally, errors are observed when OSIsoft client applications fail to obtain process data.
If the errors are related to a foreign data historian, the applications generally receive error
codes in the range -11200 to -11209, instead of returning data. As usual, you can use the
pidiag -e utility to translate these errors to text.
The source of the error can be the Redirector or the specific COM Connector in use. Before
you troubleshoot a COM Connection problem, you should verify that the Redirector is
operating correctly. Errors may be logged in either the Windows Event Log or the PI
Message Log. In general, the distinction is this:
• The Redirector logs information about its own activities to the Windows Event
Application Log. This includes startup, shutdown and loading of COM Connectors.
• The PI Subsystems record errors in foreign system point lookup and data retrieval in the
PI Message Log.
This section gives some guidelines for troubleshooting data retrieval problems from COM
Connectors. As new techniques become available, they are posted on the OSIsoft Technical
Support (http://techsupport.osisoft.com/) COM Connector page.

Check for Mapped Points in the Point Database

Mapped points should be correctly defined in the PI Point Database. A mapped point is one
that has the three identifying point attributes: ctr_progid, ctr_strmap and ctr_lmap.
To verify with piconfig:
piconfig
@table pipoint,classicctr
@mode list
@ostructure tag, ctr_progid, ctr_strmap, ctr_lmap
@select ptclassname=classicctr
@ends
Note that although this example uses classicctr point class, COM connectors are not limited
to using this point class as long as the three identifying point attributes are present in their
point class. Point class classicctr can be created using the piconfig file
classicctr.dif provided with the PI Server installation kit. You may create your own
point classes for PI Server mapped points.

200
 Troubleshooting

Check for the PI Redirector Process

If the PI Server mapped points are defined, a process called piudsrdr.exe should be
running. Check for this in the Windows Task Manager, Processes tab:

Note: After the piudsrdr service has been started, it remains in the list of running
processes, even if all mapped points are subsequently deleted.

PI Server System Management Guide 201

Tuning, Troubleshooting, and Repairs

CHECK THE PI MESSAGE LOG

If the Redirector is not running, check the PI Message Log using the pigetmsg utility.
Check for any messages related to the Redirector or a COM Connector. If the following
message appears, it means that the Redirector is not ins talled correctly:
0 pipoints 23-Jun-03 16:07:25
>> Error getting UDS Point interface. [-2147467261] Invalid
pointer
Attempt to reinstall by opening a command window, setting your default directory to the
PI\bin directory and issuing the command:
piudsrdr /RegServer
A Windows message is displayed in an alert box if the registration fails. Issuing this
command if the Redirector is already correctly installed has no effect.

CHECK THE W INDOWS EVENT VIEWER

To use the Windows Event Viewer to troubleshoot a Redirector failure:
1. Run the Windows Event Viewer.
2. Select Application.
3. Look for a message that indicates the PI Redirector can start but cannot keep running.
The Redirector will also fail to start if the Windows Event Log exceeds the maximum log
size. The default setting is to overwrite events as needed when the log file exceeds the
preconfigured maximum size.
To review the Application Properties settings:
1. Run the Windows Event Viewer.
2. Select Application > Properties. The default settings are:

202
 Troubleshooting

3. You can manually clear the log by clicking Clear Log to make room for more log events.

Note: You should adjust the settings according to your site's policy regarding logs and
your disk capacity.

RUN THE REDIRECTOR DUMP SCRIPT

Every COM Connector implements a method for obtaining information on its mapped points.
You can obtain a script for requesting this information from the OSIsoft Technical Support
Web site (http://techsupport.osisoft.com/).
Use these guidelines to ensure this script works correctly:
• Set the identity of the Redirector to This User in dcomcnfg; that is, some domain
user with administrative privileges on the hosting machine.
• Restart the PI Base, PI Snapshot and PI Archive subsystems only if the logged in user
account is different from the account those subsystems are running under.
• If the identity is set to The launching user, any logged in user who runs the script
is likely to start another instance of the Redirector. Such an instance of Redirector will
not share information with the one started by the PI Base Subsystem which contains the
mapped point information.

PI Server System Management Guide 203

Tuning, Troubleshooting, and Repairs

• If a change is made to the identity setting, restart the Redirector by restarting Base,
Snapshot, and Archive.
• If the identity of the Redirector is set to a specific user, you should make sure that all out-
of-process COM Connectors can be started and accessed by this user.
To find more information for troubleshooting Redirector and COM Connectors, go to the
OSIsoft Technical Support Web site (http://techsupport.osisoft.com/) and select Products >
COM Con nectors > PI COM Connectors.

Verify Redirector Installation

The Redirector is not installed separately; it is installed as part of the PI Server. To verify that
the Redirector was installed correctly, check the PI Server installation log file
piudsinst.log located in the root of your system disk. Look for two lines reading:
Registering PI UDS Redirector.
Creating EventLog registry key for piudsrdr
You can use the Windows utility dcomcnfg to confirm ins tallation and check the Redirector's
properties:
1. Enter dcomcnfg into a Command Prompt Window.
2. In the Component Services dialog, so to Component Services > Computers > My
Computer > DCOM Config.
3. Verify that OSI PI-UDS Redirector is included in the list of DCOM applications :

204
 Troubleshooting

Once you have confirmed from this dialog box that OSI PI-UDS Redirector is ins talled,
continue with the troubleshooting tips below until the problem is solved.
When you are able to clear the problem, you must restart the Redirector. This is done by
shutting down the Base, Snapshot, and Archive Subsystems and restarting them. There is no
method to restart the Redirector alone. The Redirector is not started if there are no mapped
points configured on the system.

COM Connectors
If a COM Connector is successfully loaded by the Redirector, a message like this is written to
the Windows Event Log:
Successfully registered PI Universal Data Server COM Connector
pipi.pipiconnector.
If the COM Connector cannot be loaded, a message to this effect is logged. Troubleshooting
steps depend on how the COM Connector is implemented. For details, see the manual for the
individual COM Connector.

PI Server System Management Guide 205

Tuning, Troubleshooting, and Repairs

COM Connectors are of two different types: in-process or out-of-process. The manual for the
specific COM Connector you are using will tell you the Connector type.

IN-PROCESS COM CONNECTOR

An in-process COM Connector is implemented as a DLL. When the PI Base Subsystem loads
a point that references the COM Connector, this DLL is loaded into the process space of the
Redirector. You will not see a separate process running.
Check the Windows Event Log. If the COM Connector is not registered, the message will say
this.
In this case, attempt to re-register the COM Connector by opening a Windows command
window, setting your default directory to the location of the COM Connector DLL and
running the regsvr32 utility. If the COM Connector DLL were named myconn.dll, enter:
regsvr32 myconn.dll
An alert box is displayed if the COM object implemented by the DLL cannot be registered. A
common cause of inability to register is DLLs upon which the COM object DLL depend are
not installed. The missing DLLs may be those provided by the foreign data historian vendor.

Note: In-process COM objects are not visible to the dcomcnfg utility. One way of seeing
the DLLs loaded by the Redirector is to use the ListDLLs utility available from
Microsoft (http://www.microsoft.com/technet/sysinternals/default.mspx ).

OUT-OF-PROCESS COM CONNECTOR

This type of COM Connector will appear as a separate process in the Windows Task Manager
window.
You should also check the COM object properties using dcomcnfg. The Properties and
Identity should match those of the Redirector, unless the COM Connector's manual says
otherwise.
If the COM Connector does not appear in the dcomcnfg list, it has not been successfully
registered. Attempt to re-register the COM Connector by opening a Windows command
window, setting your default directory to the location of the COM Connector executable and
running it with the /RegServer switch. If the COM Connector executable were named
myconn.exe, you would enter:
myconn.exe /RegServer
An alert box is displayed if dependent DLLs are missing. Other errors are not displayed.

Repairs

Repair the Archive Registry

This archive registry information is stored in a binary file called piarstat.dat. If this file
is corrupted, you can use the pidiag utility to rebuild it:

206
 Repairs

1. Copy piarstat.dat to a temporary location. Do not overwrite the original file.

Rename the file, in case you need it later.
2. Stop PI Server.
3. Run pidiag -ad and collect the dump of piarstat.dat, and verify the output.
4. If the results of the dump look normal, attempt the automated recovery. Otherwise, use
the interactive one.
5. Restart PI Server.
6. Check the message log to see if all archives are loaded. If the interactive version is used,
only the Primary Archive is loaded.
7. Register any remaining archives. If the interactive version was used, all other archives
must be registered.
Including the pidiag -ad, there are three ways to run the pidiag tool for Archive registry
repair:
-ad Dumps the current piarstat.dat file. This is used to review the data in the file.
-ar Pr ovides an interactive recovery utility for renaming the old piarstat.dat to
piarstat.old and generating a new one w ith a single entry – the Primary Archive –
provided by the user.
-ara Pr ovides an automated recovery utility that renames the old piarstat.dat to
piarstat.old and generates a new one w ith all of the entries found in the original file.
Any errors w ill cause the automated version to abort, and the user should resort to the
interactive version.

Recover Data from Corrupted Archives

Archive files have a header and a record structure. The records include data and auxiliary
information to index the records and links the records together for fast data access.
All data is susceptible to corruption if a system failure such as a power outage occurs. When
Archive file corruption occurs and the file becomes unreadable, it is important to recover the
file to the most complete state possible.
The Offline Archive Utility, piarchss, can be used to recover the data and rebuild the Archive
header and its associated metadata.

Recover a Non-primary Archive

To recover the data from a corrupted non-primary archive, run piarchss, specifying the
corrupted archive as the input file and a non-existing file as the output file. By default, the
start and end times of the input Archive are used as the start and end times of the newly
created output archive.
It is possible to recover the data in a non-primary Archive while the PI Server is still
archiving data. The Offline Archive Tool unregisters the archive during the recovery
operation.
Here is an example command to recover a non-primary archive:

PI Server System Management Guide 207

Tuning, Troubleshooting, and Repairs

$ ../bin/piarchss -if /export/PI/dat/piarch.001 -of piarch1.fix -

f 0
...First pass...
...Sorting input archive...
...Output pass...
676 Loaded in 2( 1 + 1 ) Seconds 338 Event/Sec.
739 Archive Total seconds - ratio: 369
In this example, piarch1.fix does not exist prior to the operation. It is created as a fixed
Archive the same size as the input Archive because -f 0 was specified. After it is created, it
may be registered using the piartool -ar utility, and then data events may be added to the
Archive in the usual way.
If the input file is registered prior to the recovery, it will be unregistered during the operation.
You need to register the input file when the recovery is complete.

Recover a Primary Archive

PI Server cannot archive data during the recovery process if the corrupted archive is the
Primary Archive. Because a Primary Archive cannot be unregistered, to recover it you must
either:
• stop the Archive Subsystem or
• force a shift so that the archive is no longer the Primary Archive
To force a shift, use the piartool -fs utility.
To recover the Primary Archive:
1. Stop the Archive Subsystem.
2. Run piarchss specifying the parameters:
ο Output archive is fixed size (-f 0)
ο End time left open (-oet Primary)
After recovery:
1. Rename the old Primary Archive.
2. Rename the output file to the same path and filename of the original Primary Archive.
3. Restart the Archive Subsystem.

Note: Every archive has a parallel annotation file, with an extension .ann. In PI
3.3.361.43, the annotation file is identified incorrectly after renaming its associated
archive file. Since renaming is necessary in this case, unregister the renamed file
after initial registration, and re-register it.

Example: Recover a Primary Archive

In this example, the Failed to unregister input archive message may be ignored. It occurs
because the Archive Subsystem was stopped prior to recovery.

208
 Repairs

$ ../bin/piarchss -if /export/PI/dat/piarch.005 -of

piarch.005.fix
-f 0 -oet 0
...First pass...
...Sorting input archive...
Failed to unregister input archive: [-10733] PINET: RPC Resolver
is Off-Line
Archive utility not running - or archive not registered
Continue processing...
...Output pass...
1084 Loaded in 2( 0 + 2 ) Seconds 542 Event/Sec.
1038 Archive Total seconds - ratio: 519
In this example, piarch.005.fix does not exist prior to the operation. It is created as a
fixed archive the same size as the input archive because the -f 0 parameter was specified. The
end time of the output archive is left open because the -oe t 0 parameter was specified.

Correct Archive Event Timestamps

Offline archive processing with time transformation differs little from standard offline
archive processing. All arguments, such as input file and output file, must be specified.
Additional arguments specify time transformation behavior. The additional arguments are:
-tfix time_conversion_file [-tfixend time -oeendtime time]
The argument -tfix followed by full file specification is required. The arguments -
tfixend and -oeendtime are optional.
The first option, -tfixend, followed by a timestamp specifies the time to perform no
transformations. All events with timestamps greater than or equal to this time will not be
transformed.
This option is used when only a portion of the archive has incorrect event timestamps. For
example, if a PI System was run for a period with incorrect system clock setting, then the
clock was set correctly and run for some period before applying a time transformation fix.
The second option, -oeendtime, followed by a timestamp specifies a timestamp to set as the
archive end time when conversion is complete. The archive end time is set to the passed value
if all events are older than this time; otherwise, the end time is set to the time of the oldest
archive event.

Time Conversion File Format

The time conversion file is an ASCII file containing a list of timestamp/offset pairs. The
timestamp and offset are separated with a comma. Lines beginning with #, and empty lines
and white spaces are ignored.
The timestamp may be a local time string in PI Time format; either an absolute time in the
format dd-mmm-yy hh:mm:ss or a relative time, such as *-300d or *. Only one
timestamp format can be used in a given file. The first format encountered is assumed for all
timestamps.

PI Server System Management Guide 209

Tuning, Troubleshooting, and Repairs

The offset is the number of seconds to add to the event timestamps. Sub-second precision of
the time shift is not supported. The offset is applied to all events with timestamps greater than
or equal to specified timestamp but less than next timestamp in the conversion file.
Here are some examples:
The following example uses UTC seconds time format. The timestamp 0, is January 1, 1970,
and 2000000000 is well into the 21st century. The offset is a positive 3600--one hour.
Therefore this data file will simply move all events ahead by one hour.
# Example 1, Moves entire archive ahead by 1 hour
0,3600
2000000000,3600
Example 2 is similar to Example 1, but uses local time stamps to specify a suitably large time
range to cover all events. The offset is -3600. This data file will move all events back by one
hour.
# Example 2, Also moves entire archive back by 1 hour
01-Jan-70 00:00:00,-3600
01-Jan-30 00:00:00,-3600
Example 3 applies a missed DST conversion for the Northern Hemisphere summer of 2003.
The first timestamp is set at 01-Jan-03 to include all events up to the DST transition; no offset
is applied up to, but not including 06-Apr -03 02:00:00. From 06-Apr -03 02:00:00 up to, but
not including, 26-Oct-03 02:00:00 one hour is added to all events. No offset is applied from
26-Oct-03 02:00:00 to current time.
# Example 3, Applies a missed dst conversion to an
# archive that covers summer of 2003
01-Jan-03 00:00:00,0
06-Apr-03 02:00:00,3600
26-Oct-03 02:00:00,0
31-Dec-03 23:59:59,0

Repair the Snapshot

There are two types of possible damage to the Snapshot from which PI Server can recover:
• Snapshot times in the future. Accidentally moving the PI Server system time into the
future can cause this; at a minimum all points collected loc ally will be in the future.
Snapshot events are replaced when a newer value is received; therefore these events
remain in the Snapshot until actual time catches up. Events earlier than Snapshot time
bypass compression. Events that bypass compression can put a large load on your PI
Server.
• Damaged or corrupted Snapshot file (piarcmem.dat). Corruption may be caused by
disk or power failures.

Recover from Future Times in the Snapshot

To fix Snapshot times that are in the future:
1. Stop the PI Snapshot Subsystem pisnapss on a running PI Server.

210
 Repairs

2. Re-start the PI Snapshot Subsystem from a command prompt and pass the -f argument.
This must be done interactively; not as a Windows service:
pisnapss -f
On startup, the PI Snapshot Subsystem looks for all Snapshots more than 20 minutes in
the future. These future Snapshots are overwritten with a NULL value. The Snapshot
Subsystem reports the number of future events detected to the message log. If no future
Snapshots were detected, no fix messages are written to the message log. New incoming
data immediately overwrites the NULL Snapshot, even if the incoming value is out of
order.
The Snapshot Subsystem continues to run normally after the fix.
3. Ctrl+C the interactive pisnapss process and restart it as a service.

Note: Snapshots fixed by this procedure remain set to NULL until a new snapshot event
arrives. A NULL Snapshot value is replaced by any new event that is received for
a point, even if the event is an out-of-order event.

Rebuild the Snapshot File

If you receive a message to indicate that PI Server is unable to start because the Snapshot file,
piarcmem.dat, cannot be loaded, it is necessary to generate a new Snapshot file. A
rebuilt snapshot file contains events based on the point database and, in some cases, digital
states of SnapFix. The rebuilt Snapshot is updated as the PI System receives new data.

Note: If the piarcmem.dat file is damaged, OSIsoft recommends that you contact
OSIsoft Technical Support for assistance with this procedure.

To rebuild piarcmem.dat :
1. Shut down the PI Base Subsystem, PI Archive Subsystem and the PI Snapshot
Subsystem.
2. At a command prompt, change to PI\bin and enter:
pibasess -snapfix -file

PI Server System Management Guide 211

Tuning, Troubleshooting, and Repairs

3. You may also enter these other optional parameters:

Param eters Purpose

filename - ds provides the full filename of an optional input file to use in place of
piarcmem.dat

-ds state specifies a system digital state that w ill be inserted in the new file

- maxtime sets the latest time stamp allow ed in the snapshot; pisnapss -f
truncates at *+20 minutes
time indicates a time limit beyond w hich the pr ior digital state of events
w ill be replaced w ith SnapFix, or the digital state you specify w ith
the state parameter

a. Enter a filename only if you have a file that you want your new piarcmem.dat to
be built from. If you want to rebuild the Snapshot file based on the most current
values in the Snapshot, do not enter a filename. If a piarcmem.dat exists, the PI
Base Subsystem will rename the piarcmem.dat file that contains the current
Snapshot values to DD_MON_YY_piarcmem.dat; then, it will build a new
piarcmem.dat from the renamed piarcmem.dat. If there is no
piarcmem.dat, a new file is created.
b. If you enter a state, you must use an existing digital state.
The PI Base Subsystem will write a message to the screen indicating that Snapshot
recovery mode has been specified and that recovery is in progress. If multiple points
containing multiple recnos are found, these points are listed and the snapshot recovery
process is stopped until the duplicate points are removed.

Note: If duplicate recnos exist in piarcmem.dat, you must intervene before the
Snapshot rebuild can proceed. You will need to determine which points to
remove from the Snapshot file.

4. If duplicate points are found, use the ptpurge parameter to remove duplicate points:
pibasess -snapfix -ptpurge pointtopurge
or,
pibasess -snapfix -ptpurge filelist
where pointtopurge is a single point, for example mypoint. If you want to use a file that
contains the names of multiple points, use filelist. For example,
pointstodelete.dat.
When recovery is complete, the PI Base Subsystem will write a final message to the
screen and exit.

212
 Repairs

5. Restart the PI Base, PI Archive, and PI Snapshot subsystems. Current Snapshot values
are preserved in the rebuilt piarcmem.dat file. Points that have no previous data will
use the SnapFix digital state, or the digital state you specify with the state parameter,
until the state is replaced by new snapshot values. Any snapshot record that does not have
a matching point is removed.

Note: This Snapshot recovery command can be run with the entire PI Server shut down.

Remove Future Time Snapshots

The piconfig utility can be used to remove all or selected Snapshot events. When the
Snapshot event is removed, the Snapshot Subsystem attempts to retrieve the latest archived
event from the Archive and replace the Snapshot event with it. That event is removed from
the Archive. If there are no events for the point in the Archive, the Snapshot is deleted and
remains uninitialized until a new Snapshot event is sent.
The following piconfig script shows how to do that:
piconfig table pisnap
* (Ls - PISNAP) piconfig> @sele tag=*,time>"*+10m"
* (Ls - PISNAP) piconfig> @ostru tag,value,time
* (Ls - PISNAP) piconfig> @sigd 8
* (Ls - PISNAP) piconfig> @output deletesnap.dat
@endsection
@output
* (Ls - PISNAP) piconfig> @table piarc
* (Ls - PIARC) piconfig> @mode ed,t
* (Ed - PIARC) piconfig> @modify mode=remove
* (Ed - PIARC) piconfig> @istru tag,value,time
* (Ed - PIARC) piconfig> @echo v
* (Ed - PIARC) piconfig> @input deletesnap.dat
The first part extracts all the events that are later than 10 minutes past the current time into a
file. The second part (using the PIARC table) removes all these events from the Snapshot.
The last archive event for each tag replaces then Snapshot.
Any combination of conditions can be used to select the events to be deleted, for example all
tags of a specific interface.

Note: The significant digit command, @sigd 8, ensures that rounding errors do not
cause values to be missed.

PI Server System Management Guide 213

Tuning, Troubleshooting, and Repairs

Repair Databases

If the PI Base Subsystem does not start due to a corrupted database, the log shows a message
indicating this. If there is no such message, start the PI Base Subsystem in interactive mode
and observe the errors in the window. Database corruption is a relatively rare event. It is
usually due to hardware failure or improper shutdown. To repair all databases:
pibasess -copydb path
For example:
pibasess -copydb \pi\recovereddb
Following this command, the target path contains recovered copies of all the configuration
databases. Corrupted records are eliminated and related messages displayed.
Be sure to make a backup copy of the \pi\dat\ directory before you copy the recovered
database files back into this directory.
After that, pibasess should load all databases and work normally. The resulting files are
slight ly smaller than the originals as they are compacted in the process.

Repair the Module Database

To perform a module database clean-up, use:
pibasess -mdbfix
The following results occur:
• Table and index entry count size checks are performed. The entry counts should be the
same.
• Modules that have a record size of zero are removed. These modules would be
unrecoverable.
• Parent and children references to non-existent modules are removed.
This utility may modify the Module Database. Therefore it is important to have a safe
backup.

Diagnose and Repair PI Syste m Databases

Most of the PI System internal databases are stored in files that have a common internal
structure. Data is stored in records and the records are indexed. We call this structure file
based. This section discusses the tools for diagnostics and repair of such database files.

List the Index

To list the header and index of a file base file, type:
pidiag -fb path [-header | -dv]

214
 Repairs

The -header option suppresses the listing of the index and shows only the header. The -dv
option displays the file’s version only.
OSIsoft technical support can determine from this information if any errors occur in the
structure of the file:
D:\PI\adm>pidiag -fb d:\pi\dat\pidigst.dat
PIfilebaseheader[$Workfile: pifile.cxx $ $Revision: 125
$]::
File Name: D:\PI\dat\pidigst.dat
Major Version: 4
Minor Version: 0
Byte Alignment: 1
Directory Location: 1024
Directory Size: 1024
Record Count: 18
Last Recno: 0
Maximum Recno: 128
User Block Size: 512
Data Location: 2048
Data Size: 23325
Auto Compact %: 0
Last Modified: 10-Sep-09 09:45:11
Backup Time: 25-Aug-09 14:26:11
PIsecureobject[$Workfile: pisecobj.cxx $ $Revision: 46
$]::
ACL ID: 1 [ 1:A(r,w)|5:A(r)|2:A(r) ]
% unused: 0

Compact a File-base Data File

To remove unused space in a file base file, type:
pidiag -fbc path [-header]
The percentage of unused space in a file can be viewed with pidiag -fb. If there is more than
10% of unused space, you might want to compact the file to save disk space.
The header and index of the compressed file is displayed after the compression. The -header
option can be used to suppress the listing of the index.

Recover File-base Data File Index

To recover readable data records from a file and rebuild the index, type:
pidiag -fbf inpath outpath [alignment][-compress][-header]
It is useful in cases where the index is corrupted and where some records are inaccessible or
corrupted. Note that when there are unreadable records, they are discarded and an error
message is printed. This tool should only be used following OSIsoft Tech Support’s advices.
The optional alignment parameter specifies the byte alignment to use in the recovered file. It
allows the recovered file to be able to grow larger than 2GB.

PI Server System Management Guide 215

Tuning, Troubleshooting, and Repairs

The -compress option removes unused records.

After recovering the file, the tool displays the header and index of the new file. The -header
option can be used to suppress the listing of the index.

Recover from Accidental System Time Change

The PI Server handles automatically all changes to system time. Thus we recommend that
you never manually change the system time. On Windows, always use the automatic DST
option.
However, occasionally such changes are required, and unfortunately, from time to time this
change leads to human errors. For example instead of moving the clock to 2 AM it is moved
to 2 PM. Time synchronization software, designed to keep computer clocks accurate without
error-prone human intervention, have also been implicated in moving system clocks
erroneously. As a result, the events are recorded in the future. Usually this is discovered after
many of these events were already stored in the Archive. To recover from such situation:
1. Stop the PI System.
2. Correct the system time and the time on all connected nodes.

Note: If you are using the PI Buffer Subsystem to buffer data from PI Interfaces, see
If you use the PI Buffer Subsystem (page 217).

3. Isolate the PI Server from interface nodes. The best technique is to disconnect the server
from the network. While fixing the PI Server, it is best to allow the data to buffer until the
system is verified up and running normally.
4. Rename the Event Queue file, pimapevq.dat for later processing. The Event Queue
may contain many future events. Rename the following files located in the dat
directory:
ο pilastsnap.dat
ο pilasttot_T.dat
ο pilastalarm.dat
5. Create an empty archive file using PI SMT or the piarcreate utility.
6. Run pidiag -ar and register only the new empty archive.
There are two options for fixing the Snapshot:
1. If the erroneous future data can be discarded, start the Snapshot Subsystem with -f flag
as described in Recover from Future Times in the Snapshot (page 210).
2. Otherwise, keep the current file, and after the system startup, delete or edit individual
values using piconfig, as explained above.
3. Start the PI Server in base mode. This starts only the minimum required subsystems:
PINet Manager, PI Message Subsystem, PI License Manager, PI Update Manager, PI
Snapshot Subsystem, PI Archive Subsystem and PI Base Subsystem:
pisrvstart -base

216
 Repairs

4. Register all the old Archive files except for the previous primary, which contains future
data.
5. Examine the unregistered Archive file header to confirm the time boundaries of the
various Archives involved before using offline Archive processing to merge Archives:
a. to look at the header of an unregistered Archive:
pidiag -ahd
b. to look at registered Archives
piartool -al
6. Create a new primary archive using piartool -ac.
a. Specify a start time before any events that might be coming in. Specify the end-time
as *. This instructs the Archive Subsystem to register the new archive as primary
Archive. The start time specified must account for all buffered data. If you are
unsure, set the start time well before the time the problem was first encountered.
b. If necessary, you can use offline archive processing later to merge this data with
existing archives.
7. Verify that the PI System is running correctly. Reconnect the server to the network.
8. Reprocess the old Primary Archive using the offline tool to either filter out the future
data, or correct its time by the required difference.
9. Reprocess the Event Queue into an archive file and correct timestamps as required.
10. Optionally combine these two archives: the old primary and the result of the Event
Queue.
11. Register the corrected archive file.

If you use the PI Buffer Subsystem

If the timestamp on the interface node or nodes were changed to a future timestamp and you
are using the PI Buffer Subsystem, complete these additional steps:
1. Stop the PI Buffer Subsystem.
2. Stop the interface nodes.
3. Delete the pibufmem.dat file.
4. Restart the PI Buffer Subsystem.
5. Restart the interface nodes.

Resolve Excessive CPU Usage by Utilities

The utilities piconfig, pige tmsg, pilistupd and piartool may use excessive CPU. You can fix
this problem by increasing the time-out values for these utilities. This prevents the utilities
from using when listening to messages.

PI Server System Management Guide 217

Tuning, Troubleshooting, and Repairs

Increase the values as follows:

piconfig> @table pitimeout
piconfig> @mode edit
piconfig> @istructure name, value
piconfig> piartool, 100
piconfig> piconfig,1000
piconfig> pigetmsg,1000
piconfig> pilistupd,1000
piconfig> @endsection
This message would typically be viewed with pigetmsg or in log/pinetmgr.log. This
error is due to insufficient resources available to complete the transfer of a large message.
The fix is to inc rease the default time-out and the number of retries PINet Manager uses for
message transfer. Read and write time-outs default to 50,000 microseconds, read and write
retries default to 250. We recommend increasing the time-outs in increments of
approximately 25 percent until the errors disappear. If the errors persist when the timeout
values are over 150,000 microseconds, contact OSIsoft Technical Support (page 233 ).
To increase the timeouts:
piconfig> @table pitimeout
piconfig> @mode edit
piconfig> @istructure name, value
piconfig> readtimeout,62500
piconfig> writetimeout,62500
piconfig> readretry,350
piconfig> writeretry,350
piconfig> @endsection

Note: PI Server installation sets all timeout values to well-tested initial values. Changes
to these values should be done under the advice of OSIsoft Technical Support.
Very short timeout values may cause specific utilities to spin faster and thus use
more CPU. Before making changes based on CPU consumption, isolate the CPU
to the offending processes. Use available tools to analyze each process. For
example, if pisnapss is in a high CPU state, run piartool -ss and look at
Snapshot read and write rates because excessive rates may be the true source of
CPU load.

218
Appendix A

PI SQL Subsystem
The PI SQL Subsystem (pisqlss) prepares and executes SQL statements directed at the PI
Server. The primary users of this subsystem are the PI ODBC Driver and the PI SDK. This
driver conforms to the ODBC API standards and makes PI data appear to be organized into
data tables. PI ODBC 1.1.2 or later is required to connect to PI Server.
OSIsoft's implementation of SQL gives applications access to the PI Point Database,
Snapshot, and Archive. For supporting information, such as details of OSIsoft's
implementation of SQL, see the PI ODBC Driver Manual.
SQL processing capability is also implemented in the PI System for OpenVMS. Differences
between the two are discussed in this chapter.

Architecture
This section outlines the operation of the PI SQL Subsystem and its interaction with the PI
API.
This discussion is provided as background material. You do not need to understand the details
of the subsystem's operation in order to use it.

Statement Handles

Most interactions between PI clients and the PI Server do not require the Server to maintain
any context, that is, any record of the client's operation. Any request for point information or
Archive data can be serviced using only the information provided by the client in the request
itself.
The processing of SQL statements is different. When an SQL statement is processed, the
Server must maintain a record of the statement's status in order to be able to perform
subsequent operations.
This is done by having the PI SQL Subsystem allocate a statement handle when a client
initiates the processing of an SQL statement. The client retains the handle's identifier and
provides it to the server with every request.
The details of handle allocation and de-allocation are managed internally by a PI API based
client application, such as the PI ODBC Driver.
If connection between the client and Server is lost, the PI SQL Subsystem retains any
statement handles allocated by the client. These handles become orphaned and cannot be
accessed again. The handles are de-allocated when the PI SQL Subsystem shuts down.

PI Server System Management Guide 219

PI SQL Subsystem

During shutdown, pisqlss will report the total number of handles allocated during its run, and
the number of orphaned handles that were aborted.

Concurrency

The PI SQL Subsystem handles SQL processing for all client connections to the PI Server.
Operations such as parsing an SQL statement and fetching results are relatively inexpensive.
Execution, however, can potentially take time and system resources as data are obtained from
other subsystems.

Configuration
No advance configuration is necessary to start pisqlss. It is started and stopped exactly the
same way as other subsystems. On Windows, pisqlss can be run as a service.
Some tuning of pisqlss performance is possible. Settings can be changed using an
initialization file, pisqlss command-line parameters, and through settings on a client product,
such as the PI ODBC Driver.

Note: The use of an initialization file may change in a later release to an alternate
method. At that time, any site-specific settings found in the initialization file are
migrated.

See your client product documentation for instructions on changing SQL processing settings
from the client application.

Hierarchy of PI SQL Subsyste m Settings

Since it is possible to set parameters using more than one technique, some of the settings may
be in conflict. The actual value of the settings employed follows this priority scheme:
• Initialization file settings
• pisqlss command-line arguments
• Client product settings
Settings made lower in the list override settings higher up. For example, if the SQL query
timeout is set to 45 seconds in the initialization file and to 60 seconds on the pisqlss
command-line, the value used is 60 seconds.

Initialization File Settings

The initialization file is called pisql.ini and can be found in the PI\dat\ directory of
your PI Server. The file contains defaults for all settings. You may change the settings by
editing the file.

220
 Configuration

The initialization file settings are read when a new statement is allocated. Any change to this
file is reflected in the next new statement.

Note: On a PI System for OpenVMS, the initialization file is PISysDat:pisql.ini.

The interpretation of the file settings is exactly the same for both PI Servers.

For details on the settings, see the PI ODBC Driver Manual.

pisqlss Command-Line Arguments

This section outlines the pisqlss settings that can be altered using command-line arguments.
The mechanism for specifying command-line arguments differs between supported platforms.
This section outlines the techniques.

Arguments Supported by pisqlss

In general, an argument is specified by an argument token, one or more spaces, and then the
argument value. The argument token always begins with a leading dash ( - ). For example:
pisqlss -t 60 -ts 7200 -o trace,aggrtimestart
In this example, SQL query timeout is set to 60 seconds, the default timestep (for queries
against the piinterp table) is set to 7200 seconds (that is, 2 hours) and the trace and
aggrtimestart options have been set.
The PI SQL Subsystem supports the following command-line arguments:
Argum ent Description
-o (Letter o, not zero). Options. The options are specified in a comma-separated
list of tokens. The interpretation of the tokens is not case-sensitive. See the
follow ing table for the list of supported options.
-t SQL query tim eout, in seconds. If this time expires, the PI SQL Subsystem w ill
cause the query to return either a timeout error, or a subset of the actual results, if
the SUBSET option is set. See the table of options below .
-ts Default value of the timestep column in the PIINTERP table. This value can be
overridden for any query by specifying a timestep constraint in your SEL ECT
statement.

The -o argument is followed by a comma-separated list of option tokens with no space

between the tokens. The supported options are:
Option Token Description
AGGRTIM ESTART Causes all quer ies of the aggregate tables to use the time at w hich the
interval starts to identify the aggregate; the default is to use the time at
which the aggregate period ends.
EXECSAFE If set, the query does not execute if the PI SQL deter mines that a query is
too unspec ific and w ould take too long to execute.

PI Server System Management Guide 221

PI SQL Subsystem

Option Token Description

LOG Writes a summary of every operation by pisqlss on a statement handle
to the file sqltrace.log in your \pi\log\ directory. See also the
TRACE option.
Note: This file is generated in all PI Server configurations, except w hile not
running as a service on Window s. In this case, output is directed to
standard output, w hich is the command w indow .
QEP Causes the gatew ay to dump a query execution plan to a file called
pisql_n.qep in the \pi\log\ directory on the PI Server, w here n is the
handle number.
SUBSET If a query times out w hile this option is in effect, the PI SQL Subsystem
returns a subset of the actual results w ith no error.
Note: If this option is in effect, the results returned do not represent the
actual final results of the query. When query development is complete,
remove this option.
TRACE Writes a summary of every Prepare, that is, query parsing, and Execute
operation by the PI SQL Subsystem to the file sqltrace.log in your
\pi\log\ directory. See also the LOG option.

See Troubleshooting (page 223) for details of the information generated in the
sqltrace.log file by the LOG and TRACE options.

Specifying Command-Line Arguments

There are two different methods for providing command-line arguments, depending on how
the PI Server is started.

Starting the PI SQL Subsystem in a Command Window

Command-line arguments can be provided to a Windows program by listing them after the
program name. You can edit the file pistart.bat to include command-line arguments
when starting subsystems.
Starting the PI Server this way results in a command window for every subsystem. You
cannot log off Windows in this configuration and leave the system running.
Use caution in editing pistart.bat. This file is overwritten at every PI Server upgrade.

Starting pisqlss as a Windows Service

Subsystems can be started by running Services in the Control Panel, or by using the
pisrvstart.bat file in your PI\adm directory.
To pass command-line arguments to the PI SQL Subsystem running as a Windows service: in
the Control Panel open Administrative Tools. Open Services, select the PI SQL
Subsystem, right-click and choose Properties. Stop the service, and enter the arguments into
the Start parameters window. Click the start button to restart the PI SQL Subsystem.

222
 Troubleshooting

This example shows a system manager about to restart the PI SQL Subsystem while setting
the default timestep to 7200 seconds and turning on TRACE mode.

Note: This works one time only. If you close the Services, then reopen and reselect your
service, you will not see your command-line arguments from the last run. This
method cannot be used to provide command-line parameters to services started
automatically when your Windows system boots.

Troubleshooting
Unexpected errors may be generated when using an ODBC application to communicate with
the PI Server.
This section outlines techniques to help you validate the operation of the PI SQL Subsystem
and to log its processing steps.

PI Server System Management Guide 223

PI SQL Subsystem

Generating a Trace File

A trace file can be generated by starting the PI SQL Subsystem with the LOG or TRACE
options. For details on how to do this, see Configuration (page 220).
The options LOG and TRACE are similar. Both generate information in the
sqltrace.log file in the PI\log\ directory. The LOG option provides more detail.
The options can be used together. Output from the two is interspersed.

Output from the TRACE Option

Invoking the TRACE option shows a summary of SQL statement preparation and execution
only.

Statement Preparation Output

Output lines are of the form:
Prepare[HandleNum]>[ErrorCode][ElapsedTime] query_string
Elapsed time is given in seconds. For example,
Prepare[1]>[0][0.012s] select * from picomp
where tag = sinusoid and time > ?
This statement contains one parameter, identified by a question mark ( ? ), whose value is
provided at run time. Run-time parameters are discussed in detail in the PI ODBC Driver
Manual.

Statement Execution Output

Output lines are of the form:
Execute[HandleNum]>[ErrorCode][ElapsedTime] Parameters: NParams
Columns: Ncols Rows: Nrows
If the number of run-time parameters is non-zero, this message is followed by one line for
every provided parameter:
Pnn [DataType Length] parameter_value
where nn is the run-time parameter number, starting with 0.
For example, the Execution message following the above Prepare message might read:
Execute[1]>[0][0.041s] Parameters: 1 Columns: 4 Rows: 16
P00 [time32] 21-Jul-97 00:00:00
The query in this example returned 16 rows of 4 columns. The query was provided with one
run-time parameter: a timestamp.

224
 Troubleshooting

Output from the LOG Option

Output from the LOG option is more detailed. It reflects directly the argument list of the
Remote Procedure Calls (RPCs) implemented by the PI SQL Subsystem. Most of the
information generated should be forwarded to OSIsoft in the event of a query processing
problem.
In general, the first argument of each RPC is the handle ID. The only exception is the
newstatement function, which is the routine that generates the handle ID. In this case, the
returned handle ID is the second argument.

Function Summary Format

The LOG option generates output that looks like this:
FunctionName(arg1, arg2, ...) [ErrorCode]
During query execution, progress messages are written to the log file. Each progress message
is of the form:
(HandleId): Calls: n PctDone: n Etime: n Limit: n
The items reported are:
• Number of calls to get PI data from other subsystems,
• Percent complete, based on an initial estimate,
• Elapsed time since the start of execution, in seconds,
• Timeout (Limit) in seconds. If this number is 0, no timeout limit has been set.
For example:
newstatement(8,21) [0]
clear(21,1) [0]
clear(21,0) [0]
Prepare[21]>[0][0.431s] select * from picomp
where tag = "sinusoid" and time > "y"
execute(21,&params) begins...
callback(21): Calls: 1 PctDone: 0 Etime: 1 Limit: 0
fetch(21,*results) [0]
clear(21,1) [0]

Clearing Expensive Query Problems

It is possible that an ODBC client application sends an incomplete query, or a query that
returns too many results, to PI Server. When a query is timed out, it may or may not hold on
to the server resource, mainly the virtual memory. If the timeout occurs during the query
execution, the statement handle and its resource are freed. If the timeout occurs during the
fetch, the statement handle is not freed. To clear the statement handle and its resource, shut
down and restart the PI SQL Subsystem.

PI Server System Management Guide 225

PI SQL Subsystem

To do this, send a stop command to the PI SQL Subsystem using one of the following
methods:
• From the Control Panel > Administrative Tools, run Services. Select the PI SQL
Subsystem from the list and click Stop.
• From a command-line prompt, enter:
net stop pisqlss
• From a command-line prompt, enter:
\pi\bin\pisqlss -stop
A message is written to the message log indicating that the PI SQL Subsystem has been
stopped. Another message indicates the number of handles allocated and the number of
handles aborted during the shutdown.
To restart the PI SQL Subsystem and resume normal operation, use one of the following
methods:
• From the Control Panel > Administrative Tools, run Services. Select the PI SQL
Subsystem from the list and click Start.
• From a command-line prompt, enter:
net start pisqlss
• From a command-line prompt, enter:
\pi\bin\pisqlss -start
A message is written to the message log indicating that the PI SQL Subsystem has been
continued.
Shutting down and restarting the subsystem can be done at any time and is equally effective.
This is the only option available when running the PI SQL Subsystem on Windows
interactively.

Performance Counters

In PI Server for Windows, several aspects of PI SQL Subsystem processing can be monitored
continuously using the Performance Monitor application.

Technical Support and Proble m Reports

If the PI SQL Subsystem consistently returns an error when processing SQL statements, or
appears to generate incorrect results, you should stop the PI SQL Subsystem and then restart
with the TRACE and LOG options enabled. Send the resulting sqltrace.log to OSIsoft
Technical Support.

226
Appendix B

PI Data Retrieval with Foreign Data Sources

Data is sometimes not stored in the Archive or Snapshot Subsystem. Data may be stored in an
external or foreign data source. The Base, Archive, and Snapshot Subsystems can request
data from foreign data storage systems through modules called COM Connectors. A separate
COM Connector must be installed to communicate with each specific foreign data system.
A PI Server system may have any number of COM Connectors installed. Since the identity of
the COM Connector to use is determined on a point-by-point basis, a single PI Server can
access any number of foreign data systems.
The core subsystems of the PI Server do not communicate directly with COM Connectors.
Instead, the subsystems send requests to the PI Server Redirector, which acts as a request
broker. The Redirector loads one or more COM Connectors and forwards the requests to
them.
The Redirector and the COM Connectors are COM objects, implemented using Microsoft
Component Object Model (COM) technology. The Redirector is installed as part of the PI
Server. COM Connectors are installed separately.
COM Connectors are installed on the PI Server, but are not loaded into the server's memory
until needed. When PI shuts down, the Redirector and all COM connectors are automatically
unloaded from memory.
COM Connectors may be in-process or out-of-process COM objects. In-process COM objects
are .dll files, while out -of-pr ocess COM objects are .exe files. For a list of available
COM Connectors, see the PI COM Connectors Home page on the OSIsoft Technical Support
Web site (http://techsupport.osisoft.com/). If the existing COM Connectors do not fit your
needs, contact Technical Support (page 233).
The PI Server Redirector is an out-of-process COM object. It does not run as a service, which
means it is not found in Services in the Control Panel. When the Redirector runs, system
managers can see a process called piudsrdr.exe in the Processes tab of the Windows
Task Manager.
Client applications are not aware of the difference between data retrieval from the PI Archive
and data retrieval from a foreign data storage system using a COM Connector. In all cases,
the application connects to the PI Network Manager. Each point that data is retrieved from is
identified by a tag, and has attributes stored in the PI Point Database, regardless of the source
of the data. The Snapshot and Archive Subsystems implement the differences in data flow.
For details, see Retrieval of Snapshot Data (page 228) and Retrieval of Archive Data (page
229).
The PI Server sends data to client applications in exactly the same way, regardless of whether
the data is stored in the Archive Subsystem or in a foreign data source. The same is true of
data requests from PI Server Subsystems such as the Totalizer, the Alarm Subsystem, and the
Performance Equation Scheduler.

PI Server System Management Guide 227

PI Data Retrieval w ith Foreign Data Sources

The PI Server can write data into a foreign data system if it is supported by the COM
Connector for the foreign data system.

Point Configuration
In order to interact with a point on a foreign system, a corresponding point, called a mapped
point or COM Connector point, must be created in the PI Point Database. A mapped point in
the Point Database is one that links to data in a foreign system.
To build a mapped point, select a point class that includes the following point attributes, as
well as the normal attributes of a point class:
COM Connector Point Attributes

Attribute Description
ctr_progid COM program ID, as stored in the Window s registry. This name is used to
invoke the COM Connector object w hen needed.
ctr_lm ap Longw ord mapping parameter. ctr_lm ap and ctr_strm ap are passed to the
COM Connector so that it can locate the appropr iate foreign system point.
ctr_strm ap String mapping parameter. ctr_lm ap and ctr_strm ap are passed to the COM
Connector so that it can locate the appropriate foreign system point.

PI Server includes the classicctr point class, which contains these point attributes as well as
the base and classic attribute sets. To create this point class, run the script
PI\adm\classicctr.dif using the piconfig utility.
Construct points according to the specifications of the point class. For details, see PI Point
Classes and Attributes (page 23). Points are created and maintained using the PI
TagConfigurator, a Microsoft Excel spreadsheet-based tool, or piconfig, a script-based tool.
Whenever the point information indicates that the requested point is a mapped point, the
Redirector obtains data values from the corresponding foreign system point.

Retrieval of Snapshot Data

When the PI Server Snapshot Subsystem starts, the Base Subsystem notifies it of the presence
of mapped points. When a client application requests a Snapshot value, the Network Manager
routes the request to the Snapshot Subsystem.
If the point's data is normally stored in the PI Archive, the Snapshot value is retrieved from
the Snapshot Subsystem and then returned to the Network Manager.
If a Snapshot value for a mapped point is requested, the data path is different. In this case, the
Snapshot Subsystem requests the value from the Redirector, which in turn requests the value
from the appropriate COM Connector. The COM Connector obtains the value from the
foreign data storage system and returns it to the Redirector, which sends it to the Snapshot
Subsystem. It is then routed to the Network Manager for transmission to the client.

228
 Retrieval of Archive Data

Retrieval of Archive Data

The retrieval of Archive data from the COM Connector by the PI Server Archive Subsystem
is similar to Snapshot retrieval by the Snapshot Subsystem. When the PI Server Archive
Subsystem starts, the Base Subsystem notifies it of the presence of mapped points.
If Archive values for a mapped point are requested, the Archive Subsystem requests the value
from the Redirector, which in turn obtains the value from the appropriate COM Connector.

PI Server System Management Guide 229

PI Data Retrieval w ith Foreign Data Sources

Archive Files
Even though Archive files are not used if data is retrieved using COM Connectors, the files
must exist and must be sized as if all points on the PI Server were PI Archive points. Each
COM Connector point consumes a primary record in the archive file even though it will never
be used for data storage or retrieval. Normal maintenance and backup procedures apply to the
Archive files.

Snapshot Updates
The COM Connection mechanism includes support for exception reporting. The PI Server
Snapshot Subsystem calls a sign-up method in the COM Connector if a client signs up for
exceptions on a mapped point. The Snapshot Subsystem obtains exception values from the
COM Connector by way of the Redirector.
If the foreign system does not support exception handling, it may be coded to return a
standard COM error code indicating that the method is not implemented.

230
 Compression

Compression
PI Server does not apply the PI Archive's data compression algorithm to mapped foreign
points. If the COM Connector supports putting new data values into the foreign system, then
that system is responsible for their storage. The foreign system may or may not support
compression.

Point Security
Data retrieved from foreign data system is subject to the same security as data values
retrieved from storage within the PI Archive. Every PI point, whether mapped or not, carries
a security descriptor that defines the access that PI users may have to data. For details about
how to set point security, see the Configuring PI Server Security.

PI Server System Management Guide 231

Appendix C

Technical Support and Resources

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

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location Access Num ber Local Language Options
San Leandro, CA, USA 1 510 297 5828 English
Philadelphia, PA, USA 1 215 606 0705 English
Johnson City, TN, USA 1 423 610 3800 English
Montreal, QC, Canada 1 514 493 0663 English, French
Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese
Altenstadt, Ger many 49 6047 9890 English, Ger man
Manama, Bahrain 973 1758 4429 English, Arabic
Singapore 65 6391 1811 English, Mandarin
86 021 2327 8686 Mandar in
Perth, WA, Australia 61 8 9282 9220 English

PI Server System Management Guide 233

Technical Support and Resources

Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail
will be treated as a regular phone call and will be directed to the first TSE who becomes
available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.

Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site's Support Solutions,
Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

techsupport@osisoft.com
When contacting OSIsoft Technical Support by email, it is helpful to send the following
information:
• Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue
• Message logs: See documentation for your PI System for information on obtaining
message logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft's Online Technical Support, you can:
• Enter a new call directly into OSIsoft's database (monitored 24 hours a day)
• View or edit existing OSIsoft calls that you entered
• View any of the calls entered by your organization or site, if enabled
• See your licensed software and dates of your Service Reliance Program agreements

234
 Remote Access

Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support
Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Access page for details on the various
methods you can use.

On-site service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service
Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.

Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
• System Manager Resources include tools and instructions that help you manage: Archive
sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server
security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.

Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.

PI Server System Management Guide 235

Index
list record details • 90
A minimum and maximum size • 76
moving • 80
Activity grid • 199
naming • 75
Adding a digital state Set • 148
processing • 85
API
records • 71
about • 122
registering • 70
API Nodes • 122
shift p rediction • 82
application programming interface • 122
size considerations • 76
APS utility • 126
sizing • 76
architecture
slow access • 71
distributed data collection • 121
space needs • 77
Archive
specifying maximum size • 76
combining files • 89
specifying number of points • 77
Corrupted • 114
time limit on modifying • 79
dividing • 88
Automatic Point Synchronization • 126
dynamic • 73
Fixed • 72
B
full • 72
initializing • 82 backfilling archives
Management • 69 without compression • 83, 84
Performance backfilling data • 83
daily monitoring • 133 Base Subsystem • 191
buffering
Reorganizing files • 88
Repairing the Registry • 207 PI API • 122
Restore • 115
Sequence Number • 90 C
archive record C language, API • 122
size size, archive records • 71 Classicctr • 200
Archive Subsystem COM Connector
Troubleshooting • 191 in-process • 206
archive walk • 90 out-of-process • 206
Archives troubleshooting • 200, 205
About • 69 Web site • 205
annotation files • 75 Combining Archives • 89
anticipating overflow • 77 compression
archive shift • 69 backfilling archives without • 83, 84
archive shifts • 82 for backfilling archives • 83
archive walk • 90 Connections
backfilling without compression • 83, 84 slow • 197
command-line tools • 69 Corrupted
deleting • 80 Archives • 114
editing data in • 79 non-primary • 208
fixed and dynamic • 69, 72 Primary • 208
for previously collected data • 83
CPU
gaps • 71
Excessive usage of • 199
index records • 71
CPU usage

PI Server System Management Guide 237

Index

by utilities • 217 Firewall

creating archives for old data • 83 troubleshooting • 188
ctr_lmap • 200 Fixed
ctr_progid • 200 fixed archives • 69, 72
ctr_strmap • 200 Flatline in a trend
troubleshooting • 198
D Force processing • 148
data full, archive • 69
Recovering from corrupted archives • 207
time limit on modifying • 79 G
Database gaps
Point • 82 archives • 71
Dates
overlapping • 115 I
Daylight Savings Time index record • 71
customizing changes • 12 Initialization
list of changes • 9 archive • 82
Dcomcnfg • 204, 206 Installation
deleting archives • 80 Redirector • 204
deleting connection error message • 132 Integer Format to String • 14
Digital State • 21 Interface Status Utility • 126
Digital State Set interfaces
adding • 148 and PI API • 122
distributed data collection • 121 APS utility • 126
Dynamic archive • 73 definition of • 121
dynamic archives • 69, 72 Interface Status Utility • 126
E L
editing archives • 79 limits, time • 79
error
code number M
translating to message text • 131
Mapped points • 200
error messages maximum archive size • 76
deleting connection • 132
maxpoints • 77
rpc resolver • 132
maxsize • 76
subsystem health check failed • 132 MaxUpdateQueue • 186
Event Log
Message Log • 18, 132
configuring • 201 message logs
event queue
message subsystem offline • 131
Troubleshooting • 192
rpc resolver error • 132
events message subsystem offline
time limit on modifying • 79
viewing messages • 131
minimum archive size • 76
F
Module Database
Failed to unregister input archive message • 208 Repairing • 214
File corruption • 207 moving archives • 80
File-base Utility • 214
compact • 215 N
index • 214
naming archives • 75

238
O Recovering • 208
offline archive utility • 69, 85
R
offline, message subsystem • 131
offline, viewing messages • 131 record
overflow primary recordrecord • 71 archive • 71
Overlapping dates • 115 records
listing details • 90
P Recovery tool • 207
Redirector
PI API
confirming installation • 204
about • 122
dump script • 201
Buffering • 122
starting • 204
PI Base Subsystem
regsvr32 • 206
Troubleshooting • 191
removing archives • 80
PI Processes
Repairs
Running independently • 193
Archive Registry • 207
PI Server
Excessive CPU Usage by Utilities • 217
performance monitoring • 133
Module Database • 214
restore from backup • 114
Point Database • 214
Starting • 17
Snapshot • 210
Stopping • 17
System Time • 216
tuning • 169
Tuning the Server • 169
PI System
resolver error message • 132
merging two systems • 144
Restore
piarchss • 69, 85, 191
Archive • 115
piarcreate • 69
PI Server from backup • 114
piartool • 69
Subsystem Databases • 116
-aw • 90
Reverse Name Lookup
moving archives • 80
Troubleshooting • 197
Pibasess • 191
rpc resolver error message • 132
PIBatch
considerations when merging systems • 145
S
pidiag
-e errorcode • 131 Security
-fb • 214 Troubleshooting • 191
-fbc <path> • 215 Shift
-fbf <path> • 215 Archives • 82
Recovery utility • 207 shift, archive • 69
-t time <U> • 13 Shutdown.dat • 22
-tz • 9 Site-specific files • 18
Pilistupd utility Snapshot • 21
Troubleshooting • 192 repairing • 210
Pishutev • 21, 190 Subsystem
Pisnapss • 192 recovering • 211
PITimeout Table • 186, 187 Troubleshooting • 192
Piudsrdr.exe • 201 Start
Piupdmgr • 192 PI • 17
Point Database • 82 Redirector • 204
Repairing • 214 Stdout • 18
primary archive • 69, 72

PI Server System Management Guide 239

Index

Stop W
PI • 17
Windows
String to Integer Format • 13
Stopping Processes • 193
Subsystem
Restore from Backup • 116
Update Manager • 192
subsystem health check failed • 132
System
Clock
resetting • 216

T
Tag
Mask, for shutdown • 22
Threading • 199
Time
future times in Snapshot
removing • 213
Time Zone • 9, 12
utilities • 13
time limits on modifying data • 79
Time Transformation Processing
conversion file • 210
TotalUpdateQueue • 186, 187
Troubleshooting
Checklist • 188
PI Update Manager • 192
Strategy • 187
Tuning
Utilities timeout value • 217
Tuning the PI System • 169

U
Update Manager
MaxUpdateQueue • 186
Pending Update Limit • 186
TotalUpdateQueue • 186, 187
Troubleshooting • 192
Utility
File-base • 214
pidiag recovery • 207
time • 13

V
Verifying PI Processes • 190
Visual Basic, API • 122

240