PI Server Intalacion PDF
Uploaded by
franPI Server Intalacion PDF
Uploaded by
franPI Server Installation and Upgrade Guide
PI3 Server
Version 3.4.370
© 1998-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PI Server Installation and Upgrade Guide provides the information and instructions that
System Administrators need to install a PI Server, or to upgrade an existing installation.
This guide includes comprehensive instructions to assist you in:
Installing, upgrading and removing PI Servers on Windows and UNIX platforms
Performing Cluster and Silent installations on Windows platforms
To install or upgrade your PI System, please review and follow the recommendations and
instructions for the procedure(s) you need to perform:
Preparing and Planning for Installation
PI Server Installation on Windows
• Upgrading the PI Server on Windows
• Starting and Stopping PI on Windows
• Removing PI Installations on Windows
PI Server Installation on UNIX
• Upgrading the PI Server on UNIX
• Starting and Stopping PI on UNIX
• Removing PI Installations on UNIX
PI Server Cluster Installation on Windows
PI Server Silent Installation on Windows
This guide assumes that the System Administrator has a working understanding of PI Server
tools and utilities such as PIConfig, PIDiag and PIArtool. For information about command-
line tools and other PI System setup and configuration procedures, see the PI Server System
Management Guide and the PI Server Reference Guide.
The PI Server Documentation Set provides additional PI Server information and system
management procedures.
PI Server Installation and Upgrade Guide Page iii
Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set includes seven user guides, described below.
Tip: Updated user guides, which provide the most up-to-date information, are
available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security
and trusts, and performance. It includes a glossary and resource guide.
PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows
and Upgrade Guide and UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data
Archive, monitoring system health, managing backups, interfaces,
security, and moving and merging servers. Includes comprehensive
instructions for using command-line tools: PIConfig, PIDiag, and PIArtool,
and in-depth troubleshooting and repair information.
PI Server Reference A comprehensive reference guide for the System Administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).
Auditing the PI An administration guide that explains the Audit Database, which provides
Server a secure audit trail of changes to PI System configuration, security
settings, and Archive Data. It includes administration procedures to
enable auditing, to set subsystem auditing mode, to create and archive
database files, and to export audit records.
PI Server A guide to key add-on PI Server Applications: Performance Equations
Applications User (PE), Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC
Guide (Statistical Quality Control). Includes a reference guide for Performance
Equations, and Steam calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support
migration and interoperability between PI2 and PI3 Systems.
Page iv
Preface - Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI Client Tools Use the client tool, PI ProcessBook, to verify that all
PI System Elements data has been recovered.
PI Server Subsystems All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text Files, Directories, Paths The backup script is located in the \PI\adm directory.
Emphasis Archive files can be either fixed or dynamic. The
New Terms archive receiving current data is called the Primary
Archive.
Fields
See Section 4.2, Create a New Primary Archive.
References to a chapter or section
Bold Italic text References to a publication See the PI Server Reference Guide.
Bold text System and Application The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
Procedures and Key Commands On the Tools menu, click Advanced Options.
Press CTRL+ALT+DELETE to reboot
Interface components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: Code examples use the piartool -ss command. For example:
"Consolas" Commands to be typed on the
font command line (optionally with
arguments or switches)
System input or output such as
excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
PI Server Installation and Upgrade Guide Page v
Preface - Using this Guide
Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow System Administrators and users
to perform System Administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
Administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. Preparing and Planning for Installation....................................................................1
Chapter 2. PI Server Installation on Windows ..........................................................................11
Chapter 3. Upgrade the PI Server on Windows ........................................................................23
Chapter 4. Start and Stop PI on Windows.................................................................................37
Chapter 5. Remove PI Installations on Windows .....................................................................41
Chapter 6. PI Server Installation on UNIX .................................................................................43
Chapter 7. Upgrade the PI Server on UNIX ...............................................................................61
Chapter 8. Start and Stop PI on UNIX ........................................................................................71
Chapter 9. Remove PI Installations on UNIX.............................................................................75
Chapter 10. PI Server Cluster Installation ...................................................................................77
Chapter 11. PI Server Silent Installation....................................................................................121
PI Server Installation and Upgrade Guide Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Quick Table of Contents .................................................................................................................vii
Table of Contents..............................................................................................................................ix
Chapter 1. Preparing and Planning for Installation....................................................................1
1.1 PI System Distribution ......................................................................................................1
1.2 PI License File....................................................................................................................2
1.3 System Sizing ....................................................................................................................2
1.4 Other Installation Considerations....................................................................................9
1.5 Installation and Upgrade Instructions...........................................................................10
Chapter 2. PI Server Installation on Windows ..........................................................................11
2.1 Overview...........................................................................................................................11
2.2 New Installation Instructions..........................................................................................11
Chapter 3. Upgrade the PI Server on Windows ........................................................................23
3.2 Installation Logs ..............................................................................................................34
Chapter 4. Start and Stop PI on Windows.................................................................................37
Chapter 5. Remove PI Installations on Windows .....................................................................41
Chapter 6. PI Server Installation on UNIX .................................................................................43
6.1 Overview...........................................................................................................................43
6.2 New Installation Instructions..........................................................................................51
Chapter 7. Upgrade the PI Server on UNIX ...............................................................................61
7.1 Pre-upgrade Checklist ....................................................................................................61
7.2 Upgrade ............................................................................................................................62
7.3 Post-Upgrade Checklist ..................................................................................................63
PI Server Installation and Upgrade Guide Page ix
Table of Figures
Chapter 8. Start and Stop PI on UNIX ........................................................................................71
Chapter 9. Remove PI Installations on UNIX.............................................................................75
Chapter 10. PI Server Cluster Installation ...................................................................................77
10.1 PI Server Clustering on the Windows Platform............................................................77
10.2 Installation of PI...............................................................................................................77
10.3 Sample Cluster Wizard Configuration...........................................................................95
10.4 PI Server Upgrades .......................................................................................................100
Chapter 11. PI Server Silent Installation....................................................................................121
11.1 Silent Installation and Upgrade on the Windows Platform .......................................121
11.2 Silent New Installation ..................................................................................................123
11.3 Silent Upgrade ...............................................................................................................126
Technical Support and Resources...............................................................................................129
Index of Topics...............................................................................................................................131
Page x
Chapter 1. PREPARING AND PLANNING FOR INSTALLATION
1.1 PI System Distribution
The PI System distribution package is available on CD-ROMs or by downloading it from the
OSIsoft Technical Support Download site.
1.1.1 Distribution Package for PI Server for Windows
The PI Server CD distribution package consists of the following (when downloading these
files from the web site, some components are in separate installation kits):
PI Server software for all supported platforms
Release Notes
PI System Management Tools software
Complete user guides in Microsoft Word format and/or PDF
PI-SDK (which includes the PI API)
PI Interface Configuration Utility
PerfMon, Ping, SNMP, Random, and RampSoak interfaces
PerfMon, Ping, SNMP, Random, and RampSoak ICUs
PI System Management Tools (PI SMT)
If licensed, the PI Server distribution package may also contain the following software
packages. These packages will be installed with the PI Server software.
PI Server Applications includes the following installation kits
PI Performance Equations (including Steam Functions)
PI Recalculator
PI Totalizer
PI Alarm
PI Advanced Server Applications includes the following installation kits
PI Batch
PI Batch Generator Interface
Real-Time PI SQC
PI Server Installation and Upgrade Guide Page 1
Chapter 1 - Preparing and Planning for Installation
PI Auto Point Sync
The PI Software Development Kit (PI-SDK) is a programming tool that provides an object-
oriented approach to program interaction with PI Systems. It delivers a hierarchical model of
objects and collections representing the components of PI Servers. The software consists of
ActiveX in-process servers, an ActiveX control, and supporting code libraries. The PI-SDK
application is provided for internal use by the PI Server systems, server-based interfaces, and
subsystems. The PI-SDK should not be used by any other programs or applications without a
separate software license.
PI API is the programmer’s interface to the PI System. Interfaces and user programs use PI
API to communicate with the PI System. PI API applications may run on the PI Server
computer or on a networked computer. The PI API application is provided for internal use by
the PI Server tools and server-based interfaces. The PI API should be not be used by any
other programs or applications without a separate software license.
1.1.2 Downloaded Distribution
The PI System distribution package and documentation are available from the OSIsoft
Technical Support download center. If you wish to download the software, contact your
OSIsoft Sales Representative for an account and password.
1.2 PI License File
A license file, pilicense.dat, is required for the PI Server installation to complete. The license
file is separate from the PI Server installation package. The license file is available on CD-
ROMs or by downloading it from the OSIsoft Web site.
1.3 System Sizing
PI Server should be installed on a dedicated system.
1.3.1 Operating System and Platform Requirements
The PI System runs on any of the following platforms:
Platform Operating System Minimum Processor
Intel Pentium Microsoft Windows: Server Pentium III, 800+ MHz
2003, XP Pro SP2, 2000 Server
SP3
Hewlett-Packard HP-UX version 11i (11.11) or PA8500, PA8600, or
9000 700 and 800 later PA8700; 500+ MHz
series
Sun Sparc Solaris 8 or 9 UltraSPARC II, UltraSPARC
IIi, UltraSPARC IIIi, or
UltraSPARC III Cu; 466+
MHz
Page 2
1.3 - System Sizing
Platform Operating System Minimum Processor
Compaq Alpha Compaq Tru64 UNIX V5.1B or Alpha EV6, Alpha EV67,
later Alpha EV68, or Alpha EV7;
500+ MHz
IBM RS/6000 IBM AIX 5L Version 5.1 RS64 IV; 450+ Mhz
Motorola Power PC IBM AIX 5L Version 5.1 POWER3-II, POWER4, or
POWER4+; 450+ MHz
Note: The minimum processor specifications should be used as guidelines only. The
PI Server assumes it is the only server application on the system. The PI Server, for
performance, makes aggressive use of available memory. The PI Server will not
perform optimally if it competes with other large applications such as an RDBMS.
In this manual, HP-UX, Sun Solaris, Compaq UNIX, and IBM AIX are collectively called
UNIX systems.
Network Configuration
The PI Server relies on a proper network configuration to run successfully. TCP/IP must be
installed and configured before installing PI, even on stand-alone hosts.
A standard installation uses host name lookups for client access logging and validation. It is
important for performance and security to configure a stable and responsive host name file,
DNS or other name service. A slow name service can dramatically impede PI and in some
cases cause it to fail.
1.3.2 Disk and Memory Sizing
System size configuration depends on two primary parameters: point count and amount of
online history. Several other parameters also impact size, although the effects are much less
quantitative, and therefore it is difficult to supply specific size information. Examples of these
parameters are:
Snapshot rate
Archive rate
Archive access
Non-PI activity on the system
This sizing guide addresses required disk space and physical memory. Processor and
processor count is not covered except for minimum processor support.
Disk Requirements (Windows)
During installation and upgrade from CD, a few files are copied to the system temporary
directory. The remaining files are copied directly from the CD to their target location. When
installing or upgrading from the self-extracting executable, the source files are copied to a
user-defined location (approximately 160 MB for Intel Windows), and then the setup runs
PI Server Installation and Upgrade Guide Page 3
Chapter 1 - Preparing and Planning for Installation
similarly to the CD installation, copying a few files into the system temporary directory. Both
the self-extracted files will remain in place after installation or upgrade is complete. You may
remove them if you wish.
The PI Server files installed on the system require approximately 100 MB on the system disk
for Intel Windows, excluding archive files. In addition, there are support symbols for
debugging that require an additional 60 MB of space on the system disk for Intel Windows.
The bulk of a PI Server’s disk usage is in the archives. These can typically encompass many
gigabytes of disk space, depending on the number of days of online data desired.
The disk space used by each archive is typically fixed at archive creation time. However, the
other PI Server databases and the message log files grow with time. Most of the databases
grow in size proportionally to the number of points defined in the system. The message log
files grow with time and system activity.
Detailed sizing information follows.
Archive Size
During new installations, three default archives are created. The installation script prompts
for archive size (in MB) and archive location. All three archives are created with the same
size in the same location (path). Additional archives can be created after the installation using
the utility piarcreate or, in some cases, piartool. Once created, these archive files do not
change size. Note that there is also a special kind of archive referred to as a dynamic archive
that does grow, but this is a special case.
The PI Server allows a maximum point-to-archive record ratio of 512 points per 1 MB (1024
archive records). For example, 256,000 points can be created in a 500MB archive. However,
it is recommended that you allocate as much space as possible without exceeding the limits of
your physical and backup media. Typically a ratio of between 10 and 20 records (1 KB per
record) per point per archive yields the best performance. Systems with a large percentage of
slow-moving data or a large number of fast-moving data may deviate from this dramatically.
Selecting a proper archive size can dramatically affect performance and space utilization.
Archives that are too small will waste significant space. Archives that are too large incur
overhead due to overflow index record creation and result in significant system transients
during archive maintenance such as backups and shifts. The limitations of the system
resources and backup media should also be weighed. Fortunately, archives sizes can be
changed as the system configuration changes, and old archives can be reprocessed to
optimize space use and performance.
Event Queue Size
During new installations, there is the option to choose the Event Queue size and location.
Database Size Allowances
Other than log files, the PI\dat directory contains the remaining PI databases, many of which
grow proportionally to the number of defined points. You should allow for 10 MB plus 1 MB
per 1024 points for the each of the Point and Snapshot databases.
Page 4
1.3 - System Sizing
The remaining system databases will together take at least another megabyte of disk space.
These include the User Database, Point Context and Point Attribute Set Databases, the Digital
State Database, and the network manager tables.
The PI Snapshot Event Queue overflow file resides in the PI\dat directory and is named
pieventq.dat. For example, if communications between the Snapshot and the Archive fail
(such as during an archive backup or archive shift), the Event Queue file will fill up with
incoming data. Anywhere from a few megabytes to the size of the disk may be needed to
buffer incoming data until the Archive is accessible again. The amount of disk space
available determines the maximum duration that PI can accommodate the loss of the
archiving process.
Space for Other Files
The PI\log directory contains the PI Message Log files. These files shift every night at
midnight. Log files are maintained for 35 days before the PI System deletes them. If
permanent records are desired, the System Administrator should back up the log files to
another media prior to their deletion. You should allow for 10 MB of buffering space for log
files.
1.3.3 Disk Space Requirements (UNIX)
During all installations and upgrades the distribution files are copied to a temporary path on
the host machine. Although these may be removed after the installation or upgrade is
completed, they contribute to the total disk space needed during installation.
Space requirements for distribution files are as follows:
Operating System Compressed tar File Expanded Distribution
(MB) (MB)
HP-UX 21 63
Solaris 24 108
Tru64 21 82
AIX 24 42
All platforms require the same total space for data files and tables. The bulk of a PI Server’s
disk usage is in the archives. These can typically encompass many gigabytes of disk space
depending on the number of years of online data desired.
The disk space used by archives is typically fixed at archive creation time. However, the
other PI Server databases and the message log files grow with time. Most of the databases
grow in size proportionally to the number of points defined in the system. The message log
files grow with time and system activity.
More detailed sizing information follows.
PI Server Installation and Upgrade Guide Page 5
Chapter 1 - Preparing and Planning for Installation
Archive Size
During new installations, three default archives are created. The installation script prompts
for archive size (in MB) and archive location. All three archives are created with the same
size in the same location (path). Additional archives can be created after the installation using
the utility piarcreate or, in some cases, piartool. Once created, these archive files do not
change size. Note that there is also a kind of archive referred to as a dynamic archive that
does grow. It is a special case.
The PI System allows a maximum point-to-archive-record ratio of 512 points per 1 megabyte
(1024 archive records). For example, 256,000 points can be created in a 500MB archive. It is
recommended that you allocate as much space as possible without exceeding the limits of
your physical and backup media. Typically a ratio of between 10 and 20 records (1 KB per
record) per point per archive yields the best performance. Systems with a large percentage of
slow-moving data or a large number of fast-moving data may deviate from this dramatically.
Selecting a proper archive size can dramatically affect performance and space utilization.
Archives that are too small will waste significant space. Archives that are too large incur
overhead due to index record creation and result in significant system transients during
archive maintenance such as backups and shifts. The limitations of the system resources and
backup media should also be weighed. Fortunately, archives sizes can be changed as the
system configuration changes and old archives can be reprocessed to optimize space use and
performance.
Database Size Allowances
Other than log files, the PI/dat directory contains the remaining PI databases, many of which
grow proportionally to the number of defined points. You should allow for 10 MB plus 1 MB
per 1024 points for each of the Point and Snapshot Databases.
The remaining system databases will together take at least another megabyte of disk space.
These include the User Database, Point Database, Point Attribute Set Database, Digital State
Database, and the network manager tables.
The PI Snapshot Event Queue file resides in the PI/dat directory and is named pimapevq.dat.
This file is mapped into the Snapshot and Archive Subsystems and servers as the means for
transferring event data from Snapshot to Archive. The default size of the file is 64 MB. If the
Archive Subsystem becomes unavailable (such as during an Archive backup or Archive
shift), this file may fill up with incoming data. If the file fills up, additional files will be
created. Anywhere from a few megabytes to the size of the disk may be needed to buffer
incoming data until the Archive is accessible again. The amount of disk space available
determines the maximum duration that PI can accommodate the loss of the archiving process.
Space for Other Files
The PI/log directory contains the PI Message Log files. These files shift every night at
midnight. Log files are maintained for 35 days before the PI System deletes them. If
permanent records are desired, the System Administrator should back up the log files to
another media prior to their deletion. You should allow for 10 Megabytes of buffering space
for log files.
Page 6
1.3 - System Sizing
Memory Requirements
The PI System is a memory-intensive application. Frequently accessed data structures are
kept in memory for performance reasons. The primary memory-consuming PI processes, in
descending order, are piarchss, pibasess, and pisnapss. The archive cache comprises most of
the memory use in piarchss, the Point Database in pibasess, and the Snapshot in pisnapss.
The other PI processes do not vary significantly with point count.
The memory use in pibasess, and pisnapss is directly related to point count. Memory use in
piarchss is more complicated. It is related to point count and data rates. Overall rate as well
as number of different points receiving events affects the data rate impact on memory. A high
overall data rate spread over a small percentage of points may require less memory than a
lower overall rate spread over a high percentage of points.
Once again, an empirical approach is used to estimate memory requirements. The estimate is
7 kilobytes per point, plus a constant for operating system and the PI system. The constant
depends on the operating system and does not take into account applications other than PI
System.
Point Count Memory Page file Size
Less than 75,000 1 GB 3GB
75,000 to 200,000 2 GB 4GB
Greater than 200,000 4 GB 8GB
1.3.4 Sizing Estimates
Sizing depends on the operating system. Following are guides for each supported operating
system; minimum processor requirement is stated where appropriate.
Windows
Minimum processor, Intel Pentium III (800 MHz or faster).
Minimum disk requirements in MB:
(Point Count x Days online)/1024 + 128
Minimum memory requirements in MB:
(Point Count x 7)/1024 + 64
UNIX Platforms
The following list provides the minimum system required for a PI System running on UNIX
assuming there are no other applications using system resources:
A minimum of 32 MB of system memory (48 megabytes for 64 bit operating systems
like Compaq Tru64 UNIX, HP-UX 11.x, etc.) plus 12 MB of system memory for
every 1000 points (16 MB for 64 bit operating systems).
PI Server Installation and Upgrade Guide Page 7
Chapter 1 - Preparing and Planning for Installation
A minimum of 256 MB of free disk space for Sun Solaris, HP-UX, or Compaq Tru64
installations or a minimum of 700 MB of free disk space for IBM AIX installations
are required.
Maximum Data Segment. Some Unix Operating Systems have a configurable and
small, by default, maximum data segment size. The data segment is the amount of
private virtual bytes allocated by a process. Limits are imposed to prevent rogue
applications in multi-user environments from monopolizing memory. For server
machines, the maximum data segment should be set to at least 2GB—this is the
maximum allowable for 32-bit machines.
Compaq Tru64 UNIX
Compaq Tru64 UNIX is a 64-bit operating system. The sizes reflect the larger images of 64
bit executables.
Minimum disk requirements in MB:
(Point Count x Days online)/1024 + 384
Minimum memory requirements in MB:
(Point Count x 7)/1024 + 128
HP-UX
Minimum disk requirements in MB:
(Point Count x Days online)/1024 + 128
Minimum memory requirements in MB:
(Point Count x 7)/1024 + 64
IBM AIX
Minimum disk requirements in MB:
(Point Count x Days online)/1024 + 352
Minimum memory requirements in MB:
(Point Count x 7)/1024 + 96
Sun Solaris
Minimum disk requirements in MB:
(Point Count x Days online)/1024 + 128
Minimum memory requirements in MB:
(Point Count x 7)/1024 + 64
Page 8
1.4 - Other Installation Considerations
1.4 Other Installation Considerations
1.4.1 Setting the Host Computer Time
In order for PI to accurately store and retrieve data, the PI host computer must have the
correct settings for:
Time
Time zone
Daylight Savings Time (DST)
In all cases, the home node should be set to its correct local time, time zone, and DST setting.
On Windows systems the time and date should be set using the Control Panel applet
Date/Time. The setup program on new installations will run this applet for users to verify the
system settings.
It is recommended that you do not set the TZ environment variable in the Control Panel -
System applet. This variable is not necessary for the proper operation of the PI Server. It will
adversely affect PI if set incorrectly.
Caution: Incorrect TZ settings will result in incorrect timestamps for archived data.
Also, see the section called Setting the Interface Node Clock in PI Server System
Management Reference Guide.
1.4.2 Default Points
During a new installation, you have the option of installing default points (10 of them). These
points are fed by two simulator interfaces, random and rmp_sk. Having a number of known
good points is very helpful in troubleshooting and is used for validating the behavior of the
system.
It is recommended that these points be installed unless you are intending to migrate from an
existing PI 2.x installation.
1.4.3 PI Administrator Account
A user account should be created (or an existing account specified) for the administration of
the PI Server. On Windows, the administrator account may be used, although this is not
required. The account chosen for PI administration should have sufficient privileges to install
and run system services, modify the registry, create directories and copy files. To avoid
security conflicts, this account should be used for all installation, upgrade, and administrative
activities for PI.
1.4.4 Security
A security plan should be developed for your site. The PIfirewall, PItrust Database, and PI
user names and groups should be defined to implement the security plan. The access
permissions on each tag should be set accordingly. See Managing Security in the PI Server
System Management Guide.
PI Server Installation and Upgrade Guide Page 9
Chapter 1 - Preparing and Planning for Installation
1.4.5 Media Preparation
The PI Server setup kit is provided on CD-ROM or on the Web. The kit may be run from a
local device or across the network, although all of the PI Server files should be installed on
devices local to the computer that will be running the system.
The CD-ROM launches an HTML page in your Internet browser, which has information on
the system, documentation, release notes, and a link to the setup kit.
1.5 Installation and Upgrade Instructions
For detailed installation and upgrade instructions, see Chapter 3, Upgrade the PI Server on
Windows on page 23, and Chapter 6, PI Server Installation on UNIX on page 43.
Important! Before beginning any installation or upgrade, back up your system
completely.
Page 10
Chapter 2. PI SERVER INSTALLATION ON WINDOWS
2.1 Overview
PI Server for Microsoft Windows-based operating systems is distributed on CD-ROM or via
the Internet as self-extracting executables. A graphical setup program will perform either a
new installation or upgrade to an existing system.
Review Preparing and Planning for Installation on page 1, before installing or upgrading the
PI Server. The Preparing and Planning for Installation section covers system settings and
requirements such as memory and disk sizing. These preparatory steps should be understood
before proceeding. The installation or upgrade including a backup of the system, usually
takes less than one hour. The time required for post-installation steps, such as creating
additional archives, configuring tags, and setting up the site-specific interface files will vary.
As part of a default installation, you may permit Setup to create several demonstration points.
Two sample interfaces that generate simulated data when PI runs populate these points. This
means that you are collecting and archiving test data as soon as you start PI. These data can
be viewed immediately using client applications such as PI ProcessBook and PI DataLink.
If licensed, the PI Server Applications, and basic versions of the PI Performance Monitor, PI
SNMP and PI Ping interfaces will be installed.
2.2 New Installation Instructions
Before starting an installation, be sure that you have reviewed the Installation and Upgrade
Planning section in this booklet.
The following section provides a detailed pre-installation checklist for new installations, a
step-by-step overview of the installation script activities, and a discussion of necessary post-
installation tasks.
2.2.1 Pre-installation Checklist
As you prepare to execute a new installation, you must address the following:
1. Ensure that you have a license file, pilicense.dat.
2. Ensure that your operating system version and patches are supported.
3. Ensure that you have a proper backup of your system.
4. Review system and sizing requirements. Ensure that sufficient disk space is available
and that system resources are adequate for the intended installation.
PI Server Installation and Upgrade Guide Page 11
Chapter 2 - PI Server Installation on Windows
5. Ensure that you have created or identified the user account with sufficient privileges
for installation and administration of the PI Server.
6. Verify the host time settings.
7. Verify the host network configuration.
8. Determine a path for the target installation consistent with disk space requirements.
All files except the archives are installed to the same path. Default interfaces may or
may not be installed in that same path.
9. Ensure that enough space is available on the system disk.
10. Determine whether you intend to install the default points.
11. Determine the size and directory for the first three default archives. The default
directory is PI\dat. You may want to specify a different directory if the PI Server disk
is small.
12. A new installation cannot be performed on any host that has an existing installation
of the same version. If this is the case, review Removing PI Installations at the end of
this chapter.
13. To install the PI Server in a Microsoft Cluster Service (MSCS) environment, ensure
that the MSCS software is installed and tested.
14. For a clustered installation, in the event that a reboot is needed during the installation,
make sure the other nodes in the cluster are paused.
2.2.2 Installation
Once you have completed the installation checklist you are ready to begin the installation.
For a PI Server installation package on CD-ROM, insert the CD, which launches an HTML
page in your Internet browser that offers a link to the setup program. Click the link to start the
setup.
If the setup program does not open automatically, run it by executing:
m:\nt\setup.exe
where “m:” is the device letter of the CD-ROM. For a PI Server installation package from
self extracting executable, running the self extracting executable copies the source files to a
user-defined location and then runs the setup.
During new installations, the setup program executes the following tasks:
1. Setup opens a log file PIServerMaster.log in the root directory of the system
partition. For example, if Windows is installed in e:\winnt, the log file would reside
in the root of the e: drive: e:\PIServerMaster.log. This log file documents the overall
progress of the PI Server installation as well as the installations of the supporting
software.
2. Setup installs or upgrades supporting software such as Microsoft® Windows
Installer, Microsoft® Windows Script, Microsoft® Data Access Components, and
Page 12
2.2 - New Installation Instructions
.NET Framework. In the event that a reboot is needed, the setup program will
automatically continue with the setup after the reboot.
3. Setup opens a log file SetupPIServer.log in the root directory of the system partition.
4. Certain system .dlls are checked for necessary installation or updates.
5. The version of the system to be installed is determined.
6. The system requirements are verified, such as Windows version, CPU, and network
installation.
7. Setup checks for the Microsoft Cluster Service. If the service is detected, then the
user is prompted for a clustered installation of the PI Server.
8. Setup asks for the location of the license file (pilicense.dat).
9. User information is solicited, including the user name, company name, and the
system number (serial number). The system number identifies the installation to
OSIsoft and is provided on the packing list. This number is useful when contacting
OSIsoft Technical Support or Sales.
10. Setup solicits the target path for installation and creates it if necessary.
11. If the pipc.ini file does not exist in the operating system directory or pihome is not
defined in the pipc.ini file, setup solicits the target path for the installation of the PI-
SDK.
12. Setup allows the user to specify additional installation options. These include
whether PI services will be installed to automatically start on system reboot and
whether the default points should be installed (default points are recommended).
13. Setup solicits the default archive size and location.
14. Files are copied to the target.
15. The registry is updated with PI installation information.
16. PI databases are created. These include the Point Database, Digital State Table, and
Security Tables.
17. For clustered installations, Setup installs PI Cluster Wizard.
18. PI Services are registered.
19. The log file is closed and moved to the \dat subdirectory of the directory indicated by
the pihome entry of the pipc.ini file.
20. If necessary, the PI-SDK installation (which includes the PI API) is installed or
updated. In the event that a reboot is needed, the setup program will automatically
continue with the setup after the reboot. It is recommended that for a clustered
installation, the PI-SDK be installed on the non-shared disk.
21. The default PI interfaces are installed. Setup installs these interfaces in the Interfaces
subdirectory of the directory indicated by the pihome entry of the pipc.ini file. The
installation log files for each interface installation is located in the \dat subdirectory
of directory indicated by the pihome entry of the pipc.ini file
PI Server Installation and Upgrade Guide Page 13
Chapter 2 - PI Server Installation on Windows
22. The PI Interface Configuration Utility is installed in the \ICU subdirectory of the
directory indicated by the pihome entry of the pipc.ini file. The ICUs for the default
interfaces are installed in the same directory.
23. For clustered installs, if the installation is for the first cluster node, the installation
procedure will need to be repeated on that second cluster node.
24. The first time the PI Server is run, it will complete installation by processing the
PI\adm\pirunonce.dif script. After the first run, this script will no longer be
processed.
2.2.3 Post-Installation Checklist
Once the installation script has completed, there are a number of administrative and
maintenance tasks that need to be addressed to ensure successful operation of the PI Server.
This section provides a checklist that should be reviewed before running PI.
1. After running the setup program, review the ASCII log files PIServerMaster.log,
SetupPIServer.log, all the interface logs and all the server application logs for any
errors.
2. For non-clustered installations, the scripts PI\adm\pisitestart.bat,
PI\adm\pisrvsitestart.bat and PI\adm\pisrvsitestop.bat should be modified to include
the interfaces that are used at your site.
3. At this point any temporary files generated by the setup program are no longer
needed and may be removed from the system.
4. The entire PI Server should be backed up, and a daily backup strategy should be
developed. If you are upgrading from PI 3.4.364.32 or earlier, you will need to
review your backup procedures for the PI Server and reinstall the any automated
backups because the backup procedure for PI changed as of PI 3.4.370.
5. Install the PI System Management Tools on the home node and on any other
Windows client computers where it will be useful.
6. Configure network access and install software for OSIsoft to provide remote
technical support.
7. For clustered installs, after installation is complete on all cluster nodes, run the PI
Cluster Wizard (PIClusWizard.exe) located in the directory PI\adm to configure the
cluster group and resources for the PI Server.
8. Proceed to the Running PI section.
2.2.4 Sample Installation
In this example, Microsoft® Windows Installer and Microsoft® Windows Script is already
installed. The Microsoft® Data Access Components (MDAC) and the PI-SDK need to be
installed. Setup begins and presents a dialog box displaying the list of software that is to be
installed or upgraded.
Page 14
2.2 - New Installation Instructions
Setup checks if MDAC is installed and if the version of MDAC is greater or equal to 2.7.
Setup launches the MDAC installation.
Setup checks the version of Windows Installer and then silently installs the new version of
Windows Installer. The Windows Installer installation may ask for a reboot to complete.
Setup then checks for the existence of the Microsoft® Windows Script. This is installed if it
is not already installed. The final pre-installation step is to install Microsoft .Net Framework
if it is not already installed.
PI Server Installation and Upgrade Guide Page 15
Chapter 2 - PI Server Installation on Windows
After all the prerequisite installs are complete, the PI Server installation begins.
Page 16
2.2 - New Installation Instructions
The user is prompted for the directory containing the license file, pilicense.dat.
After license information is obtained, the user information is gathered.
PI Server Installation and Upgrade Guide Page 17
Chapter 2 - PI Server Installation on Windows
If the PI-SDK is not installed, Setup asks for the location to install the PI-SDK. The standard
location is in the \Program Files\PIPC directory.
The location for the PI Server is chosen.
Page 18
2.2 - New Installation Instructions
The user is asked if default points are to be installed and if the services are installed as
automatic startup.
Setup asks for the location for the default archives.
PI Server Installation and Upgrade Guide Page 19
Chapter 2 - PI Server Installation on Windows
The Advanced button on the Default Archive Information screen is used to select the Event
Queue settings.
The installation is ready to begin.
Page 20
2.2 - New Installation Instructions
Setup now copies all the files into the proper location.
The PI-SDK installation runs after the PI Server installation is complete.
PI Server Installation and Upgrade Guide Page 21
Chapter 2 - PI Server Installation on Windows
Setup installs default PI interfaces and other server applications in its own separate Windows
Installer window. As an example, the PI Random Simulator Interface Windows Installer
window is displayed.
After the PI interfaces and server applications are installed, setup is finished.
Page 22
Chapter 3. UPGRADE THE PI SERVER ON WINDOWS
If you are upgrading to the PI Server 3.4, you must be running the PI Server 3.2 or later. If
you are running the PI Server 3.1 or the PI Server 3.0, you must first upgrade to the PI Server
3.2.
If you are upgrading from the PI Server 3.4.364.32 or earlier, you will need to reconfigure
your backup procedures for PI because the backup procedure for PI changed as of the PI
Server 3.4.370. The PI Server backup now utilizes the Microsoft Volume Shadow Copy
Services if it is available on the operation system. The pibackupat.bat file has been replaced
by the pibackuptask.bat file. If you are upgrading from the PI Server 3.4.364.32 or earlier,
any currently scheduled backup tasks that utilize the pibackupat.bat file will cease to function
after the upgrade. You will need to review the backup section of the PI Server manual for
further details and schedule a new PI Server backup after the upgrade.
Before starting an upgrade, be sure that you have reviewed the Preparing and Planning for
Installation on page 1.
This section provides a detailed checklist for upgrades, a step-by-step overview of the
upgrade script activities, and a discussion of necessary post-upgrade tasks.
3.1 Pre-upgrade Checklist
As you prepare to execute an upgrade, you must address the following:
1. Ensure that your operating system version and patches are supported by this release.
See Operating System and Platform Requirements on page 2.
2. Make sure you have no site-specific changes in the following files. Each of these files
will be overwritten during the upgrade.
• pibackup.bat
• pibackuptask.bat (first installed as of PI 3.4.370)
• pisrvstart.bat
• pisrvstop.bat
• pisrvsvrappsstart.bat
• pisrvsvrappsstop.bat
• pistart.bat
• pisvrappsstart.bat
3. The following files are obsolete and will be deleted when upgrading to 3.4.370.
PI Server Installation and Upgrade Guide Page 23
Chapter 3 - Upgrade the PI Server on Windows
• pibackupat.bat (replaced by pibackuptask.bat)
• pibackuparchive.bat
• pibackupsvrapps.bat
4. Ensure that you have a license file, pilicense.dat
5. Ensure that you have a proper backup of your system.
6. Log into the user account designated for PI administration.
7. Review available disk space and usage. Verify the location of the current installation.
You will be asked to confirm this during the upgrade process.
8. For clustered upgrades, ensure that the resources for the group that contains the PI
Server are offline.
9. For a clustered upgrade, in the event that a reboot is needed during the upgrade, make
sure the other nodes in the cluster are paused so control of the shared clustered disk is
not transferred to the other nodes before the upgrade completes.
3.2 Upgrading the PI Server
Once you have completed the upgrade checklist you are ready to begin the upgrade.
For a PI Server installation package on CD-ROM, insert the CD, which launches an HTML
page in your Internet browser that offers a link to the setup program. Click the link to start the
setup.
If the setup program does not run automatically, run it by executing:
m:\nt\setup.exe
where “m:” is the device letter of the CD-ROM. For a PI Server installation package from
self extracting executable, running the self extracting executable copies the source files to a
user-defined location and then runs the setup.
The setup program during upgrades executes the following tasks:
1. Setup opens a log file PIServerMaster.log in the root directory of the system
partition. For example, if Windows is installed in e:\winnt, the log file would reside
in the root of the e: drive: e:\PIServerMaster.log. This log file documents the overall
progress of the PI Server installation as well as the installations of the supporting
software.
2. Setup installs or upgrades supporting software such as Microsoft® Windows
Installer, Microsoft® Windows Script, Microsoft® Data Access Components, and
.NET Framework. In the event that a reboot is needed, the setup program will
automatically continue with the setup after the reboot.
3. Setup opens a log file SetupPIServer.log in the root of the system partition.
4. Certain system .dlls are checked for necessary installation or updates.
5. The version of the system to be installed is determined.
Page 24
3.2 - Upgrading the PI Server
6. The system requirements are verified, such as Windows version, CPU, and network
installation.
7. Setup checks for any running PI processes and asks to stop the PI services before
continuing with the upgrade.
8. Setup checks for upgrade (any evidence of a prior installation). If detected, the
upgrade procedure is executed. If a new installation is desired, the existing PI Server
should first be removed. See the section below on Removing PI Installations.
9. Setup checks for the Microsoft Cluster Service. If the cluster service is detected and
is running, then the user is prompted for a clustered upgrade of the PI Server. For
more details, see Chapter 10, PI Server Cluster Installation.
10. Setup checks for downgrades. Downgrading PI is not supported. To return to a prior
version (build) of PI, the entire system including the data file and archives need to be
restored from backup.
11. Setup asks for the location of the license file (pilicense.dat).
12. User information including the user name, company name, and the system number
(serial number) is verified. The system number identifies the installation to OSIsoft
and is provided on the packing list. This number is useful when contacting OSIsoft
Technical Support or Sales.
13. Setup verifies the target path of the existing installation.
14. Setup allows the user to specify the additional installation option of whether PI
services will be installed to automatically start on system reboot.
15. Setup reminds you that the PI Server uses a new backup subsystem and that
previously scheduled backups will no longer run.
16. The user is prompted to acknowledge that they have a good backup of the PI Server.
It is recommended that a complete backup of the PI Server be done before upgrading.
17. If the PI Server services are still running, setup asks if it can stop the services before
the upgrade can start.
18. Setup verifies and creates if necessary all target directories.
19. The remaining files are copied to the target.
20. The registry is updated with PI installation information, and old registry information
is removed if found.
21. PI databases are updated if necessary.
22. Out of date files are removed.
23. The default interfaces are installed or upgraded. When upgrading from PI 3.2, the
upgrade will first check to see if each of the six interfaces have been installed in the
PI\interfaces directory. If found, then the interface will be upgraded in that directory.
Otherwise the interface will be installed in the directory that is indicated by the
pipc.ini file. Refer to the PI-SDK documentation for further information regarding
the pipc.ini file.
PI Server Installation and Upgrade Guide Page 25
Chapter 3 - Upgrade the PI Server on Windows
24. PI Service Registry entries are updated.
25. The log file is closed and offered to the user.
26. The first time the PI Server is run, it will complete the upgrade by processing the
PI\adm\pirunonce.dif script (if it exists). Not all upgrades will provide this script.
3.3 Post-Upgrade Checklist
Once the upgrade has completed, there are a number of administrative and maintenance tasks
that may need to be addressed to ensure continued successful operation of the PI Server. This
section provides a checklist that should be reviewed before restarting PI (especially since
there may have been changes from previous releases).
1. After running the setup program, review the ASCII log files PIServerMaster.log,
SetupPIServer.log, all the interface logs and all the server application logs for any
errors.
2. During the upgrade, a number of site-specific files are not overwritten. However, new
versions of these files are provided (with the extension .new). These new files may
have significant changes from the original versions. These files should be compared
to the originals and changes incorporated as needed. In particular, the following files
should be examined:
C:\PI\adm\pisitestart.bat.new
C:\PI\adm\pisrvsitestart.bat.new
C:\PI\adm\pisrvsitestop.bat.new
C:\PI\dat\shutdown.dat.new
The pisrvsitestop.bat.new and pisrvsitestart.bat.new, contain the startup information
for the new default interfaces. Be sure to include these changes into the older
versions of the site-specific files. In addition, the interface site-specific files (if
installed) also need to be checked for significant changes.
random.bat.new
rmp_sk.bat.new
pisnmp_basic.bat.new
piping_basic.bat.new
piperfmon_basic.bat.new
3. Review Managing Security in the PI Server System Management Guide, as some
security features may have been enhanced from previous releases. For example,
PItrust tables have replaced PIproxy tables.
4. At this point any temporary files generated by the setup program are no longer
needed and may be removed from the system.
3.4 Sample Upgrade
Setup begins and checks whether Microsoft® Windows Installer, Microsoft® Windows
Script, and Microsoft® Data Access Components need to be installed or upgraded.
Page 26
3.4 - Sample Upgrade
In this example, Microsoft® Windows Installer has already been installed. Microsoft®
Windows Script, Microsoft® Data Access Components, and the PI-SDK are to be installed or
upgraded.
Setup checks if MDAC is installed and if the version of MDAC is greater or equal to 2.7.
Setup launches the MDAC installation.
Setup checks the version of Windows Installer and then silently installs the new version of
Windows Installer. The Windows Installer installation may ask for a reboot to complete.
Setup then checks for the existence of the Microsoft® Windows Script. This is installed if it
is not already installed.
PI Server Installation and Upgrade Guide Page 27
Chapter 3 - Upgrade the PI Server on Windows
The final pre-installation step is to install Microsoft .Net Framework if it is not already
installed.
Page 28
3.4 - Sample Upgrade
The PI Server installation begins.
The user is prompted for the directory containing the license file, pilicense.dat.
After license information is obtained, the user information from the previous installation is
then displayed.
PI Server Installation and Upgrade Guide Page 29
Chapter 3 - Upgrade the PI Server on Windows
The location of the pervious installation is shown.
The upgrade options are then presented.
Page 30
3.4 - Sample Upgrade
If you are upgrading from 3.4.364.32 or earlier, the setup kit will warn you that the backup
procedure has changed.
After accepting the new backup scheme, you are asked to verify that you good backup of the
PI Server, and you are asked to stop PI if it is running.
PI Server Installation and Upgrade Guide Page 31
Chapter 3 - Upgrade the PI Server on Windows
The Next button will not be enabled until both questions are answered.
Setup will attempt to stop these services and any other services configured to be dependent on
the PI Server and start the upgrade.
Page 32
3.4 - Sample Upgrade
If the PI-SDK needs to be updated or installed, setup installs the PI-SDK.
Setup installs each of the default PI interfaces and the server applications in its own separate
Windows Installer window. As an example, the PI Random Simulator Interface Windows
Installer window is shown.
After the PI interfaces and the server applications are installed, setup is complete.
PI Server Installation and Upgrade Guide Page 33
Chapter 3 - Upgrade the PI Server on Windows
3.5 Installation Logs
The installation logs for the PI Server installation can be found in the dat subdirectory of the
directory indicated by the pihome entry of the pipc.ini file. Depending on your license, some
of these log files may not exist.
Log File Description
PIServerMaster.log Overall Installation log
SetupPIServer.log Installation log for core PI Server
SetupPISDK.log Installation log for PI SDK
SetupRandom.log Installation log for PI Random Interface
SetupRandom_ICU.log Installation log for PI Random ICU Control
SetupRmp_sk.log Installation log for PI Ramp Soak Interface
SetupRampsoak_ICU.log Installation log for PI Ramp Soak ICU Control
SetupPingBasicSetup.log Installation log for PI Ping Interface (basic version)
SetupPIPing_ICU.log Installation log for PI Ping ICU Control
SetupSNMPBasicSetup.log Installation log for PI SNMP Interface (basic version)
SetupPISNMP_ICU.log Installation log for PI SNMP ICU Control
SetupPIPerfmon_basic.log Installation log for PI Performance Monitor Interface (basic
version)
Page 34
3.5 - Installation Logs
Log File Description
SetupPIPerfmon_ICU.log Installation log for PI Performance Monitor ICU Control
SetupPIIntStatus.log Installation log for PI Interface Status Utility
SetupPIIntStatus_ICU.log Installation log for PI Interface Status Utility ICU Control
SetupPIICUSetup.log Installation log for PI Interface Configuration Utility
SetupPIGenericNamesSetup.log Installation log for PI Interface Configuration Utility helper
SetupPISptSetup.log Installation log for PI Interface Configuration Utility helper
Setuppipeschd.log Installation log for PI Performance Equation Scheduler
Setuppirecalc.log Installation log for PI Recalculator Subsystem
Setuppitotal.log Installation log for PI Totalizer Subsystem
Setuppibagen.log Installation log for PI Batch Generator Interface
Setuppialarm.log Installation log for PI Alarm Subsystem
Setuppibatch.log Installation log for PI Batch Subsystem
Setupaf.log Installation log for PI Application Framework
SetupPIAPSSetup.log Installation log for PI Auto Point Sync
SetupPIAPSRegisterInterfaceSet Installation log for PI Auto Point Sync Registration Interface
up.log
PI Server Installation and Upgrade Guide Page 35
Chapter 4. START AND STOP PI ON WINDOWS
Start the PI Server by running the pisrvstart.bat script from the \adm directory. This starts all
PI subsystems and then runs the script pisrvsitestart.bat, which contains commands for all of
the interfaces and other site-specific applications.
Alternatively, if the PI Server was installed to start the services automatically on reboot, you
may also reboot the system. If the PI Server was installed on a cluster, use the Cluster
Administrator to start the PI Server after using the PI Cluster Wizard to configure the PI
Server on the cluster.
The first time the PI Server is run, certain error messages appear because installation is not
quite complete. The PI Server does not yet recognize any points. The messages are:
>> Invalid Start/End times in Primary archive file.
/usr/PI/dat/ piarch.001 - Archiving disabled until Archive shift.
Archive file /usr/PI/dat/piarch.002 loaded.
Archive file /usr/PI/dat/piarch.003 loaded
Primary archive file failed to load or has invalid dates.
Archiving will be turned off.
No intervention is necessary.
Next, the PI Server will run the PI\adm\pirunonce.dif script, which will install the default
points. After the first run, this script is renamed and will no longer be processed.
Once the PI Server is started, verify that the base PI processes are running:
pinetmgr PI Network Manager
pimsgss PI Message Subsystem
pilicmgr PI License Manager
piupdmgr PI Update Manager
pisnapss PI Snapshot Subsystem
piarchss PI Archive Subsystem
pibasess PI Base Subsystem
pisqlss PI SQL Subsystem
pishutev PI Shutdown Event Interface
(runs only at PI System startup time for non-Clustered installs)
The default interfaces are:
PI Server Installation and Upgrade Guide Page 37
Chapter 4 - Start and Stop PI on Windows
random PI Random and Sinusoid Data Simulator
rmp_sk PI Ramp Soak Batch Data Simulator
piperfmon PI Performance Monitor Interface (if service is installed)
pisnmp PI SNMP Data Collection Interface (if service is installed)
piping PI Ping Data Measurement Program (if service is installed)
You may build points and configure interfaces now or later. For more information, see the PI
System Management Tools (PI SMT) on the OSIsoft Technical Support site.
It is useful to monitor the data transfer rate from each interface to the PI Home node. See
Data Rate Monitoring in the PI Server System Management Guide.
4.1.1 Running PI as Windows Services
During installation, setup automatically configures the PI System to be run as Windows
Services.
PI processes can be started as Windows Services by running the command file pisrvstart.bat
from the PI\adm directory. The file pisrvstart.bat calls pisrvsitestart.bat, which starts the
interfaces and other site-specific programs as Windows Services. For a clustered PI Server,
use the Cluster Administrator to start the group for the PI Server.
There is no icon or other visible indicator that PI is running as Windows Services. To
determine if PI is running as Windows Services, look at the Control Panel Services dialog
box. Each PI process and interface is listed. The status is “Started” if the process or interface
is running; the status will be blank otherwise.
You can also enter the command net start at a command prompt.
Windows Services are automatically stopped on system shutdown but are not stopped when a
user logs off from an NT console.
Stopping PI Services Manually
To manually stop all running PI services, run the pisrvstop.bat command file from the PI\adm
directory. This command files calls pisrvsitestop.bat, which stops the interfaces and other
site-specific programs which have been configured to run as Windows Services. For clustered
PI Servers, use the Cluster Administrator to stop the group that contains the PI Server.
Starting PI Services Automatically at System Startup
During the installation, for non-clustered PI Servers, the PI services can be configured to
manual or automatic startup. For manual startup, the services must be told to start and stop
using the pisrvstart.bat and pisrvstop.bat commands. To change the PI System to start
automatically on reboot, use the Services Control Panel applet to change startup to
Automatic.
Note: For clustered PI Servers, the services are always installed manually and
should never be configured to start automatically during reboot.
Page 38
3.5 - Installation Logs
If the following programs and services are installed, the following interfaces can be
configured to automatically start with the system startup.
PIPerfMon PI Performance Monitor Interface
PIsnmp PI SNMP Data Collection Interface
PIPing PI Ping Data Measurement Program
PIBaGen PI Batch Generator Interface
Starting Site-Specific Services
Any site-specific services that are expected to be associated with the PI Server should have
startup and shutdown commands added to the pisrvsitestart.bat and the pisrvsitestop.bat
command files. For example, interfaces are usually added to this file if they can be run as
Windows Services. When the service is started, it looks in the batch file used to configure the
interface (for example, random.bat). It starts the service using the parameters that it finds in
the file.
By default, the pisrvsitestart.bat (not overwritten during an upgrade) starts the random and
rmp_sk interfaces only. The other interfaces are commented out. To include these interfaces,
edit the pisrvsitestart.bat file and uncomment the other interfaces. Be sure that the other
interfaces are installed as services. For upgrades, if you would like to start the other default
interfaces, use the pisrvsitestart.bat.new file as guide to edit the pisrvsitestart.bat file or
replace the pisrvsitestart.bat file with the content in the pisrvsitestart.bat.new file. Also
remember to edit the pisrvsitestop.bat file to stop the other default interfaces if they have
been added in the pisrvsitestart.bat file.
4.1.2 Running PI Interactively
If problems occur during the operation of the PI Server, it may be useful to run the PI Server
interactively so that each PI process is associated with a command window. Output for each
process is written to its command window.
Start PI interactively from the PI\adm directory with the command file pistart.bat. This will
generate a command window for each of the PI subsystems and interfaces. The file pistart.bat
calls the pisitestart.bat command file.
Any site-specific applications should be added to the pisitestart.bat command file if they are
to be started every time PI is started. For new installs, the pisitestart.bat file will start the
random and rmp_sk interfaces only. The pisitestart.bat file will need to be edited to include
the other default interfaces by uncommenting out the commands to start the interfaces. The
pisitestart.bat file is not upgraded. For upgrades, the pisitestart.bat file is not overwritten. A
pisitestart.bat.new file can be used as a guide to include the other default interfaces.
It is not advisable to run part of the system as services and part interactively. On clustered PI
Server installations, all generic services should be offline before running the PI Server
interactively. Refer to Chapter 10, PI Server Cluster Installation.
PI Server Installation and Upgrade Guide Page 39
Chapter 4 - Start and Stop PI on Windows
Stopping PI When Running Interactively
To stop PI when running interactively, the command windows must be closed down in a
particular order, which is prescribed below. There is no pistop.bat command file. Stop each
subsystem by pressing <Ctrl-C>. Once the command prompt appears, close the window.
Close the PI command windows in this order:
1. Close all interfaces and user-written applications.
2. After these applications have exited, highlight the pinetmgr command window and
press <Ctrl-C> to stop the main subsystems. The pinetmgr process automatically
notifies each of the remaining PI processes to shutdown.
3. Wait five minutes (longer on large systems). Then, if any of the processes have not
exited, highlight the appropriate command window and press <Ctrl-C>.
4.1.3 Configuring Interfaces as Windows Services
As stated earlier, the PI System is automatically configured to run as Windows Services
during installation. This also includes running the default interfaces as Windows Services.
It is usually possible to configure other interfaces to run as Windows Services. Check the
interface documentation for instructions. In particular, all UniInt-based interfaces can be run
as Windows Services. UniInt is an OSIsoft software design standard for developing
interfaces.
For example, the PI Random Simulator is a UniInt-based interface. Thus you can use
Random as an example to configure other UniInt-based interfaces as Windows Services.
Page 40
Chapter 5. REMOVE PI INSTALLATIONS ON WINDOWS
To uninstall the PI Server, run the Add/Remove Programs applet from the Control Panel.
Select PI Server to uninstall. Uninstalling the PI Server will also uninstall the PI-SDK, the
interfaces that were installed with the PI Server, and PI Server Applications. If there are other
programs that require the PI-SDK, the PI-SDK installation must be reinstalled. Sometimes
you must reboot after uninstalling. Also, a number of files including Archives may remain
and will need to be manually removed from the system (especially if a reinstallation is to be
attempted).
PI Server Installation and Upgrade Guide Page 41
Chapter 6. PI SERVER INSTALLATION ON UNIX
6.1 Overview
The PI Server for UNIX-based operating systems is distributed on CD ROM or via the
Internet as compressed .tar files (which may be obtained from the OSIsoft Web site). As of
the 3.4 release, both the PI Server and the Server Applications are distributed in a single
bundle. Installation files are copied to a temporary (source) directory and then the pi_install
script is run to perform the PI System installation or upgrade.
Review the UNIX-related sections of Chapter 1, Preparing and Planning for Installation, in
this guide before a new PI Server installation or upgrade. This material covers system settings
and requirements such as memory and disk sizing. These preparatory steps should be
understood before proceeding. The installation or upgrade itself usually takes less than
one hour.
The time required for post-installation steps, such as creating additional archives, configuring
tags, and setting up the site-specific interface files will vary.
As part of a default installation, several points are automatically created. When PI is started,
two sample interfaces that generate simulated data are run to populate these points. This
means that you are collecting and archiving test data as soon as you start PI. These data can
be viewed immediately by using client applications such as PI ProcessBook and PI DataLink.
6.1.1 File Descriptor Limits
In general, the default setting for the maximum number of open file descriptors for a single
process is adequate for purposes of the PI server's operation. If the limit is set too low,
problems such as lost connections between subsystems and the Network Manager Subsystem
and lost connections between interfaces and clients and the PI server may result. The sections
that follow describe the procedures for checking the current state of this limit and, if
necessary, changing it to the recommended value.
Important: The procedures described in this section must be performed under a root
log-in. The changes involved affect system configuration files and data structures
which, if improperly modified, could cause the system to become unusable.
Rebuilding of the operating system kernel may be involved. On most platforms, a
reboot will be required to make any change take effect. If you are unfamiliar with
system administration procedures for UNIX systems, please enlist the help of you
local UNIX System Administrator when making any of the changes outlined below.
Please read the entire section that applies to your system before attempting any changes.
PI Server Installation and Upgrade Guide Page 43
Chapter 6 - PI Server Installation on UNIX
IBM AIX
To check the limit on open file descriptors, log in as piadmin and run the following
command:
ulimit –aH
Look for the line that begins nofiles(descriptors), followed by a number. If the number is
greater than 1024 or is unlimited, no further action is required.
The recommended procedure for changing the limit depends on whether there is a Network
Information Service (NIS) database installed on the system. The preferred method for
changing the limit is the chuser command. However, this command must not be used if there
is an NIS database installed on the system. In that case, direct modification of the appropriate
system configuration file is the appropriate method.
For AIX systems that do not have an NIS database installed, log in as root and run the
following command:
chuser nofiles_hard=1024 piadmin
This change will take effect the next time piadmin logs in. In order to insure that the PI server
can take advantage of the change, shut down the server, log out of the piadmin account, log
back in as piadmin, and restart the server.
For AIX systems that have an NIS database installed, log in as root and edit the file
/etc/security/limits to include the following line in the stanza for piadmin:
nofiles_hard = 1024
Consult the man page for the limits file (run: man limits) for details concerning the format of
the file. Alternatively, the value may be specified as -1 to allow an unlimited number of file
descriptors. Consult your AIX System Administrator before selecting a value.
As with the chuser command, this change will take effect the next time piadmin logs in. Use
the procedure given above to shut down and restart the PI server.
Compaq Tru64 (DEC) UNIX
To check the limit on open file descriptors, log in as root and run the following command:
/sbin/sysconfig -q proc | grep open_max_hard
The output from the command will display the open_max_hard label followed by the current
value. If the current value is greater than 1024 or is unlimited, no further action is required.
If the open file limit must be changed, do the following:
Using a text editor, prepare a stanza file consisting of the following lines:
proc:
open_max_hard = 1024
The exact name of the file is not important. For purposes of this example, the file name is
assumed to be stanza_file. For further information about the stanza file and its format, consult
the manual page for stanza (run: man stanza).
Page 44
6.1 - Overview
Log in as root and apply the stanza file to the system configuration by running the following
command:
/sbin/sysconfigdb -m -f stanza_file proc
The change will take effect after the system is rebooted.
HP-UX
To check the limit on open file descriptors, log in as piadmin and run the following
command:
sh exec ulimit –aH
1. Look for the line that begins nofiles(descriptors), followed by a number. If the
number is greater than 1024 or is unlimited, no further action is required.
2. To increase the descriptor limit, use the System Administrator Management utility,
SAM. Log in as root and start SAM, then do the following:
3. Enter the Kernel Configuration area.
4. Call up the Configurable Parameters utility.
5. Check whether the current value of the parameter nfile is 1024 or greater. If it is,
proceed to step 11. If not, continue with the next step. The value of this parameter is
the upper limit for the maxfiles_lim parameter which is the one that must be changed
to increase the descriptor limit.
6. Find the entry for the parameter maxusers. The standard formula for the value of
nfile is dependent on this parameter. Setting maxusers to 48 should yield a value for
nfile that is greater than 1024. If the current value of maxusers is less than 48, set it
to 48 or more and save the change.
7. Exit the Configurable Parameters utility.
8. Exit SAM.
9. When prompted to Create a New Kernel, choose the option to rebuild the kernel
now, press OK and wait for the new kernel to be built.
10. When prompted to Reboot the System, choose to install the new kernel, shut down
and reboot now. Press OK in response to the dialog about overwriting the /etc/system
file.
11. Wait while the system shuts down and reboots.
12. Once the system has restarted, log in as root, start SAM, return to the Configurable
Parameters utility and continue with the next step.
13. Modify the value of the parameter maxfiles_lim to be 1024 or greater.
14. Exit the Configurable Parameters utility, saving the change.
15. Since maxfiles_lim is a dynamic tuning parameter, the change should take effect
immediately. Verify the change by repeating the check described at the beginning of
this section.
PI Server Installation and Upgrade Guide Page 45
Chapter 6 - PI Server Installation on UNIX
Sun Solaris
To check the limit on open file descriptors, log in as piadmin and run the following
command:
ulimit –aH
Look for the line that begins nofiles(descriptors), followed by a number. If the number is
greater than 1024 or is unlimited, no further action is required.
To increase the descriptor limit, the system configuration file, /etc/system, must be modified.
Note: Damage to the file /etc/system could make the system unbootable. Always
make a backup copy before changing the file. See the man page for /etc/system
(run: man system) for further details concerning the format of the file and recovery
procedures.
To modify the descriptor limit in the /etc/system file, do the following:
1. Login as root.
2. Make a backup copy of the system tuning file:
cd /etc
cp ./system ./system.good
3. Edit the system tuning file using a text editor and add the following line at the end of
the file:
set rlim_fd_max = 1024
4. Save the changes.
5. Reboot the system.
6.1.2 Network Configuration
The PI Server relies on a proper network configuration to run successfully. TCP/IP must be
installed and configured before installing PI, even on stand-alone hosts.
A standard installation uses host name lookups for client access logging and validation. It is
important for performance and security to configure a stable and responsive host name file,
DNS, or other name service. A slow name service can dramatically impede PI and in some
cases cause it to fail.
6.1.3 Setting the Host Computer Time
In order for PI to accurately store and retrieve data, the PI host computer must have the
correct settings for:
Time
Time zone
Daylight Savings Time (DST)
Page 46
6.1 - Overview
In all cases, the home node should be set to its correct local time, time zone, and DST setting.
See Setting the Interface Node Clock in Chapter 6, Managing Interfaces, in the PI Server
System Management Guide,
Examine the current settings by using the UNIX date command. For example:
$ date
Fri Mar 6 10:30:17 PST 1998
The syntax to reset the date, time zone and daylight saving observation varies with UNIX
platform. Time settings should be verified before PI is installed.
Important: Incorrect settings will result in corrupted data!
If possible, configure your UNIX system to use xntp to synchronize the system clock with a
reliable network time source. Using xntp can greatly simplify the task of keeping server and
interface node clocks synchronized.
6.1.4 PI Administrator Account
root vs. piadmin
The PI System is designed to be run and administered by a PI System Administrator who is
logged in to the piadmin account. This account requires fewer privileges than the superuser
(root). However, whenever PI is installed or upgraded, the root account is required. After
completion of installation or upgrade, superuser privileges are no longer needed and the
administrator should log out of root and login as piadmin before proceeding to start PI.
UNIX Users and Groups
The PI System requires two UNIX login accounts for system maintenance. The PI System
Administrator uses the piadmin account. OSIsoft engineers use the osi account for remote
support. Both of these accounts belong to the same group, named pigrp.
The installation script will not attempt to create these user and group accounts. It is up to you
or your UNIX System Administrator to set up these accounts prior to installing the PI Server.
If the accounts do not exist, the installation procedure will issue a message and exit without
installing the server.
The PI user accounts should be set up according to the following tables. The home directory
for both accounts is set to the PI installation directory.
Username Userid groupid shell
piadmin 545 545 /bin/ksh
osi 546 545 /bin/ksh
Groupname groupid required members
pigrp 545 piadmin, osi
PI Server Installation and Upgrade Guide Page 47
Chapter 6 - PI Server Installation on UNIX
6.1.5 Security
A security plan should be developed for your site. The PIfirewall, PIproxy database, and PI
user names and groups should be defined to implement the security plan. The access
permissions on each tag should be set accordingly. See Chapter 7, Managing Security, in the
PI Server System Management Guide.
6.1.6 Platform-Specific Issues
HP-UX Real-Time Scheduling Privilege
To allow the correct setting of thread scheduling priorities and policy, the RTSCHED
privilege must be enabled for the pigrp group on HP-UX systems. In order to do this, you
must add or edit the file /etc/privgroup. Log in as root, open the file in a text editor and insert
the following line at the end of the file:
pigrp RTSCHED
After the file has been updated, remain logged in as root and execute the following command:
setprivgrp -f /etc/privgroup
These operations must be performed before starting the PI server. Please refer to the man
page for setprivgrp(1M) or consult your HP-UX System Administrator for further details.
Compaq Tru64 UNIX Libraries
For Compaq Tru64 UNIX systems, the latest C++ Run-Time Library Redistribution must be
installed prior to upgrading to PI 3.3. This kit must be obtained from Compaq. The kit is
available on Compaq’s FTP server at:
ftp://ftp.compaq.com/pub/products/C-CXX/Tru64/cxx/cxxredist.htm.
The environment variable LD_LIBRARY_PATH must point to the directory /PI/lib.
6.1.7 Media Preparation
Before installation or upgrade can commence, the PI distribution files need to be copied to a
local temporary path on the host machine. The steps necessary will vary with media and
configuration. The most common cases are addressed below.
During installation and upgrade the term source and target are used to refer to the temporary
PI installation directory and the actual installed PI System directory respectively
The administrator should create the installation source directory and the target directory prior
to installation and upgrade. After installation or upgrade the source directory should be
deleted.
An example of source and target is /tmp/PIsource and /opt/PI.
Loading the PI Source from CD-ROM
If the installation media is CD-ROM, mount the CD-ROM and do a directory listing. You
will see distribution files for many different computer platforms. The UNIX distributions are
Page 48
6.1 - Overview
all in compressed tar format. In each platform-specific subdirectory, the distribution file is
called pi.tar.gz.
There are two methods to copy the tar files from CD to the target machine’s PI source
directory:
The first method is to read the CD using a PC:
Insert the CD into a PC and copy the appropriate tar.gz file to the target machine,
using FTP in binary mode.
On the target UNIX machine, change your working directory to the PI source
directory, decompress using gunzip and extract the distribution files using the tar
command as shown in the examples below.
The second method is to read the CD on the target UNIX machine:
Mount the CD directly on the target machine.
Copy the appropriate tar.gz file and if necessary the appropriate gunzip
decompression utility to the PI source directory.
There are examples below that show how to mount the CD on the target machine, copy the
tar.gz file to the PI source directory, decompress and extract the distribution files. If you have
used FTP to copy the tar.gz file to the UNIX machine, ignore the commands for mounting
and dismounting the CD.
The examples may need to be modified slightly for your system. If you experience any
difficulty in getting the examples to work, first do a directory listing to check the actual
names of the directories and filenames on your system. The case of the directory names and
the file names themselves may change depending on which operating system you are using to
view the CD-ROM.
For more information on the mount and tar commands, use the UNIX man command to view
the online documentation. The gunzip utility is provided on the CD for each of the supported
platforms if it is not already available. The source and license for gunzip are provided in the
/support/unix directory of the CD and on the ftp.osisoft.com FTP site.
Note: These are examples only. Use the actual paths and device names on your
system. As of the 3.4 release, the server (PI Server) is distributed together with the
PI Server Applications in a single distribution file. Separate installation of the Server
and Server Applications is no longer required.
Sun Solaris Example
In this example, the system automatically mounts the CD when it is inserted.
# mkdir /tmp/PIsource
# cp /cdrom/cdrom0/unix/solaris/pi.tar.gz \ /tmp/PIsource
# cp /cdrom/cdrom0/support/unix/solaris/gunzip \ /tmp/PIsource
# eject
# cd /tmp/PIsource
# chmod 555 gunzip
# gunzip pi.tar.gz
PI Server Installation and Upgrade Guide Page 49
Chapter 6 - PI Server Installation on UNIX
# tar xvf ./pi.tar
HP-UX Example
# mkdir /cdrom
# /etc/mount -o ro -t cdfs /dev/dsk/c201d2s0 /cdrom
# mkdir /tmp/PIsource
# cp "/cdrom/UNIX/HP-UX/PI.TAR.GZ;1" \ /tmp/PIsource/pi.tar.gz
# cp "/cdrom/SUPPORT/UNIX/HP-UX/GUNZIP;1" \ /tmp/PIsource/gunzip
# /etc/umount /cdrom
# cd /tmp/PIsource
# chmod 555 gunzip
# gunzip pi.tar.gz
# tar xvf pi.tar
Compaq Tru64 UNIX Example
In this example, the “4” in rz4c indicates the SCSI address of the CD-ROM drive.
# mkdir /cdrom
# /usr/sbin/mount -t cdfs -o noversion -r /dev/rz4c /cdrom
# mkdir /tmp/PIsource
# cp /cdrom/unix/compaqunix/pi.tar.gz /tmp/PIsource
# cp /cdrom/support/unix/compaqunix/gunzip /tmp/PIsource
# /usr/sbin/umount /cdrom
# cd /tmp/PIsource
# chmod 555 gunzip
# gunzip pi.tar.gz
# tar xvf ./pi.tar
IBM AIX Example
In this example, the /etc/filesystems file has an entry similar to the one shown:
/usr/cdrom/sws:
dev = /dev/cd0
vfs = cdrfs
mount = true
options = ro
account = false
The mount -a command will read the file and mount the CD accordingly.
# mount -a
# mkdir /tmp/PIsource
# cp /usr/cdrom/sws/unix/aix/pi.tar.gz /tmp/PIsource
# cp /usr/cdrom/sws/support/unix/aix/gunzip \ /tmp/PIsource
# umount /usr/cdrom/sws
# cd /tmp/PIsource
# chmod 555 gunzip
# gunzip pi.tar.gz
# tar xvf ./pi.tar
Page 50
6.2 - New Installation Instructions
Loading the PI Source from Compressed TAR
If the installation media is obtained from the Web site at OSIsoft, it will be in the form of a
compressed tar file.
1. Create a temporary PI Server distribution directory.
2. Copy the compressed tar file (in binary transfer mode) to the temporary directory.
3. Decompress the file using the gunzip utility (which is also available on the OSIsoft
FTP server, under pub/unix). Extract the distribution files using the tar command.
The server distribution files will be placed in a subdirectory with a name of the form
370.XX.serv where “XX” is the build number. Then go to either the New Installation
Instructions or Upgrade Instructions section to continue the installation.
After Loading the PI Distribution
Once the files have been extracted from the tar file, go to one of the following sections to
continue the installation:
For a first-time installation of the PI Server, go to New Installation Instructions.
To upgrade an existing PI Server installation, go to Upgrade Instructions.
6.2 New Installation Instructions
Before starting a new installation, be sure that you have reviewed Chapter 1, Preparing and
Planning for Installation, in this manual.
6.2.1 Pre-installation Checklist
As you prepare to execute a new installation, you must address the following:
1. Ensure that you have a license file, pilicense.dat.
2. Ensure that you have a proper backup of your system.
3. Review system and sizing requirements. Ensure that sufficient disk space is available
and that system resources are adequate for the intended installation. If your system
will be used only to run PI, and no other applications will be run from the piadmin
account, then your default process quotas should be sufficient. If this is not the case,
read UNIX Process Quotas in Chapter 12, PI Troubleshooting and Repair in the PI
Server System Management Guide.
4. Ensure that you have access to the root account (necessary for a new installation).
5. Verify the host time settings.
6. Verify the host network configuration.
7. Verify that your operating system and versions are supported.
8. Create user accounts as required.
9. Review and address any platform-specific requirements.
PI Server Installation and Upgrade Guide Page 51
Chapter 6 - PI Server Installation on UNIX
10. Determine a path for the target installation consistent with disk space requirements.
All files except the archives are installed to the same path.
11. Determine whether you intend to install the default points.
12. Determine the size and directory for the first three default archives. The default
directory is PI/dat. You may want to specify a different directory if the PI disk is
small. Create the directory prior to installation.
13. A new installation cannot be performed on any host that has an existing installation.
If this is the case, review Chapter 9, Removing PI Installations on UNIX.
14. Create a directory for the source media and load the installation files on the host
machine.
6.2.2 Installation
Once you have completed the installation checklist you are ready to begin the installation.
1. Log into the target host as root.
2. Change your working directory to the source directory and run the installation using
the script pi_install:
# cd /tmp/Pisource/370.XX.serv
# ./pi_install
Output from a sample installation is available in the section A Sample New
Installation at the end of this chapter. The installation script executes the following
tasks:
• The pi_install script runs adm/piins.sh, redirecting the output to generate a record
of the installation in the file /tmp/piinstall.log.
• The initial display presents the current system date and system information.
• The script checks that it is being run on a supported platform.
• The source files location (path) is verified. The default path should be correct. If
not, make sure that you are running the installation script from the source path.
• The script checks for an existing PI installation. If the /etc/piparams.default file
is detected, the script attempts to run an upgrade. If a new installation is desired
(as opposed to an upgrade), the existing PI System must first be removed. See
Chapter 9, Removing PI Installations on UNIX.
• The target (installation) location is verified. If the default directory is not the
intended target, enter the complete path where you want PI to be installed.
• Setup asks for the location of the license file (pilicense.dat).
• The /etc/piparams.default file is created to record the target (installation)
location.
• The script verifies that it is being run from the root account. It then checks if the
piadmin and osi users and the pigrp group are defined. If not, it creates them.
• The script checks that you are satisfied with the backup of your system.
• Distribution files are copied to the PI target. File permissions are set.
Page 52
6.2 - New Installation Instructions
• Next you are asked to specify whether to install the default points.
• The script prompts for the initial size and location parameters for the Event
Queue file. If you are unsure about the appropriate settings for these parameters,
accept the default values and continue. Adjustments can be made at a later date,
if the need is identified.
• The archive files and PI databases are created, including the Point Database,
Digital State Table, batch tables and the security tables. Event queue file
parameters are saved in the PITimeout Table.
• The system ID file is created.
• A record of the installation session is put in the file /tmp/piinstall.log.
• The first time the PI Server is run it will complete the install by processing the
PI/adm/pirunonce.dif script (if it exists).
6.2.3 Post Installation Checklist
Once the installation script has completed there are a number of administrative and
maintenance tasks that need to be addressed to ensure successful operation of the PI Server.
This section provides a checklist that should be reviewed before running PI.
1. After running the setup program, review the ASCII log file /tmp/piinstall.log for any
errors.
2. Review the notes at the end of the log file for information regarding new or changed
features. In particular, please note the changes that affect backup procedures.
3. For all UNIX platforms, environment variables must be configured in order for PI to
run properly. Refer to Setting Environment Variables in Chapter 9, Running PI on
UNIX, in this manual. These variables must be set for the piadmin account.
4. Be sure to log out of the root account and into piadmin for PI administrative tasks.
5. The scripts PI/adm/pisitestart.sh and PI/adm/pisiteverify.sh should be modified to
include the interfaces that are used at your site.
6. It is useful to monitor the data transfer rate from each interface to the PI Home node.
Refer to Data Rate Monitoring, in Chapter 5 of the PI Server System Management
Guide.
7. At this point, the PI source directory is no longer needed and may be removed from
the system.
8. A backup scheme should be developed and a full PI system backup should be
executed while the system is shut down.
9. Install the PI System Management Tools on any Windows client computers where it
will be useful. To do this, run setup.exe from the Data Archive CD.
10. Configure network access and install software for OSIsoft to provide remote
technical support.
11. Proceed to the Running PI section.
PI Server Installation and Upgrade Guide Page 53
Chapter 6 - PI Server Installation on UNIX
6.2.4 A Sample New Installation
*****************************************************************************
*
* P I S e r v e r 3 . 4
* I n s t a l l a t i o n / U p g r a d e
*
*****************************************************************************
Thu Nov 10 15:00:38 PST 2005
SunOS lime 5.8 Generic_108528-11 sun4u sparc SUNW,Ultra-5_10
It takes between 15 minutes and 1 hour to install PI Server.
Install has determined that source files for the PI installation/upgrade
are in /opt/pitemp/distrib/3.4.370/370.53.serv.
Is this the correct location of the source files? (y/n/q) [y] y
Install has determined that the target directory for the PI
installation/upgrade is /opt/PI.
Is this the correct location for installation/upgrade? (y/n/q) [y] y
Licensing
---------
A license file (pilicense.dat) must be present in order for the installation
to continue. Please specify the location of the license file (below). If you
do not have a license file, cancel this installation and contact OSIsoft, Inc.
Technical Support to obtain a license.
======= Menu =======
f) Enter license file path [ /tmp ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (f/q/c) [c] f
Enter new path: /opt/pitemp/distrib/3.4.370
======= Menu =======
f) Enter license file path [ /opt/pitemp/distrib/3.4.370 ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (f/q/c) [c] c
*****************************************************************************
* *
* P I S e r v e r 3 . 4 *
* I n s t a l l a t i o n / U p g r a d e *
* *
*****************************************************************************
Thu Nov 10 15:01:04 PST 2005
SunOS lime 5.8 Generic_108528-11 sun4u sparc SUNW,Ultra-5_10
It takes between 15 minutes and 1 hour to install PI Server.
PI Server version 3.4.370.53 will be installed.
The installation source directory is /opt/pitemp/distrib/3.4.370/370.53.serv
target directory is /opt/PI
Are you satisfied with the backup of your System? (y/n/q) [y] y
Thu Nov 10 15:01:05 PST 2005
Copying files...
Creating Directory /opt/PI/adm
Creating Directory /opt/PI/bin
Creating Directory /opt/PI/dat
Creating Directory /opt/PI/interfaces
Creating Directory /opt/PI/interfaces/random
Creating Directory /opt/PI/interfaces/rmp_sk
Page 54
6.2 - New Installation Instructions
Creating Directory /opt/PI/lib
Creating Directory /opt/PI/log
Creating Directory /opt/PI/man
Creating Directory /opt/PI/patches
Creating Directory /opt/PI/utility
Copying file /opt/PI/lib/libC.so.5
Copying file /opt/PI/lib/libCrun.so.1
Copying file /opt/PI/lib/libpilicense.so
Copying file /opt/PI/lib/libpiut.so
Copying file /opt/PI/lib/libpiarss.so
Copying file /opt/PI/lib/libpiptss.so
Copying file /opt/PI/lib/libpidiff.so
Copying file /opt/PI/lib/libpisdk.so
Copying file /opt/PI/lib/libpipe.so
Copying file /opt/PI/lib/libpiparse.so
Copying file /opt/PI/lib/libpiba.so
Copying file /opt/PI/lib/libpimoduledb.so
Copying file /opt/PI/lib/libpiapi.so
Copying file /opt/PI/adm/relnotes.txt
Copying file /opt/PI/adm/relnotes.html
Copying file /opt/PI/adm/install.txt
Copying file /opt/PI/adm/pialias.sh
Copying file /opt/PI/adm/pibackup.sh
Copying file /opt/PI/adm/piins.sh
Copying file /opt/PI/adm/pisitestart.sh
Copying file /opt/PI/adm/pisitestop.sh
Copying file /opt/PI/adm/pisiteverify.sh
Copying file /opt/PI/adm/pistart.sh
Copying file /opt/PI/adm/piappstart.sh
Copying file /opt/PI/adm/pistop.sh
Copying file /opt/PI/adm/piverify.sh
Copying file /opt/PI/adm/upgrade.txt
Copying file /opt/PI/bin/pipeschd.sh
Copying file /opt/PI/adm/apitestpoints.dif
Copying file /opt/PI/adm/base.dif
Copying file /opt/PI/adm/classic.dif
Copying file /opt/PI/adm/defaultpt.dat
Copying file /opt/PI/adm/defaultpt.dif
Copying file /opt/PI/adm/demopt.dat
Copying file /opt/PI/adm/digstate.dif
Copying file /opt/PI/adm/distrib.dat
Copying file /opt/PI/adm/install.txt
Copying file /opt/PI/dat/pe314.llr
Copying file /opt/PI/dat/pe314.dfa
Copying file /opt/PI/adm/piarc.dif
Copying file /opt/PI/adm/pibalist.dif
Copying file /opt/PI/adm/pibatch.dif
Copying file /opt/PI/adm/piinstall.dif
Copying file /opt/PI/adm/pinoptins.dif
Copying file /opt/PI/adm/pipeschd.dif
Copying file /opt/PI/adm/pisnap.dif
Copying file /opt/PI/dat/pisql.ini
Copying file /opt/PI/dat/pisql.res
Copying file /opt/PI/dat/pisystem.res
Copying file /opt/PI/adm/rmp_sk.dat
Copying file /opt/PI/adm/rmp_sk.dif
Copying file /opt/PI/dat/shutdown.dat
PI Server Installation and Upgrade Guide Page 55
Chapter 6 - PI Server Installation on UNIX
Copying file /opt/PI/adm/Totalizerpts.dif
Copying file /opt/PI/adm/alarmpts.dif
Copying file /opt/PI/adm/almstate.dif
Copying file /opt/PI/adm/SunOS.txt
Copying file /opt/PI/bin/pialarm
Copying file /opt/PI/bin/piarchss
Copying file /opt/PI/adm/piarcreate
Copying file /opt/PI/adm/piartool
Copying file /opt/PI/bin/pibackup
Copying file /opt/PI/adm/pibainst
Copying file /opt/PI/bin/pibatch
Copying file /opt/PI/bin/pibasess
Copying file /opt/PI/adm/piconfig
Copying file /opt/PI/adm/pidiag
Copying file /opt/PI/adm/pifirewall
Copying file /opt/PI/adm/pigetmsg
Copying file /opt/PI/bin/pilicmgr
Copying file /opt/PI/adm/pilistupd
Copying file /opt/PI/adm/piinstall
Copying file /opt/PI/adm/pimanager
Copying file /opt/PI/bin/pimsgss
Copying file /opt/PI/bin/pinetmgr
Copying file /opt/PI/bin/pisnapss
Copying file /opt/PI/bin/pipeschd
Copying file /opt/PI/bin/pirecalc
Copying file /opt/PI/adm/pipetest
Copying file /opt/PI/adm/piparams
Copying file /opt/PI/adm/pisetpass
Copying file /opt/PI/bin/pishutev
Copying file /opt/PI/bin/pisqlss
Copying file /opt/PI/bin/pitotal
Copying file /opt/PI/bin/piupdmgr
Copying file /opt/PI/adm/piversion
Copying file /opt/PI/adm/pisysdig
Copying file /opt/PI/adm/pisetevq
Copying file /opt/PI/adm/apisnap
Copying file /opt/PI/adm/pisnap.sh
Copying file /opt/PI/adm/ipisql
Copying file /opt/PI/interfaces/random/random
Copying file /opt/PI/interfaces/random/random.sh
Copying file /opt/PI/interfaces/rmp_sk/rmp_sk
Copying file /opt/PI/interfaces/rmp_sk/rmp_sk.sh
New license file /opt/pitemp/distrib/3.4.370/pilicense.dat installed.
Specifying Default Points:
--------------------------
During installation, a number of defaults points will be
created and populated by the default simulator interfaces.
This are often used for diagnostic purposes and it is
recommended that they be installed. Installations which
are to be used for migration from PI 2.x systems should
not install the default points.
Do you wish to install the default points? (y/n) [y] y
Specifying an archive size:
--------------------------
Although PI allows a minimum archive size of 1 Mb per 256 points (or 4
records per point, for optimum performance it is recommended that you
Page 56
6.2 - New Installation Instructions
allocate between 10 and 20 records per expected point, without exceeding
the limits of your backup tapes.
50 - 100 Mb is a typical archive size for a 5,000 point system.
200 - 400 Mb is a typical archive size for a 20,000 point system.
500 - 1000 Mb is a typical archive size for a 50,000 point system
Three archives are defined during installation. Use the piarcreate utility to
create more archives after you have verified this installation by running PI.
======= Menu =======
s) Set archive size [ 128 ] Mbytes
1) Set archive 1 path [ /opt/PI/dat ]
2) Set archive 2 path [ /opt/PI/dat ]
3) Set archive 3 path [ /opt/PI/dat ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (1/2/3/s/q/c) [c] s
Enter new size: 256
======= Menu =======
s) Set archive size [ 256 ] Mbytes
1) Set archive 1 path [ /opt/PI/dat ]
2) Set archive 2 path [ /opt/PI/dat ]
3) Set archive 3 path [ /opt/PI/dat ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (1/2/3/s/q/c) [c] c
Event Queue Defaults
--------------------
Please specify the location and size for the Event Queue file (pimapevq.dat).
It is recommended that the size of the queue be large enough to hold 24 hours
worth of data. A good rule of thumb for the Event Queue file size is at least
half the size of an archive. The Event Queue page size is the maximum size of
a single event sent to the archive.
======= Menu =======
s) Set Event Queue file size [ 64 ] Mbytes (Range: 8 - 131072)
p) Set Event Queue page size [ 1024 ] Kbytes (Range: 64 - 8192)
f) Set Event Queue file path [ /opt/PI/dat ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (s/p/q/c) [c] s
Enter new size (MB): 128
======= Menu =======
s) Set Event Queue file size [ 128 ] Mbytes (Range: 8 - 131072)
p) Set Event Queue page size [ 1024 ] Kbytes (Range: 64 - 8192)
f) Set Event Queue file path [ /opt/PI/dat ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (s/p/q/c) [c] c
Generating default PI Server databases.
Commencing Installation of PI System default
Data Directory: /opt/PI/dat/
Beginning Database Creation...
Loading Digital State Database.
Creating Archive Memory Tables.
Thu Nov 10 15:02:05 2005 :0 0
PI Server Installation and Upgrade Guide Page 57
Chapter 6 - PI Server Installation on UNIX
Snapshot records loaded, count: 0, found: 0, status: [0] Success
Thu Nov 10 15:02:05 2005 :0 0
Snapshot tables created, /opt/PI/dat/, status: [0] Success
Creating archive file piarch.001 in /opt/PI/dat/
Registering archive file piarch.001 in /opt/PI/dat/
Thu Nov 10 15:02:15 2005 :0 0
Invalid Start/End times in Primary archive file.
/opt/PI/dat/piarch.001 - Archiving disabled until Archive shift
Thu Nov 10 15:02:15 2005 :0 0
Successful archive file definition: /opt/PI/dat/piarch.001
Creating archive file piarch.002 in /opt/PI/dat/
Registering archive file piarch.002 in /opt/PI/dat/
Thu Nov 10 15:02:15 2005 :0 0
Archive file /opt/PI/dat/piarch.002 loaded.
Thu Nov 10 15:02:15 2005 :0 0
Successful archive file definition: /opt/PI/dat/piarch.002
Creating archive file piarch.003 in /opt/PI/dat/
Registering archive file piarch.003 in /opt/PI/dat/
Thu Nov 10 15:02:15 2005 :0 0
Archive file /opt/PI/dat/piarch.003 loaded.
Thu Nov 10 15:02:15 2005 :0 0
Successful archive file definition: /opt/PI/dat/piarch.003
Finished defining archive files.
Thu Nov 10 15:02:15 2005 :0 0
Creating Attribute Sets Database (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating Point Classes Database (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating Point Aliases Database (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating Point Units Database (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating Point Database (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating Point Source Index (offline mode).
Thu Nov 10 15:02:15 2005 :0 0
Creating COM-Connector Index (offline mode).
Database Creation Complete...
Thu Nov 10 15:02:16 PST 2005
Updating shared library path environment.
Installing pinetmgr tables
Creating PI firewall table, status is [0] Success
Creating/updating PI timeout table, status is [0] Success
PI proxy table is now replaced by Trust-Relations - not creating...
Installing pibatch tables
PI Batch installation/upgrade completed, status is [0] Success
Setting Event Queue file path to /opt/PI/dat;
queue size 128 MB; page size 1024 KB.
Creating PISysID.dat for new installation.
Server ID file created.
Dumping file /opt/PI/dat/PISysID.dat
1. MajorVersion: 3
2. MinorVersion: 4
3. MajorBuild: 370
4. MinorBuild: 53
5. ServerID: 0ab7cb88-523e-11da-8daa-080020fe4219
Page 58
6.2 - New Installation Instructions
6. APIServerID: 87312
chown: /opt/PI/log/*: No such file or directory
chgrp: /opt/PI/log/*: No such file or directory
Installation/upgrade complete at Thu Nov 10 15:02:18 PST 2005
************************************************************
PI Universal Data Server 3.4 Post Installation Instructions
************************************************************
REVIEW LOG FILES
If there were any problems reported during the upgrade
process with the startup or shutdown of PI, please
check the log files in the log directory for any
documented errors.
POST INSTALLATION TASKS
After new installations there are a number of post
installation administrative tasks such as creating more
archives (three are created by default), configuring
site specific activites and scheduling backups. Please follow
the post installation instructions in the UNIX installation
section of the PI 3 UDS manual, review any
published release notes and review the additional
information provided below.
NEW BACKUP SCHEME
The PI server backup scheme has changed. The PI server backup is now
implemented by a backup subsystem process as opposed to a shell script. The
pibackup.sh script remains as the command-line interface to the backup
subsystem, however the argument list has changed. The cronpibackup.sh file
formerly installed for automatic backups has been replaced by the file
pibackuptask.sh. If this is an upgrade, any currently scheduled cron job that
utilitzes cronpibackup.sh will cease to function. Please review the backup
section of the PI Server manual for details concerning the changes to the
pibackup.sh script and the procedure for scheduling an automatic backup task.
START PI
PI is currently not running. To start PI, you should be logged
in as piadmin. Start PI using pistart.sh in the adm directory.
REMOVE TEMPORARY FILES
You may now remove the temporary PI installation directory,
it is no longer needed.
PI API
The PI API development kit for use on the PI 3 host is
no longer distributed and installed as part of the PI 3
installation / upgrade procedure.
****************************************************
PI Universal Data Server 3.4
Notes for Solaris Users
****************************************************
DEFINE SHARED LIBRARY PATH
You must define and export the shared library environment variable
for the piadmin account to point to the PI lib directory:
If using Korn Shell or Bourne Shell:
LD_LIBRARY_PATH=/opt/PI/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
If using C Shell:
setenv LD_LIBRARY_PATH /opt/PI/lib:$LD_LIBRARY_PATH
PI Server Installation and Upgrade Guide Page 59
Chapter 7. UPGRADE THE PI SERVER ON UNIX
If you are upgrading to PI 3.4, you must be running PI 3.2 or later. If you are running PI 3.1
or PI 3.0, you must first upgrade to PI 3.2.
Before starting an upgrade, be sure that you have reviewed Chapter 1, Preparing and
Planning for Installation, in this guide.
The following section provides a detailed checklist for upgrades as well as a step by step
overview of the upgrade script activities followed by a discussion of necessary post-upgrade
tasks.
7.1 Pre-upgrade Checklist
Before you execute an upgrade, you must address the following:
1. Ensure that you have a proper backup of your system.
2. Ensure that you have access to the root account.
3. Make sure you have no site-specific changes in the following files. Each of these files
will be overwritten during the upgrade:
pibackup.sh
pistart.sh
pistop.sh
piverify.sh
4. Review the files piappstart.sh and piappbackup.sh for site-specific changes. These
files are no longer used as of the 3.3.4 release. Changes in these files should be
migrated to pisitestartup.sh and pisitebackup.sh, respectively.
5. Review and address any platform-specific requirements.
6. Verify that your operating system versions are supported. See Chapter 1, Preparing
and Planning for Installation, in this manual.
7. Review system and sizing requirements. Review available disk space and usage.
8. Verify the location of the current installation, which should be used as the upgrade
path (upgrades must be in the same location as the original installation). The
pimanager command may be useful for this purpose. See Path Verification Example,
below.
PI Server Installation and Upgrade Guide Page 61
Chapter 7 - Upgrade the PI Server on UNIX
9. If your system is being used only to run PI, and no other applications are run from the
piadmin account, then your default process quotas should be sufficient. If this is not
the case, read UNIX Process Quotas in Chapter 12, PI Troubleshooting and Repair in
the PI Server System Management Guide.
10. Create a path for the source media and load the upgrade files on the host or network
accessible machine.
Path Verification Example:
$ pwd
/opt/PI/adm
$ ./piparams -pb # Print binaries path
/opt/PI/bin/
$ ./piparams -pd # Print data path
/opt/PI/dat/
$ ./piparams -pi # Print interfaces path
/opt/PI/interfaces/
$ ./piparams -pl # Print log path
/opt/PI/log/
7.2 Upgrade
Once you have completed the upgrade checklist, you are ready to begin the installation.
Log into the target host as root. Change your working directory to the source directory and
run the upgrade using the script pi_install:
# cd /tmp/Pisource/370.XX.serv
# ./pi_install
Output from a sample upgrade is available in A Sample Upgrade at the end of this chapter.
The upgrade script executes the following tasks:
• The pi_install script runs /adm/piins.sh redirecting the output to generate a record
of the upgrade in the file /tmp/piinstall.log.
• The initial display presents the current system date and system information.
• The script checks that it is being run on a supported platform.
• The script verifies that the piadmin and osi users and the pigrp group are defined.
If not, the upgrade terminates immediately with a message indicating that they
must be created before the upgrade can be completed.
• The source files location (path) is verified. The default path should be correct. If
not, make sure that you are running the installation script from the source path.
• The script checks for an existing PI installation. If the /etc/piparams.default file
is detected, the script prompts the user for verification that the upgrade is
intended.
• The target (installation) location is verified. If the PI system is properly
configured, the default path should point to the existing installed system.
• The script asks for the location of the license file (pilicense.dat).
Page 62
7.3 - Post-Upgrade Checklist
• The script will now inform the user about changes in the server backup scheme
and ask the user to accept the new scheme. If the user refuses, the upgrade will
terminate immediately with no changes to the existing PI server installation.
• The script will now check whether a downgrade is being attempted. As data file
structures evolved between releases, there can be unexpected results from
downgrading so this is not supported. To downgrade, you should perform a
complete restore from a full backup of the PI server.
• The script checks that you are satisfied with the backup of your system.
• The script runs pistop.sh from the target directory to stop any running PI
processes.
• Distribution files are copied to the PI target and file permissions and ownerships
are set. The existing archives and files in the PI/dat directory are preserved. The
site-specific files PI/dat/shutdown.dat, PI/adm/pisitestart.sh,
PI/adm/pisitestop.sh, and PI/adm/pisiteverify.sh are preserved. The interface
startup files are preserved. The new versions of these files are copied with the
.new extension.
• The license file (pilicense.dat) is installed in the /dat subdirectory.
• If an automatic backup script (cronpibackup.sh) is found in the /adm directory, it
is renamed to cronpibackup.sh.old.
• PI databases are updated or created where necessary. This includes an update to
the System Digital State Set to add new elements.
• The script will now either print the contents of an existing system ID file or
create a new one and display its contents.
• Any platform specific post-upgrade information is displayed.
• A record of the upgrade session is put in the file /tmp/piinstall.log.
• The first time the PI Server is restarted, it will complete the upgrade by
processing the PI/adm/pirunonce.dif script (if it exists). Not all upgrades will
provide this script.
7.3 Post-Upgrade Checklist
Once the upgrade script has completed, there are a number of administrative and maintenance
tasks that may need to be addressed to ensure continued successful operation of the PI Server.
This section provides a checklist that should be reviewed before restarting PI (especially
since there may have been changes from previous releases).
1. Be sure to log out of the root account and into piadmin for PI administrative tasks.
2. Review the log file /tmp/piinstall.log for any errors. In particular, please note the
changes that affect backup procedures.
3. With the 3.4 release, a new PI server backup scheme has been introduced. If an
automatic backup was scheduled for the old server, it will no longer work following
the upgrade. In order to continue the automatic backups, the old backup task must be
removed from the crontab file and a new task scheduled using the pibackup.sh script
PI Server Installation and Upgrade Guide Page 63
Chapter 7 - Upgrade the PI Server on UNIX
which is found in the /adm subdirectory. For further details see Chapter 4, Backing
up the PI Server, in the PI Server System Management Guide.
4. During the upgrade, a number of site-specific files are not overwritten. However, new
versions of these files are provided (with the extension .new), which may have
significant changes from the original versions. These files should be compared to the
originals and changes incorporated as needed. In particular, the following files should
be examined:
• PI/adm/pisitestart.sh.new
• PI/adm/pisitestop.sh.new
• PI/adm/pisiteverify.sh.new
• PI/adm/rmp_sk.dat
• PI/adm/rmp_sk.dif
• PI/bin/pipeschd.sh.new
• PI/dat/shutdown.dat.new
• PI/interfaces/random/random.sh.new
• PI/interfaces/rmp_sk/rmp_sk.sh.new
5. Review the Managing Security subsection in the PI Server System Management
Guide, as some security features may have been enhanced from previous releases.
6. At this point, the PI source directory is no longer needed and may be removed from
the system.
7. Proceed to the Running PI section.
7.3.1 A Sample Upgrade
*****************************************************************************
P I S e r v e r 3 . 4
I n s t a l l a t i o n / U p g r a d e
*****************************************************************************
Thu Nov 10 14:38:10 PST 2005
SunOS lime 5.8 Generic_108528-11 sun4u sparc SUNW,Ultra-5_10
It takes between 15 minutes and 1 hour to install PI Server.
Install has determined that source files for the PI installation/upgrade
are in /opt/pitemp/distrib/3.4.370/370.53.serv.
Is this the correct location of the source files? (y/n/q) [y] y
There is an existing PI installation on this machine, as
indicated by the presence of the /etc/piparams.default file.
If you want to install instead of upgrade then you must delete
this file as well as the existing PI installation and run this
installation script again.
Also, PI 3.4 can only upgrade a 3.2 or later system. If this
is a 3.1 system, please upgrade it to 3.2 before proceeding.
Do you want to upgrade ? (y/n/q) [y] y
Install has determined that the target directory for the PI
installation/upgrade is /opt/PI.
Is this the correct location for installation/upgrade? (y/n/q) [y] y
Validating previous installation paths.
Licensing
---------
Page 64
7.3 - Post-Upgrade Checklist
A license file (pilicense.dat) must be present in order for the installation
to continue. Please specify the location of the license file (below). If you
do not have a license file, cancel this installation and contact OSIsoft, Inc.
Technical Support to obtain a license.
======= Menu =======
f) Enter license file path [ /tmp ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (f/q/c) [c] f
Enter new path: /opt/pitemp/distrib/3.4.370
======= Menu =======
f) Enter license file path [ /opt/pitemp/distrib/3.4.370 ]
q) Quit installation Changes not saved
c) Continue installation
Selection ? (f/q/c) [c] c
New Backup Scheme
-----------------
The PI server backup scheme has changed. The PI server backup is now
implemented by a backup subsystem process as opposed to a shell script. The
cronpibackup.sh file formerly installed for automatic backups has been
replaced by the file pibackuptask.sh. Any currently scheduled cron job that
utilitzes cronpibackup.sh will cease to function after this upgrade. Please
review the backup section of the PI Server manual and schedule a new PI Server
backup after the upgrade.
Please Note: If you do not accept the new backup scheme, this upgrade will
terminate immediately and the server installation will remain unchanged.
Do you accept the new backup scheme? (y/n) [n] y
Checking for PI Server downgrade.
*****************************************************************************
P I S e r v e r 3 . 4
I n s t a l l a t i o n / U p g r a d e
*****************************************************************************
Thu Nov 10 14:38:38 PST 2005
SunOS lime 5.8 Generic_108528-11 sun4u sparc SUNW,Ultra-5_10
It takes between 15 minutes and 1 hour to install PI Server.
Upgrade from 3.3.362.55 to 3.4.370.53
The installation source directory is /opt/pitemp/distrib/3.4.370/370.53.serv
target directory is /opt/PI
Are you satisfied with the backup of your System? (y/n/q) [y] y
Thu Nov 10 14:38:40 PST 2005
PI Server will now be stopped (if it is running) on this machine.
Running PI Site Specific Stop...
Interface random not found
Interface rmp_sk not found
Stopping PI Subsystems...
PI Subsystem pialarm not found
PI Subsystem pibatch not found
PI Subsystem pirecalc not found
PI Subsystem pipeschd not found
PI Subsystem pisqlss not found
PI Subsystem pitotal not found
PI Subsystem pishutev not found
PI Subsystem piupdmgr not found
PI Subsystem pimsgss not found
PI Subsystem pibasess not found
PI Server Installation and Upgrade Guide Page 65
Chapter 7 - Upgrade the PI Server on UNIX
PI Subsystem pisnapss not found
PI Subsystem piarchss not found
PI Shutdown is Complete.
PI Subsystem pinetmgr is not present
PI Subsystem pimsgss is not present
PI Subsystem piupdmgr is not present
PI Subsystem pisnapss is not present
PI Subsystem piarchss is not present
PI Subsystem pibasess is not present
All expected PI Subsystems are stopped
Copying files...
Directory Exists /opt/PI/adm
Directory Exists /opt/PI/bin
Directory Exists /opt/PI/dat
Directory Exists /opt/PI/interfaces
Directory Exists /opt/PI/interfaces/random
Directory Exists /opt/PI/interfaces/rmp_sk
Directory Exists /opt/PI/lib
Directory Exists /opt/PI/log
Directory Exists /opt/PI/man
Directory Exists /opt/PI/patches
Directory Exists /opt/PI/utility
Copying file /opt/PI/lib/libC.so.5
Copying file /opt/PI/lib/libCrun.so.1
Copying file /opt/PI/lib/libpilicense.so
Copying file /opt/PI/lib/libpiut.so
Copying file /opt/PI/lib/libpiarss.so
Copying file /opt/PI/lib/libpiptss.so
Copying file /opt/PI/lib/libpidiff.so
Copying file /opt/PI/lib/libpisdk.so
Copying file /opt/PI/lib/libpipe.so
Copying file /opt/PI/lib/libpiparse.so
Copying file /opt/PI/lib/libpiba.so
Copying file /opt/PI/lib/libpimoduledb.so
Copying file /opt/PI/lib/libpiapi.so
Copying file /opt/PI/adm/relnotes.txt
Copying file /opt/PI/adm/relnotes.html
Copying file /opt/PI/adm/install.txt
Copying file /opt/PI/adm/pialias.sh
Copying file /opt/PI/adm/pibackup.sh
Copying file /opt/PI/adm/piins.sh
Copying file /opt/PI/adm/pisitestart.sh.new
Copying file /opt/PI/adm/pisitestop.sh.new
Copying file /opt/PI/adm/pisiteverify.sh.new
Copying file /opt/PI/adm/pistart.sh
Copying file /opt/PI/adm/piappstart.sh
Copying file /opt/PI/adm/pistop.sh
Copying file /opt/PI/adm/piverify.sh
Copying file /opt/PI/adm/upgrade.txt
Copying file /opt/PI/bin/pipeschd.sh.new
Copying file /opt/PI/adm/apitestpoints.dif
Copying file /opt/PI/adm/base.dif
Copying file /opt/PI/adm/classic.dif
Copying file /opt/PI/adm/defaultpt.dat
Copying file /opt/PI/adm/defaultpt.dif
Copying file /opt/PI/adm/demopt.dat
Copying file /opt/PI/adm/digstate.dif
Page 66
7.3 - Post-Upgrade Checklist
Copying file /opt/PI/adm/distrib.dat
Copying file /opt/PI/adm/install.txt
Copying file /opt/PI/dat/pe314.llr
Copying file /opt/PI/dat/pe314.dfa
Copying file /opt/PI/adm/piarc.dif
Copying file /opt/PI/adm/pibalist.dif
Copying file /opt/PI/adm/pibatch.dif
Copying file /opt/PI/adm/piinstall.dif
Copying file /opt/PI/adm/pinoptins.dif
Copying file /opt/PI/adm/pipeschd.dif
Copying file /opt/PI/adm/pisnap.dif
Copying file /opt/PI/dat/pisql.ini
Copying file /opt/PI/dat/pisql.res
Copying file /opt/PI/dat/pisystem.res
Copying file /opt/PI/adm/rmp_sk.dat.new
Copying file /opt/PI/adm/rmp_sk.dif.new
Copying file /opt/PI/dat/shutdown.dat.new
Copying file /opt/PI/adm/Totalizerpts.dif
Copying file /opt/PI/adm/alarmpts.dif
Copying file /opt/PI/adm/almstate.dif
Copying file /opt/PI/adm/SunOS.txt
Copying file /opt/PI/bin/pialarm
Copying file /opt/PI/bin/piarchss
Copying file /opt/PI/adm/piarcreate
Copying file /opt/PI/adm/piartool
Copying file /opt/PI/bin/pibackup
Copying file /opt/PI/adm/pibainst
Copying file /opt/PI/bin/pibatch
Copying file /opt/PI/bin/pibasess
Copying file /opt/PI/adm/piconfig
Copying file /opt/PI/adm/pidiag
Copying file /opt/PI/adm/pifirewall
Copying file /opt/PI/adm/pigetmsg
Copying file /opt/PI/bin/pilicmgr
Copying file /opt/PI/adm/pilistupd
Copying file /opt/PI/adm/piinstall
Copying file /opt/PI/adm/pimanager
Copying file /opt/PI/bin/pimsgss
Copying file /opt/PI/bin/pinetmgr
Copying file /opt/PI/bin/pisnapss
Copying file /opt/PI/bin/pipeschd
Copying file /opt/PI/bin/pirecalc
Copying file /opt/PI/adm/pipetest
Copying file /opt/PI/adm/piparams
Copying file /opt/PI/adm/pisetpass
Copying file /opt/PI/bin/pishutev
Copying file /opt/PI/bin/pisqlss
Copying file /opt/PI/bin/pitotal
Copying file /opt/PI/bin/piupdmgr
Copying file /opt/PI/adm/piversion
Copying file /opt/PI/adm/pisysdig
Copying file /opt/PI/adm/pisetevq
Copying file /opt/PI/adm/apisnap
Copying file /opt/PI/adm/pisnap.sh
Copying file /opt/PI/adm/ipisql
Copying file /opt/PI/interfaces/random/random
Copying file /opt/PI/interfaces/random/random.sh.new
PI Server Installation and Upgrade Guide Page 67
Chapter 7 - Upgrade the PI Server on UNIX
Copying file /opt/PI/interfaces/rmp_sk/rmp_sk
Copying file /opt/PI/interfaces/rmp_sk/rmp_sk.sh.new
New license file /opt/pitemp/distrib/3.4.370/pilicense.dat installed.
The cronpibackup.sh file has been moved to cronpibackup.sh.old.
Thu Nov 10 14:39:12 PST 2005
Updating shared library path environment.
Installing pinetmgr tables
Creating PI firewall table, status is [0] Success
Creating/updating PI timeout table, status is [0] Success
PI proxy table is now replaced by Trust-Relations - not creating...
Installing pibatch tables
Found existing batch unit table.
PI Batch installation/upgrade completed, status is [0] Success
Upgrading system state digital set...
System state set upgrade was successful.
System ID file exists:
Dumping file /opt/PI/dat/PISysID.dat
1. MajorVersion: 3
2. MinorVersion: 3
3. MajorBuild: 362
4. MinorBuild: 55
5. ServerID: fdb99902-9902-fdb9-9a90-080020fe4219
6. APIServerID: 87312
Installation/upgrade complete at Thu Nov 10 14:39:13 PST 2005
*******************************************************
PI Universal Data Server 3.4 Post Upgrade Instructions
*******************************************************
REVIEW LOG FILES
If there were any problems reported during the upgrade
proocess with the startup or shutdown of PI, please
check the log files in the log directory for any
documented errors.
POST UPGRADE TASKS
After upgrade installations there are a number of
post upgrade administrative tasks. Please follow
the post upgrade instructions in the Unix Upgrade
section of the PI 3 UDS manual, review any
published release notes and review the additional
information provided below.
NEW BACKUP SCHEME
The PI server backup scheme has changed. The PI server backup is now
implemented by a backup subsystem process as opposed to a shell script. The
pibackup.sh script remains as the command-line interface to the backup
subsystem, however the argument list has changed. The cronpibackup.sh file
formerly installed for automatic backups has been replaced by the file
pibackuptask.sh. Any currently scheduled cron job that utilitzes
cronpibackup.sh will cease to function after this upgrade. In order for
automatic backups to continue, a new automatic backup task must be scheduled
after the upgrade. Please review the backup section of the PI Server manual
for details concerning the changes to the pibackup.sh script and the procedure
for scheduling an automatic backup task.
CHANGES TO SITE SPECIFIC SCRIPTS
Many of the site specific scripts have not been modified although new versions
of these files have been copied during upgrade with the .new extension. These
new files should be compared to the existing scripts for suggested changes.
Page 68
7.3 - Post-Upgrade Checklist
To list out all files in the PI subdirectories with the
.new extension run:
ls -o `find /PIHOMEDIR -name *.new -print
where PIHOMEDIR is the location of the PI installation
( e.g. /opt/PI ). These files can then be diff'ed with the
original files and changes incorporated as needed.
START PI
PI is currently not running. To start PI, you should be logged
in as piadmin. Start PI using pistart.sh in the adm directory.
REMOVE TEMPORARY FILES
You may now remove the temporary PI installation directory,
it is no longer needed.
PI API
The PI API development kit for use on the PI 3 host is
no longer distributed and installed as part of the PI 3
installation / upgrade procedure.
****************************************************
PI Universal Data Server 3.4
Notes for Solaris Users
****************************************************
DEFINE SHARED LIBRARY PATH
You must define and export the shared library environment variable
for the piadmin account to point to the PI lib directory:
If using Korn Shell or Bourne Shell:
LD_LIBRARY_PATH=/opt/PI/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
If using C Shell:
setenv LD_LIBRARY_PATH /opt/PI/lib:$LD_LIBRARY_PATH
PI Server Installation and Upgrade Guide Page 69
Chapter 8. START AND STOP PI ON UNIX
Once the pi_install script has completed, log out of the root account and login as piadmin. All
PI Server administration should be performed while logged in from the piadmin account.
8.1 Start PI
Start PI by running the pistart.sh script from the /adm directory. This starts all PI Server
subsystems. Next, the script pisitestart.sh is run, which contains commands for all of the
interfaces and other site-specific applications.
The pistart.sh script can take a number of arguments:
./pistart.sh -nosite
starts the PI processes but does not run pisitestart.sh. Thus the site-specific applications and
interfaces will not be started.
./pistart.sh M
causes only the PI Network Manager and the PI Message Log processes to be started. This is
used when the message log is to be searched for diagnostics without starting the other
subsystems.
./pistart -stdout
causes the PI message log to not be started. All messages are instead directed to the standard
output. By default, this means that a separate ASCII log file is created in the PI/log directory
for each PI process.
Note: If you have a large point count, it may take a while for PI to complete its
initialization at startup time. During the initialization, the processes are all running,
but none of the utilities will work. When the utilities work, that is an indication that
initialization is complete. It can take as long as 30 minutes for initialization to
complete on a system of 50,000 points or more, depending on the hardware.
8.1.1 Verify Processes Are Running
Verify that the base PI Processes are running. The PI Server base processes are:
pinetmgr PI Network Manager
pilicmgr PI License Manager
PI Server Installation and Upgrade Guide Page 71
Chapter 8 - Start and Stop PI on UNIX
pinetmgr PI Network Manager
pimsgss PI Message Subsystem
piupdmgr PI Update Manager
pisnapss PI Snapshot Subsystem
piarchss PI Archive Subsystem
pibasess PI Base Subsystem
pishutev PI Shutdown Event Interface (runs only at PI System startup time)
pisqlss PI SQL Subsystem
The default simulator interfaces are:
random Random and Sinusoid Data Simulator
rmp_sk Ramp Soak Batch Data Simulator
8.1.2 Build Points and Configure Interfaces
You may configure interfaces and install points for them now or later. For more information,
see the PI System Management Tools (PI SMT) Web page on the OSIsoft support site:
http://techsupport.osisoft.com/ReleasedProducts/Utilities/PISMT/
8.1.3 To Stop PI
To stop PI, run the pistop.sh script from the /adm directory. This stops all of the PI processes
and then calls the site-specific script, pisitestop.sh, which contains the shutdown commands
for all of the interfaces and other site-specific applications.
The piverify.sh script in the /adm directory can be used to determine the running status of the
PI System. This utility prints the PI version and the running state of each PI process. It then
calls pisiteverify.sh to run site-specific verifications.
8.2 Setting Environment Variables
PI requires the shared library environment variable to be set on all UNIX platforms. These
variables provide the path to the PI/lib directory.
The name of the environment variable depends on the operating system. The configuration of
this environment variable depends on which shell you are using. Thus there are six cases.
In each case, you can enter the commands on the command line. However, it is strongly
recommended that these commands be placed in the shell startup file for the piadmin account
so that the commands are automatically configured every time you login. Remember to
logout and login after modifying the startup file so that the changes will be executed.
Page 72
8.2 - Setting Environment Variables
Case 1: On HP-UX systems using the Korn Shell, enter the commands in the .profile file as
follows:
SHLIB_PATH=<PItarget>/lib:$SHLIB_PATH
export SHLIB_PATH
Case 2: On HP-UX systems using the C Shell, enter the commands in the .cshrc file as
follows:
setenv SHLIB_PATH <PItarget>/lib:$SHLIB_PATH
Case 3: On Sun Solaris and Compaq Tru64 UNIX systems using the Korn Shell, enter the
commands in the .profile file as follows:
LD_LIBRARY_PATH=<PItarget>/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
Case 4: On Sun Solaris and Compaq Tru64 UNIX systems using the C Shell, enter the
commands in the .cshrc file as follows:
setenv LD_LIBRARY_PATH <PItarget>/lib:$LD_LIBRARY_PATH
Case 5: On IBM AIX systems using the Korn Shell, enter the commands in the .profile file as
follows:
LIBPATH=<PItarget>/lib:$LIBPATH
export LIBPATH
Case 6: On IBM AIX systems using the C Shell, enter the commands in the .cshrc file as
follows:
setenv LIBPATH <PItarget>/lib:$LIBPATH
PI Server Installation and Upgrade Guide Page 73
Chapter 9. REMOVE PI INSTALLATIONS ON UNIX
To fully remove PI from a UNIX host, perform the following tasks:
1. Stop PI and any dependent applications.
2. At this time you may wish to make a complete backup of PI. To do this, make a
backup copy of the entire PI directory, the /etc/piparams.default file, all of the
archive files (if they do not reside in the PI directory), and the Event Queue file (if it
does not reside in the PI directory).
3. Remove the entire PI installation directory.
4. Remove any installation source directories or temporary files.
5. Remove any archive files that were created in locations outside of the PI installation
directory.
6. Remove the Event Queue file if it was created in a location outside of the PI
installation directory.
7. Remove the piparams.default file from the /etc directory.
PI Server Installation and Upgrade Guide Page 75
Chapter 10. PI SERVER CLUSTER INSTALLATION
10.1 PI Server Clustering on the Windows Platform
This documentation details the installation of the PI Server software on a two-node, single-
quorum Microsoft Cluster. For more information about configuring and operating the
Microsoft Cluster Service (MSCS), please consult Microsoft’s TechNet
(http://technet.microsoft.com). At the time of this publication, the following links were valid
for installing the Cluster Service for Windows Server 2003 Enterprise Edition (or Datacenter
Edition) and Windows 2000 Advanced Server (or Datacenter Server), respectively:
http://www.microsoft.com/technet/prodtechnol/windowsserver2003/library/ClusteringQuickS
tart/dba487bf-61b9-45af-b927-e2333ec810b6.mspx
http://www.microsoft.com/technet/prodtechnol/windows2000serv/howto/clustep.mspx
Prior to installation of the PI Server software, it is assumed that MSCS has already been
installed properly, tested successfully, and is currently running.
10.2 Installation of PI
The PI Server must be installed on each node of the cluster. For each node, PI should be
installed on a shared disk, but not on the quorum disk, and have the same installation path.
For example, if installing the PI Server onto the drive F:\PI, then all other nodes must install
the PI Server using the same path. It is necessary to have the cluster service running during
installation of the PI Server, and it is also necessary that the node onto which the PI Server is
being installed has control of the shared disk. To ensure that this node will maintain control
of the shared disk in case a reboot is necessary during the installation, it is recommended that
the node that is not currently participating in the install be paused using the Cluster
Administrator. If the PI Server archives are to be placed in another directory or drive other
than the default, be sure that every cluster node has access to the archives.
Note: For clustered PI Servers, the services are always installed manually and
should never be configured to start automatically during reboot.
10.2.1 Preparation of Cluster Resources for PI
The PI System components need to be configured as resources of the cluster in order for it to
fail over. Use the PI Cluster Wizard (PIClusWizard.exe) in the PI/adm directory to create a
cluster group and cluster resources. The PI Cluster Wizard will only be installed on machines
that are running MSCS.
PI Server Installation and Upgrade Guide Page 77
Chapter 10 - PI Server Cluster Installation
10.2.2 PI Server Backups
The backup procedure for the PI Server in a cluster should follow the same guidelines that are
in Chapter 5: Backing up the PI Server of the PI Server System Management Guide. The
only additional requirement is that the daily backup task must be scheduled on each cluster
node—it will only succeed on the active node at the time the backup job executes.
10.2.3 Sample Installation and Configuration of PI
Using the Cluster administrator, pause the node that does not have control of the shared disk.
Run Setup on the node that has control of the shared disk. The PI Server installation begins
after Setup confirms that at least Microsoft® Data Access Components 2.7, Microsoft®
Page 78
10.2 - Installation of PI
Windows Installer 2.0, Microsoft® Windows Script 5.6, and Microsoft® .NET Framework
1.1 have already been installed.
The PI Server installation begins.
The user is prompted for the directory containing the license file, pilicense.dat.
PI Server Installation and Upgrade Guide Page 79
Chapter 10 - PI Server Cluster Installation
After license information is obtained, the user information is gathered.
Setup determines that MSCS is installed and asks about installing the PI Server on a cluster.
Page 80
10.2 - Installation of PI
Two questions are shown after selecting “Yes, setup the PI Server for clustering”. Setup asks
if this is the first node of the cluster and if the default interfaces are to be installed in the PI
directory on the shared disk or in the directory where the PI-SDK is installed. To allow for
rolling upgrades of the interface software, OSIsoft recommends installing the default
interfaces on a local disk containing the PI-SDK.
Setup asks where to install the PI Server. The chosen drive should be a separate physical
drive than the one containing the cluster quorum.
PI Server Installation and Upgrade Guide Page 81
Chapter 10 - PI Server Cluster Installation
The PI Server installation options are then presented. For clustered installations, services are
always installed as manual.
Setup asks for the location and size for the default archives. The Default Archive Size of 128
MB is almost certainly too small for most systems, but archives larger than 1 GB are
generally not recommended either on Windows computers that can address only 32 bits of
memory.
Page 82
10.2 - Installation of PI
The Advanced button on the Default Archive Information screen is used to select the Event
Queue settings. The default sizes are typically adequate for most systems.
The installation is ready to begin.
PI Server Installation and Upgrade Guide Page 83
Chapter 10 - PI Server Cluster Installation
Setup now copies all the files into the proper location.
Once the PI Server component is complete, the PI SDK installation runs.
Page 84
10.2 - Installation of PI
Setup installs the default PI interfaces after the PI SDK installation. If PI Server Applications
are part of the installation, setup installs the PI Server Applications after the default
interfaces.
After the PI Server Applications are installed, setup is complete for the first node on the
cluster.
It is necessary to install the PI Server on all other nodes of the cluster. In this sample, there
are only two nodes. Using the Cluster Administrator, resume the paused second node.
PI Server Installation and Upgrade Guide Page 85
Chapter 10 - PI Server Cluster Installation
Move the group with the shared disk to the second node.
Pause the first node of the cluster.
Page 86
10.2 - Installation of PI
Run Setup on the second node. The PI Server installation begins after Setup confirms that at
least Microsoft® Data Access Components 2.7, Microsoft® Windows Installer 2.0,
Microsoft® Windows Script 5.6, and Microsoft® .NET Framework 1.1 have already been
installed.
The PI Server installation begins.
PI Server Installation and Upgrade Guide Page 87
Chapter 10 - PI Server Cluster Installation
The user is prompted for the directory containing the license file, pilicense.dat.
Enter the same user information as the first node.
Page 88
10.2 - Installation of PI
Setup determines that MSCS is installed and asks about installing the PI Server on a cluster.
Two questions are shown after selecting “Yes, setup the PI Server for clustering.” Setup asks
if this is the first node of the cluster and if the default interfaces are to be installed in the PI
directory on the shared disk or in the directory where the PI-SDK is installed. This is not the
first node, so select “No, this is not the first node of the cluster.” Because the interfaces were
installed with the PI SDK on the first node, they must also be installed with the PI SDK on
the subsequent node.
PI Server Installation and Upgrade Guide Page 89
Chapter 10 - PI Server Cluster Installation
The location for the PI Server should also be the same as the first node.
The PI Server installation options are then presented. For clustered installations, services are
always installed as manual.
Page 90
10.2 - Installation of PI
The default archives should be installed in the same location with the same size as the first
node.
The Event Queue should also have the same location and size information as the first node.
PI Server Installation and Upgrade Guide Page 91
Chapter 10 - PI Server Cluster Installation
Setup is ready to begin the install.
Setup now copies all the files into the proper location.
Page 92
10.2 - Installation of PI
Once the PI Server component is complete, the PI SDK installation runs.
Setup installs the default PI interfaces after the PI SDK installation. If PI Server Applications
are part of the installation, setup installs the PI Server Applications after the default
interfaces.
After the PI Server Applications are installed, setup is complete on the second node.
PI Server Installation and Upgrade Guide Page 93
Chapter 10 - PI Server Cluster Installation
Page 94
10.3 - Sample Cluster Wizard Configuration
10.3 Sample Cluster Wizard Configuration
After completing installations on all nodes of the cluster, the PI Cluster Wizard can be used to
configure the Cluster Resources for the PI Server. The PI Cluster Wizard must be run on the
cluster node that has control of the shared disk where the PI Server was installed. If a
predefined IP Address and Network Name resource are to be used, those resources must also
be controlled by the cluster node. The PI Cluster Wizard will create a Cluster Group and the
necessary Cluster Resources for the PI Server.
The PI Cluster Wizard (PIClusWizard.exe) is located in the PI/adm directory. A shortcut to
the PI Cluster Wizard can also be found in the Start Menu under the PI System submenu.
The PI Cluster Wizard first asks for an IP Address that clients will use to communicate with
the PI Server. If you wish to use an existing IP Address Cluster Resource, check the “Use
existing IP Address” check box, and a drop-down list of all available IP Address Cluster
Resources will be displayed. The IP Address for the default Cluster Group (containing the
quorum disk) should not be used. An existing IP Address Resource will be moved to the
Cluster Group for the PI Server.
PI Server Installation and Upgrade Guide Page 95
Chapter 10 - PI Server Cluster Installation
Next, the Network Name associated with the IP Address is obtained along with the network
to be used. During the configuration of MSCS, each NIC card should have been named
appropriately according to its role. In the “Network to use” drop-down list, choose the name
of the NIC that will be used to communicate with clients.
Choose the name of the Cluster Group that will be created for the PI Server. The default
name is PI GROUP. If the name of the Cluster Group exists prior to running the PI Cluster
Wizard, then all resources will simply be created in that group. Also, from the drop-down list
Page 96
10.3 - Sample Cluster Wizard Configuration
of shared cluster disks, choose the disk drive where the PI Server was installed. The selected
disk will be moved to the Cluster Group for the PI Server.
Check any optional Cluster Resources to be included in the Cluster Group for the PI Server.
Click Finish to create the Cluster Group and Resources for the PI Server.
PI Server Installation and Upgrade Guide Page 97
Chapter 10 - PI Server Cluster Installation
In the Cluster Administrator, the PI Group should appear as partially online and should
contain all the configured resources for the PI Server.
Resume the paused first node.
Page 98
10.3 - Sample Cluster Wizard Configuration
Bring the complete PI Server online.
PI Server Installation and Upgrade Guide Page 99
Chapter 10 - PI Server Cluster Installation
10.4 PI Server Upgrades
The PI Server does not yet support a rolling upgrade, and thus, downtime must be scheduled
for the upgrade. Prior to upgrading, take the PI Server Generic Service resources offline and
pause inactive cluster nodes. Upgrade the PI Server on the node with ownership of the PI
Server Cluster Group. Once the upgrade is complete on the first node, move the PI Server
Cluster Group to the other node and upgrade the PI Server. Once the upgrade is complete on
all nodes, run the PI Cluster Wizard once to create cluster resources for any new required or
optional PI Server subsystems. Finally, resume all nodes and bring the PI Server Cluster
Group back online.
10.4.1 Sample Upgrade
Take all the PI Server Generic Service resources offline by taking the PINETMGR resource
offline (all other resources should have either a direct or indirect dependency on
PINETMGR).
Using the Cluster Administrator, pause the node that does not own the PI Server Cluster
Group.
Page 100
10.4 - PI Server Upgrades
Run Setup on the node that does own the PI Server Cluster Group. The PI Server upgrade
begins after Setup confirms that at least Microsoft® Data Access Components 2.7,
Microsoft® Windows Installer 2.0, Microsoft® Windows Script 5.6, and Microsoft® .NET
Framework 1.1 have already been installed.
The PI Server upgrade begins.
PI Server Installation and Upgrade Guide Page 101
Chapter 10 - PI Server Cluster Installation
The user is prompted for the directory containing the license file, pilicense.dat.
The user information from the installed PI Server is displayed.
Page 102
10.4 - PI Server Upgrades
Setup determines that MSCS is installed and asks about installing the PI Server on a cluster.
Two questions are shown after selecting “Yes, setup the PI Server for clustering”. Setup asks
if this is the first node of the cluster and if the default interfaces are to be installed in the PI
directory on the shared disk or in the directory where the PI-SDK is installed. To allow for
rolling upgrades of the interface software, OSIsoft recommends installing the default
interfaces on a local disk containing the PI-SDK.
PI Server Installation and Upgrade Guide Page 103
Chapter 10 - PI Server Cluster Installation
Setup shows the location of the installed PI Server.
The PI Server upgrade options are then displayed.
Page 104
10.4 - PI Server Upgrades
If you are upgrading from 3.4.364.32 or earlier, Setup warns you that the backup procedure
has changed.
After accepting the new backup scheme, Setup asks if you have a good current backup of the
PI Server.
PI Server Installation and Upgrade Guide Page 105
Chapter 10 - PI Server Cluster Installation
When you select, “Yes, I have a good current backup of the PI Server”, the Next button is
activated.
Setup now updates all the files.
Page 106
10.4 - PI Server Upgrades
Once the PI Server component is complete, the PI SDK installation runs.
Setup installs the default PI interfaces after the PI SDK installation. If PI Server Applications
are part of the installation, setup installs the PI Server Applications after the default
interfaces.
After the PI Server Applications are installed, the upgrade is complete for the first node in the
cluster.
PI Server Installation and Upgrade Guide Page 107
Chapter 10 - PI Server Cluster Installation
It is necessary to upgrade the PI Server on the other nodes of the cluster. In this sample, there
are only two nodes in the cluster. Using the Cluster Administrator, resume the paused node.
Move the PI Server Cluster Group to the second node.
Page 108
10.4 - PI Server Upgrades
Pause the first node.
Run Setup on the second node. The PI Server upgrade begins after Setup confirms that at
least Microsoft® Data Access Components 2.7, Microsoft® Windows Installer 2.0,
Microsoft® Windows Script 5.6, and Microsoft® .NET Framework 1.1 have already been
installed.
PI Server Installation and Upgrade Guide Page 109
Chapter 10 - PI Server Cluster Installation
The PI Server upgrade begins.
The user is prompted for the directory containing the license file, pilicense.dat.
Page 110
10.4 - PI Server Upgrades
The user information from the installed PI Server is displayed.
Setup determines that MSCS is installed and asks about installing the PI Server on a cluster.
PI Server Installation and Upgrade Guide Page 111
Chapter 10 - PI Server Cluster Installation
Two questions are shown after selecting “Yes, setup the PI Server for clustering”. Setup asks
if this is the first node of the cluster and if the default interfaces are to be installed in the PI
directory on the shared disk or in the directory where the PI-SDK is installed. This is not the
first node, so select “No, this is not the first node of the cluster”. Because the interfaces were
installed with the PI SDK on the first node, they must also be installed with the PI SDK on
the subsequent node.
Setup shows the location of the installed PI Server.
Page 112
10.4 - PI Server Upgrades
The PI Server upgrade options are then displayed.
If you are upgrading from 3.4.364.32 or earlier, Setup warns you that the backup procedure
has changed.
PI Server Installation and Upgrade Guide Page 113
Chapter 10 - PI Server Cluster Installation
After accepting the new backup scheme, Setup asks if you have a good current backup of the
PI Server.
When you select, “Yes, I have a good current backup of the PI Server”, the Next button is
activated.
Page 114
10.4 - PI Server Upgrades
Setup now updates all the files.
Once the PI Server component is complete, the PI SDK installation runs.
PI Server Installation and Upgrade Guide Page 115
Chapter 10 - PI Server Cluster Installation
Setup installs the default PI interfaces after the PI SDK installation. If PI Server Applications
are part of the installation, setup installs the PI Server Applications after the default
interfaces.
After the PI Server Applications are installed, the upgrade is complete on the second node.
Run the PI Cluster Wizard to create any new required or optional resources. For example,
version 3.4.370.52 introduced two new requirements: PI Backup Subsystem and PI License
Manager. Recall that the PI Cluster Wizard (PIClusWizard.exe) is located in the PI/adm
Page 116
10.4 - PI Server Upgrades
directory, and a shortcut to the PI Cluster Wizard can also be found in the Start Menu under
the PI System submenu.
Because the PI Server Cluster Group already exists, check “Use existing IP Address” and
select the correct IP Address from the drop-down list.
The network name should automatically be populated based on the selected IP Address.
Simply select the correct “Network to use” from the drop-down list.
PI Server Installation and Upgrade Guide Page 117
Chapter 10 - PI Server Cluster Installation
Enter the name of the existing PI Server Cluster Group and select the appropriate disk where
the PI Server is installed.
Check any additional optional resources that you want added to the existing PI Server Cluster
Group.
Page 118
10.4 - PI Server Upgrades
Click Finish to create the new required and optional Cluster Resources in the existing PI
Server Cluster Group. All new resources will initially be offline.
Using Cluster Administrator, resume the paused first node.
PI Server Installation and Upgrade Guide Page 119
Chapter 10 - PI Server Cluster Installation
Bring the complete PI Server back online.
Page 120
Chapter 11. PI SERVER SILENT INSTALLATION
11.1 Silent Installation and Upgrade on the Windows Platform
This section details the silent installation and upgrade of the PI Server on Microsoft®
Windows Platforms. Silent installs or upgrades require that the Microsoft® Data Access
Components (MDAC) be at version 2.7 or greater and Microsoft® Windows Installer be at
version 2.0 or greater. Silent installs can not be run from the original CD or self extracting zip
file because installation files within the distribution need to configured for silent installation
or upgrade.
11.1.1 Prerequisite Check
The PI Server distribution contains a prerequisite.ini file that can be used to determine if
Microsoft® Data Access Components (MDAC) is at version 2.7 or greater and if Microsoft®
Windows Installer is at version 2.0 or greater. By default, when the setup executable,
setup.exe is run, it looks for the setup.ini file in the same directory as the distribution kit and
copies it to the root directory of the destination machine as pisetup.ini. Setup then uses
pisetup.ini to control the installation. Optionally, Setup can use another file instead of the
setup.ini file when the –f flag is specified. This flag is used for prerequisite checks before
silent installations. In the following example below, setup.exe is run with the –f flag using
the prerequisite.ini file. The file m:\nt\prerequisite.ini is copied to the root directory of the
destination machine as pisetup.ini and is used in the installation.
m:\nt\setup.exe –f m:\nt\prequisite.ini
The letter of the drive containing the distribution is denoted as “m:” in this case.
A prerequisite.ini file is shown below.
[SETUPKIT]
; Setup wrapper master log file name
NAME = PIServer
DISPLAYNAME = PI Server
; With this set to TRUE no files are actually installed
CHECKFORINSTALLEDONLY = TRUE
; These suppress the setup wrapper dialogs, not those for the individual
setup modules
; Change these three to FALSE for non-silent (interactive) mode
SUPPRESSCOMPLETIONMESSAGE = TRUE
SUPPRESSDIALOGS = TRUE
SUPPRESSHEADERMESSAGE = TRUE
[NUMSETUPMODULES]
NUM = 2
PI Server Installation and Upgrade Guide Page 121
Chapter 11 - PI Server Silent Installation
[SETUPMODULES]
1 = MDACSetup
2 = WindowsInstallerSetup
[DISPLAYNAME]
1 = Microsoft Data Access (MDAC)
2 = Microsoft Windows Installer
[UNSUPPORTED_OPERATING_SYSTEMS]
; Defined Operating Systems ( Win95, Win98, WinME, WinNT, Win2K, WinXP,
WinNET)
; A 0 entry denotes that the setup can not run on the given operating
systems.
; An entry that corresponds to an entry in the [SETUPMODULES] section
denotes that
; the particular setup module will be skipped on the given operating
system
0 = Win95, Win98, WinME, WinNT
When the setup is run using the prerequisite.ini file, the Microsoft® Data Access
Components (MDAC) and Microsoft® Windows Installer are not installed. It is the user’s
responsibility to install Microsoft® Data Access Components (MDAC) and Microsoft®
Windows Installer before the PI Server installation can run silently. The entry that triggers a
check for installation is the CHECKFORINSTALLEDONLY entry in the [SETUPKIT]
section. Setting the value of CHECKFORINSTALLEDONLY to true triggers the prerequisite
installation. The prerequisite check installation can be run in silent mode or verbose mode. In
silent mode, three parameters in the [SETUPKIT] section of the prerequisite.ini file are set to
true. These parameters are
• suppresscompletionmessage = true
• suppressdialogs = true
• suppressheadermessage = true
When running in silent mode, setup.exe will return the number of setup modules that have not
been installed. For example, if both MDAC and Windows Installer are already installed, the
return is 0. If either MDAC or Windows Installer is not already installed, the return is 1. If
both are not installed, setup.exe returns 2. In addition, setup.exe outputs messages to the setup
master log describing which setup modules are not installed. If the prerequisite check
installation is run in verbose mode, three parameters in the [SETUPKIT] section of the
prerequisite.ini file are set to false. These parameters are
• suppresscompletionmessage = false
• suppressdialogs = false
• suppressheadermessage = false
In this scenario, the welcome dialog will list the setup modules that are not installed. In
addition, setup.exe outputs messages to the setup master log describing which setup modules
are not installed.
Page 122
11.2 - Silent New Installation
11.2 Silent New Installation
The silent.ini file included in the PI Server distribution is used for silent installations. This
file needs to be configured to satisfy the specifications of the destination machine. The
silent.ini file is used in the overall execution of the installation. It executes the PI Server
installation as well as supporting software that is included in the PI Server distribution. By
default, when the setup executable, setup.exe is run, it looks for the setup.ini file in the same
directory as the distribution kit and copies it to the root directory of the destination machine
as pisetup.ini. Setup then uses pisetup.ini to control the installation. Optionally, Setup can use
another file instead of the setup.ini file when the –f flag is specified. This flag is used for
silent installations. In the following example below, setup.exe is run with the –f flag using
the silent.ini file. The file m:\nt\silent.ini is copied to the root directory of the destination
machine as pisetup.ini and is used in the installation.
m:\nt\setup.exe –f m:\nt\silent.ini
The letter of the drive containing the distribution is denoted as “m:” in this case.
A silent.ini file is shown below. This file may look different depending on your license
agreement.
[SETUPKIT]
; Setup wrapper master log file name
NAME = PIServer
DISPLAYNAME = PI Server
; These suppress the setup wrapper dialogs, not those for the individual
setup modules
SUPPRESSCOMPLETIONMESSAGE = TRUE
SUPPRESSDIALOGS = TRUE
SUPPRESSHEADERMESSAGE = TRUE
[NUMSETUPMODULES]
NUM = 30
[SETUPMODULES]
1 = MDACSetup
2 = WindowsInstallerSetup
3 = ScriptingRuntimeSetup
4 = dotnetSetup
5 = PIServer.msi
6 = pisdk.msi
7 = Random.msi
8 = Random_ICU.msi
9 = Rmp_sk.msi
10 = Rampsoak_ICU.msi
11 = PingBasicSetup.msi
12 = PIPing_ICU.msi
13 = SNMPBasicSetup.msi
14 = PISNMP_ICU.msi
15 = PIPerfmon_basic.msi
16 = PIPerfmon_ICU.msi
17 = PIIntStatusSetup.msi
18 = PIIntStatus_ICU.msi
19 = PIICUSetup.msi
PI Server Installation and Upgrade Guide Page 123
Chapter 11 - PI Server Silent Installation
20 = PIGenericNamesSetup.msi
21 = PISptSetup.msi
22 = pialarm.msi
23 = pibatch.msi
24 = pipeschd.msi
25 = pirecalc.msi
26 = pitotal.msi
27 = pibagen.msi
28 = piaf.msi
29 = PIAPSSetup.msi
30 = PIAPSRegisterInterfaceSetup.msi
[COMMANDLINE]
3 =:a /r:ns
4 =:a /c:"install /l /q"
5 = REBOOT=Suppress ALLUSERS=1 /qn SET_EXTERNAL_DIRS=1
INSTALLDIR="C:\PI\" ARCHIVEDATDIR="C:\PI\dat\"
EVENTQUEUEDIR="C:\PI\dat\" PIPCHOME="C:\Program Files\PIPC\"
ARCHIVESIZE=128 EVENTQUEUEPAGESIZE=1024 EVENTQUEUESIZE=64 SERVICESTART=1
DEFAULTPTS=1 USERNUMBER=12345
6 = REBOOT=Suppress ALLUSERS=1 /qn SUPPRESS_PINS=1 PI_SERVER=localhost
PI_ALIAS=localhost PI_TYPE=3 PI_PORT=5450 PI_USER=piadmin
7 = REBOOT=Suppress ALLUSERS=1 /qn
8 = REBOOT=Suppress ALLUSERS=1 /qn
9 = REBOOT=Suppress ALLUSERS=1 /qn
10 = REBOOT=Suppress ALLUSERS=1 /qn
11 = REBOOT=Suppress ALLUSERS=1 /qn
12 = REBOOT=Suppress ALLUSERS=1 /qn
13 = REBOOT=Suppress ALLUSERS=1 /qn
14 = REBOOT=Suppress ALLUSERS=1 /qn
15 = REBOOT=Suppress ALLUSERS=1 /qn
16 = REBOOT=Suppress ALLUSERS=1 /qn
17 = REBOOT=Suppress ALLUSERS=1 /qn
18 = REBOOT=Suppress ALLUSERS=1 /qn
19 = REBOOT=Suppress ALLUSERS=1 /qn
20 = REBOOT=Suppress ALLUSERS=1 /qn
21 = REBOOT=Suppress ALLUSERS=1 /qn
22 = REBOOT=Suppress ALLUSERS=1 /qn
23 = REBOOT=Suppress ALLUSERS=1 /qn
24 = REBOOT=Suppress ALLUSERS=1 /qn
25 = REBOOT=Suppress ALLUSERS=1 /qn
26 = REBOOT=Suppress ALLUSERS=1 /qn
27 = REBOOT=Suppress ALLUSERS=1 /qn
28 = REBOOT=Suppress ALLUSERS=1 /qn ADDLOCAL=ALL
29 = REBOOT=Suppress ALLUSERS=1 /qn
30 = REBOOT=Suppress ALLUSERS=1 /qn
[DISPLAYNAME]
1 = Microsoft Data Access (MDAC)
2 = Microsoft Windows Installer
3 = Microsoft Windows Script
4 = Microsoft .NET Framework 1.1
[UNSUPPORTED_OPERATING_SYSTEMS]
Page 124
11.2 - Silent New Installation
; Defined Operating Systems ( Win95, Win98, WinME, WinNT, Win2K, WinXP,
WinNET)
; A 0 entry denotes that the setup can not run on the given operating
systems.
; An entry that corresponds to an entry in the [SETUPMODULES] section
denotes that
; the particular setup module will be skipped on the given operating
system
0 = Win95, Win98, WinME, WinNT
[MANDATORYSETUPMODULECHECK]
1 = TRUE
2 = TRUE
In order to personalize the installation the silent.ini file must be configured. The
[COMMANDLINE] section entry 5 must be changed provide the correct information for the
silent installation. The defaults for the installation are supplied in the silent.ini file.
5 = REBOOT=Suppress ALLUSERS=1 /qn SET_EXTERNAL_DIRS=1
INSTALLDIR="C:\PI\" ARCHIVEDATDIR="C:\PI\dat\"
EVENTQUEUEDIR="C:\PI\dat\" PIPCHOME="C:\Program Files\PIPC\"
ARCHIVESIZE=128 EVENTQUEUEPAGESIZE=1024 EVENTQUEUESIZE=64 SERVICESTART=1
DEFAULTPTS=1 USERNUMBER=12345
The following table describes the parameters that can be changed. All paths need to be within
double quotes.
Parameter Description
INSTALLDIR Installation path for the PI Server
ARCHIVEDATDIR Path to install the default archives
ARCHIVESIZE Size in megabytes for each of the 3 default archives
EVENTQUEUEDIR Path to install the Event Queue
EVENTQUEUESIZE Size of the Event Queue in megabytes
EVENTQUEUEPAGESIZE Size of a single event sent to the archive
PIPCHOME Location to install the PI SDK
SERVICESTART This parameter is set to 1 if you want the PI Server to start when
the machine is started. Set this parameter to “” if you want the
service start to be manual.
DEFAULTPTS This parameter is set to 1 if you want to install default points. Set
this parameter to “” if you do not want to install default points.
USERNUMBER The PI Server system number
PI Server Installation and Upgrade Guide Page 125
Chapter 11 - PI Server Silent Installation
11.3 Silent Upgrade
A silent upgrade requires that the PI Server be shut down before upgrading the PI Server. The
silent.ini file included in the PI Server distribution is used for silent upgrades. It executes the
PI Server upgrade as well as supporting software that is included in the PI Server distribution.
By default, when the setup executable, setup.exe is run, it looks for the setup.ini file in the
same directory as the distribution kit and copies it to the root directory of the destination
machine as pisetup.ini. Setup then uses pisetup.ini to control the upgrade. For a silent
upgrade, Setup needs to use another file instead of the setup.ini file. This is accomplished by
specifying the –f flag. In the following example below, setup.exe is run with the –f flag using
the silent.ini file. The file m:\nt\silent.ini is copied to the root directory of the destination
machine as pisetup.ini and is used in the upgrade.
m:\nt\setup.exe –f m:\nt\silent.ini
The letter of the drive containing the distribution is denoted as “m:” in this case.
A silent.ini file is shown below. This file may look different depending on your license
agreement.
[SETUPKIT]
; Setup wrapper master log file name
NAME = PIServer
DISPLAYNAME = PI Server
; These suppress the setup wrapper dialogs, not those for the individual
setup modules
SUPPRESSCOMPLETIONMESSAGE = TRUE
SUPPRESSDIALOGS = TRUE
SUPPRESSHEADERMESSAGE = TRUE
[NUMSETUPMODULES]
NUM = 30
[SETUPMODULES]
1 = MDACSetup
2 = WindowsInstallerSetup
3 = ScriptingRuntimeSetup
4 = dotnetSetup
5 = PIServer.msi
6 = pisdk.msi
7 = Random.msi
8 = Random_ICU.msi
9 = Rmp_sk.msi
10 = Rampsoak_ICU.msi
11 = PingBasicSetup.msi
12 = PIPing_ICU.msi
13 = SNMPBasicSetup.msi
14 = PISNMP_ICU.msi
15 = PIPerfmon_basic.msi
16 = PIPerfmon_ICU.msi
17 = PIIntStatusSetup.msi
18 = PIIntStatus_ICU.msi
19 = PIICUSetup.msi
20 = PIGenericNamesSetup.msi
Page 126
11.3 - Silent Upgrade
21 = PISptSetup.msi
22 = pialarm.msi
23 = pibatch.msi
24 = pipeschd.msi
25 = pirecalc.msi
26 = pitotal.msi
27 = pibagen.msi
28 = piaf.msi
29 = PIAPSSetup.msi
30 = PIAPSRegisterInterfaceSetup.msi
[COMMANDLINE]
3 =:a /r:ns
4 =:a /c:"install /l /q"
5 = REBOOT=Suppress ALLUSERS=1 /qn SET_EXTERNAL_DIRS=1
INSTALLDIR="C:\PI\" ARCHIVEDATDIR="C:\PI\dat\"
EVENTQUEUEDIR="C:\PI\dat\" PIPCHOME="C:\Program Files\PIPC\"
ARCHIVESIZE=128 EVENTQUEUEPAGESIZE=1024 EVENTQUEUESIZE=64 SERVICESTART=1
DEFAULTPTS=1 USERNUMBER=12345
6 = REBOOT=Suppress ALLUSERS=1 /qn SUPPRESS_PINS=1 PI_SERVER=localhost
PI_ALIAS=localhost PI_TYPE=3 PI_PORT=5450 PI_USER=piadmin
7 = REBOOT=Suppress ALLUSERS=1 /qn
8 = REBOOT=Suppress ALLUSERS=1 /qn
9 = REBOOT=Suppress ALLUSERS=1 /qn
10 = REBOOT=Suppress ALLUSERS=1 /qn
11 = REBOOT=Suppress ALLUSERS=1 /qn
12 = REBOOT=Suppress ALLUSERS=1 /qn
13 = REBOOT=Suppress ALLUSERS=1 /qn
14 = REBOOT=Suppress ALLUSERS=1 /qn
15 = REBOOT=Suppress ALLUSERS=1 /qn
16 = REBOOT=Suppress ALLUSERS=1 /qn
17 = REBOOT=Suppress ALLUSERS=1 /qn
18 = REBOOT=Suppress ALLUSERS=1 /qn
19 = REBOOT=Suppress ALLUSERS=1 /qn
20 = REBOOT=Suppress ALLUSERS=1 /qn
21 = REBOOT=Suppress ALLUSERS=1 /qn
22 = REBOOT=Suppress ALLUSERS=1 /qn
23 = REBOOT=Suppress ALLUSERS=1 /qn
24 = REBOOT=Suppress ALLUSERS=1 /qn
25 = REBOOT=Suppress ALLUSERS=1 /qn
26 = REBOOT=Suppress ALLUSERS=1 /qn
27 = REBOOT=Suppress ALLUSERS=1 /qn
28 = REBOOT=Suppress ALLUSERS=1 /qn ADDLOCAL=ALL
29 = REBOOT=Suppress ALLUSERS=1 /qn
30 = REBOOT=Suppress ALLUSERS=1 /qn
[DISPLAYNAME]
1 = Microsoft Data Access (MDAC)
2 = Microsoft Windows Installer
3 = Microsoft Windows Script
4 = Microsoft .NET Framework 1.1
[UNSUPPORTED_OPERATING_SYSTEMS]
PI Server Installation and Upgrade Guide Page 127
Chapter 11 - PI Server Silent Installation
; Defined Operating Systems ( Win95, Win98, WinME, WinNT, Win2K, WinXP,
WinNET)
; A 0 entry denotes that the setup can not run on the given operating
systems.
; An entry that corresponds to an entry in the [SETUPMODULES] section
denotes that
; the particular setup module will be skipped on the given operating
system
0 = Win95, Win98, WinME, WinNT
[MANDATORYSETUPMODULECHECK]
1 = TRUE
2 = TRUE
A silent upgrade of the PI Server requires that the silent.ini file be configured. The
[COMMANDLINE] section entry 5 must be edited as follows.
5 = REBOOT=Suppress ALLUSERS=1 /qn
Since the path and size the PI Server features are already exist, an upgrade does not need to
specify these parameters.
Page 128
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
PI Server Installation and Upgrade Guide Page 129
Technical Support and Resources
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a
Page 130
INDEX OF TOPICS
Administrator Account for interfaces, vi
UNIX, 47 Environment variable, 9
Windows, 9 Event Queue, 5
Archive Gunzip, 49, 51
Default on UNIX, 6 HP-UX, 2
Default on Windows, 4 Environment variable, 72
Size, 4 Installation disk space
Backup required, 5
Before upgrade, 24 Mount command, 49
cluster, 78 Piadmin, 71
Compaq Tru64 UNIX Root, 71
Environment variable, 72 System memory requirements,
7
Installation disk space
required, 5 IBM AIX, 3
Mount command, 50 Installation disk space
required, 5
Piadmin, 71
Mount command, 50
Root, 71
Piadmin, 71
System memory requirements,
7 Root, 71
System sizing, 8 system memory requirements,
7
Compressed tar file, 51
Installation
Computer platform
Cluster, 77
Information, 130
Directory, UNIX, 48
Database
HP-UX Example, 50
Sizing, 4
IBM AIX Example, 50
Daylight Savings Time, 46
Instructions
Default
UNIX, 51
Points, 9
Overview
Disk space
UNIX, 43
Requirements
Windows, 11
On UNIX, 5
Removing a PI System
On Windows, 3
UNIX, 75
Distribution package, 1
Windows, 41
Documentation
Setup Log, 12, 13, 24
conventions, v
Setup program
PI Server Installation and Upgrade Guide Page 131
Index of Topics
Windows, 12, 13, 24 Pentium, 2, 125
Sun Solaris Example, 49 PI Processes
UNIX installation script, 47 UNIX, 71
Intel, 2 Windows, 37
Interface PI Server
Configure, 38, 72 contents of CD-ROM, 1
As Windows Services, 40 distribution package, 1, 2
Random and ramp soak, 40 Installation
UNIINT-based, 40 UNIX, 43
Interfaces Windows, 11
downloading documentation Software download, 2
for, vi Windows
Korn Shell Setting the host time, 9
Compaq Tru64 UNIX, 73 PI Server Applications
HP-UX, 73 Software download, 2
Sun Solaris, 73 PI System
Loading the PI Source Administrator
From a compressed TAR file, Account
51
UNIX, 47
From CD-ROM
Windows, 9
UNIX, 48
Cluster Installation, 77
Windows, 12
Databases, 6
Login
Memory Requirements, 7
UNIX accounts, 47
Setup kit, 10
Man command, 49
Silent Installation, 121
Management
Sizing Guide, 3
Sizing Guide, 3
Piadmin
Memory Requirements, 7
Account, 47
Message Log, 5, 6
Piarcreate, 4
Microsoft Cluster, 77
PIClusWizard.exe, 77, 95, 116
Mount command, 49
pidainst.log, 13
Compaq Tru64 UNIX, 50
Pidainst.log, 12, 24
HP-UX, 49
pigrp, 47
IBM AIX, 50
Pisrvstart.bat script
Sun Solaris, 49
Windows, 23, 37
Network
pisrvstop.bat script
Configuration
Windows, 38
UNIX, 46
Pisrvstop.bat script
Windows, 3
Windows, 23
OSIsoft
Pistart.sh script
Account, 47
UNIX, 61, 71
FTP site, 49, 51
Page 132
Index of Topics
Pistop.sh script Script
UNIX, 61, 72 UNIX Installation, 47
Piverify.sh script UNIX startup, 71
UNIX, 61, 72 Servers
Platforms, 2 Platforms for PI Server, 2
Point Shared library environment
Build, 38, 72 variable
Default, 9 Compaq Tru64 UNIX, 72
Post-installation Checklist HP-UX, 72
UNIX, 53 Sun Solaris, 72
Windows, 14 Shell, 72
Post-upgrade Checklist Compaq Tru64 UNIX, 73
UNIX, 63 HP-UX, 73
Windows, 26 Sun Solaris, 73
Power PC, 3 Simulator interfaces, 9
Pre-installation Checklist Site-specific services
UNIX, 51 Start, 39
Windows, 11 Size
Pre-upgrade Checklist Archive, 4, 6
UNIX, 61 Sizing Guide, 3
Windows, 23 SMT
Privileges, 47 about, vi
Random Simulator, 40 Snapshot
Remote access for troubleshooting Event queue overflow file, 5, 6
UNIX, 47 Software distribution package, 1, 2
Windows, 14 Stop
Removing PI Installations PI
UNIX, 75 As NT services, 38
Windows, 41 On UNIX, 72
Root, 47 When running Windows
interactively, 40
Running PI
Sun Solaris
As Windows Services, 38
Installation disk space
Interactively on Windows, 39
required, 5
UNIX, 71
Mount command, 49
Windows, 37
Ppiadmin, 71
Sample Installation
Root, 71
UNIX, 54
Sparc, 2
Windows, 18
System memory requirements,
Sample Upgrade 7
UNIX, 64 System sizing, 8
Windows, 27 Superuser, 47
PI Server Installation and Upgrade Guide Page 133
Index of Topics
System UniInt
Number, 13, 25 downloading documentation
Requirements for, vi
UNIX, 7 Universal Interface
System Management Tools, vi downloading documentation
for, vi
System sizing
UNIX
Compaq Tru64 UNIX, 8
Installation and Upgrade, 43
Guide to, 2
Login accounts, 47
Sun Solaris, 8
Upgrade
Windows, 7
Cluster, 100
Tar command, 49, 51
Earlier versions, 23, 61
Tar file, 51
Overview
Technical Support, 129
UNIX, 62
Time
Windows, 11
Daylight Savings Time, 9, 46
Windows Services
Setting, 9
Configuring, 40
UNIX, 46
Running PI, 38
TZ environment variable, 9
Zone, 9, 46
Page 134
Introduction to PI Server
System Management
PI3 Server
Version 3.4.370
© 2005-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
This guide provides a starting place for new PI System Managers on Windows-based PI
Systems. This guide:
Introduces the PI System, PI Server and Interface Nodes.
Explains PI system components, architecture, data flow, utilities and tools.
Provides instruction for managing points, archives, backups, interfaces, security and
trusts, and performance.
Includes a glossary and resource guide.
This guide does not cover systems with PI Servers on VMS. For information on managing an
OpenVMS-based PI Server System, see the VMS PI Server page on the Technical Support
Web site (http://techsupport.osisoft.com/).
Introduction to PI Server
System Management Page iii
Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set includes seven user guides, described below.
Tip: Updated user guides, which provide the most up-to-date information, are
available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security and
trusts, and performance. It includes a glossary and resource guide.
PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data Archive,
monitoring system health, managing backups, interfaces, security, and
moving and merging servers. Includes comprehensive instructions for using
command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth
troubleshooting and repair information.
PI Server Reference A comprehensive reference guide for the system administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).
Auditing the PI Server An administration guide that explains the Audit Database, which provides a
secure audit trail of changes to PI System configuration, security settings,
and Archive Data. It includes administration procedures to enable auditing,
to set subsystem auditing mode, to create and archive database files, and
to export audit records.
PI Server Applications A guide to key add-on PI Server Applications: Performance Equations (PE),
User Guide Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical
Quality Control). Includes a reference guide for Performance Equations, and
Steam calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
Page iv
Preface - Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI Client Tools Use the client tool, PI ProcessBook, to verify that all
PI System Elements data has been recovered.
PI Server Subsystems All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text Files, Directories, Paths The backup script is located in the \PI\adm directory.
Emphasis Archive files can be either fixed or dynamic. The
New Terms archive receiving current data is called the Primary
Archive.
Fields
See Section 4.2, Create a New Primary Archive.
References to a chapter or section
Bold Italic text References to a publication See the PI Server Reference Guide.
Bold text System and Application The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
Procedures and Key Commands On the Tools menu, click Advanced Options.
Press CTRL+ALT+DELETE to reboot
Interface components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: Code examples use the piartool -ss command. For example:
"Consolas" Commands to be typed on the
font command line (optionally with
arguments or switches)
System input or output such as
excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
Introduction to PI Server
System Management Page v
Preface - Using this Guide
Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. Introduction to PI System Management ...................................................................1
Chapter 2. System Manager Checklist ........................................................................................3
Chapter 3. PI System Administration Tools................................................................................5
Chapter 4. Introduction to the PI System ....................................................................................9
Chapter 5. Managing PI Points ...................................................................................................17
Chapter 6. Managing Archives ...................................................................................................25
Chapter 7. Managing Backups ...................................................................................................35
Chapter 8. Managing Interfaces .................................................................................................41
Chapter 9. Managing PI Security................................................................................................47
Chapter 10. Monitoring PI System Performance ........................................................................57
Chapter 11. Managing Buffering ..................................................................................................63
Chapter 12. Managing Data Source Equipment..........................................................................71
Chapter 13. Where to Go to Get More Help.................................................................................73
Chapter 14. Glossary.....................................................................................................................75
Introduction to PI Server
System Management Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Tables and Figures .........................................................................................................................xiii
Chapter 1. Introduction to PI System Management ...................................................................1
1.1 About this Book.................................................................................................................1
Chapter 2. System Manager Checklist ........................................................................................3
2.1 System Manager Checklist ...............................................................................................3
Chapter 3. PI System Administration Tools................................................................................5
3.1 Getting and Using the Tools You Need...........................................................................5
3.1.1 The PI System Management Tools (SMT) .............................................................5
3.1.2 The PI Interface Configuration Utility (ICU) ............................................................6
3.1.3 Using Other PI Tools ..............................................................................................7
3.1.4 Using the Windows Command Interpreter .............................................................7
Chapter 4. Introduction to the PI System ....................................................................................9
4.1 About PI Interface Nodes................................................................................................10
4.2 About the PI Server .........................................................................................................11
4.2.1 What's in the PI Directory? ...................................................................................11
4.2.2 File System Dos and Don'ts .................................................................................12
4.2.3 Checking whether the PI Server is Running.........................................................12
4.2.4 Data Flow in the PI Server....................................................................................13
4.2.5 What is the Snapshot? .........................................................................................13
4.2.6 What are Out of Order Events?............................................................................14
4.2.7 What is Compression Testing? ............................................................................14
4.2.8 What is the Event Queue?....................................................................................15
4.3 About Client Applications...............................................................................................16
Chapter 5. Managing PI Points ...................................................................................................17
Introduction to PI Server
System Management Page ix
Table of Contents
5.1 About Points ....................................................................................................................17
5.2 About Point Attributes ....................................................................................................17
5.2.1 Point Name: Tag Attribute ....................................................................................18
5.2.2 Class of Point: PtClass Attribute ..........................................................................18
5.2.3 Data Type of Point: PointType Attribute ...............................................................19
5.2.4 Data Source: PointSource Attribute .....................................................................19
5.2.5 Interface ID Number: Location1 Attribute .............................................................20
5.2.6 Setting Scan Class: Location4 Attribute ...............................................................20
5.2.7 Exception Specifications.......................................................................................20
5.2.8 Compression Specifications .................................................................................21
5.2.9 Point Value Range: Zero, Span and Typical Value..............................................22
5.2.10 Configuring Shutdown Events: Shutdown ............................................................22
5.2.11 Point Security: PtOwner, PtGroup, PtAccess, DataOwner, DataGroup,
DataAccess ..........................................................................................................22
5.3 Creating New Points........................................................................................................23
5.4 Finding Malfunctioning Points .......................................................................................23
5.5 Decommissioning Points................................................................................................24
5.6 Deleting Points ................................................................................................................24
Chapter 6. Managing Archives ...................................................................................................25
6.1 About Archives ................................................................................................................25
6.2 Finding the Archive Files................................................................................................26
6.3 Making Sure PI Doesn’t Overwrite Your Archives .......................................................27
6.4 Creating an Archive.........................................................................................................27
6.5 Registering an Archive ...................................................................................................28
6.6 Unregistering an Archive................................................................................................29
6.7 Moving an Archive...........................................................................................................30
6.8 Fixing Archive Gaps........................................................................................................31
6.9 Automating Archive File Creation .................................................................................32
Chapter 7. Managing Backups ...................................................................................................35
Page x
Table of Contents
7.1 About PI Server Backups................................................................................................35
7.2 Choosing a Backup Strategy..........................................................................................35
7.3 Checking Your Backup Files ..........................................................................................36
7.4 Checking Whether Backups are Scheduled .................................................................36
7.5 Checking the Message Logs ..........................................................................................37
7.6 Setting up Automatic Backups ......................................................................................38
7.7 Site-Specific Backup Tasks............................................................................................39
Chapter 8. Managing Interfaces .................................................................................................41
8.1 About PI Interfaces..........................................................................................................41
8.1.1 What's a Point Source? ........................................................................................41
8.1.2 What's an Interface ID Number? ..........................................................................42
8.1.3 What's a Scan Class? ..........................................................................................42
8.2 Configuring Interfaces ....................................................................................................43
8.3 Starting and Stopping Interfaces...................................................................................44
8.4 Monitoring Interface Performance.................................................................................44
8.4.1 Checking IORates and Performance Points.........................................................44
8.4.2 Checking Log Files ...............................................................................................44
8.5 Configuring Interfaces for Buffering .............................................................................45
8.6 Where to Go for More Information on Interfaces .........................................................45
Chapter 9. Managing PI Security................................................................................................47
9.1 About PI Security.............................................................................................................47
9.2 Managing Users and Groups..........................................................................................47
9.2.1 About Users and Groups ......................................................................................48
9.2.2 What are Access Permissions?............................................................................48
9.2.3 What are PI Access Categories? .........................................................................48
9.2.4 What are the piadmin and pidemo User Accounts?.............................................49
9.2.5 Setting up Groups to Manage Resource Access .................................................50
9.2.6 Simple Case Example for Managing Groups .......................................................51
9.2.7 Example for Managing Multiple Groups ...............................................................51
9.2.8 Adding, Editing and Deleting Users and Groups..................................................51
9.3 Managing PI Trusts .........................................................................................................52
9.3.1 About Trusts .........................................................................................................52
9.3.2 Managing Trusts with SMT...................................................................................53
9.4 Managing PI Database Security .....................................................................................54
9.4.1 About Databases ..................................................................................................54
9.4.2 Managing Databases with SMT ...........................................................................55
Introduction to PI Server
System Management Page xi
Table of Contents
Chapter 10. Monitoring PI System Performance ........................................................................57
10.1 About PI System Performance Monitoring ...................................................................57
10.2 Which Performance Counters to Monitor .....................................................................58
10.3 Building Performance Monitor Points...........................................................................59
10.4 Trending Performance Points ........................................................................................59
10.5 Performance Monitoring Kit (PI 3.4 and Later) .............................................................60
10.6 Configuring the PIPerfmon Interface.............................................................................60
Chapter 11. Managing Buffering ..................................................................................................63
11.1 About Buffering ...............................................................................................................63
11.2 Checking whether the Buffering Service Is Running ..................................................64
11.3 Testing the Buffering Service.........................................................................................65
11.3.1 When should I test the buffering service? ............................................................66
11.3.2 How do I test the buffering service? .....................................................................66
11.4 If the Buffering Service Isn't Working ...........................................................................66
11.4.1 How to Check the Login Information for Buffering ...............................................66
11.4.2 How to Check the pipc.log File .............................................................................68
11.5 Starting the Buffering Service........................................................................................68
Chapter 12. Managing Data Source Equipment..........................................................................71
12.1 About Data Sources ........................................................................................................71
12.2 Adding New Equipment ..................................................................................................71
12.3 Removing Obsolete Equipment .....................................................................................72
12.4 Replacing Equipment......................................................................................................72
Chapter 13. Where to Go to Get More Help.................................................................................73
13.1 Training.............................................................................................................................73
13.2 Technical Support Web Site ...........................................................................................73
13.3 Developers Network ........................................................................................................73
Chapter 14. Glossary.....................................................................................................................75
Technical Support and Resources.................................................................................................97
Index of Topics.................................................................................................................................99
Page xii
TABLES AND FIGURES
Tables
PI System Health Checklist........................................................................................................3
Overview of PI System Data Flow..............................................................................................9
Figures
Data Flow with Buffering ..........................................................................................................63
Introduction to PI Server
System Management Page xiii
Chapter 1. INTRODUCTION TO PI SYSTEM MANAGEMENT
1.1 About this Book
This guide provides a starting place for new PI System Managers on Windows-based PI
Systems. It introduces the PI System, PI Server and Interface Nodes, and gives you the PI
System Management basics, including system backups, archive management, and security.
This guide contains the following topics:
System Manager Checklist on page 3
PI System Administration Tools on page 5
Introduction to the PI System on page 9
Managing PI Points on page 17
Managing Archives on page 25
Managing Backups on page 35
Managing Interfaces on page 41
Managing PI Security on page 47
Monitoring PI System Performance on page 57
Managing Buffering on page 63
Where to Go to Get More Help on page 73
This guide does not cover systems with PI Servers on VMS. If you need information on
managing an OpenVMS-based PI Server System, a good starting point is the VMS PI Server
page on the Technical Support Web site (http://techsupport.osisoft.com/).
Introduction to PI Server
System Management Page 1
Chapter 2. SYSTEM MANAGER CHECKLIST
2.1 System Manager Checklist
This section provides a quick-reference table for checks that you need to perform regularly, to
make sure that your PI System is working properly. This is sometimes called a “Daily Health
Check” because we recommend you perform each of these checks each day.
The checklist is organized into functional areas, with a list of things to check in each area.
This table does not provide detailed instructions for checking each item. To learn more about
how to check a particular item, go to the section listed in the column on the right. You
perform most of the checks using the PI System Management Tools (SMT). To learn how to
get these tools, see PI System Administration Tools on page 5.
PI System Health Checklist
Area Check to see that: How to check it:
PI Server 9 Core PI systems and interfaces are SMT Server Process Manager
Subsystems running (see Checking whether the PI Server
is Running on page 12)
Archives 9 All archives are loaded SMT Archive Manager
9 There are no gaps between archives (see Managing Archives on page 25)
9 There is an empty archive available for Update Manager
the next shift
9 There is enough disk space for the new
archives (for automatically created
archives)
9 The Archive data for a reference tag
looks normal
Backups 9 PI System backups have been run Check the files and disk
9 There is enough disk space for future (see Managing Backups on page 35)
backups
9 The backup files are copied to the
backup media or device
Introduction to PI Server
System Management Page 3
Chapter 2 - System Manager Checklist
Area Check to see that: How to check it:
Event Queue 9 The Archive data flow is normal PI Performance Monitor points
9 The Snapshot data flow is normal (see Monitoring PI System
9 The Event Queue flow is normal Performance on page 57)
9 There is enough disk space available
for the Event Queue(s)
9 There are no unexpected out-of-order
events
Message 9 There are no errors or unusual events SMT Message Log viewer
Log in the message logs
Connections 9 No unusual connection SMT Network Manager Statistics
losses/reconnections
9 No stale connections are accumulating
9 There are no network errors
Data 9 The I/O rate tag trends look good Check I/O rate tags
Sources 9 There are no error messages in the (see Monitoring Interface
pipc.log file Performance on page 44)
Points 9 There are no stale or bad tags SMT Stale and Bad Tags
(Tags) (see Finding Malfunctioning Points on
page 23)
Technical 9 There are no new bulletins Technical Support Web Site
Support Site 9 There are no software upgrades or (http://techsupport.osisoft.com/)
patch releases you should install
Page 4
Chapter 3. PI SYSTEM ADMINISTRATION TOOLS
3.1 Getting and Using the Tools You Need
OSIsoft provides two tools that make it much easier to manage a PI System. If you haven't
already installed these two tools, do it now:
The PI System Management Tools (SMT) on page 5
The PI Interface Configuration Utility (ICU) on page 6
Make a habit of checking the Technical Support Web Site (http://techsupport.osisoft.com)
regularly for updates to these tools.
OSIsoft also provides some other helpful tools that you might want to look at, if you have the
time:
Using Other PI Tools on page 7
3.1.1 The PI System Management Tools (SMT)
The PI System Management Tools (SMT) is set of easy-to-use plug-ins, that provide all the
basic tools you need to manage a Windows-based PI System. You access this set of tools
through a single host application, called the SMT Host. The SMT Host is more commonly
called the System Management Tools or simply, SMT.
How to Install SMT
You can get the latest version of SMT on the Technical Support Web Site
(http://techsupport.osisoft.com):
1. On the Products menu, point to System Management and click on PI SMT 3.
2. On the right side of the page, under Docs and Downloads, left-click on Install Kits.
At this point, you might need to log into the Web site, if you haven’t already.
3. Click the Download button for the System Management Tools install kit.
4. After downloading the install kit, double-click the Setup executable to install SMT.
How to Run SMT
To run SMT, on the Windows Start menu, point to Programs, point to PI System, and then
click PI System Management Tools.
Introduction to PI Server
System Management Page 5
Chapter 3 - PI System Administration Tools
How to Select a Server in SMT
SMT includes a PI Servers pane, which lists all the available Servers. Most tasks are easier in
SMT, if you select a single PI Server on which you want to perform that task. To select a PI
Server in SMT:
1. Open the SMT Console (How to Run SMT on page 5).
2. From the PI Servers pane, click the box next to the PI Server that you want to work
with.
You can select more than one server at a time.
3.1.2 The PI Interface Configuration Utility (ICU)
The PI Interface Configuration Utility (ICU) is a tool that makes it easy to configure and
manage your PI interfaces. Install the ICU on each of your Interface Nodes.
How to Install the ICU
You can get the latest version of the ICU on the Technical Support Web Site
(http://techsupport.osisoft.com):
1. On the Products menu, point to Interfaces and click on PI Interface Configuration
Utility.
2. On the right side of the page, under Docs and Downloads, left-click on Install Kits.
At this point, you might need to log into the Web site, if you haven’t already.
3. Click the Download button for the PI Interface Configuration Utility (ICU) install
kit.
4. After downloading the install kit, double-click the Setup executable to install the
ICU.
How to Run the ICU
The ICU is a point-and-click tool for configuring interfaces. You can only run it directly on
the Interface Node where the interface is installed.
To run the ICU, go to the Interface Node and, on the Windows Start menu, point to Programs,
point to PI System, and then click PI Interface Configuration Utility.
The first time you run the ICU on an Interface Node, you need to register each interface. Also
make sure that the interface supports the ICU utility. See Configuring Interfaces on page 43.
Page 6
3.1 - Getting and Using the Tools You Need
3.1.3 Using Other PI Tools
In addition to SMT and the ICU, OSIsoft provides many other tools that are useful to System
Managers. The most current tools are always available on the Technical Support Web Site
(http://techsupport.osisoft.com). Here are a few that are good to know about:
PI TagConfigurator: An Excel plug-in that allows you to create new tags and
modify the attributes of existing tags from a spreadsheet.
PI Module Database Builder: An Excel plug-in that allows you to view and modify
items from the Module Database in an Excel spreadsheet.
PI SQC Alarm Manager: Used to manage the Real Time SQC Alarms on PI
Servers.
3.1.4 Using the Windows Command Interpreter
As a PI System Manager, you sometimes need to use one of PI's command line utilities. To
do this, you need to open a Windows command prompt window:
1. On the Windows Start menu, click Run. The Windows Run dialog box appears.
2. In the Open text field, type:
cmd
3. Click OK. A Windows command prompt window appears.
4. Use the cd command to change to the directory that contains the PI utility. For
example to change to the PI\adm directory on the D drive, you would type:
cd /D D:\PI\adm
Introduction to PI Server
System Management Page 7
Chapter 4. INTRODUCTION TO THE PI SYSTEM
The PI System collects, stores and manages data from your plant or process. You connect
your data sources to one or more PI Interface Nodes. The Interface Nodes get the data from
your data sources and send it to the PI Server. Users get data from the PI Server and display it
with client tools (for example, ProcessBook, DataLink or RtWebParts).
Overview of PI System Data Flow
Data Sources: Your data sources are the instruments that generate your data. They
can be almost anything and they can connect to the Interface Nodes in a variety of
different ways. PI’s Performance Equations, ACE, and Totalizer are also all data
sources. See Managing Data Source Equipment on page 71 for more information
about Data Sources.
Interface Nodes: Interface Nodes run PI interfaces. PI interfaces get the data from
the data sources and send it to the PI Server. Each different data source needs a PI
interface that can interpret it. OSIsoft has over 300 different interfaces. For more
information, see About PI Interface Nodes on page 10 and Managing Interfaces on
page 41.
PI Server: The PI Server stores the PI data and acts as a data server for Microsoft
Windows-based client applications. You can also use the PI Server to interact with
data that is not stored in PI (external systems). For more information, see About the
PI Server on page 11.
Clients: Operators, engineers, managers and other plant personnel use a variety of
client applications to connect to the PI Server to view plant data. For more
information, see About Client Applications on page 16.
Introduction to PI Server
System Management Page 9
Chapter 4 - Introduction to the PI System
4.1 About PI Interface Nodes
OSIsoft provides specialized interface programs (interfaces) for each data source. These
interfaces typically run on a dedicated system, called an Interface Node, which connects both
to the data sources and to the PI Server. For historical reasons, Interface Nodes are also
sometimes referred to as API Nodes or Data Source Nodes.
Interface Nodes can run multiple interfaces to multiple PI Servers. The Interface Node might
be a machine that is a part of the foreign data system, or a stand-alone dedicated interface
machine, or even a PI Server itself (PI to PI).
Data Flow on the Interface Nodes
About Buffering
Data Flow on the Interface Nodes
The PI Server stores data in the form of events. Each event has a value and a timestamp that
tells you what time the value was collected. The interfaces collect data from the data sources
and typically use exception reporting, meaning that they pass significant events on to the PI
Server and discard the rest. If the buffering service (Managing Buffering on page 63) is
configured on the interface node, then the events go through the buffering service. If the
Interface Node cannot connect to the PI Server, the buffering service holds the data until the
Server connection is restored.
What is Exception Reporting?
The point of exception reporting is for the interface to send you the data you are interested in,
rather than taxing the network connection by sending a lot of data that is not meaningful.
Exception reporting uses a simple dead band algorithm to determine whether to send events
to the PI Server. For each point, you can set exception reporting specifications that create the
dead band. The interface ignores values that fall inside the dead band.
In the preceding illustration, values A, D and C are reported to the PI Server. Value A is the
last reported value, values B and C fall within the exception dead band, but value D falls
Page 10
4.2 - About the PI Server
outside the deadband, so the interface reports value D and the previous value, in this case,
value C.
The interface uses the point’s ExcDev, ExcMin and ExcMax attributes to decide whether to
report the new value to PI:
The ExcDev (or ExcDevPercent) attributes determine how much a point's value
needs to change before the interface sends it to the Server. For example, a 12 bit A/D
converter can never be more precise than 1 part in 4096.
The ExcMax attribute sets a limit on how long the interface can go without reporting
a value to PI. After the ExcMax time period, the interface sends the next new value
to PI, regardless of whether the new value is different from the last reported value.
The ExcMin attribute sets a limit on how frequently the interface can report values.
For example, if you want the interface to wait a full ten minutes before reporting a
new value to the PI Server, then you would set the ExcMin attribute to ten minutes.
For details on setting exception reporting attributes, see Exception Specifications on page 20.
Some interfaces do not support exception reporting. See the documentation for your interface
to determine whether it supports this capability.
4.2 About the PI Server
The PI Server is the heart of your PI System. It gets the data and routes it in real time
throughout the PI System and your entire information infrastructure, making it possible for
everyone to work from a common set of real data. Operators, engineers, managers, and other
plant personnel can connect to the PI Server and view manufacturing data from PI Data
Storage or from external data storage systems.
What's in the PI Directory?
File System Dos and Don'ts
Checking whether the PI Server is Running
Data Flow in the PI Server
4.2.1 What's in the PI Directory?
By default, the PI Server installs its files in a folder called PI on the disk with the most
available space, but you can choose a different location for PI during installation. Within the
PI directory, the PI Server installs the subdirectories listed in the table below.
Directory Contents
adm Contains administrative tools.
bin Contains subsystem or PI service executables.
dat Contains databases such as points and digital states. This is also the
default directory for archives.
Introduction to PI Server
System Management Page 11
Chapter 4 - Introduction to the PI System
Directory Contents
log Contains log files.
setup Contains files for install and uninstall.
4.2.2 File System Dos and Don'ts
The two most important tips on the file system are:
Disable virus scanning on the archive folder. Virus scanning may corrupt archive
files. The problem with virus scanning is that, because the data is random, it might
have a bit pattern that matches a known virus signature. The virus scanning software
then locks and quarantines the primary archive.
Don't use the Windows File System Compression feature on the PI Server. When
you use compressed files, you slow down PI's access to archive files. The
compression might save disk space, but it requires more CPU resources.
4.2.3 Checking whether the PI Server is Running
The PI Server consists of several modules, including a set of core subsystems. To check
whether the PI Server is running, you simply check that the core subsystems are running.
Core Subsystem What It Does
PI Archive subsystem The PI Archive subsystem stores and serves the data after it comes out
of the Snapshot subsystem.
PI Backup subsystem The PI Backup subsystem controls the backup of the PI Server.
PI Base subsystem The PI Base subsystem maintains the point configuration data. This
subsystem also hosts the PI Module Database.
PI License Manager The PI License Manager maintains licensing information for the PI
Server and all connected applications
PI Message subsystem The PI Message subsystem records status and error messages for the
PI Server in a log file.
PI Network Manager The PI Network Manager provides the connection between all the
subsystems in the Server. This subsystem also manages network
connections between the PI System and client applications.
PI Shutdown subsystem Determines when the PI Server was stopped and writes shutdown
events to points configured to receive these events (runs only at startup
and then stops on non-Clustered PI Servers)
PI Snapshot subsystem The PI Snapshot subsystem stores the most recent event for each point.
It applies compression, sends data to the Event Queue, and serves
Snapshot events to the client applications.
PI SQL Subsystem The PI SQL Subsystem processes SQL statements, including those
submitted by the PI ODBC Driver.
Page 12
4.2 - About the PI Server
Core Subsystem What It Does
PI Update subsystem The PI Update subsystem sends notifications of changes in values or
point attributes to any interface or client application that is signed up for
notification.
To check whether the core subsystems are running, you can use the Server Process Manager
plug-in in the PI System Management Tools (SMT):
1. Open the PI System Management Tools and select the Server you want to check (see
The PI System Management Tools (SMT) on page 5).
2. In the System Management plug-ins list, under Operation, choose Server Process
Manager. The list of processes appears.
3. If the core subsystems (except Shutdown on non-Clustered PI Servers) are running,
then the PI Server is running. The Shutdown subsystem runs only when the PI Server
is starting up, so Shutdown is listed as Stopped.
In addition to the core subsystems, the Server Process Manager lists the status of optional
subsystems, such as Batch and Performance Equation Scheduler. These optional subsystems
do not need to be running in order for the PI Server to be running.
4.2.4 Data Flow in the PI Server
When the PI Server gets a new event from an interface or manual input program, it sends the
event to the Snapshot Subsystem. The Snapshot Subsystem holds a single value for each PI
point in memory. When a new value comes in, the PI Server sends the old value to the
Archive Subsystem. The Archive Subsystem performs compression testing on the value and
either discards it or sends it on to the Event Queue, depending on the result of the test.
4.2.5 What is the Snapshot?
The Snapshot Subsystem gets the new data from the Interface Node and holds the most recent
value for each point. This most recent value is called the Snapshot for that point.
Introduction to PI Server
System Management Page 13
Chapter 4 - Introduction to the PI System
When a new event comes in, it becomes the Snapshot for that point. The PI Server evaluates
the previous Snapshot according to the compression specifications and either sends the new
value to the Event Queue or discards it.
These values in the Snapshot Subsystem are called Snapshot events or, sometimes, just
Snapshots. The collection of all the Snapshot values for all the points is the Snapshot
database.
4.2.6 What are Out of Order Events?
An out of order event is an event that enters the Snapshot Subsystem with a timestamp that is
older than the current Snapshot value. The PI Server sends out of order events directly to the
Event Queue for archiving, without compression testing.
4.2.7 What is Compression Testing?
The Archive Subsystem uses compression testing to determine what events need to be saved
in the Archive. The point of compression testing is to store just enough data to accurately
reproduce the original signal.
For example, in the following illustration, all the events fall on the same straight line. In a
simple case like this, you don’t actually need to store all the points on the line. If you store
just two points, you can exactly recreate the point value for any other time.
Page 14
4.2 - About the PI Server
The same principle applies to compressing real-world data. The PI Server uses a sophisticated
compression algorithm to determine which events it needs to keep in order to provide an
accurate data history. The CompDev, CompMin and CompMax attributes allow you to
control the “granularity” of the compression algorithm.
The CompMin and CompMax attributes give you some control over how often the
PI Server should save a new value for a particular point.
CompDev and CompDevPercent allow you to decide how much a point's value
needs to change in order for PI to save it.
For details on setting compression testing attributes, see Compression Specifications on page
21.
4.2.8 What is the Event Queue?
The PI Event Queue serves as a memory buffer between the Snapshot and Archive
Subsystems. The Snapshot Subsystem adds data to this queue while the Archive Subsystem
removes data from the queue.
Normally the Event Queue passes events through to the Archive as quickly as they arrive, but
in some circumstances the Archive Subsystem might be too busy or an archive file might be
unavailable. When this happens, the Event Queue holds the data, filling until the Archive is
again available. This is called Archive Queuing.
The most common causes of Archive Queuing are:
The archives are unavailable because Archive Shift or archive backups are occurring.
Introduction to PI Server
System Management Page 15
Chapter 4 - Introduction to the PI System
The Archive Subsystem is busy because incoming events are out of order.
4.3 About Client Applications
The PI Server works with a wide range of client applications, from ProcessBook and
DataLink to RtWebParts. Some of the client software packages available from OSIsoft are
listed in the table below.
Software Description
PI ProcessBook An easy-to-use graphics package that allows users to create dynamic,
interactive graphical displays featuring real-time PI data.
PI ProfileView Creates a comprehensive display of surface data for monitoring sheet
products.
PI DataLink Allows PI to access and deliver data to and from spreadsheet programs
and create easy-to-read reports.
PI Control Monitor Oversees plant control systems, ensuring accuracy, and keeps a
historical system record.
PI BatchView Displays PI Batch data on Windows desktop computers.
PI Manual Logger Used to organize and manually enter data from handheld loggers,
computer terminals, scanners, and other input devices into the PI
System.
PI AlarmView Summarizes PI Alarm server information and displays those data in a
hierarchical tree structure to any number of clients on- or off-site.
PI ActiveView Seamlessly renders existing PI ProcessBook displays for the Web.
RtWebParts Web parts that work with RtBaseline Services to display PI and other
data in various ways.
Page 16
Chapter 5. MANAGING PI POINTS
This section gives you a brief introduction to PI points and point attributes and then covers
the basic point-related tasks that a System Manager needs to know how to do:
About Points
About Point Attributes
Creating New Points
Finding Malfunctioning Points
Decommissioning Points
Deleting Points
This material is an introduction to PI points. For comprehensive documentation on PI points,
see the PI Server Reference Guide.
5.1 About Points
Points, sometimes also called tags, are the basic building blocks of a PI system, because they
are how you track the events that comprise your data history. When the System Manager or
OSIsoft Field Services engineer installs a PI Server, he creates a PI Point for every source of
data that the PI System needs to track.
Each point has more than 50 attributes (About Point Attributes on page 17) that define exactly
how the data should be collected for that point. These attributes determine how frequently the
point gets new values, the data type of the point values (whether integer or string, for
example), who is allowed to view and/or edit the point, and so on. The PI Base Subsystem
stores points and their attributes in the Point Database.
Note: Some PI interfaces are compatible with PI Auto Point Sync (PI APS), which
tracks changes in foreign data systems and automatically updates the PI Points
Configuration to reflect those changes.
5.2 About Point Attributes
Point attributes are where you configure how and when PI should collect data from a
particular data source. Point attributes specify the data source location, how often PI should
Introduction to PI Server
System Management Page 17
Chapter 5 - Managing PI Points
get new values from the data source, which values PI can ignore and which represent valid
data, and much more.
Point attributes are fully documented in the PI Server Reference Guide. This section gives
you a brief overview of a few key attributes:
Point Name: Tag Attribute
Class of Point: PtClass Attribute
Data Type of Point: PointType Attribute
Data Source: PointSource Attribute
Interface ID Number: Location1 Attribute
Setting Scan Class: Location4 Attribute
Exception Specifications
Compression Specifications
Point Value Range: Zero, Span and Typical Value
Configuring Shutdown Events: Shutdown
Point Security: PtOwner, PtGroup, PtAccess, DataOwner, DataGroup, DataAccess
There are more than 50 different point attributes that you can specify for each point. The
exact list of attributes that configures a point depends on the class of the point (see Class of
Point: PtClass Attribute on page 18).
5.2.1 Point Name: Tag Attribute
The Tag attribute specifies the name of the point. Many PI users use the terms tag and point
interchangeably, which is fine. Technically though, the tag is actually just the name of the
point. Follow these rules for naming PI points:
The name must be unique on the PI Server
The first character must be alphanumeric, the underscore (_), or the percent sign (%)
No control characters are allowed; such as linefeeds or tabs
The following characters are not allowed:
* ’ ? ; { } [ ] | \ ` ‘ “
5.2.2 Class of Point: PtClass Attribute
The attributes that you need to configure for a particular point depend on what the point is
for. PI provides several different classes of points, each of which provides a slightly different
set of attributes to work with. You can also build your own point classes.
Points that represent data from a PI interface are always in the Classic point class. The list of
available PI point classes is as follows:
Classic: The Classic point class includes attributes used by interfaces.
Page 18
5.2 - About Point Attributes
Base: The Base class is a common set of attributes that all point classes include. The
Base class includes both system-assigned and user-assigned attributes. This is the
minimum set of attributes that a PI point needs in order to function.
Alarm: The Alarm class is used for alarm points. See the PI Server Applications Guide
for more information on Alarm points.
Totalizer: The Totalizer class is for a type of point that represents a running total of data.
There are many different kinds of Totalizer points. For more information on Totalizer
points, see the PI Server Applications Guide and the SMT help topic for the Totalizer
Editor.
SQC_Alarm: The SQC_Alarm class is for SQC_Alarm points. See the PI Server
Applications Guide for more information on SQC_Alarm points.
5.2.3 Data Type of Point: PointType Attribute
Use the Type attribute to specify the data type of the point values.
Point Type When to Use It
Digital Use the Digital point type for points whose value can only be one of several
discrete states, such as ON/OFF or Red/Green/Yellow.
Int16 Use the Int16 point type for points whose values are integers between 0 and
32767 (15-bit unsigned integers).
Int32 Use the Int32 point type for points whose values are integers between -
2147450880 and 2147483647 (32-bit signed integers).
Float16 Use the Float16 point type for floating point values, scaled. The accuracy is one
part in 32767.
Float32 Use the Float32 point type for single-precision floating-point values, not scaled
(IEEE floating points).
Float64 Use the Float64 point type for double-precision floating-point values, not scaled
(IEEE floating points).
String Use the String point type for strings of up to 976 characters.
Blob Blob stands for Binary Large Object. Use the Blob point type to store any type
of binary data up to 976 bytes.
Timestamp Use the Timestamp point type for any time/date in the range 1-jan-1970 to 1-
Jan-2038 Universal Time (UTC).
5.2.4 Data Source: PointSource Attribute
The PointSource attribute specifies which interface is the data source for this point. Set the
PointSource attribute to match the point source character for the interface (see What's a
Point Source? on page 41).
The default point source is L, which stands for “Lab”. Depending on your installation, the
default point source is either L or Lab. Use L or Lab for points that are not associated with
any interface to specify lab-input points.
Introduction to PI Server
System Management Page 19
Chapter 5 - Managing PI Points
5.2.5 Interface ID Number: Location1 Attribute
The Location1 attribute is only for interface points, meaning points that get their data from a
PI interface, as opposed to some other source. Most interfaces use the Location1 attribute to
specify the interface ID number (described in What's an Interface ID Number? on page 42).
5.2.6 Setting Scan Class: Location4 Attribute
The Location4 attribute is only for interface points, meaning points that get their data from a
PI interface, as opposed to some other source. Each PI interface has one or more scan classes
for scheduling data collection (See What's a Scan Class? on page 42). You set the Location4
attribute for a point to specify which of the interface's scan classes you want to use.
Note: Most interfaces require you to use the Location4 attribute to set the scan
class, however there are exceptions, particularly among older interfaces. Also, some
interfaces get data on command, rather than scanning. Always check the
documentation for the interface.
5.2.7 Exception Specifications
Exception reporting specifications determine which events the interface sends to PI and
which it discards. To learn more about exception reporting, refer to What is Exception
Reporting on page 10.
Each point can set the following three attributes to configure the exception reporting
specifications:
Specification Attribute How and When to Use it
Exception ExcDev Use this attribute to specify how much a point value must
Deviation change before the interface reports the new value to PI.
Use ExcDev to specify the exception deviation in the
point's engineering units. As a general rule, you should
set the exception slightly smaller than the precision of the
instrument system.
ExcDevPercent You can use ExcDevPercent instead of ExcDev.
ExcDevPercent sets the exception deviation as a
percentage of the Span attribute, but be careful. If your
Span attribute is not set correctly, your exception
reporting will be wrong too. A typical exception deviation
value is about 1% of Span.
Exception ExcMin Use ExcMin to limit how often (in seconds) the interface
Minimum reports a new event to PI. For example, if you set ExcMin
to five, then the interface discards any values collected
within five seconds of the last reported value. ExcMin is
typically set to zero.
Exception ExcMax Set ExcMax to the maximum length of time (in seconds)
Maximum you want the interface to go without reporting a new event
to PI. After this time, the interface will report the new
event to PI without applying the exception deviation test.
Page 20
5.2 - About Point Attributes
To learn more about exception reporting, see the PI Server Reference Guide.
Note: For Digital, Blob, or String points, only the exception maximum and minimum
times are important. PI ignores the exception deviation specification for them.
5.2.8 Compression Specifications
PI uses the compression specifications to filter the data passed from the Snapshot to the
Archive. The goal is to store just enough data to accurately reproduce the original signal. By
filtering out data that you don’t need, you get more efficient Archive storage and the Archive
can serve the data to the clients more efficiently.
Where exception reporting uses a simple dead band method for filtering data, PI’s
compression testing uses a more complex method that follows the slope of the data (the
swinging door compression algorithm). PI’s compression testing algorithm is explained in
detail in the PI Server Reference Guide.
The compression specifications include a flag that allows you to turn compression on or off.
We recommend you turn compression on for all real-time points in the system. You usually
turn compression off for points with manually-entered data, production targets, control limits,
and so on.
For each point, you can set four attributes to configure the compression specifications.
Specification Attribute What it Does
Compression Flag Compressing Turns compression on or off (set to 1 to turn compression
on or 0 to turn compression off).
Compression CompDev or As a rule of thumb, set CompDev to the precision of the
deviation instrument. Set it a little “loose” to err on the side of
collecting, rather than losing data. After collecting data for a
while, go back and check the data for your most important
tags and adjust CompDev if necessary.
Use CompDev to specify the compression deviation in the
point's engineering units.
CompDevPercent Use CompDevPercent to specify the compression
deviation as a percent of the point's Span attribute.
Compression CompMin Sets a minimum limit on the time between events in the
minimum time Archive. Set the CompMin attribute to zero for any point
coming from an interface that does exception reporting.
You typically use CompMin to prevent an extremely noisy
point from using a large amount of archive space
Compression CompMax CompMax sets a maximum limit on the time between
maximum events in the Archive. If the time since the last recorded
event is greater than or equal to CompMax, then PI
automatically stores the next value in the Archive,
regardless of the CompDev setting.
You typically set CompMax to the same value for all points
in the system. It's common practice to choose a CompMax
setting of one work shift (for example, 8 hours).
Introduction to PI Server
System Management Page 21
Chapter 5 - Managing PI Points
To learn more about how PI calculates compression, see the PI Server Reference Guide.
Note: For Digital, Blob, or String points, only the compression maximum and
minimum times are important. PI ignores the compression deviation specification for
them.
5.2.9 Point Value Range: Zero, Span and Typical Value
The Zero, Span, and Typical Value attributes specify the range of values for a point.
Zero Indicates a point’s lowest possible value. Zero does not have to be the
same as the instrument zero, but that is usually a logical choice. This
attribute is required for all numeric data type points and is critically important
for float16 points.
Span The difference between the top of the range and the bottom of the range.
This attribute is required for all numeric data type points.
Typical Value Documents an example of a reasonable value for this point. For a numeric
tag, it must be greater than or equal to the zero, and less than or equal to
the zero plus the span.
5.2.10 Configuring Shutdown Events: Shutdown
The Shutdown attribute has two possible values: 1 (On) and 0 (Off). If the PI Server shuts
down, PI writes a shutdown event to all points that have the shutdown flag set to 1 (On). Set
Shutdown to Off for points on interfaces that are buffered (See Managing Buffering on page
63). The buffering service restores the data for these tags as soon as it connects to the PI
Server again.
5.2.11 Point Security: PtOwner, PtGroup, PtAccess, DataOwner, DataGroup,
DataAccess
Each point has different, configurable, access privileges for its data and its point
configuration. To control who has access to what, you assign an owner and a group for each
point's data and attributes, respectively. Then you set owner, group and world privileges.
Read What are PI Access Categories? on page 48 to learn how this works.
PI point security is divided into two separate pieces, Data Access and Point Access.
Data Access Specifies who has access to a point's data values (Snapshot and Archive
data).
Point Access Specifies who has access to the point's attributes (Zero, Span, Descriptor,
and so on).
You can have different owners and different group access for a point's attributes than for the
point's data. So, for example, one user might be allowed to edit the data for a point, but not be
allowed to edit the attributes of that point.
Page 22
5.3 - Creating New Points
Note: If users don’t have permission to view a point’s attributes, they won’t be able
to see that point’s data either, in most cases. This is because client applications
need access to the point attributes in order to get the data.
To edit the owner, group and permissions for a point, select the point in SMT's Point Builder
and click the Security tab.
5.3 Creating New Points
As a PI System Manager, you might need to create a new PI Point. The easiest way to create
a new tag is to copy an existing tag that is very similar to the tag you want to create—then
you can just edit the Tag attribute and any other attributes that you want to change. SMT's
Point Builder provides an easy interface for editing and creating PI points. If you're very
familiar with Excel, you will probably find the Excel plug-in, TagConfigurator, a better tool
to use. If you want to create more than one point at the same time, use TagConfigurator.
5.4 Finding Malfunctioning Points
At least once a month, you should use SMT's PI Stale and Bad Tags plug-in to search for
stale and/or bad points. This plug-in identifies points that have not received data for a long
time or that have current values representing error conditions such as “I/O timeout”, “Pt
Created”, “bad input” or, in many cases “Shutdown”. Also check any “flat-lined” or “stuck”
points.
When you find points that are no longer useful (points that represent data from obsolete
equipment, for example), you should decommission them (see Decommissioning Points on
page 24).
Introduction to PI Server
System Management Page 23
Chapter 5 - Managing PI Points
5.5 Decommissioning Points
Typically, to decommission a point, you set the Scan attribute to 0 (off):
1. Open SMT and select the PI Server for that point (see How to Run SMT on page 5).
2. In the System Management plug-ins list, under Points, choose Point Builder.
3. Search for the point.
4. Click the Archive tab.
5. Under Scan, click Off.
Some interfaces don’t use the scan bit to turn off points. If you want to decommission a point
for such an interface, change the point source attribute for that point to a value that you use
only for decommissioned points.
5.6 Deleting Points
When you delete a point, you lose all data for that point, so you break any client displays that
use the point. Further, once you delete a point, you can't get it back. If you are unsure about
the purpose of a point’s existence or about the need for any historical data associated with it,
it’s safer to decommission the point (see Decommissioning Points on page 24) rather than
deleting it.
Page 24
Chapter 6. MANAGING ARCHIVES
You need to pay close attention to the PI archives, because this is where PI stores your data
(About Archives on page 25). As the data accumulates, you need new archives to hold it.
Otherwise, PI overwrites data in existing archives. You can do all or most of your archive
management with the SMT Archive Manager plug-in.
About Archives
Finding the Archive Files
Making Sure PI Doesn’t Overwrite Your Archives
Creating an Archive
Registering an Archive
Unregistering an Archive
Moving an Archive
Fixing Archive Gaps
Automating Archive File Creation
6.1 About Archives
The PI System stores your data in archives. Typically, archives are files of a fixed size that
can hold PI data. Fixed archives allocate the full amount of space upfront, meaning that an
empty archive and a full archive take the same amount of disk space.
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.
Note: PI actually performs the archive shift before the Primary Archive is completely
full so that older data can be added later, if necessary.
Introduction to PI Server
System Management Page 25
Chapter 6 - Managing Archives
For an archive file to be eligible to be the new Primary Archive, it must be registered
(Registering an Archive on page 28), writeable, shiftable, and large enough to handle the
current size of the Point Database.
If no eligible archives are available for an Archive Shift, PI uses the oldest available filled
archive as the new Primary Archive, overwriting the data in the old archive. For example in
the preceding illustration, after the shift from piarch.003 to piarch.004, no empty registered
archives are left. If no new archives are created, then piarch.001 becomes the next Primary
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.
Note: Archives that can grow in size to accept variable amounts of data are called
dynamic archives. Dynamic archives are not discussed in this document. See the PI
Server System Management Guide for details.
6.2 Finding the Archive Files
By default the archives are placed in the PI\dat directory, but you can put them anywhere you
like. The Archive Manager lists the location of each registered archive file:
1. Run SMT and select the PI Server on which you want to view the archives (How to
Run SMT on page 5).
2. Click to expand the Operation item in the System Management Plug-ins pane.
Page 26
6.3 - Making Sure PI Doesn’t Overwrite Your Archives
3. From the list of Operation plug-ins, double-click on Archive Manager. The
Archive Manager plug-in appears in the Active Plug-in pane. The Archive File
column lists all the archives registered on the selected server and displays the full
path for each. The Primary Archive is first on the list.
Note: Don't use anti-virus software to scan the directories containing PI Server
database and archive files on systems collecting production data.
6.3 Making Sure PI Doesn’t Overwrite Your Archives
If you don’t have an empty, writable, shiftable, archive available when the archive shift
occurs, PI overwrites the oldest available full archive—unless your Server is set up to create
archives automatically. If your PI System does not create new archives automatically, you
can set it up to do that, if you like (Automating Archive File Creation on page 32).
Here's what you need to do:
1. Find out where the PI archive files are located (Finding the Archive Files on page
26).
2. If you don't want PI to create new archives automatically, then you need to figure out
how often your archives fill and you need to create new archives (Creating an
Archive on page 27) as needed so that PI doesn't run out of space and start
overwriting data.
3. If you do use automatic archive creation, then you need to make sure you don't run
out of disk space on that machine.
6.4 Creating an Archive
The SMT Archive Manager plug-in provides an easy interface for creating, editing, and
monitoring your PI archives. To create a new PI archive, follow these steps:
1. Run SMT and select the PI Server on which you want to view the archives (How to
Run SMT on page 5).
Introduction to PI Server
System Management Page 27
Chapter 6 - Managing Archives
2. Click to expand the Operation item in the System Management Plug-ins pane.
3. From the list of Operation plug-ins, double-click on Archive Manager. The Archive
Manager plug-in appears in the Active Plug-in pane. It lists all the archives registered
on the selected server. The Primary Archive is first on the list.
4. To create a new archive, click the Create a New Archive icon.
5. The Create New Archive dialog box appears. Name the new archive file and choose
the Clone the primary archive fixed size radio button.
6. If you want to choose a different size for the archive, you need to understand the
issues in archive sizing. Read the chapter on managing archives in the PI Server
System Management Guide.
7. Click the OK button. The Archive Manager plug-in creates and registers the
archive.
6.5 Registering an Archive
In order for the PI Server to recognize a file as an archive file you must register it. By
registering an archive file, you tell the PI Server that the file exists and that is an archive file.
The PI Server cannot access data in unregistered archives, nor can the PI client applications.
Page 28
6.6 - Unregistering an Archive
The SMT Archive Manager plug-in provides an easy interface for registering archives. To
register an archive, follow these steps:
1. Run SMT and select the PI Server on which you want to view the archives (How to
Run SMT on page 5).
2. Click to expand the Operation item in the System Management Plug-ins pane.
3. From the list of Operation plug-ins, double-click on Archive Manager. The Archive
Manager plug-in appears in the Active Plug-in pane. It lists all the archives registered
on the selected server. Unregistered archive files do not appear in the list.
4. Click the Register an Archive icon to register the archive.
5. A file-browsing window appears. Double-click on the archive file you want to
register. The Archive Manager plug-in registers the file and it appears in the list of
registered archive files.
6.6 Unregistering an Archive
If you want to move or reprocess an archive file, you need to unregister it, make your
changes, and then re-register it. You cannot unregister the primary archive.
Introduction to PI Server
System Management Page 29
Chapter 6 - Managing Archives
The SMT Archive Manager plug-in provides an easy interface for unregistering archives. To
register an archive, follow these steps:
1. Run SMT and select the PI Server on which you want to view the archives (How to
Run SMT on page 5).
2. Click to expand the Operation item in the System Management Plug-ins pane.
3. From the list of Operation plug-ins, double-click on Archive Manager. The Archive
Manager plug-in appears in the Active Plug-in pane. It lists all the archives registered
on the selected server. Unregistered archive files do not appear in the list.
4. To unregister an archive file, click the Unregister selected archive icon to unregister
the archive. The archive disappears from the list.
6.7 Moving an Archive
If you want to move an archive file, you unregister it (Unregistering an Archive on page 29),
move it to the new location, and then register it again (Registering an Archive on page 28).
When you move the archive file, be sure to move the associated annotation file as well. The
annotation file has the same name as the archive file, except that it ends in .ann. For example,
if the archive is named piarch.003, then the associated annotation file would be called
piarch.003.ann.
Page 30
6.8 - Fixing Archive Gaps
6.8 Fixing Archive Gaps
PI archive files meet chronologically end-to-end, accounting for all of history with no gaps
and no overlaps. If a gap does occur, it’s important to identify and fix it as soon as possible.
To check for (and fix) archive gaps, follow these steps:
1. Run SMT and select the PI Server on which you want to view the archives (How to
Run SMT on page 5).
2. Click to expand the Operation item in the System Management Plug-ins pane.
3. From the list of Operation plug-ins, double-click on Archive Manager. The Archive
Manager plug-in appears in the Active Plug-in pane. It lists all the archives registered
on the selected server. Any archive gaps are clearly labeled and highlighted in red.
Introduction to PI Server
System Management Page 31
Chapter 6 - Managing Archives
4. To fix an archive gap, right-click on the line displaying the archive gap.
5. Select Create New from the resulting pop-up menu. The Create New Archive
dialog box appears. The dialog box is already filled in for you, with the right start and
end times to fill the archive gap.
6. Click OK. The Archive Manager plug-in creates and registers the new archive and an
archive gap no longer appears in the archive list.
6.9 Automating Archive File Creation
If your PI Server is running PI 3.4 or later, you can set it up to create archive files
automatically, as needed. This is very convenient, but you need to keep a close eye on
available disk space for the archives.
To automate archive file creation, follow these steps:
1. Make sure you have a fixed-size Primary Archive (automatic archive generation
won’t work if you have a dynamic Primary Archive). The automatically-generated
archives will be the same size as the Primary Archive.
2. Make sure you have a valid, shiftable target archive available. This gives you a
backup in case the file creation fails for some reason. This target archive can be
dynamic or fixed.
3. Run SMT (How to Run SMT on page 5).
4. Select the Server on which you want to automate archive file creation (How to Select
a Server in SMT on page 6).
5. From the list of Operation plug-ins, double-click on Timeout Table Editor. The
Timeout Table Editor appears in the Active Plug-in pane.
6. Click the Archive tab and select any item in the list.
7. Click the New Timeout Setting button.
Page 32
6.9 - Automating Archive File Creation
A dialog box appears.
8. In the top field, which is the Name field, type in:
Archive_AutoArchiveFileRoot
9. In the Value field, type in the path to the directory where you want PI to create the
archives, along with the archive file prefix. For example, if you type:
D:\PI\arc\piarch
then PI creates new archive files in the D:PI\arc\ and names them piarch.001,
piarch.002, and so on.
10. Click OK.
If there is not enough disk space to create the new archives, PI overwrites data in the old
archives. You can find more information about automatic archive file creation in the PI
Server System Management Guide.
Introduction to PI Server
System Management Page 33
Chapter 7. MANAGING BACKUPS
It's important to back up the PI Server daily, so that you don't lose data and configuration
information. On a PI Server that is already correctly configured to back itself up
automatically, all you need to do is check your backups periodically and check that you have
enough disk space available for upcoming scheduled backups.
About PI Server Backups
Choosing a Backup Strategy
Checking Whether Backups are Scheduled
Setting up Automatic Backups
7.1 About PI Server Backups
All backups of PI that are done while the PI System is running are managed by the PI Backup
Subsystem (PI\bin\pibackup.exe). Typically, the backups are launched via the
PI\adm\pibackup.bat backup script. However, if PI is installed on Windows 2003 Server, you
can backup PI with any third party backup application that supports Volume Shadow Copy
Services (VSS). This chapter only discusses backups with the backup script.
Note: If you don't have buffering turned on for all interfaces, you might lose data
during backups. See Checking whether the Buffering Service Is Running on page 64.
(PINet buffers data for interfaces running on PINet nodes.)
7.2 Choosing a Backup Strategy
The easiest backup strategy is to set up PI to automatically run the backup scripts every day
as described in Setting up Automatic Backups on page 38 and in more detail in the PI Server
System Management Guide.
You can also run the scripts manually. The backup script initiates backups via NTBackup
(NTBackup.exe) on platforms that support VSS, and/or with the piartool –backup command
on platforms that do not support VSS. It is highly recommended that you run PI on a platform
that supports VSS because VSS backups cause minimal disruption to the operation of PI.
Introduction to PI Server
System Management Page 35
Chapter 7 - Managing Backups
7.3 Checking Your Backup Files
It’s important to check your backup files each day:
Check the backup log daily (Checking the Message Logs on page 37). Make sure that
the last backup completed successfully.
Periodically test your backups by simulating a disaster recovery.
Check to make sure that the backup files are where they're supposed to be, and that
the file size looks right. These files should be about the same size each time—if the
backup file is suddenly substantially smaller, then the backup might not have
successfully completed.
Make sure that you are not running out of space on the disk where PI creates the
backups.
7.4 Checking Whether Backups are Scheduled
Open the “Scheduled Task” control panel.
The name of the backup task that is installed with the pibackup.bat file is called “PI Server
Backup”. If backups have been running successfully, the “Last Run Time” should not be
blank. The next run time should be about one day apart from the Last Run Time. Details of
the scheduled task can be viewed by double clicking on the task.
Page 36
7.5 - Checking the Message Logs
Backup file destination
Number of Archives to
backup
The backup
script being
run.
The user login /
account.
From the above picture, you can tell the following.
The destination of the files for the backup operation is e:PI\backup.
The number of Archives to be backed up is 1. That is, only the primary archive will
be backed up.
The scheduled task will run the e:PI\adm\pibackuptask.bat command file. The
pibackuptask.bat in turn launches the e:PI\adm\pibackup.bat command file.
The backup task will be run under the System account.
7.5 Checking the Message Logs
There are several places to look for messages related to backup.
1. You can search the PI Message Log for messages related to backup with the
following command.
\pi\adm\pigetmsg -st t -et * -pn pibacku*
Introduction to PI Server
System Management Page 37
Chapter 7 - Managing Backups
2. The above command will search for backup-related messages from midnight until
current time.
3. The output of the pibackup.bat script is written to a log file. The destination of this
log file is the same as the destination of the backup, and the name of the log file is of
the form pibackup_dd-mmm-yy_hh.mm.ss.txt.
4. The NTBackup log file (VSS Backups only). If there was a problem creating a VSS
shadow copy during a backup, the reason for the failure will be logged at the
beginning of the NTBackup log file.
5. If the “Run As” user for the “PI Server Backup” scheduled task is the same as your
account, then you will be able to view the NTBackup log from the “Tools |
Report…” menu of NTBackup. Launch NTBackup from a DOS command prompt
and choose to run in advanced mode.
7.6 Setting up Automatic Backups
An automated backup task can be installed with the PI\adm\pibackup.bat backup script. You
must install the automated task because the installation of the PI Server does not install a
backup task. The syntax for using the pibackup.bat file is as follows.
PIbackup.bat <path> [number of archives]
[archive cutoff date] [-install]
where <> indicates a required parameter and [] indicates an optional parameter. The
command line parameters must be specified in the above order. If the -install flag is not
specified, a backup will be performed immediately. The more restrictive of [number of
Page 38
7.7 - Site-Specific Backup Tasks
archives] and [archive cutoff date] takes precedence. Regardless of [number of archives] and
[archive cutoff date] archives that do not contain data will not be backed up.
Parameter Example Description
<path> E:\PI\backup Path must be the complete drive letter and path to a
directory with sufficient space for the entire backup.
[number of archives] 2 The number of archives to backup. For example, "2"
will backup the primary archive and archive 1.
[archive cutoff date] *-10d The cutoff date is specified in PI time format. For
example, "*-10d" restricts the backup to archives
archives that contain data between 10 days prior to
current time and current time. The more restrictive
of [number of archives] and [archive cutoff date]
takes precedence.
[–install] Installs a scheduled task to run pibackup.bat daily
at 2:00 am. If the –install flag is not specified, then a
non-VSS backup is performed immediately.
7.7 Site-Specific Backup Tasks
If the pisitebackup.bat file exists, then the pibackup.bat backup script calls it before exiting.
If you have any tasks you want pibackup.bat to execute each day after the backup, then add
these tasks to a file called pisitebackup.bat in the PI\adm directory.
Typically, PI System Managers use the pisitebackup.bat file to move the backup directory to
tape. PI System Managers may also use the script to back up specific files that are not
included in the PI Server backup.
Introduction to PI Server
System Management Page 39
Chapter 8. MANAGING INTERFACES
Once you install and configure an interface on a PI Interface Node, you can typically then
leave it to run indefinitely without any intervention. If you perform software upgrades or
security patches or if the network infrastructure changes, you might need to know how to
perform a few basic tasks.
About PI Interfaces
Configuring Interfaces
Starting and Stopping Interfaces
Monitoring Interface Performance
Configuring Interfaces for Buffering
Where to Go for More Information on Interfaces
8.1 About PI Interfaces
PI interfaces are the software applications that take the data from your data source and send
them to the PI Server. There are hundreds of PI interfaces and they each have their own
specific documentation. However, because most interfaces are based on the OSIsoft
Universal Interface (UniInt), they share a common set of features.
The three basic variables that define an interface are interface ID, scan class, and point
source.
8.1.1 What's a Point Source?
The PointSource attribute is a single character that identifies a PI point as belonging to a
particular interface. When you configure an interface, you specify a point source for that
interface. All the points that belong to that interface must use that point source code as the
value for the PointSource attribute.
The PI Server comes pre-configured with applications that use some of the otherwise
available point source characters. When you're choosing a character to use as the point source
for an interface, avoid using the following characters:
Character Reserved For
9 RampSoak Simulator
Introduction to PI Server
System Management Page 41
Chapter 8 - Managing Interfaces
Character Reserved For
C Performance Equations scheduler
G Alarm
L default point source character
R Random Interface Simulator
T Totalizer program
@ Alarm
8.1.2 What's an Interface ID Number?
The Interface ID number is a number that associates a point with a particular copy of an
interface. Set the Interface ID number to any positive integer. Points that use the interface
then typically use the ID number as the value of the Location1 attribute. Refer to the
interface documentation though, to be sure.
8.1.3 What's a Scan Class?
A scan class is a code that PI interfaces use to schedule data collection. Scan classes consist
of a period, which tells PI how often to collect the data and, optionally, an offset, which tells
PI when to start collecting data. A scan class can also optionally contain a code that requires
that the interface use UTC time:
Scan Class Description Example
Component
Period The period specifies the interval 01:00:00
between calculations. The first two Get data every hour.
digits are the hours, the second two the
minutes, and the third two the seconds.
Offset The offset specifies a start time for the 01:00:00, 13:00:00
calculation. The offset is optional. PI Get data every hour, starting at
counts the offset from midnight of the 1PM
current day. As with the period, the first
two digits are the hours, the second two
the minutes, and the third two the
seconds.
Page 42
8.2 - Configuring Interfaces
Scan Class Description Example
Component
UTC Time The UTC time specifies that the 01:00:00, 13:00:00, U
scheduling sync with Universal Get data every hour, starting at
Coordinate Time (UTC). The UTC time 1PM, UTC time.
is optional. To use it, add a comma
followed by a capital U to the end of the
scan class.
Note: If a scan class has a frequency of more than an hour, make it a UTC scan
class. Otherwise, your scheduling might be thrown off the next time there's a switch
change to or from daylight savings time. UTC scan classes don't have this problem
because they force the scan class scheduling to sync with UTC, rather than local
time.
8.2 Configuring Interfaces
If you have access to the Interface Nodes for your PI System, then the Interface
Configuration Utility (ICU) is the best way to manage your PI interfaces. You need to do an
initial configuration in the ICU for each interface. This is called registering the interface with
the ICU:
1. On the ICU menu, select New. The Configure a New Interface dialog appears.
2. Click the Browse… button and browse to the location of the interface executable. By
default, PI installs your interface executables in the Program Files\PIPC\Interfaces
directory.
3. Type in a descriptive name for the interface. The ICU uses this name in its displays,
so choose a name that you can remember.
4. Type in a Point Source.
5. Type in an Interface ID number.
6. Select the Host PI System.
7. Click OK.
Introduction to PI Server
System Management Page 43
Chapter 8 - Managing Interfaces
8.3 Starting and Stopping Interfaces
The first time you start a PI Interface, you need to start it from the Windows Services control
panel. After that, you can start and stop the Interface from the ICU (Configuring Interfaces on
page 43). Start and stop the interface directly on the Interface Node:
1. From the Windows Start menu on the Interface Node, open the Control Panel and
then open Administrative Tools.
2. In the Administrative Tools folder, double-click on Services.
3. In the Services window, find the interface that you want to start or stop. In the
Windows Services panel, PI interface services are listed with the PI- prefix. For
example, the buffering service is listed as PI-Buffer Server.
4. Right-click on the interface service select either Start or Stop from the resulting pop-
up menu.
8.4 Monitoring Interface Performance
There are two main ways to check how your interfaces are working:
Checking IORates and Performance Points
Checking Log Files
8.4.1 Checking IORates and Performance Points
Create a PI ProcessBook display that shows the IOrates and performance points for each
interface. Some interfaces do not have performance points, so for these interfaces, you rely on
IORates points alone.
Type of Point What it Does
IORates point Monitors the flow of data from an interface. Every 10 minutes each IOrates
point registers the 10-minute average data transfer rate to PI in
events/second.
Performance Reads the value in seconds that it takes the interface to complete one round
Point of data collection for a set of points. You can create one performance point
for each scan class of each interface.
You can easily create both IORates points and performance points for an interface using the
ICU (Configuring Interfaces on page 43).
8.4.2 Checking Log Files
The PI System logs interface and buffering errors in the pipc.log and/or the pigetmsg log on
the interface machine. You can use SMT's Message Log Viewer tool to see these messages.
Some interfaces also produce an interface output file that might contain information about
how the interface is performing.
Page 44
8.5 - Configuring Interfaces for Buffering
Most interfaces also write a performance summary every 8 hours to pipc.log. For each scan
class, the summary shows the duration of the most recent scan, the percent of scans missed,
and the percent of scans skipped. PI counts a scan as missed if it was started after its
scheduled start time (due to a previous scan taking too long). PI counts a scan as skipped if it
did not have an opportunity to run at all. Note that a previous scan can be from any of the
defined scan classes.
Performance points are an important tool for tuning scan classes, because if a scan takes too
long, it can cause the next scan to be skipped, resulting in data loss. You can tune scan classes
by changing the scan frequency, the scan offset, and the number of tags in the scan list. For
more information on configuring scan classes and scan lists, see the user manual for your
interface.
8.5 Configuring Interfaces for Buffering
If you are starting the buffering service on an Interface Node for the first time, you also need
to re-configure the interfaces so that they work correctly with buffering:
1. Configure the interfaces on this node so that they're dependent on the buffering
service.
2. Set the shutdown attribute to off for points on these interfaces.
3. Restart the interfaces, so that they can send their data through the buffering service.
Note: When installing an interface for the first time, it is a good idea to disable
buffering until you are sure the interface is correctly collecting data and storing it in
the archive. Bufserv stands in for the archive when it is not available and may mask
errors your interface would see when running unbuffered.
8.6 Where to Go for More Information on Interfaces
There are many different sources of information on PI interfaces. You can download all of
the following documents from the Technical Support Web Site
(http://techsupport.osisoft.com).
Each interface has its own documentation. If you're not sure how to configure a
particular interface, check the documentation for that specific interface.
Many interfaces are based on the Universal Interface (UniInt). You can learn a lot by
reading the UniInt End User manual.
The PI Server System Management Guide contains a chapter on managing
interfaces.
The Technical Support Web Site also provides a product page dedicated to PI
interfaces and a PI System Manger Resources page. You can get information on new
releases, as well as information on the Interface Configuration Utility and other tools.
Introduction to PI Server
System Management Page 45
Chapter 9. MANAGING PI SECURITY
PI has two main mechanisms for security: log-in accounts (users and groups) and trusts.
About PI Security
Managing Users and Group
Managing PI Trusts
Managing PI Database Security
9.1 About PI Security
The two most commonly used methods of PI Security are user identification security (login
accounts with access permissions) and trusts (trusted computers that are granted access
without having to log in).
User Identification Security: The PI Server has its own user identification and
password security. Users typically access client applications, server connections and
other PI resources by typing in a valid user name and password. For some resources,
such as point data and attributes, you can set access permissions based on user name
and group association. User identification security is explained in Managing Users
and Group on page 47. PI databases rely on user identification security (Managing PI
Database Security).
Trusts: In some situations, you don’t want to require a username and password to
establish a PI connection. A typical example of this is a PI interface application
requesting a connection to a PI Server. PI provides trust security for this type of
situation. Trusts are explained in Managing PI Trusts.
Note: PI also provides a firewall mechanism that is not covered in this guide. The PI
firewall is explained in the PI System Management Guide.
9.2 Managing Users and Groups
This section explains how to manage user accounts and how to set up groups to manage
access permissions to PI resources. It contains the following sections:
About Users and Groups
Introduction to PI Server
System Management Page 47
Chapter 9 - Managing PI Security
Setting up Groups to Manage Resource Access
Adding, Editing and Deleting Users and Groups
9.2.1 About Users and Groups
The PI Server has its own user account security. Each user account is protected by a
password. Users can also belong to one or more groups. PI groups are collections of users
who need the same level of access to a particular PI resource, such as point data or attributes.
As System Manager, you can configure which users and groups have access to which PI
resources (point data and attributes, for example) and how much access they have. To
configure this access, you set permissions for a particular resource’s owner and group.
9.2.2 What are Access Permissions?
PI Permissions, like Windows permissions, determine whether a particular user is allowed to
view and/or edit an item in PI. PI provides the three standard levels of access permissions:
Access Description
Read-only access Users can view the item, but they cannot change it.
Read-write access Users can view the item and they are also allowed to edit it.
No access Users cannot view or edit the item.
9.2.3 What are PI Access Categories?
PI grants access to certain resources (databases, point data and point attributes) based on user
access category. There are three categories of user access in PI: owner, group, and world. For
each PI resource, you can configure the permissions for each user category:
PI grants resource access based on whether a user is the Owner of the item being accessed, a
member of its Group, or neither. Each resource has one Owner and one associated Group.
Page 48
9.2 - Managing Users and Groups
Category Description
Owner Each resource has one (and only one) owner. The owner is always a single user,
not a group. Owner access is usually read-write, but it doesn't have to be.
Group Each resource has one (and only one) associated group. Group access is often
read-only, but it doesn't have to be. Since each resource has only one
associated group, you sometimes need to create additional groups to give access
to all the users who need it (Setting up Groups to Manage Resource Access on
page 50).
World The World category is where you set the permissions for users that are not the
owner and not in the associated group. By default, world access is none, but it
doesn't have to be.
The piadmin user always has read-write access to all resources regardless of access settings.
By default, the pidemo user has read-only access to all objects. For more information about
these two accounts, see What are the piadmin and pidemo User Accounts on page 49.
9.2.4 What are the piadmin and pidemo User Accounts?
By default, each PI Server has two accounts:
The Administrator account, called piadmin, is the super user account. It has
permission to do anything on the PI System, regardless of security settings. This
means that you need to restrict access to the piadmin account to a very small group of
trusted managers. You cannot delete the piadmin account.
Introduction to PI Server
System Management Page 49
Chapter 9 - Managing PI Security
Demonstration account: the pidemo user is the demonstration account. The pidemo
user has permission to look at all the data, but is not allowed to make any changes.
For example, the pidemo user cannot edit a point. You can delete the pidemo account,
if you wish.
The default password is blank for both the piadmin and the pidemo accounts. Since the
piadmin account can do just about anything on the PI Server, you should choose a good
password for the piadmin account and change it periodically. You cannot delete the piadmin
account.
9.2.5 Setting up Groups to Manage Resource Access
When a user is not the owner of a particular PI resource (such as a point or database), PI
checks to see if the user is a member of the group that is associated with that resource. If so,
then the user gets whatever access level the group has.
You can associate only one group with a particular PI resource. This means that, if you want
to configure access for more than one group, you typically need to create a new group that
includes all the users for whom you want to configure access.
For example, the following figure illustrates an organization with three groups: Developers,
Managers and Operators. One user is a member of both the Developers and the Managers
group.
Suppose that all the users in the Developers and Managers groups need read-write access to a
particular resource, such as the attributes for the Sinusoid point. Because a resource can have
only one associated group, you need to create a group that contains all the developers and all
the managers and then associate that resource with the new group.
Page 50
9.2 - Managing Users and Groups
Typically, you create different PI groups for groups in your organization that need different
point access.
9.2.6 Simple Case Example for Managing Groups
Consider the simple example in which you have a single group in your company, developers,
that needs the ability to see and edit point attributes and data. Everyone else in your company
needs to see all the points—but they are not allowed to edit them.
In this case, you create a PI group, called developers and you make all the developers
members of this group. You configure every point's data and attributes to belong to the
developers group (this does not effect the point owner) and you set the group permissions for
all the points to read-write. You set the World permissions for each group to read-only. Now
all the members of the developers group have read-write access to the Data and Attributes for
all the points, and everyone else has read-only access to all the points.
9.2.7 Example for Managing Multiple Groups
Now consider the example in which you have three groups in your company, developers,
managers and operators. Operators need read-only access to the data for the Sinusoid point.
Developers and managers need read-write access to the data for the Sinusoid point. You set
World permissions to read-only, so that the operators can see the point. But, since you can
associate only one group with the Sinusoid point data, you need to create a combination
group, which you might call devMan. All the users in the developers group and all the users
in the managers group belong to the devMan group. You associate the Sinusoid data with the
devMan group, giving all these users read-write access to that data.
9.2.8 Adding, Editing and Deleting Users and Groups
Use the SMT User and Group Editor to add and delete users and groups, to change user
passwords, and to add and remove users from groups:
Introduction to PI Server
System Management Page 51
Chapter 9 - Managing PI Security
1. Run the System Management Tools (How to Run SMT on page 5).
2. Select the Server on which you want to manage the accounts (How to Select a Server
in SMT on page 6).
3. Click to expand the Security item in the System Management Plug-ins pane.
4. From the list of Security plug-ins, double-click on User and Group Editor. The
User and Group Editor plug-in appears in the Active Plug-in pane.
The Users tab lists all the users who have accounts on the selected server. Similarly,
the Groups tab lists all the groups registered on the selected server.
5. To work with users (to add or delete users or to change a password) select the Users
tab. To work with groups (to add or delete a group, or to add users to or delete users
from a group) select the Groups tab.
6. Different icons appear in the toolbar, depending on whether you select the Users or
Groups tab. Some icons are enabled only when you click on an item in the list.
9.3 Managing PI Trusts
As System Manager, you need to update the PI trusts anytime any trusted machine changes
host name or IP address. Use SMT's PI Trust Editor to view and manage your PI trusts.
About Trusts
Managing Trusts with SMT
9.3.1 About Trusts
PI uses trusts to allow access to resources without requiring that someone enter a user name
and password. PI typically uses trusts to grant access to interfaces.
At a bare minimum, every PI Server has the following four trusts:
The PI Server itself, by host name
The PI Server itself, by IP address
The PI Server itself by the special name localhost
The special IP address: 127.0.0.1
Page 52
9.3 - Managing PI Trusts
In addition, you set up a trust for each Interface Node that connects to the PI Server. For each
Interface Node, configure the following three trusts:
The Interface Node by IP address and netmask
The Interface Node by fully-qualified host name (for example, apollo.osisoft.com)
The Interface Node by the short host name (for example, apollo)
The preceding interface trust configuration is the most general configuration. If you want
tighter security, read the section on PI security in the PI System Management Guide.
9.3.2 Managing Trusts with SMT
Use the SMT Trust Editor to view existing trusts and to add, edit or delete trusts:
1. Run the System Management Tools (How to Run SMT on page 5).
2. Select the Server on which you want to manage the trusts (How to Select a Server in
SMT on page 6).
3. Click to expand the Security item in the System Management Plug-ins pane.
4. From the list of Security plug-ins, double-click on Trust Editor. The Trust Editor
plug-in appears in the Active Plug-in pane.
5. To view the settings for an existing trust, right-click on that trust in the list and select
Properties from the resulting pop-up menu. The Trust Properties dialog box appears.
Each trust has a name and three basic areas of information: IP information, Windows account
information, and application information. In addition, each trust has an associated PI user.
You do not need to fill in all the areas in the Properties form. The more details you fill in, the
more restrictive the trust becomes. For example, if you create a trust for a particular
Introduction to PI Server
System Management Page 53
Chapter 9 - Managing PI Security
hostname, then any request from that hostname gets access, based on that trust. However, if
in addition to the hostname, you add an application name, then that trust lets through only the
specified application from that hostname.
9.4 Managing PI Database Security
PI stores its configuration information and process data in databases. You can configure
access to the databases with SMT's Database Security Editor:
About Databases
Managing Databases with SMT
9.4.1 About Databases
The PI Server includes several databases that store PI configuration information and process
data. The two main databases are the Point Database (also called the Point Configuration) and
the Data Archive (usually called simply, the Archive).
Database security is similar to point security, in that you can set Owner, Group and World
permissions for most PI databases. Users need read access to be able to read information
within a database. Users need to have write access in the database to be able to create an item.
For example, write access to the point database allows you to create a point.
You can configure security for the following PI Databases by setting Owner, Group and
World permissions (see What are PI Access Categories on page 48):
Database What it Stores
PI Batch Database (PIBatch) Database for PI Batch objects
PI Digital State Table (PIDS) Contains the digital state sets
PI Heading Sets Database Stores the heading sets for the Module Database
(PIHeadingSets).
PI Module Database (PIModules) Stores and maintains all the data objects associated
with the Module Database, including PIModules,
PIHeadingSets, and PIHeadings
PI Point Database (PIPOINT) Contains the list of points that are either recorded in
the Data Archive or mapped to points in foreign data
systems
PI Transfer Record Database Stores the transfer records for plant materials
(PITransferRecords)
PI User Database (PIUSER) Database where PI users are defined
For comprehensive information on databases, refer to the PI Server Reference Guide.
Page 54
9.4 - Managing PI Database Security
9.4.2 Managing Databases with SMT
The SMT Database Security Editor plug-in provides a simple interface for managing user and
group access to PI databases.To use the Database Security Editor:
1. Run the System Management Tools (How to Run SMT on page 5).
2. Select the Server on which you want to manage the database security (How to Select
a Server in SMT on page 6).
3. Click to expand the Security item in the System Management Plug-ins pane.
4. From the list of Security plug-ins, double-click on Database Security Editor. The
Database Security Editor plug-in appears in the Active Plug-in pane, listing all the PI
databases for which you can configure the access permissions (What are Access
Permissions on page 48).
5. Select the database for which you want to configure access. The Database Properties
dialog box appears.
6. Select your access configuration from the pull-down menus and click OK.
Introduction to PI Server
System Management Page 55
Chapter 10. MONITORING PI SYSTEM PERFORMANCE
As System Manager, you should check regularly on how PI is performing. By creating PI
performance points (called PIPerfmon points) and trending them in a ProcessBook display,
you can see how a system is doing at a glance.
About PI System Performance Monitoring
Which Performance Counters to Monitor
Building Performance Monitor Points
Trending Performance Points
Performance Monitoring Kit (PI 3.4 and Later)
Configuring the PIPerfmon Interface
Note: PI performance points (PIPerfmon points) are different from interface
performance points, which are discussed in Monitoring Interface Performance on
page 44.
10.1 About PI System Performance Monitoring
One important way to monitor your PI System's performance is to record key performance
counters. Performance counters can provide important insights into a number of performance
management problems, including memory, disk, and process management problems.
PI gets performance counter data through the PI Performance Monitor interface, PIPerfmon.
PIPerfmon reads the PI point database to determine which performance counters to monitor.
It then scans for the performance counter and sends exception reports to the PI system.
There are two versions of the PIPerfmon interface, full and basic. The PI Server comes with
the basic version, which is just like the full version, except that it:
Must run on the machine with the PI Server.
Is limited to 512 points.
Allows one instance of the interface.
Will collect data for local performance counters only.
Introduction to PI Server
System Management Page 57
Chapter 10 - Monitoring PI System Performance
To use PIPerfmon to monitor performance, you build a point for each performance counter
you’re interested in (Which Performance Counters to Monitor on page 58) and then create a
ProcessBook display that contains those points (Trending Performance Points on page 59).
You can then open the ProcessBook display and check system performance at a glance.
Note: You can also view the statistics for the PI performance counters in Microsoft’s
Performance Monitor utility (System Monitor in Windows 2000).
10.2 Which Performance Counters to Monitor
The most confusing thing about performance counters for new System Managers is figuring
out which ones to monitor. The following list contains the basic set of performance counters
that OSIsoft recommends you monitor. This list includes some counters that are available
only on PI 3.4 and later. If you are running an earlier version of PI, and don't want to
upgrade, just use the other counters in the list.
PI Performance Counter Tag Name Description
PI Archive Subsystem\Archived Events/sec Rate of successful event addition to the archive.
PI Archive Subsystem\Cache Flush Rate at which points are flushed from the archive
Operations/sec cache to disk.
PI Archive Subsystem\Cache Record Count Archive cache records in memory.
PI Archive Subsystem\Events Read/sec Rate of archive events read.
PI Archive Subsystem\Time to Archive Shift Number of seconds until the archive is projected
to shift. This time is not calculated if the archive
is less than 20% full.
PI Base Subsystem\Module Count Total number of modules in the PI Module
Database.
PI Base Subsystem\Point Count Total number of defined points. This number
includes the Connector Point Count.
PI Snapshot Subsystem\GetSnapshots/sec Rate of events read from the Snapshot.
PI Snapshot Out of order events sent to the Snapshot.
Subsystem\OutOfOrderSnapshots/sec
PI Snapshot Subsystem\Queued Events/sec Events sent to Event Queue.
PI Snapshot Subsystem\Snapshots/sec Events sent to the Snapshot.
PI Archive Subsystem\Primary Archive % Percent of used records in Primary Archive file.
Used Available in PI Server v. 3.4 and later.
PI Archive Subsystem\Total Unflushed Total number of unflushed events. Available in
Events PI Server v. 3.4 and later.
PI Snapshot Subsystem\Events in Overflow Total of events in the overflow queue files.
Page 58
10.3 - Building Performance Monitor Points
PI Performance Counter Tag Name Description
Queues Available in PI Server v. 3.4 and later.
PI Snapshot Subsystem\Events in Primary Number of events in the primary queue file.
Queue Available in PI Server v. 3.4 and later.
PI Snapshot Subsystem\Number of Overflow Number of overflow queue files (0 if only the
Queues primary queue is active). Available in PI Server
v. 3.4 and later.
Note: This table lists only a very small subset of the PI performance counters. The
PI Server System Management Guide provides a comprehensive list of all available
PI performance counters.
10.3 Building Performance Monitor Points
The PI System Management Tools (The PI System Management Tools (SMT) on page 5)
includes a plug-in for building PIPerfmon tags, called the Performance Monitor Tag Builder.
To build a performance monitor point, follow these steps:
1. Run the System Management Tools (How to Run SMT on page 5).
2. Select the Server on which you want to create the performance point (How to Select
a Server in SMT on page 6).
3. In the list of Points plug-ins, double-click on Performance Monitor Tag Builder.
The Performance Monitor Tag Builder appears in the Active Plug-in pane.
4. Under the Tag Settings tab, choose an existing PIPerfmon interface from the pull-
down menu. If no interfaces appears in the list, make sure PIPerfmon is installed and
running on the PI Server (Configuring the PIPerfmon Interface on page 60).
5. Click the Build Tag tab and select the performance monitor points you want to
create from the list of available counters.
6. Click the Create Tags button. The plug-in creates the performance monitor tags for
you.
10.4 Trending Performance Points
If you put your PI-Performance Monitor points on a ProcessBook display, you can check
your PI System performance at a glance. You might also include interface performance points
(Monitoring Interface Performance on page 44) and representative points from each of the
batch, alarm, performance equation, and ACE component.
The following illustration shows the ProcessBook display for the Performance Monitoring
Kit from the OSI Developer’s Network (Performance Monitoring Kit (PI 3.4 and Later on
page 60). This is a good example of a ProcessBook display for performance monitoring.
Introduction to PI Server
System Management Page 59
Chapter 10 - Monitoring PI System Performance
10.5 Performance Monitoring Kit (PI 3.4 and Later)
If you're running PI 3.4 or later, then you can download and use the PI Server Performance
Monitor Kit. This kit gives you a point configuration spreadsheet that allows you to create
your performance points in a matter of seconds, and it also gives you a great Performance
Monitoring display for ProcessBook. You can get this kit from OSIsoft's Developers Network
(http://devnet.osisoft.com).
Note: The Developer’s Network is a useful source of tools and information for PI
System Managers, but the downloads are not actively supported by OSIsoft. If you
have trouble getting, installing or running the Performance Monitor Kit, you cannot
get help from Technical Support. Also, this kit might not work with future releases of
PI.
10.6 Configuring the PIPerfmon Interface
The executable for the basic version of the PIPerfmon interface is included in your PI Server
installation. To configure PIPerfmon on your PI Server, follow these steps:
1. Run the ICU (How to Run the ICU on page 6).
2. On the ICU menu, select New. The Configure a New Interface dialog appears.
Page 60
10.6 - Configuring the PIPerfmon Interface
3. Click the Browse… button and browse to the location of the PIPerfmon executable.
By default, PI installs the PIPerfmon executable in the PIPC directory under:
Interfaces\PIPerfmon_basic
4. Type in a descriptive name for the interface, such as Performance Monitor Interface
or PIPerfmon.
5. Type in a Point Source (What's a Point Source? on page 41). The default point
source for PIPerfmon is the pound sign (#).
6. Type in an Interface ID number (What's an Interface ID Number? on page 42).
7. Select the Host PI System. This can be the PI Server itself.
8. Click OK. A dialog appears saying that the interface is ready to be configured.
9. Click OK.
10. If you're using the Performance Monitor Kit from DevNet, add the following scan
classes for the interface (What's a Scan Class? on page 42):
00:00:05
00:01:00
11. Click Apply.
12. Under the Service Tab, type in a user name and password for a Windows account
with Administrative privileges on the PI Server, then click the Create button. This
installs the interface.
Introduction to PI Server
System Management Page 61
Chapter 10 - Monitoring PI System Performance
13. Click the Start the Interface arrow button at the top of the ICU. This starts the
interface.
Page 62
Chapter 11. MANAGING BUFFERING
If you are not currently using the buffering service on your Interface Nodes, refer to
Configuring Interfaces for Buffering on page 45. Once it's running, buffering typically takes
care of itself.
About Buffering
Checking whether the Buffering Service Is Running
Testing the Buffering Service
If the Buffering Service Isn't Working
Starting the Buffering Service
11.1 About Buffering
OSIsoft provides a buffering service that can save your data if the Interface Node loses its
connection to the PI Server. When an Interface Node is running the buffering service
(bufserv), data flows from the data source, through the interface to the buffering service and
from there to the Snapshot Subsystem on the PI Server.
Data Flow with Buffering
If the PI Server is not available (e.g., for an upgrade on the Server) then bufserv stores the
data in a file buffer on the Interface Node. When the PI Server becomes available again,
bufserv sends all the stored data from the buffer, in chronological order, back to the PI
Introduction to PI Server
System Management Page 63
Chapter 11 - Managing Buffering
Server. At this point, if you look at the data in ProcessBook, you see a continuous flow of
data, with no gaps.
As System Manager, you should make sure that the buffering service is running on each
Interface Node. The main exception to this rule is for PINet Nodes, which perform their own
buffering. Also, a few interfaces, such as batch file and event file, work better without the
buffering service. If you're not sure whether a particular interface is compatible with the
buffering service, check the documentation for that interface.
You need only one buffering service running on each Interface Node to buffer all the
interfaces for a particular Server, however you can only buffer data to one Server at a time
from each Interface Node. You can set the maximum size of the file buffer (up to 2GB) in the
ICU (Configuring Interfaces on page 43).
11.2 Checking whether the Buffering Service Is Running
To check whether buffering is running on an Interface Node look for the APIBE process for
that particular Interface Node in the Network Manager Statistics SMT plug-in:
1. Run the System Management Tools (How to Run SMT on page 5).
2. Select the Server that is connected to the Interface Nodes you want to check (How to
Select a Server in SMT on page 6).
3. It's easier to check one PI Server at a time, so while you're in the PI Servers pane,
click to deselect all other PI Servers. Now there should be only one checkmark in the
PI Servers pane.
4. Click to expand the Operation item in the System Management Plug-ins pane.
5. From the list of Operation plug-ins, double-click on Network Manager Statistics.
The Network Manager Statistics plug-in appears in the Active Plug-in pane.
6. Click on the Name column header to sort the list alphabetically by service (or
application) name.
Page 64
11.3 - Testing the Buffering Service
7. Now look in the Name column for the buffer service, which in this display is called
APIBE. You should see one APIBE connection for every Interface Node that is
running the buffering service.
8. For each APIBE row in the table, look under the PeerName column to find the
hostname for the Interface Node associated with that particular buffering service.
(The IP address is also listed, under the PeerAddress column.)
9. Interface Nodes that do not have an APIBE application associated with them are not
running the buffering service.
10. Start the buffering service on all Interface Nodes where it is not running (Starting
the Buffering Service on page 68).
Note: If you are looking for a particular Interface Node among many, click the
PeerName heading to sort the table by host name.
11.3 Testing the Buffering Service
The only way to actually test whether the buffering service is working is to interrupt the
connection between the PI Server and the Interface Node for a period of time and then, after
restoring the connection, check to see whether you have data:
Introduction to PI Server
System Management Page 65
Chapter 11 - Managing Buffering
11.3.1 When should I test the buffering service?
The best time to check the buffering service is when you're shutting down the PI Server
anyway. For example, if you stop your PI Server for software upgrades or other maintenance,
be sure to check for data loss after you restart.
Also, if your network connection goes down so that the PI Server loses its connection to the
Interface Node anyway, that's a great time to check that your data was saved by the buffering
service.
If you decide to interrupt the connection between an Interface Node and the PI Server for a
buffering test, choose a time when your PI users will be least inconvenienced by missing data
and access to the PI Server. Do this test once or twice a year.
11.3.2 How do I test the buffering service?
To test the buffering service, unplug the PI Server from the network:
1. Choose a time when your PI users will be least inconvenienced by missing data and
access to the PI Server.
2. Send a memo or email warning users in advance of the test and telling them how long
the Server will be off the network.
3. Unplug the network connections from the back of your PI Server for a few minutes.
4. Plug the connections back into the PI Server.
5. Notify your users that the PI Server is back on the network.
6. Open ProcessBook and look to see if you have continuous data (it might take several
minutes for PI to fully restore the data). If you do have continuous data, then your
buffering is working correctly. If you have gaps in your data, then the buffering isn’t
working properly (If the Buffering Service Isn't Working on page 66).
Note: Why unplug the PI Server and not the Interface Node? Because many
Interface Nodes get their data from the network. If you unplug such an Interface
Node from the data source, then the interface gets no data and you can’t test data
buffering.
11.4 If the Buffering Service Isn't Working
If the buffering service is not working correctly, first check the login information for the
buffering service, then check the pipc.log file.
11.4.1 How to Check the Login Information for Buffering
Be sure that bufserv service is set to run under a local Windows Administrator account on the
Interface Node, not under System Account, or any other unprivileged account. To check this,
follow these steps:
1. From the Windows Start menu, open the Control Panel and then open
Administrative Tools.
Page 66
11.4 - If the Buffering Service Isn't Working
2. In the Administrative Tools folder, double-click on Services.
3. In the Services window, right-click on PI-Buffer Server and select Properties from
the resulting pop-up menu.
4. Click the Log On tab and enter the account information for a Windows account that
has administrative privileges on this Interface Node. Do not use the System account.
5. Click on the General tab and click the Start button under Service status.
6. Click OK.
Note: Make sure the interface that you are buffering is running under this same
Windows account. The buffering program shares memory between bufserv and the
interface. If they are not running under the same account then they can not share
memory and buffering will not work.
Introduction to PI Server
System Management Page 67
Chapter 11 - Managing Buffering
11.4.2 How to Check the pipc.log File
PI writes messages about the interfaces in the pipc.log file. If you’re having trouble with the
buffering service, it’s a good idea to check the log file:
1. From the Windows Start menu on the Interface Node, point to Programs, point to
PI System, and then click PI-Interface Configuration Utility. The ICU appears.
2. On the Tools pull-down menu, click Log Files… The Log File dialog box appears.
3. In the Log Files dialog box, double-click on the pipc.log entry. The pipc.log file
appears.
4. If you see the error message, “Unable to create shared memory buffers” you're
probably trying to run the buffering service under an account that does not have
administrative privileges. Follow the instructions in Starting the Buffering Service on
page 68.
11.5 Starting the Buffering Service
These instructions assume that you are starting the buffering service on an Interface Node
that is configured for buffering (Managing Buffering on page 63) and that the following items
are installed on the Interface Node:
The interface software for the interface(s) you want to buffer
PI Interface Configuration Utility (ICU)
PI API (this is installed with the interface software)
PI-SDK (this is installed with the ICU)
To start the buffering service on an Interface Node, follow these steps:
1. From the Windows Start menu on the Interface Node, point to Programs, point to
PI System, and then click PI-Interface Configuration Utility. The ICU appears.
2. Select an interface from the Interface pull-down menu. If the interface you want
does not appear in the Interface pull-down menu, then you need to register that
interface with the ICU (Configuring Interfaces on page 43).
Page 68
11.5 - Starting the Buffering Service
3. On the Tools menu, point to API Buffering. The Buffering dialog box appears.
4. Under the Settings tab, make sure the Enable buffering checkbox is checked.
5. Change the maximum file size, if necessary. The maximum is 2GB.
6. Under the Service tab, type in the name and password for a Windows account that
has administrative privileges on this computer.
7. Click OK.
8. From the Windows Start menu, open the Control Panel and then open
Administrative Tools.
9. In the Administrative Tools folder, double-click on Services.
Introduction to PI Server
System Management Page 69
Chapter 11 - Managing Buffering
10. In the Services window, right-click on PI-Buffer Server and select Start from the
resulting pop-up menu. The buffering service should start now. If it doesn't, see If the
Buffering Service Isn't Working on page 66.
Page 70
Chapter 12. MANAGING DATA SOURCE EQUIPMENT
Changes to your plant or process equipment sometimes mean you need to make changes to
PI.
About Data Sources
Adding New Equipment
Replacing Equipment
Removing Obsolete Equipment
12.1 About Data Sources
Your data sources can be almost anything, including Distributed Control Systems (DCSs),
Programmable Logic Controllers (PLCs), lab systems, Supervisory Control and Data
Acquisition systems (SCADA), process models, and other business information systems.
12.2 Adding New Equipment
When new equipment comes online, you need to configure PI to recognize it and set up
points to collect the data:
Connect the equipment to an Interface Node and install the appropriate interface
software. You can download interface documentation from the Technical Support
Web Site (http://techsupport.osisoft.com). If this is a new Interface Node, you also
need to install the ICU (How to Install the ICU on page 6) and set up the trusts
(Managing PI Trusts on page 52).
Install the interface according to the instructions in the interface documentation.
Register and configure the interface with the ICU (Configuring Interfaces on page
43).
Start the buffering service, if it isn't already running on this Interface Node (Starting
the Buffering Service on page 68).
Build a new point(s) to get the data from the equipment into PI (Creating New Points
on page 23).
Introduction to PI Server
System Management Page 71
Chapter 12 - Managing Data Source Equipment
12.3 Removing Obsolete Equipment
When equipment goes offline, you need to decommission any points associated with that
equipment (Decommissioning Points on page 24).
If you do not decommission obsolete points, the PI System continues to try to get values for
them, which is bad for system performance and can sometimes even lead to data loss for
other points.
12.4 Replacing Equipment
If you replace an instrument with a different one that measures the same process value, it's
usually best to continue using the same PI point. Edit the point as required so that it will
collect the new data. If the instrument is significantly different, you might need to adjust the
compression and exception attributes, among others. Don't change the Tag attribute.
When you change the point, insert a digital event into the data to indicate when the transition
from the old to the new instrument took place.
Page 72
Chapter 13. WHERE TO GO TO GET MORE HELP
13.1 Training
OSIsoft offers training classes and computer-based training (CBT) CDs on managing PI
Servers. For more information, look at the OSIsoft training website:
http://training.osisoft.com
13.2 Technical Support Web Site
The OSIsoft Technical Support Web site (http://techsupport.osisoft.com) has great
information for PI System Managers. Check the site daily for support bulletins and for
information about software updates.
You can also download software and documentation from the Download Center on the
Technical Support Web site. To do this, you must first sign in (or register and then sign in).
This Web site also has a System Manager Resources area that provides how-to information,
as well as tips and tricks for PI System Managers.
13.3 Developers Network
The OSIsoft Developers Network (DevNet) is a Web site dedicated to helping PI users and
developers create productive PI applications. PI users post a lot of these homegrown
applications on the DevNet site so, even if you're not interested in developing your own PI
applications, you're still likely to find some useful tools and information on DevNet. The
DevNet Web site is here:
http://devnet.osisoft.com
Introduction to PI Server
System Management Page 73
Chapter 14. GLOSSARY
Annotation
Arbitrary information (e.g. text comment, other binary data) that can be associated
with any archive value. Annotations are accessed exclusively with the PI-SDK and
are stored in an archive file’s corresponding annotation file
(<archive_filename>.ANN). The maximum size of an annotation is equal to the page
size in the Event Queue, which is 1 MB by default with a maximum of 8 MB.
API
A C-based Application Programming Interface library of functions that enable
programs to access PI Servers locally or remotely across a network. PI ProcessBook
2.x (and earlier), PI DataLink 2.x (and earlier), a majority of interfaces, and many
custom programs depend on this library.
API Node
A synonym for Interface Node.
Archive
The historical record of time-series data maintained by the PI Server. The term is
often overloaded: sometimes it’s used to refer to the entire logical data record itself;
sometimes it’s used to refer to a specific archive file; and sometimes it’s used to refer
to the subsystem responsible for actively hosting the historical data record.
Archive Event
Any Event that is stored in the Archive.
Archive File
A binary file that contains a section of the data archive covering some finite time
range. These files, defined by start and end times, should be contiguous and non-
overlapping. Two types of archive files may be created: Dynamic and Fixed.
Introduction to PI Server
System Management Page 75
Glossary of Terms
Archive Gap
A non-zero period of time between the end time of one archive file and the start time
of the chronologically next archive file. Archive gaps are not desirable because
archive events with a timestamp during the gap cannot be stored on disk in an archive
file and will be discarded. To avoid archive gaps, archive files should always be
created such that the end time of one archive equals the start time of the
chronologically next archive.
Archive Queue
A less commonly used synonym for Event Queue.
Archive Shift
The process of clearing the oldest writeable and shiftable archive file and making it
the new primary archive. An archive shift typically happens automatically when the
previous primary archive becomes full, but it sometimes must be performed manually
for maintenance and troubleshooting purposes.
Archive Shift Flag
A flag that controls whether or not a particular archive file can participate in archive
shifts. If the flag is disabled (set to 0), then that specific archive file will not
participate in archive shifts. Unlike a fixed archive, once a dynamic archive receives
any data, the shift flag is automatically and permanently disabled.
Archive Subsystem
The core PI Server component that is responsible for writing data to, reading data
from, and otherwise managing the complete data archive. The Archive Subsystem is
very tightly coupled with the Snapshot Subsystem, which is actually responsible for
performing compression on the incoming data.
Argument, Command-Line
User input specified after the name of a program to control or modify the behavior of
that program in some fashion. A command line argument must typically be separated
from the program name and other command line arguments by at least one space.
Depending on the program, command line arguments must typically be prefixed by a
hyphen (‘-’) or a slash (‘/’). Several of the diagnostic utility programs that are
distributed with the PI Server like piartool and pidiag will require the use of one or
more command line arguments.
Attribute, Point
A characteristic or parameter of a point that directs an interface and the PI Server in
the collection and processing of data values for that point.
Page 76
Glossary of Terms
Attribute Set
A named collection of attributes. One or more attribute sets are used to define point
classes to establish the complete list of attributes that can specified when creating or
modifying a point of that class.
Base Point Class
The common set of point attributes that all other point classes include. The Base class
includes both system- and user-assigned attributes.
Base Subsystem
The core PI Server component that is responsible for hosting several configuration
stores such as the Point database, the User and Group database, and the Trust table.
The Base Subsystem also hosts the hierarchical Module Database.
Batch
A batch represents a span of time on a unit.
Batch Alias
An additional name, usually the common name, for a unit attribute. A batch alias
allows batch users and applications to reference the more natural common name of a
unit attribute instead of its more obscure instrument name, which may only be readily
understood by the instrument or process engineer.
Batch Database (BDB)
A logical collection of batch objects hosted by the Module Database and the Archive
Subsystem. All access to the Batch Database is provided exclusively by the SDK.
The Batch Database is independent of the older batch information store maintained
by the Batch Subsystem.
Batch Generator (PIBaGen)
An SDK-based interface that writes batch information into the Batch Database. The
interface detects batch activity by monitoring specific points on the PI Server for
events that trigger the beginning and ending of a batch.
Batch Subsystem (BSS)
A PI Server process that is responsible for configuring, monitoring, and recording
batch activity in the data archive. The main interface to the Batch Subsystem is
provided by piconfig. Read-only access to the batches recorded by the Batch
Subsystem is typically provided by the API, but it is possible to map Batch
Subsystem units to the Batch Database so that their batches can also be accessed by
Introduction to PI Server
System Management Page 77
Glossary of Terms
the SDK. The batch information store maintained by the Batch Subsystem is
independent of the newer Batch Database.
BatchView
A Windows client application that allows the viewing of batch data from the Batch
Database and the Batch Subsystem. BatchView consists of three different
components: an SDK-based ProcessBook Add-In, an API-based Excel Add-in, and a
stand-alone SDK-based application for quick batch searching.
Blob Point Type
The acronym for Binary large object and the point type typically chosen for an
arbitrary unstructured array of bytes. Interpretation of the bytes can only be
performed by the retrieving application. Because the record size in archive files is
currently fixed in size at 1024 bytes, the value of a single event for a Blob point can
contain binary data of up to only 976 bytes in length. If larger binary objects must be
written, then either the binary data must be split into multiple events for the Blob
point or the data must be stored as an annotation.
Buffering Service
An API process that typically runs on an Interface Node for the purpose of storing
interface data during periods when network communication to the PI Server is
unavailable. When network communication is restored, the buffering service relays
the stored data to the PI Server. Because the buffering service works to help prevent
data loss but is disabled by default, enabling and configuring buffering is a critical
task for an administrator.
Bufserv
The executable or process name that performs the Buffering Service.
Calculated Point
A synonym for PE Point.
Calculated Tag
A synonym for PE Point.
Classic Point Class
The common set of attributes required by most standard OSIsoft interfaces, such as
Location1 and Location4.
Page 78
Glossary of Terms
Clock Scheduling
A method of triggering program execution to occur based on a fixed time or clock
schedule such as that defined by a scan class. Clock scheduling is one method
available for triggering PE or ACE calculations. Another method is Event
Scheduling.
COM Connector
A COM object designed to allow the PI Server to access data from foreign data
sources and make it available to any PI client application in a seamless fashion. Some
currently available COM Connectors include those for data historians from
AspenTech and Honeywell as well as one for any data source with an OLEDB
provider. In order to function, all COM Connectors require the services provided by
the Redirector. COM Connectors are only available on Windows platforms.
COM Connector Point
A point belonging to a special point class that has at least three attributes defining
how to reference a particular value on a foreign data source. One of the attributes is
the name of the COM Connector needed to communicate with the foreign data
source. These points are only available on Windows platforms.
CompDev
The base attribute that specifies the compression deviation in engineering units. This
represents the maximum error when historical data values need to be interpolated
and, at the very least, should typically be set to the error of the underlying instrument.
CompDevPercent
The base attribute that specifies compression deviation as a percentage of Span,
another base attribute. The relationship is defined by the following equation:
CompDev = (CompDevPercent / 100) * Span. If both CompDev and
CompDevPercent are specified when creating or editing a point, CompDevPercent
takes precedence.
CompMax
The base attribute that specifies the compression maximum time, in seconds.
CompMax is the maximum time difference from the previous archive event before
the next event will be sent to the archive. Because the PI Server itself never generates
events, a lower bound on the archiving rate for the associated point cannot be
determined from CompMax alone.
CompMin
The base attribute that specifies the compression minimum time, in seconds.
CompMin is the minimum time difference from the previous archive event before the
Introduction to PI Server
System Management Page 79
Glossary of Terms
next event is eligible to be archived. Because the PI Server itself never generates
events, the archiving rate for the associated point will be at most one event every
CompMin seconds.
Compressing
The base point attribute that controls whether or not compression is performed for a
particular point. If Compressing is disabled (set to 0), then all events will bypass
compression.
Compression
The process of selecting which Snapshot events will be sent to the Archive for
storage. Applying compression is one of the main responsibilities of the Snapshot
Subsystem, and the specific algorithm used is known as Swinging Door
Compression.
Compression Specification
The three base attributes that control the compression process for a particular point:
CompDev, CompMax, CompMin. Although they are technically not included in the
specification, CompDevPercent and Span affect CompDev, and Compressing
determines whether the specification is needed at all.
Connection Credentials
The set of identifying information about a client application seeking connection to
the PI Server. This information can include the client computer’s IP address or
hostname, the client application’s name, or the Windows Domain name and
Windows user name under which the client application is running. API applications
are restricted in the credentials that they can specify. The PI Server uses connection
credentials to determine if there is a matching Trust.
D Point Type
Interface manuals sometimes refer to the D point type. This is synonymous with
Digital Point Type.
Data Archive
The fundamental and most important information store of the PI Server that contains
the historical data record of all events for all points. The Data Archive is commonly
referred to as simply the Archive.
Data Source Node
A synonym for Interface Node.
Page 80
Glossary of Terms
Data Type
The kind of value that will be used. Both points and point attributes have a data type.
Some of the possible types include several kinds of numbers, digital, string, and
Blob.
Descriptor
The base point attribute that can be used to provide a textual description of a point.
The Descriptor is a common attribute to display in various client applications and
user reports.
Deviation Blanket
In compression, the conceptual parallelogram with a width that extends from the
previous archive event to the current event and a height equal to twice the
compression deviation.
DigitalSet
The base attribute required for all digital points to indicate the appropriate digital set
containing the list of possible digital state values for the point.
Digital Point Type
A point type typically used when values can only be one of several discrete states,
such as ON/OFF or Red/Green/Yellow. This point type is the nearest equivalent to
the PI 2.x Digital type.
Digital State Set
A named collection of digital states. For example, a digital state set called
ValveStates may contain the two possible discrete states of a valve: OPEN and
CLOSED.
Digital State Table
A table that contains the complete definition of all defined digital state sets. This
table is hosted by the Base Subsystem.
Distributed Data Collection
Gathering data from multiple sources and from more than one computer on a
network. The PI System is designed to work extremely well in an environment with
distributed data collection.
Introduction to PI Server
System Management Page 81
Glossary of Terms
Dynamic Archive
A type of archive file that does not pre-allocate its disk space at creation time but
instead grows as needed. A dynamic archive can be configured to grow up to a
maximum size and support a maximum number of points, but a non-empty dynamic
archive cannot participate in archive shifts. Another archive type is a Fixed Archive.
Event
The fundamental unit of information used in the PI Server. Each event consists of
two main components: a value and a timestamp. The value can be one of several
different data types (e.g. string, digital, int32, float64). The timestamp is always
represented as UTC seconds and can contain a sub-second component.
Event Queue
A buffer consisting of one or more memory-mapped files that stores events that have
passed or bypassed compression and are destined for archive storage. The Snapshot
Subsystem writes events into the Event Queue, and the Archive Subsystem reads
events out of the Event Queue. While events are still in the Event Queue, they are not
visible by any client applications. Under normal operating conditions, the Event
Queue should typically be empty.
Event Scheduling
A method of triggering program execution when some specific condition occurs such
as the arrival of a new Snapshot event for a particular point. Event scheduling is one
method available for triggering PE or ACE calculations. Another method is Clock
Scheduling.
ExcDev
The base attribute that specifies exception deviation in engineering units. ExcDev
specifies the deadband or how much a new value must differ from the previous value
sent to the Snapshot Subsystem on the PI Server in order to determine whether the
new value is significant and should also be sent.
ExcDevPercent
The base attribute that specifies exception deviation as a percentage of Span, another
base attribute. The relationship is defined by the following equation: ExcDev =
(ExcDevPercent / 100) * Span. If both ExcDev and ExcDevPercent are specified
when creating or editing a point, ExcDevPercent takes precedence.
Exception Reporting
The process, normally executed by an interface program or external system, of
sending events to the Snapshot Subsystem on the PI Server only when there has been
Page 82
Glossary of Terms
a significant change in the monitored value. Significance is determined with a simple
deadband algorithm.
Exception Specification
The three base attributes that control the exception reporting process for a particular
point: ExcDev, ExcMax, and ExcMin. Although they are technically not included in
the specification, ExcDevPercent and Span affect ExcDev.
ExcMax
The base attribute that specifies exception maximum time, in seconds. ExcMax is the
maximum time difference from the last sent event before the next event will be sent.
ExcMax thus effectively limits the length of time that events can be discarded
because their values did not exceed exception deviation.
ExcMin
The base attribute that specifies exception minimum time, in seconds. ExcMin is the
minimum time difference from the last sent event before the next event is eligible to
be sent. Thus, the send rate of events for the associated point can be at most one
event every ExcMin seconds.
Firewall
A table hosted by Network Manager that provides the first level of security access to
a PI Server. Access can either be allowed or disallowed based on the IP address or
hostname of a client computer.
Fixed Archive
A type of archive file that allocates all of its disk space at creation time. Thus, both
an empty and full archive occupy the same amount of disk space. Unless shifting has
explicitly been disabled, non-empty fixed archives will participate in archive shifts.
Another archive type is a Dynamic Archive.
Float16 Point Type
The only floating-point type that is scaled. The accuracy is one part in 32767, and the
range is defined by the Zero and Span base attributes. This type is the nearest
equivalent to the PI 2.x Real type.
Float32 Point Type
The floating-point type typically chosen for single-precision floating-point values.
This type is not scaled.
Introduction to PI Server
System Management Page 83
Glossary of Terms
Float64 Point Type
The only floating-point type capable of storing double-precision floating-point
values. This type is not scaled.
Home Node
A computer running the PI Server software or the network location (IP address or
hostname) of such a computer.
I Point Type
Interface manuals sometimes refer to the I point type. This is synonymous with either
Int16 Point Type or Int32 Point Type.
Initializing Archive
The process of writing all the primary records, one for each existing point, to an
archive file and cleaning and preparing overflow records in order to receive data.
Int16 Point Type
The integer point type typically chosen for values that are 15-bit unsigned integers (0
to 32767). This type is the nearest equivalent to the PI 2.x Integer type.
Int32 Point Type
The only integer type capable of representing 32-bit signed integers. Because the
lowest 32K values of the 32-bit range are reserved for digital states, the effective
useful range of possible integer values is -2147450880 to 2147483647.
Interface Configuration Utility (ICU)
A Windows GUI application installed on an Interface Node for the purpose of easing
the burden of managing interfaces and their configuration files.
Interface Node
A computer running one or more PI interfaces or the network location (IP address or
hostname) of such a computer.
Interface
A software program that collects data from some type of data source and sends the
data to a PI Server. Some interfaces also have the ability to read data from a PI
Server and write back to the data source.
Page 84
Glossary of Terms
Interface Status Utility (ISU)
A standalone program for determining whether or not an interface is sending fresh
data to the PI Server.
Ipisql Utility
An interactive command line program that executes SQL statements directed at the
PI Server. The utility depends on the API to communicate to the PI Server.
Mapped Point
A synonym for COM Connector Point.
Message Subsystem
The PI Server component that records informational and error messages from various
PI Server subsystems in a series of log files. The Message Subsystem can also serve
these messages to various client applications.
Module Database (MDB)
A hierarchical information store hosted by the Base Subsystem that consists of one or
more Modules. Each Module contains collections of Properties, Aliases, and other
Modules.
Module Database Builder
An SDK-based Excel Add-In that allows the creation, modification, or viewing of
elements of the Module Database in a spreadsheet. The Module Database Builder is
the ideal user interface when performing bulk operations on the Module Database.
Network Manager
The core PI Server component that handles all communication between the PI Server
subsystems. Network Manager also manages all connections from client applications
and their communication with the PI Server.
Node
A computer on a network or the network location (IP address or hostname) of such a
computer.
ODBC
The driver software that exposes a PI Server as an ODBC-compliant data source and
thus provides the PI Server with the ability to communicate with any ODBC-
compliant client application that needs to access the process data stored on the PI
Server.
Introduction to PI Server
System Management Page 85
Glossary of Terms
Offline Archive Utility
The same program that runs the Archive Subsystem, but just in a different mode. The
offline archive utility is used for a variety of archive maintenance tasks such as
merging multiple archives files into a single archive file or reprocessing an archive
file to recover it from a corrupt or failed state.
Offset
An optional field used when defining a scan class that specifies the first time at which
a scan should occur. If no offset is specified, the first scan occurs immediately after
the specified interval. After the initial scan, subsequent scans continue to occur after
every specified interval.
Out of Order Event
An incoming event whose timestamp is prior to the timestamp of the event currently
residing in the Snapshot table for a particular point. All such events bypass
compression and are written directly to the Event Queue.
Owner
The individual user that has permission to view and edit a resource on the PI Server.
Each resource can have only one owner. Two examples of resources include a point’s
data (attribute name: DataOwner) and a point’s configuration (attribute name:
PtOwner).
PE Point
A PI point whose value is calculated by the Performance Equation (PE) Scheduler
based on the point’s configured performance equation specified in the ExDesc base
attribute.
Perfmon (PIPerfmon)
The Windows-only Performance Monitor interface which reads Windows
Performance Counters and stores the values in PI points. The basic version of the
interface can only monitor a limited number of Windows Performance Counters from
the local computer.
Performance Equation (PE)
An expression that allows a user to implement an arbitrary and potentially
sophisticated calculation without formal programming. A performance equation has
an intuitive syntax and may consist of standard mathematical and logical operators as
well as a wide variety of built-in functions. The result of a performance equation can
be archived for a PE point just like data for any other point. Performance equations
are also available programmatically via the SDK for archive calculations and other
data filtering operations.
Page 86
Glossary of Terms
Performance Equation Scheduler (PIPESCHD)
The hybrid interface and subsystem on the PI Server responsible for evaluating
performance equations for all points that specify its point source (default: ‘C’).
Performance Point
An overloaded term that can mean either a point associated with the Perfmon
interface or a special point used to monitor interface performance on a per-scan class
basis. In the case of monitoring interface performance, the point tracks how long (in
seconds) the interface took to collect data for all tags in that scan class for each scan.
PI2
Nickname for the original generation of the PI Server software that (still) runs on
VAX and Alpha computers with the OpenVMS operating system.
PI3
Nickname for the current generation of the PI Server software that runs on computers
with the Windows or UNIX operating systems.
PI Server
The set of several software subsystems packaged together that constitute a single
logical server application capable of storing time-series data from distributed data
sources and serving this same data to client applications in real-time.
PI System
The complete collection of OSIsoft software applications running on one or more
computers that function to collect, store, retrieve, analyze, view, or manage process
data. Examples of these software applications include interfaces, the PI Server, and
client applications.
Piarchss
The executable or process name that implements both the Archive Subsystem and the
Offline Archive Utility.
Piarcreate
A command line utility program for creating both fixed and dynamic archive files.
After creation, the archive files must be registered with the Archive Subsystem in
order to be made available for use.
Introduction to PI Server
System Management Page 87
Glossary of Terms
Piartool
A command line utility program that provides a number of diagnostic and
management functions. The PI Server must be started for nearly all of the commands
to function properly.
Pibasess
The executable or process name that implements the Base Subsystem.
Pibatch
The executable or process name that implements the Batch Subsystem.
Piconfig
An interactive command line utility program that provides access to nearly all the
configuration and data stores maintained by the PI Server. Several client applications
have come along to provide a graphical interface to these various tables and
databases, but certain tasks can still only be performed with this command line
utility. To achieve some degree of automation, a series of piconfig commands can be
saved to a text file which can then be passed as input to piconfig.
Pigetmsg
A command line utility program that allows the viewing of PI Server messages stored
by the Message Subsystem. Messages can be retrieved based on characteristics like
timestamp, a search string, or the program name that generated the message.
Pilistupd
A command line utility program that displays information about the registered
consumers and producers maintained by Update Manager. Consumer info includes
the number of outstanding events in its buffer.
Pinetmgr
The executable or process name that implements Network Manager.
PINet on OpenVMS
Software running on a remote VMS computer that collects data from interfaces and
sends it to a PI Server for data archiving.
Ping
An interface that monitors the network availability of computers by directing an
ICMP ping request agai them and then storing the response times in PI points. A
basic version of the interface is included with the PI Server.
Page 88
Glossary of Terms
PIonPINet/VMS
Software running on a remote VMS computer that includes all the PINet on
OpenVMS functionality as well as additional utility programs for analysis, reporting,
and graphical displays of process data.
Pipeschd.bat
The script file containing the startup configuration for the Performance Equation
Scheduler.
PIPOINT Table
A synonym for Point Database. In piconfig, the table that provides access to the Point
Database.
Pishutev
The executable or process name that implements the Shutdown Subsystem.
Pisnapss
The executable or process name that implements the Snapshot Subsystem.
Pisqlss
The executable or process name that implements the SQL Subsystem.
Piupdmgr
The executable or process name that implements Update Manager.
Point
A variable whose value is measurable and typically dynamic. Examples include
transmitter readings, status indicators, manual inputs, control limits, etc. Each point
must be assigned a unique tag on the PI Server, and measurements of the point
captured over time are effectively stored as an array of timestamped values in the
data archive.
Point Class
A collection of one or more attribute sets. Examples of point classes include Base,
Classic, Alarm, and Totalizer. All point classes include all the attributes from the
Base class, which has a core set of attributes needed by various processes in the PI
System. Other point classes add attributes needed to provide functionality for certain
processes. The base attribute PtClassName specifies the point class for every point.
Introduction to PI Server
System Management Page 89
Glossary of Terms
Point Configuration
The complete list of attributes characterizing a point.
Point Database
The information store that contains the list of all points and their complete point
configuration. The list includes both typical points that have their data stored in the
archive and COM connector points that have their data stored on foreign data
sources. The point database is hosted by the Base Subsystem.
Point Identifier (PointID)
The unique number used to identify a point. This is primarily meant for internal use
within the PI Server, but it is often needed in API / SDK programming and
troubleshooting scenarios. Point identifiers are assigned sequentially as points are
created, and they are not reused if points are deleted. The base attribute PointID
stores a point’s assigned number after creation.
Point Security
Access control for a point which consists of specifying an owner and a group and the
respective read / write permissions. Each point has one security specification for
controlling access to its attribute configuration and a second separate security
specification for controlling access to its archive data. The base attribute PtAccess
holds the security specification for configuration, and the base attribute DataAccess
holds the security specification for archive data.
PointType
The base attribute that specifies the data type for the values that a point stores. The
possible point types include the following: int16, int32, float16, float32, float64,
digital, string, Blob, and timestamp. PointType can be edited after point creation, but
not all type transitions are allowed.
PointSource
The base attribute that identifies the interface or other scanning software responsible
for providing data for the associated point.
Posting
Sending events packaged into messages that contain either 128 or 256 events
(depending on the server platform), from the Snapshot Subsystem to the Archive
Subsystem. Posting is typically no longer performed with the introduction of the
memory-mapped Event Queue in later versions of the PI Server.
Page 90
Glossary of Terms
Postprocessing
Processing by the Totalizer on the values stored in the Snapshot table that enables
accurate counting and summary calculations. The results of these operations are then
stored in other points.
Primary Archive
The archive file with an end time of current time. All events recorded with a
timestamp after the start time of the primary archive are stored in this archive file.
Thus, the primary archive typically contains the most recent data for all points. At
most one primary archive may be registered at any given time.
Product
In batch processing, the description of a specific material or class of materials. This
term is used in batch applications that use equipment to produce a variety of different
materials.
R Point Type
Interface manuals sometimes refer to the R point type. This is synonymous with the
Float16 Point Type or Float32 Point Type or Float64 Point Type.
Ramp Soak
A standard interface program included with the PI Server that generates signals that
might have come from a batch process. This interface is useful for testing and
validating a PI Server without affecting actual process data.
Random Simulator
A standard interface program included with the PI Server that is capable of
generating a sinusoidal wave and several kinds of pseudo-random data. This interface
is useful for testing and validating a PI Server without affecting actual process data.
Real-time SQC
The component of the PI Server that provides continual evaluation of Statistical
Quality Control pattern tests and the management of alarms generated from these
tests. Use of this component will assist in monitoring how well a process stays within
its control limits.
Recalculator
The component of the PI Server that adjusts the values of PE points automatically
whenever the values of points used in their expressions are added, edited, or deleted
by any application.
Introduction to PI Server
System Management Page 91
Glossary of Terms
Redirector
The component of the PI Server that functions as the intermediary between server
subsystems and all COM connectors. The redirector is an out-of-process COM server
that is only available on Windows platforms.
Registering an archive
Informing the Archive Subsystem of the name and location of an archive file that is
available for use. Registering an archive can be performed with several different
programs including piartool and SMT.
Satellite node
Any remote computer on a network running PI software other than the PI Server
software. Examples of the software the computer might be running include interfaces,
PINet, or PIonPINet.
Scan
The base attribute that specifies whether or not the interface or scanning program
should collect new data for the associated point. If Scan is disabled (set to 0), then
new data will not be collected.
Scan Class
A specification that provides an interface with the schedule for performing data
collection for its associated points. The scan class specification consists of a period
and an optional offset. The period determines the recurring interval when data
collection should occur, and the offset determines when data collection should first
start. A scan class can also optionally contain a code to force the interface to use
UTC time for scheduling. A point can only be in one scan class, and assignment to a
scan class is typically configured through the classic attribute Location4.
SDK
A COM-based Software Development Kit that provides rich access to objects and
data stored on the PI Server. The SDK is used for other PI applications like
ProcessBook 3.x and DataLink 3.x and also for custom user applications. The SDK is
only available for Windows platforms, but it can access a PI Server running on any
supporting operating system. The distribution kit for the SDK also includes the API.
Shutdown Event
An Event whose value consists of the Shutdown digital state from the SYSTEM
digital set and whose timestamp is intended to mark when the PI Server or an
interface or some other application or device is not available.
Page 92
Glossary of Terms
Shutdown Subsystem
The component of the PI Server that writes a shutdown event for all points that match
a particular tag mask and attribute selection. By default, any tag with its base
attribute Shutdown set to 1 will receive a shutdown event. After the Shutdown
Subsystem writes all the shutdown events for the appropriate points, it will stop
running.
Snapshot Event
An overloaded term that can refer to either any Event sent to the Snapshot Subsystem
or the event currently residing in the Snapshot table for a particular point. The event
stored in the Snapshot table for each point has the most recent timestamp of all events
received so far for that point; when a new event arrives with a more recent
timestamp, the previous event is passed through the compression filter.
Snapshot Subsystem
The core component of the PI Server that receives all the new data events for all
points regardless of the sending application. The most recent of these events for each
point is maintained in the Snapshot table along with additional information necessary
to perform compression. Besides performing compression and writing events to the
Event Queue, the Snapshot Subsystem responds to client requests for Snapshot
events and forwards Snapshot events for requested points to Update Manager.
SNMP Interface
An interface included that collects performance data from any device that supports
the Simple Network Management Protocol and then stores the values in PI points.
Examples of devices include computers, printers, and routers. A basic version of the
interface is included with the PI Server for Windows.
SNMP Point Builder
An SMT plug-in useful for creating and editing points for the SNMP Interface.
Span
The base point attribute that specifies the range or the difference between the
maximum and minimum values for a point. Span is required for all numeric points
and is linked to compression and exception specifications through CompDevPercent
and ExcDevPercent, respectively. Span is only enforced for values for float16 points.
SQC
The SDK-based Add-In to ProcessBook that enables users to create and view a
variety of Statistical Quality Control charts on their ProcessBook displays. SQC chart
limits can be PI points, manually entered constants, or values from ODBC datasets
defined within ProcessBook.
Introduction to PI Server
System Management Page 93
Glossary of Terms
SQC Alarm Manager
A stand-alone client application used for managing Real-Time SQC Alarms on a PI
Server. This application has been replaced with the SMT SQC Alarms plug-in that
provides equivalent functionality.
SQL Subsystem
The component of the PI Server that prepares and executes Structured Query
Language statements directed against it from mainly ODBC and SDK applications.
The existence of the SQL Subsystem allows clients to access PI Server information
stores like the Data Archive and Point Database using the same SQL syntax used to
interact with relational databases.
State Set
A synonym for Digital State Set or DigitalSet.
Statement Handle
An object allocated by the SQL Subsystem to enable servicing of a SQL request or
statement.
Status
The classification of an Event depending on the nature of its value. If the event has a
valid value considering the type of point, then the event is considered to have a Good
status. If the event has a SYSTEM digital state as a value, then the event is
considered to have a Bad status.
Steam Functions
A set of built-in functions available within a Performance Equation that calculate the
thermodynamic properties of steam.
Step
The base attribute that specifies how to interpolate between successive archive
events. If Step is non-zero, the value is assumed to change in a stepwise or staircase
fashion.
String Point Type
The point type used for storing strings, sequences of alphanumeric characters, up to
976 characters in length.
Subnet
A networking term that refers to a range of numerical IP addresses.
Page 94
Glossary of Terms
Subsystem
A functionally distinct software component or module that executes in its own
process space. The PI Server has several core subsystems such as Network Manager,
Update Manager, Base, Snapshot, and Archive.
Swinging Door Compression
A data compression algorithm used by the Snapshot Subsystem that guarantees all of
the original samples were within a specified value, the compression deviation, of a
straight line drawn between any two events selected for archiving. In other words,
this compression algorithm allows for the reconstruction of the original signal as a
series of straight lines, and the maximum error between the reconstructed and
original signals is guaranteed to be no more than the compression deviation.
System Digital State Set
The default digital state set that contains a few hundred digital states that may apply
to any tag. States may be added to this set, but states in the offset range 193-320 are
reserved for use by the PI System and should not be modified.
System Management Tools (SMT)
A set of easy-to-use programs for performing a wide variety of common
administrative tasks in a PI System. The tools can be downloaded from the Technical
Support Web Site (http://techsupport.osisoft.com).
Tag
The base attribute that is the unique alphanumeric name for a point. Certain
characters are not allowed like ‘*’, ‘?’, ‘\’, and ‘;’. The term Tag and Point are often
used interchangeably.
Tag Configurator
An SDK-based Add-In to Excel that facilitates creating, editing, and viewing points
from a spreadsheet. This is the ideal application for bulk point operations.
Timeout Table
The information store that contains all the configuration parameters for the PI Server.
When tuning the performance of the PI Server, several of these Timeout Table
parameters will typically need to be adjusted.
Timestamp
A date and time, almost always associated with a data value through an Event. The PI
Server stores timestamps internally in UTC (Universal Coordinated Time).
Introduction to PI Server
System Management Page 95
Glossary of Terms
Timestamp Point Type
The point type used to store values that are timestamps. The possible range of
timestamps that can be stored is 1-Jan-1970 through 1-Jan-2038.
Totalizer Subsystem
The component of the PI Server that can be used to continuously calculate a variety
of quantities like totals, averages, minimum and maximum values, and standard
deviations.
Trust
A record stored on the PI Server that automatically grants access for a program
connecting to the PI Server without requiring an explicit PI user login. A trust
consists of one or more Connection Credentials criteria and the name of an existing
PI user to be used for access. All trusts are stored in the Trust Table which is hosted
by the Base Subsystem. Trust lookup is always performed when an application first
connects to the PI Server.
Unit
In batch processing, the name of the equipment set on which batch activity takes
place. The definition of a unit is not limited to a single piece of equipment. For
example, a unit could be a single reactor or a group of reactors and related
equipment.
Universal Data Server (UDS)
An obsolete name for the PI Server.
Update Manager
The core component of the PI Server that buffers data events and notifications of
configuration changes for programs that have requested this service. For example,
ProcessBook will request updates of Snapshot events for a point on a trend so that the
trace will remain current; all such events will pass through Update Manager.
Zero Attribute
The base point attribute that indicates the lowest possible value for a point. Zero is
only enforced for values for float16 points.
Page 96
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
Introduction to PI Server
System Management Page 97
Technical Support and Resources
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a
Page 98
INDEX OF TOPICS
.ann files, 30 Tag, 18
Access categories, 48 Attributes
Access permissions, 48 Compression specification, 21
Access privileges Exception reporting, 20
Points, 22 Location1, 42
Adding new data sources, 71 Location4, 20
adm directory, 11 Point source, 41
Administrator account, 49 Points, 17
Alarm Manager, SQC, 7 PointSource, 19
Alarm point class, 19 PointType, 18, 19
Annotation files, 30 Shutdown, 22
API Nodes, 10 Span, 22
APS, 17 Typical value, 22
Archive Gaps, 31 Zero, 22
Archive Manager, 27, 29 Auto Point Sync, 17
archive queuing, 15 Automating archive creation, 32
Archive shift, 25 Backups
Archives Monitoring, 36
About, 25 Bad points
Annotation files, 30 Finding, 23
Archive Manager, 27, 29 Base point class, 19
Archive shift, 25 Batch Database, 54
Creating, 27 bin directory, 11
Creating automatically, 32 Blob point type, 19
Fixing Gaps, 31 Buffering
Moving, 30 About, 63
Preventing overwrites, 27 Account, 66
Primary, 25 Checking if running, 64
Registering, 28 Configuring interfaces for, 45
Unregistering, 29 How to fix, 66
Attribute How to test, 66
PtClass, 18 pipc.log, 68
Introduction to PI Server
System Management Page 99
Index of Topics
Starting service, 68 Data Archive, 54
Testing, 65 Data flow
When to test, 66 Interface Nodes, 10
bufserv, 63 Overview, 9
chdir command, 7 Server, 13
Checking Backups, 36 Data Source Nodes, 10
Checking interface log files, 44 Data sources, 71
Checklist for System Managers, 3 Adding new, 71
Class attribute, 18 Removing equipment, 72
Classic point class, 18 Database Security Editor, 55
cmd, 7 Databases
Command Line, 7 About, 54
CompDev, 15 Decommissioning points, 24
CompDev attribute, 21 Deleting points, 24
CompDevPercent, 15 Demonstration account, 50
CompDevPercent attribute, 21 Developers Network, 73
CompMax, 15 DevNet, 73
CompMax attribute, 21 Digital point type. See
CompMin, 15 Digital State Table, 54
CompMin attribute, 21 Directories
Compressing attribute, 21 Server, 11
Compression deviation, 21 Documentation
Compression Flag, 21 conventions, v
Compression specifications for interfaces, vi
Attributes, 21 On interfaces, 45
Compression testing, 14 Equipment
Compression Testing, 14 Adding new, 71
Computer platform Removing, 72
Information, 98 Event Queue, 15
Configuring interfaces ExcDev, 10
In the ICU, 43 ExcDev attribute, 20
Configuring Interfaces ExcDevPercent attribute, 20
For buffering, 45 Exception reporting, 10
Creating archives, 27 Attributes, 20
Creating performance points, 59 ExcMax, 10
Creating points, 23 ExcMin, 10
Daily Health Check, 3 File system
dat directory, 11 Server, 11
Data Filtering data
How often to get new values, Exception reporting, 10
20 Firewall, 47
Data Access privileges, 22
Page 100
Fixed archives, 25 PIPerfmon, 60
Fixing archive gaps, 31 Point source, 41
Float16 point type. See Registering, 43
Float32 point type, 19 Starting and stopping, 44
Float64 point type, 19 IORates points, 44
Frequency Load Sharing
Data collection, 20 Interface Nodes, 10
Gaps, Archives, 31 Location1 attribute, 42
Generating archives automatically, Location4 Attribute, 20
32 log directory, 12
Group access, 49 Log files
Groups Interfaces, 44
Managing, 47 Log Files
Setting up, 50 pigetmsg, 44
Heading Sets Database, 54 pipc.log, 44
Health Check, 3 Message logs
ICU, 6 pipc.log, 68
About, 6 Module Database, 54
Configuring interfaces with, 43 Module Database Builder, 7
Starting Buffering, 68 Monitoring Backups, 36
ID number, Interface, 42 Moving archives, 30
Information Naming points
On interfaces, 45 Tag attribute, 18
Instruments. See Data Sources No access, 48
Int16 point type, 19 Nodes
Int32 point type, 19 Interface, 10
Interface Configuration Utility. See Obsolete points, 24
ICU
Offset, 42
Interface ID number, 42
OSIsoft Universal Interface, 41
Interface Nodes
out of order event, 14
About, 10, 41
Owner access, 49
Buffering, 63
Performance
Data flow, 10
Interfaces, 44
Multiple interfaces, 10
Performance counters
Interfaces
Which to use, 58
Configuring, 43
Performance points
Configuring for Buffering, 45
About, 57
downloading documentation
Creating, 59
for, vi
Interfaces, 44
Getting more information, 45
PI 3.4 and later, 60
Log files, 44
PIPerfmon interface, 60
Monitoring performance, 44
Introduction to PI Server
System Management Page 101
Index of Topics
Trending, 59 pisnapss_OutOfOrderSnapshots/sec
Period, 42 , 58
Permissions pisnapss_Queued Events/sec, 58
Access, 48 pisnapss_Snapshots/sec, 58
Owner, group, world, 48 PITransferRecords, 54
PI PIUSER, 54
Overview, 9 Point Access
PI APS, 17 Privileges, 22
PI Backups. See Backups Point classes, 18
PI databases. See Databases Point Database, 54
PI Points. See Points Point Security
PI Security. See Security Configuration, 22
PI Server. See Server Point Source
PI trusts. See Trusts PIPerfmon, 61
piadmin account, 49 Point sources, 41
piarchss_Archived Events/sec, 58 Point types. See
piarchss_Cache Record Count, 58 Points
piarchss_Events Read/sec, 58 About. See Points
piarchss_Primary Archive % Used, Attributes, 17
58 Creating, 23
piarchss_Time to Archive Shift, 58 Decommissioning, 24
piarchss_Total Unflushed Events, Deleting, 24
58 Finding Malfunctioning, 23
pibasess_Module Count, 58 points vs. tags, 18
pibasess_Point Count, 58 PointSource attribute, 19
PIBatch, 54 PointType attribute, 18, 19
pidemo account, 50 Primary archive, 25
PIDS, 54 Privileges
pigetmsg, 44 Points, 22
PIHeadingSets, 54 PtClass attribute, 18
PIModules, 54 Queue, Event, 15
pipc.log, 44, 68 Read only access, 48
PIPerfmon interface, 60 Read/Write access, 48
Point source, 61 Registering archives, 28
PIPOINT, 54 Registering interfaces, 43
pisnapss_Events in Overflow Removing equipment, 72
Queues, 58
Retiring points, 24
pisnapss_Events in Primary Queue,
Run command, 7
59
Scan class
pisnapss_GetSnapshots/sec, 58
PIPerfmon interface, 61
pisnapss_Number of Overflow
Queues, 59 Scan Class
Location4 attribute, 20
Page 102
Scan classes Technical support Web site, 73
About, 42 Testing Buffering, 66
Security Time
About, 47 UTC, 43
Owner, group, world, 48 Timestamp point type, 19
Point configuration, 22 Tools for System Managers, 5
Server Totalizer point class, 19
About, 11 Training
Compression, 14 Where to find, 73
Compression testing, 14 Transfer Record Database, 54
Data flow, 13 Troubleshooting
File system. See Buffering, 66
Snapshot, 14 Trusts
Setting up groups, 50 About, 47
Shutdown attribute, 22 About, 52
SMT Type attribute, 18, 19
about, vi Typical Value attribute, 22
About, 5 UniInt, 41
Archive Manager, 27, 29 downloading documentation
Database Security Editor, 55 for, vi
Installing, 5 UNIINT
Running, 5 Documentation, 45
User and Group Editor, 51 Universal Interface
Snapshot, 14 Documentation, 45
Span attribute, 22 downloading documentation
for, vi
SQC Alarm Manager, 7
Unregistering archives, 29
SQC_Alarm point class, 19
User and Group Editor, 51
Stale points
User Database, 54
Finding, 23
User Identification Security, 47
Starting buffering, 68
Users
Starting interfaces, 44
Managing, 47
Stopping interfaces, 44
UTC Time, 43
String point type, 19
Web site
Support Web site, 73
Developers Network, 73
System Management Tools, vi, See
SMT support, 73
Tag attribute, 18 Windows command prompt
window, 7
TagConfigurator, 7
World access, 49
Tags. See Points
Zero attribute, 22
tags vs. points, 18
Technical Support, 97
Introduction to PI Server
System Management Page 103
PI Server System Management Guide
PI3 Server
Version 3.4.370
© 1998-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PI Server System Management Guide is an in-depth manual that provides the
information and instructions that system administrators need to operate the PI System.
This guide includes comprehensive instructions to assist you in:
Using PI Server command-line tools such as PIConfig, PIDiag, and PIArtool
Configuration and tuning of your PI Server for optimum performance
Monitoring system health, and ensuring data preservation and integrity
Managing the Snapshot, Event Queue and Data Archive
Troubleshooting and repair
To effectively manage a PI System, follow the recommendations and procedures for each of
the following topics:
Starting and Stopping PI Systems
Backing Up PI Servers
Managing Archives
Managing Interfaces
Managing Security
Monitoring PI System Health
Moving, Copying or Merging PI Servers
For troubleshooting and performance issues, this guide includes Appendices of error
messages provided in the System Message Log, and an extensive list of performance
measurements (statistics) you can use to optimize the System.
PI Server System Management Guide Page iii
Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set includes seven user guides, described below.
Tip: Updated user guides, which provide the most up-to-date information, may be
available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security and
trusts, and performance. It includes a glossary and resource guide.
PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data Archive,
monitoring system health, managing backups, interfaces, security, and
moving and merging servers. Includes comprehensive instructions for using
command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth
troubleshooting and repair information.
PI Server Reference A comprehensive reference guide for the system administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).
Auditing the PI An administration guide that explains the Audit Database, which provides a
Server secure audit trail of changes to PI System configuration, security settings,
and Archive Data. It includes administration procedures to enable auditing, to
set subsystem auditing mode, to create and archive database files, and to
export audit records.
PI Server A guide to key add-on PI Server Applications: Performance Equations (PE),
Applications User Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality
Guide Control). Includes a reference guide for Performance Equations, and Steam
calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
Page iv
Preface - Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI Client Tools Use the client tool, PI ProcessBook, to verify that all
PI System Elements data has been recovered.
PI Server Subsystems All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text Files, Directories, Paths The backup script is located in the \PI\adm directory.
Emphasis Archive files can be either fixed or dynamic. The
New Terms archive receiving current data is called the Primary
Archive.
Fields
See Section 4.2, Create a New Primary Archive.
References to a chapter or section
Bold Italic text References to a publication See the PI Server Reference Guide.
Bold text System and Application The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
Procedures and Key Commands On the Tools menu, click Advanced Options.
Press CTRL+ALT+DELETE to reboot
Interface components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: Code examples use the piartool -ss command. For example:
"Consolas" Commands to be typed on the
font command line (optionally with
arguments or switches)
System input or output such as
excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
PI Server System Management Guide Page v
Preface - Using this Guide
Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins that provide all the basic tools you need to manage a PI
System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management User Guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. Starting and Stopping PI ............................................................................................1
Chapter 2. Monitoring PI System Health ...................................................................................17
Chapter 3. Managing Archives ...................................................................................................33
Chapter 4. Backing up the PI Server..........................................................................................63
Chapter 5. Managing Interfaces .................................................................................................93
Chapter 6. Managing Security ..................................................................................................115
Chapter 7. Moving PI Servers ...................................................................................................147
Chapter 8. Copying a PI Server ................................................................................................151
Chapter 9. Merging Two PI Servers .........................................................................................153
Chapter 10. The piconfig Utility..................................................................................................171
Chapter 11. PI Troubleshooting and Repair..............................................................................225
Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................263
PI Server System Management Guide Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Table of Tables................................................................................................................................xix
Table of Figures ..............................................................................................................................xxi
Chapter 1. Starting and Stopping PI ............................................................................................1
1.1 Starting PI...........................................................................................................................1
1.1.1 Starting PI on Windows Systems ...........................................................................2
1.1.2 Starting PI on UNIX Systems .................................................................................3
1.2 Stopping PI.........................................................................................................................3
1.2.1 Stopping PI on Windows Systems .........................................................................3
1.2.2 Stopping PI on UNIX Systems ...............................................................................4
1.3 Automatic Startup .............................................................................................................6
1.3.1 Automatic Startup and Shutdown on UNIX Systems .............................................7
1.4 Shutting Down an Individual Subsystem......................................................................16
Chapter 2. Monitoring PI System Health ...................................................................................17
2.1 Checking Key System Indicators...................................................................................17
2.2 Viewing System Messages .............................................................................................18
2.2.1 Available Log History............................................................................................18
2.2.2 Viewing System Messages with pigetmsg ...........................................................18
2.2.3 Viewing Messages When the Message Subsystem Goes Down.........................20
2.2.4 Viewing Message Log Files Generated on other Servers....................................20
2.2.5 Interpreting Error Messages (pidiag)....................................................................21
2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages) ................................22
2.3 Monitoring Snapshot Data Flow.....................................................................................22
2.3.1 Listing Current Snapshot Information with piartool -ss.........................................22
2.4 Monitoring the Event Queue...........................................................................................25
2.4.1 piartool -qs ............................................................................................................25
2.5 Monitoring the Archive ...................................................................................................27
2.5.1 piartool -as ............................................................................................................27
PI Server System Management Guide Page ix
Table of Contents
2.6 Monitoring the Update Manager ....................................................................................30
2.6.1 Adjusting the Pending Update Limit .....................................................................31
2.7 System Date and Time ....................................................................................................31
Chapter 3. Managing Archives ...................................................................................................33
3.1 Tasks for Managing Archives.........................................................................................33
3.2 About Archives ................................................................................................................33
3.2.1 About Archive Shifts .............................................................................................33
3.2.2 About Archive Files...............................................................................................34
3.2.3 About Primary Archives ........................................................................................35
3.2.4 About Fixed and Dynamic Archives .....................................................................35
3.2.5 About Read-Only Archives ...................................................................................37
3.3 Tools for Managing Archives .........................................................................................37
3.3.1 Using the piartool Utility........................................................................................37
3.3.2 Using the Offline Archive Utility (piarchss) ...........................................................40
3.4 Listing the Registered Archives ....................................................................................46
3.4.1 Determining an Archive Sequence Number from a Listing ..................................47
3.5 Listing Archive Record Details ......................................................................................49
3.5.1 Performing an Archive Walk with piartool -aw......................................................49
3.6 Estimating Archive Utilization........................................................................................51
3.7 Editing Archives ..............................................................................................................51
3.8 Creating Archives............................................................................................................52
3.8.1 Naming Archives ..................................................................................................52
3.8.2 Choosing an Archive Size ....................................................................................52
3.8.3 Selecting an Archive Type: Fixed or Dynamic......................................................53
3.8.4 Specifying the Number of Points in the Archive ...................................................53
3.8.5 Specifying the Maximum Archive Size .................................................................54
3.9 Creating Data Archives Prior to the Installation Date..................................................54
3.10 Creating a New Primary Archive ....................................................................................55
3.10.1 Registering an Archive .........................................................................................56
3.10.2 Unregistering an Archive ......................................................................................56
3.10.3 Deleting an Archive ..............................................................................................56
3.10.4 Moving an Archive ................................................................................................56
3.11 Managing Archive Shifts.................................................................................................57
3.11.1 Archive Shift Enable Flag .....................................................................................58
3.11.2 Forcing Archive Shifts...........................................................................................58
3.12 Combining and Dividing Archives .................................................................................59
Page x
Table of Contents
3.12.1 Combining Archives into a Single Archive............................................................59
3.12.2 Event Queue Recovery ........................................................................................61
Chapter 4. Backing up the PI Server..........................................................................................63
4.1 Planning for Backups......................................................................................................63
4.1.1 Choosing the Backup Platform (VSS vs. Non-VSS) ............................................63
4.1.2 Choosing a Backup Strategy ................................................................................63
4.2 Other Backup Considerations........................................................................................64
4.2.1 Guidelines for VSS Backups ................................................................................64
4.2.2 Guidelines for non-VSS Backups .........................................................................65
4.3 Guidelines for Backing Up Before Upgrading ..............................................................65
4.4 Automating PI Backups ..................................................................................................66
4.4.1 Automating Backups on Windows........................................................................66
4.4.2 Do a Test Backup .................................................................................................69
4.4.3 Do a Test Restore ................................................................................................70
4.4.4 Automating Backups on Windows with a 3rd Party Backup Application..............72
4.5 Automating Backups on a Windows Cluster................................................................73
4.6 Automating Backups on UNIX........................................................................................73
4.7 How The PI Backup Subsystem Works.........................................................................74
4.7.1 Principles of Operation .........................................................................................74
4.7.2 Selecting Files or Components for Backup ..........................................................75
4.7.3 The Backup Components of PI ............................................................................77
4.7.4 The Files and Components for each Subsystem .................................................78
4.7.5 Lifetime of a Backup .............................................................................................80
4.8 Launching Non-VSS Backups with piartool -backup <path>......................................83
4.9 Managing Backups with piartool ...................................................................................84
4.9.1 Backup Command Summary ...............................................................................84
4.9.2 piartool -backup -query.........................................................................................85
4.9.3 piartool -backup -identify ......................................................................................87
4.10 Timeout Parameters ........................................................................................................87
4.11 Troubleshooting Backups ..............................................................................................89
4.11.1 Log Messages ......................................................................................................89
4.11.2 VSSADMIN ...........................................................................................................90
Chapter 5. Managing Interfaces .................................................................................................93
5.1 Introduction......................................................................................................................93
5.2 General Interface Principles ...........................................................................................94
5.2.1 About PI Interfaces ...............................................................................................94
PI Server System Management Guide Page xi
Table of Contents
5.2.2 About PI Interface Nodes .....................................................................................94
5.2.3 About Data Buffering ............................................................................................95
5.2.4 About the PI API ...................................................................................................96
5.2.5 About the PI SDK .................................................................................................96
5.2.6 About UniInt-Based Interfaces .............................................................................96
5.3 Basic Interface Node Configuration ..............................................................................97
5.3.1 Install the PI SDK and/or the PI API.....................................................................97
5.3.2 Connect to PI with apisnap.exe............................................................................98
5.3.3 Connect with AboutPI SDK.exe............................................................................98
5.3.4 Configure PI Trusts for the Interface Node...........................................................98
5.3.5 Install the Interface .............................................................................................101
5.3.6 Set the Interface Node Time ..............................................................................101
5.3.7 Connect to the PI Server with the Interface........................................................102
5.3.8 Configure Points for the Interface.......................................................................103
5.3.9 Configure Buffering.............................................................................................104
5.3.10 Configure Interface for Automatic Startup ..........................................................106
5.3.11 Configure Site-Specific Startup Scripts ..............................................................107
5.3.12 Configure PointSource Table .............................................................................108
5.3.13 Monitor Interface Performance...........................................................................108
5.3.14 Configure the PI Interface Status Utility .............................................................112
5.3.15 Configure Auto Point Synchronization................................................................113
Chapter 6. Managing Security ..................................................................................................115
6.1 Physical Security...........................................................................................................115
6.2 Network Security ...........................................................................................................115
6.3 Operating System Security...........................................................................................116
6.4 PI Server Security..........................................................................................................116
6.4.1 Running applications on the system console .....................................................117
6.4.2 Running applications remotely ...........................................................................117
6.5 Firewall Security ............................................................................................................117
6.5.1 Firewall Database...............................................................................................118
6.6 Database Security .........................................................................................................120
6.6.1 PIDBSEC ............................................................................................................120
6.6.2 PIARCADMIN .....................................................................................................120
6.6.3 PIARCDATA .......................................................................................................121
6.6.4 PIBatch ...............................................................................................................121
6.6.5 PICampaign........................................................................................................121
Page xii
Table of Contents
6.6.6 PIDS ...................................................................................................................121
6.6.7 PIHeadingSets....................................................................................................121
6.6.8 PIModules...........................................................................................................121
6.6.9 PIPOINT .............................................................................................................121
6.6.10 PITransferRecords .............................................................................................121
6.6.11 PIUSER ..............................................................................................................121
6.6.12 Individual Subsystem Tokens.............................................................................121
6.7 Point Security.................................................................................................................122
6.7.1 Point Data Access ..............................................................................................122
6.7.2 Point Attribute Access ........................................................................................122
6.7.3 Access Algorithm................................................................................................122
6.7.4 Assigning and Changing Ownership and Access Permissions..........................123
6.7.5 How to Make All Points Accessible ....................................................................124
6.7.6 Security for Default Points in the PI Server ........................................................125
6.8 User Security .................................................................................................................125
6.8.1 Group Database .................................................................................................125
6.8.2 User Database....................................................................................................126
6.9 Trust Login Security......................................................................................................128
6.9.1 Connection Credentials ......................................................................................128
6.9.2 Defining Trust Records in the Trust Database ...................................................130
6.9.3 Evaluating the Match Between Trust Records and Connection Credentials .....134
6.9.4 New PI Server Installations ................................................................................136
6.9.5 Trust changes on System Startup ......................................................................136
6.9.6 Multiple Network Cards ......................................................................................136
6.9.7 Examples ............................................................................................................137
6.10 Resolving Ambiguities..................................................................................................144
Chapter 7. Moving PI Servers ...................................................................................................147
7.1 Preparation.....................................................................................................................147
7.2 Different Computer........................................................................................................147
7.3 Same Computer .............................................................................................................148
Chapter 8. Copying a PI Server ................................................................................................151
8.1 Understanding the Server ID ........................................................................................151
8.2 Situations where Server ID must be Addressed ........................................................151
Chapter 9. Merging Two PI Servers .........................................................................................153
9.1 Server Merging - Procedures .......................................................................................153
PI Server System Management Guide Page xiii
Table of Contents
9.2 Server Merge Procedure - Example.............................................................................156
9.3 Shut Down the Retired System ....................................................................................163
9.3.1 Add Retired Point Configuration to Destination System.....................................164
9.3.2 Add PI Batch Unit Configuration to Destination System ....................................165
9.3.3 Convert the Archives ..........................................................................................165
9.3.4 Merge the PI Batches .........................................................................................169
Chapter 10. The piconfig Utility..................................................................................................171
10.1 PI TagConfigurator & PI SMT Point Builder plug-in...................................................171
10.2 A Note to Pidiff Users....................................................................................................171
10.3 Key Concepts for Using Piconfig ................................................................................172
10.3.1 Starting and Stopping Piconfig ...........................................................................172
10.3.2 Interactive Session vs. Batch Method ................................................................172
10.3.3 Selecting PI Tables.............................................................................................172
10.3.4 Table Attributes ..................................................................................................174
10.3.5 Records ..............................................................................................................175
10.3.6 Piconfig Commands ...........................................................................................176
10.3.7 Mode...................................................................................................................178
10.3.8 Structure Type ....................................................................................................179
10.3.9 Select Command ................................................................................................181
10.3.10 Operators............................................................................................................181
10.3.11 Wildcards ............................................................................................................182
10.3.12 The Ellipsis (…) Construct for Repeating Attributes...........................................182
10.3.13 Endsection..........................................................................................................182
10.3.14 Exit......................................................................................................................183
10.3.15 Batch Methods....................................................................................................183
10.3.16 Security on Piconfig Sessions ............................................................................185
10.3.17 Remote Piconfig Sessions..................................................................................185
10.4 Piconfig Commands and Tables ..................................................................................186
10.4.1 Point Database Table .........................................................................................188
10.4.2 PI Attribute Set Table .........................................................................................191
10.4.3 Point Class Database .........................................................................................192
10.4.4 Point Source Database.......................................................................................194
10.4.5 Digital States Table ............................................................................................195
10.4.6 Snapshot and Snapshot2 Tables .......................................................................200
10.4.7 Archive Table......................................................................................................202
10.4.8 PI Batch Unit Table.............................................................................................207
Page xiv
Table of Contents
10.4.9 PI Batch Alias Table ...........................................................................................208
10.4.10 PI Batch Table ....................................................................................................209
10.4.11 PI Subsystem Table ...........................................................................................210
10.4.12 PI Subsystem Statistics Table ............................................................................211
10.4.13 PINet Manager Statistics Table..........................................................................212
10.4.14 PI Users Table....................................................................................................214
10.4.15 PI Group Table ...................................................................................................215
10.4.16 PI Thread Table..................................................................................................215
10.4.17 PI Database Security Table................................................................................216
10.4.18 PI Trust Database...............................................................................................218
10.4.19 PI General Table Interface .................................................................................219
10.5 Helpful Hints...................................................................................................................220
10.5.1 Abbreviations......................................................................................................220
10.5.2 Case-sensitivity ..................................................................................................220
10.5.3 Command Input Files .........................................................................................220
10.5.4 Input Line Length................................................................................................220
10.5.5 Using Quoted Strings .........................................................................................221
10.5.6 Sending Values as Strings .................................................................................222
10.5.7 Boolean Values ..................................................................................................222
10.5.8 Configuration Persistence ..................................................................................223
10.5.9 Command Line Parameters................................................................................223
10.5.10 Changing Special Characters.............................................................................223
10.5.11 Convert Mode Example ......................................................................................224
10.5.12 Converting Point Database Information from PI2 to PI Server...........................224
10.5.13 Hexadecimal and Octal Numbers.......................................................................224
Chapter 11. PI Troubleshooting and Repair..............................................................................225
11.1 Troubleshooting Checklist ...........................................................................................225
11.2 Verifying PI Processes..................................................................................................228
11.2.1 Verifying PI Processes on Windows Systems....................................................228
11.2.2 Verifying PI Processes on UNIX Systems..........................................................228
11.2.3 Communication with PINet Manager..................................................................229
11.2.4 Pimsgss ..............................................................................................................229
11.2.5 PI Update Manager ............................................................................................230
11.2.6 PI Base Subsystem ............................................................................................230
11.2.7 Snapshot Subsystem..........................................................................................230
11.2.8 Archive Subsystem.............................................................................................231
PI Server System Management Guide Page xv
Table of Contents
11.2.9 Pishutev ..............................................................................................................231
11.2.10 Random Interface ...............................................................................................232
11.2.11 RampSoak Interface...........................................................................................232
11.2.12 Running PI Processes Independently ................................................................232
11.3 UNIX Process Quotas....................................................................................................233
11.3.1 IBM AIX...............................................................................................................234
11.3.2 Compaq Tru64....................................................................................................234
11.3.3 HP-UX.................................................................................................................235
11.3.4 Sun Solaris .........................................................................................................235
11.4 PI Server Data Files .......................................................................................................235
11.5 Identifying the Update Manager Issues: the pilistupd utility ....................................238
11.6 Repairs............................................................................................................................241
11.6.1 Recovering Data from Corrupted Archives.........................................................241
11.6.2 Restoring a Complete Server from Backup........................................................243
11.6.3 Restoring Archives From Backup.......................................................................244
11.6.4 Restoring Subsystem Databases From Backup.................................................245
11.6.5 Correcting Archive Event Timestamps ...............................................................245
11.6.6 Repairing the Archive Registry...........................................................................246
11.6.7 How to Repair the Snapshot...............................................................................247
11.6.8 Recovering from Accidental Change to System Time........................................249
11.6.9 How to Repair the Point Database .....................................................................250
11.6.10 How to Repair the Module Database .................................................................250
11.7 Tuning the PI Server......................................................................................................251
11.7.1 Communications Layer of the PI Server.............................................................251
11.7.2 Resolving Excessive CPU Usage by Utilities .....................................................252
11.7.3 Identifying Abusive Usage ..................................................................................253
11.8 Solving Other Problems................................................................................................254
11.8.1 Failed Backups ...................................................................................................254
11.8.2 Slow Reverse Name Lookup ..............................................................................254
11.8.3 Slow Domain Controller Access .........................................................................255
11.8.4 Flatline in a PI ProcessBook Trend ....................................................................255
11.9 COM Connectors ...........................................................................................................257
11.9.1 Redirector Troubleshooting ................................................................................257
11.9.2 COM Connector Troubleshooting.......................................................................261
Chapter 12. Finding and Fixing Problems: the pidiag Utility ..................................................263
12.1 General Information ......................................................................................................265
Page xvi
Table of Contents
12.1.1 Version Information ............................................................................................265
12.1.2 Error Code Translation .......................................................................................265
12.2 Time Utilities ..................................................................................................................265
12.2.1 Time Translations ...............................................................................................265
12.2.2 Time Zone ..........................................................................................................266
12.3 File-base Utilities ...........................................................................................................269
12.3.1 Dump File-base Data File...................................................................................269
12.3.2 Compact a File-base Data File ...........................................................................269
12.3.3 Recover File-base Data File Index .....................................................................270
12.4 Archive Management ....................................................................................................270
12.4.1 Dump the Archive Manager Data File ................................................................270
12.4.2 Automatic Recovery of the Archive Manager Data File .....................................270
12.4.3 Manual Recovery of the Archive Manager Data File..........................................271
12.4.4 Information about Unregistered Archives ...........................................................271
12.4.5 Verify the Integrity of Archive Files.....................................................................272
12.4.6 Downgrade Archive File to Older Versions ........................................................274
12.5 Server ID Utilities...........................................................................................................275
12.6 Performance Counter Utilities (Windows Only) .........................................................276
12.6.1 Get Performance Counter Path ..........................................................................276
12.6.2 Uninstall Performance Counters ........................................................................276
12.6.3 Get Performance Counter Values ......................................................................276
12.7 Miscellaneous ................................................................................................................278
12.7.1 Wait for Passed Milliseconds..............................................................................278
12.7.2 Testing Crash Dump Capability of an OS ..........................................................278
12.7.3 Reset Password to Blank ...................................................................................278
12.7.4 Display Network Definitions................................................................................278
12.7.5 Register a COM Component ..............................................................................279
12.7.6 Replaceable Parameter......................................................................................279
12.7.7 GUID Generation................................................................................................280
12.7.8 Machine-specific Programming Information .......................................................280
Appendix A: PI Messages .............................................................................................................281
Appendix B: PI Performance Counters .......................................................................................331
Technical Support and Resources...............................................................................................345
Index of Topics...............................................................................................................................347
PI Server System Management Guide Page xvii
TABLE OF TABLES
Table 3–1. Options for Use with piartool..................................................................................37
Table 10–1. PI Tables Accessible Through piconfig..............................................................172
Table 10–2. Piconfig Commands ...........................................................................................186
Table 10–3. Snapshot and Snapshot2 Tables Attributes ......................................................200
Table 10–4. Archive Table Attributes .....................................................................................202
Table 10–5. PI Batch Unit Table Attributes............................................................................207
Table 10–6. PI Batch Alias Table Attributes ..........................................................................209
Table 10–7. PI Batch Table Attributes ...................................................................................209
Table 10–8. Subsystem Table Attributes ...............................................................................210
Table 10–9. PI Subsystem Statistics Table Attributes ...........................................................211
Table 10–10. PINet Manager Statistics Table Attributes .......................................................212
Table 10–11. PI Users Table Attributes .................................................................................214
Table 10–12. PI Group Table Attributes ................................................................................215
Table 10–13. PI Thread Table Attributes ...............................................................................215
Table 10–14. PI Thread Table Actions ..................................................................................216
Table 10–15. PI Database Security Table Attributes .............................................................216
Table 10–16. Trust Table Attributes.......................................................................................218
Table 10–17. PI Timeout Table Attributes .............................................................................219
Table 10–18. PI Firewall Table Attributes ..............................................................................219
Table A–1. Error Codes 1-99, With Messages ......................................................................294
Table A–2. Error Codes 100-199, With Messages ................................................................297
Table A–3. Error Codes 200-299, With Messages ................................................................297
Table A–4. Error Codes 500-599, With Messages ................................................................298
Table A–5. Error Codes 800-899, With Messages ................................................................300
Table A–6. Error Codes 900-999, With Messages ................................................................300
Table A–7. Error Codes 1000-1099, With Messages ............................................................301
Table A–8. Error Codes 10000-10999, With Messages ........................................................302
Table A–9. Error Codes 11000-11999, With Messages ........................................................308
Table A–10. Error Codes 12000-12999, With Messages ......................................................314
PI Server System Management Guide Page xix
Table of Tables
Table A–11. Error Codes 13000-13999, With Messages ......................................................319
Table A–12. Error Codes15000-15999, With Messages .......................................................321
Table A–13. Error Codes 16000-16999, With Messages ......................................................322
Table A–14. Error Codes 17000-17999, With Messages ......................................................329
Table A–15. Error Codes 30000-30999, With Messages ......................................................329
Table B–16. PI Performance Counters ..................................................................................341
Page xx
TABLE OF FIGURES
Figure 6-1. Establishing PI Performance Monitor as a Windows Service..............................134
Figure 11-1. Distributed COM Configuration Properties ........................................................258
Figure 11-2. Windows Task Manager Processes ..................................................................259
Figure 11-3. Application Log Properties.................................................................................260
Figure 11-4. COM Connector Loading...................................................................................261
PI Server System Management Guide Page xxi
Chapter 1. STARTING AND STOPPING PI
The PI Server includes several separate processes that participate in startup and shutdown.
These are referred to as PI processes or PI subsystems. This section describes the relationship
between the processes, and the startup and shutdown scripts used to control them.
PI should only be started or stopped by the PI System manager. It is important to remember
that stopping PI affects all client applications, performance equation calculations, and the
archiving of data.
PI Server startup is performed with a pair of scripts: a generic PI startup script starts all PI
processes, which then calls a site-specific script to start interfaces and other site specific
programs. The system manager should modify only the site-specific script since the generic
startup script may be replaced during a PI Server upgrade. The actual file names of these
scripts vary with the operating system. Platform-specific details are provided in the following
subsections.
In general, the PI Server shutdown scripts are similar: a generic PI shutdown script calls a
site-specific script to shut down interfaces and site specific programs, and then shuts down all
PI processes.
Note: The only exception to this is shutting down PI processes running as individual
command windows. In this case, you must bring each window in focus and type
<CTRL-C>. Running PI subsystems in command windows is very rare; and usually
only encountered in troubleshooting scenarios.
It is important to configure Shutdown Events. Generally, points collected by interfaces
running on the PI Server node should be configured for shutdown events; points collected on
remote, buffered nodes usually are not configured for shutdown events. See Stopping PI on
page 3.
Production systems are usually configured so that PI is automatically started when the
computer is powered on. See Automatic Startup on page 6 for more information.
1.1 Starting PI
The PI Subsystems may take several minutes to start. Remote or PI API based interfaces and
other applications are blocked from connecting until the core PI Subsystems have completed
startup. The connection blocking is accomplished by opening the TCP/IP listener when the
core subsystems are ready to service requests. The following message is posted to the PI
Server log when the listener is opened:
PI Server System Management Guide Page 1
Chapter 1 - Starting and Stopping PI
>> TCP/IP connection listener opened on port: 5450
Connection attempts before the listener is opened will fail. Interfaces will retry until a
connection is made.
1.1.1 Starting PI on Windows Systems
On Windows systems, the Manager can be logged into any account that allows full access to
the PI Server files and enough privileges to start services. To start PI, change to the PI\adm
directory.
PI normally runs as Windows services. For diagnostic purposes, you can also start PI in
interactive mode.
Starting PI as Windows Services
To start PI as Windows services:
1. Log in to a Windows account that has full access to the PI Server files, and
permission to start PI services
2. Open a Windows Command Prompt window.
3. Change to the PI\adm directory.
4. Use the pisrvstart.bat script to start PI as Windows services:
pisrvstart.bat [-nosite] [-base]
Nosite is an optional parameter to indicate that the site-specific script file should not be
called. This results in the interfaces not being started.
Base starts only the core subsystems and is used for troubleshooting.
The pisrvstart.bat script starts all the PI Server processes, and then calls pisrvsvrappsstart.bat
if PI Server Applications are installed. Then, it calls pisrvsitestart.bat to start all of the
interfaces.
Starting PI in Interactive Mode
To start PI in interactive mode:
pistart.bat [-nosite] [-stdout] [-base]
The pistart.bat script calls pisitestart.bat.
Nosite is an optional parameter to indicate that the site-specific script file should not be
called. This results in the interfaces not being started.
Base starts only the core subsystems and is used for troubleshooting.
Stdout is an optional parameter to indicate that all messages for the processes should be sent
to the standard output instead of to the message log. When you use this parameter, the PI
Message Subsystem is not started.
The error Control service unknown error 5 opening Service Control Manager is returned if
the PI startup is attempted by a user without enough privileges.
Page 2
1.2 - Stopping PI
Some interfaces on Windows cannot be run as services. Check the interface documentation.
1.1.2 Starting PI on UNIX Systems
On UNIX systems the manager should be logged in as root or piadmin. For a UNIX system,
type:
pistart.sh [-nosite] [-stdout] [-base] [M]
This starts all the PI Server processes, calls piappstart.sh if Server applications are installed,
and then calls the interfaces and programs that are listed in the site-specific script file,
pisitestart.sh.
Nosite is an optional parameter for pistart used to indicate that the site-specific script file
should not be called. This results in the interfaces not being started.
Base starts only the core subsystems and is used for troubleshooting.
Stdout is an optional parameter to indicate that all messages for the processes should be sent
to the standard output instead of the Message Log. When you use this parameter, the PI
Message Subsystem is not started.
M starts only PI Network Manager, PI License Manager, and the PI Message Subsystem.
1.2 Stopping PI
The procedure for stopping PI is slightly different, depending on whether you’re running on
Windows or UNIX.
1.2.1 Stopping PI on Windows Systems
To stop PI on a Windows system, if PI processes are running as Windows services, type:
pisrvstop.bat
This stops all of the interfaces and programs listed in pisrvsitestop.bat, and then the PI
processes. PI services are shut down automatically when you shut down your system. The
order of the shutdown in this case is determined by the operating system.
Windows has a registry entry that defines the maximum wait for a service to exit. On PI
Systems with large point counts, the maximum wait time may need to be increased to allow
PI enough time to shut down properly. The PI installation procedure increases the default
value of 20,000 milliseconds to 300,000 milliseconds, or 5 minutes. This is generally enough
time for proper shutdown on systems with fewer than 50,000 points. Larger systems may
require more time. This can be determined by manually stopping the PI Server using
pisrvstop.bat and record the time to shutdown. If it is longer than 5 minutes, the registry
entry:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WaitToKillServiceTimeout
should be set to reflect the actual shutdown time. Failing to allow proper shutdown of the PI
Server can result in lost data or corrupted data files.
PI Server System Management Guide Page 3
Chapter 1 - Starting and Stopping PI
To shut down an interactively started PI Server, type <CTRL-C> in each of the command
windows corresponding to the PI processes. These should be stopped in the following order:
Utilities (for example, piconfig)
Interfaces (for example, Ramp Soak and Random)
pinetmgr (When you instruct pinetmgr to stop, the remaining processes are told to
exit in the proper order and, finally, pinetmgr will stop.)
1.2.2 Stopping PI on UNIX Systems
To stop PI on a UNIX system, change to the PI/adm directory and type:
pistop.sh
This stops all the interfaces and programs that are listed in the site-specific script file
pisitestop.sh. Then it stops all the PI processes.
If some processes do not stop successfully, run the pistop.sh script again. If you still have
problems stopping the individual programs, use the UNIX kill command.
Distributed systems use PINet and Interface Nodes as data source machines. Normally these
systems buffer data if the PI Server is not available. The buffered data is sent to the PI Server
when it becomes available.
There are a few instances in which data is not buffered when the home node is down.
Examples include cases where an interface is loaded on the PI Server machine and the PI
Server is shut down or where the data is generated locally with performance equations.
In these cases, you may wish to record intervals when the PI Server on the home node was
shut down. This is accomplished by inserting a shutdown event.
A shutdown event is a timestamp and a digital state, typically shutdown, which are written to
one or more points. The digital state prevents the interpolation of data over periods with
possible missing data, and also records system status, providing a clear indication of a gap in
the data.
The PI Server provides a utility, pishutev, to insert shutdown events for points that are
configured to receive them. The pishutev utility uses a configuration file, shutdown.dat, to
determine which points should receive events.
Note: Interfaces may also be configured to record instances when no data is
received from an interface.
Shutdown Flag
The shutdown point attribute in the point database is set to TRUE (1) by default.
If the shutdown attribute for a point is set to TRUE, the point is able to receive shutdown
events if the shutdown.dat file targets the point.
Page 4
1.2 - Stopping PI
pishutev
Shutdown events are written at system startup by the pishutev interface. The utility reads a
configuration file to determine which tags should receive shutdown events. It also supplies a
configurable timestamp for the PI Server shutdown. Unlike most PI processes, pishutev exits
after completion.
The startup command line for pishutev is located in the PI startup files PI/adm/pistart.sh
(UNIX), PI\adm\pistart.bat and PI\adm\pisrvstart.bat.
By default, the configuration file is PI\dat\shutdown.dat. It is sometimes useful to create
additional shutdown configuration file(s) with additional point selections. These files are
processed by starting another instance of the interface. The new shutdown configuration file
name is passed as a parameter using the -f flag in the pishutev command line: For example:
pishutev -f myshutdown.dat
This command line should be added to the PI site-specific startup files PI/adm/pisitestart.sh
(UNIX) and PI\adm\pisitestart.bat. Starting a second instance of pishutev in order to process
an additional shutdown configuration file is not supported when starting PI as Windows
services.
By default, pishutev determines the shutdown event timestamp from a file written by the
Snapshot Subsystem. This file is updated whenever the Snapshot is flashed to disk, usually
every 10 minutes. Hence, in the event of a power failure, the timestamp of the shutdown
event are accurate to within 10 minutes. When PI is shut down normally, the timestamps are
the actual shutdown time. If the file that is written by the Snapshot Subsystem is missing, the
shutdown events interface uses the current time to timestamp the shutdown events.
The default time may be overridden by a user-specified time using the -t flag and passing the
time as a parameter in the command line.
For example:
pishutev -t 11:00
By default, the digital state of shutdown is written for each shutdown event.
To write a digital state other than shutdown, use the -s flag and pass the digital state as a
parameter in the command line. The specified state must already be configured in the System
Digital State Set in the Digital State Table. For example:
pishutev -s SpecialState
The -f, -t, and -s flags may be used in any combination.
Shutdown.dat
The points receiving shutdown events are specified using the file PI\dat\shutdown.dat.
The PI Server is delivered with a shutdown.dat file that selects all points whose shutdown
flag is TRUE. This file is shown below. You may wish to edit the file to restrict shutdown
events to certain groups of tags.
! @(#)shutdown.dat 1.1 05/24/96
! default shutdown events file
PI Server System Management Guide Page 5
Chapter 1 - Starting and Stopping PI
! login info - only localhost is supported
localhost
! tag mask
*
! attrib selection
! add here point attributes,value to select points receiving shutdown
shutdown,1
! pointsource,R*
! location1, 1
! etc...
To specify more than one tag name use a tag mask. The tag mask may contain the wildcards *
and ?. The symbol * matches all possibilities with any number of characters. The symbol ?
matches a single character and may be used any number of times.
Caution: Do not specify additional tags by appending comma separated tag masks
or by using additional lines. Only one tag mask may be specified.
If you do not specify a tag-mask, the interface exists with an error. To prevent all shutdown
events, specify a tag mask that does not match any tag.
Other point attributes and values may be used in addition to or instead of the shutdown flag.
These conditions are logically ANDed together.
For example, the following configuration file selects only tags that start with s, have the
location1 attribute set to 0, and Pointsource set to H. No other tags will receive shutdown
events.
! tag mask
s*
! point attributes
location1,0
pointsource,H
If no point attributes are specified, all tags specified by the tag mask are selected to receive
shutdown events.
Caution: The Shutev process is used to execute post installation procedures;
therefore the Shutev process should not be disabled or removed from the normal
startup procedures. The shutdown.dat file, or point shutdown attribute should be
used to prevent writing shutdown events.
1.3 Automatic Startup
The procedure to configure PI for automatic startup depends on the operating system.
PI Server on Windows is normally run as a collection of services. The installation procedure
provides a dialog to optionally set automatic startup on reboot. The reboot startup behavior of
PI can also be set using the Control Panel Services applet.
Page 6
1.3 - Automatic Startup
1.3.1 Automatic Startup and Shutdown on UNIX Systems
Shutdown and startup for UNIX systems varies with platform, but there are generally two
varieties: BSD style systems use one file, /etc/inittab, which specifies what scripts to run in
each run level, while System V flavors of UNIX use scripts which reside in a set of
directories called rcn.d, where n is an number ranging from 0 on up. Usually these
subdirectories are in the /etc directory, but can be in others (HP-UX 10 has them under /sbin,
for example). Here, we're going to give examples of how to configure each of the systems we
support.
No matter which UNIX platform you're using, if you want to have PI automatically start up
when the system boots or reboots, and shut down when the system shuts down, you MUST
ensure that the .profile or .login file for piadmin does not require interaction with a terminal.
This means that if you use, for example, tset to set the TERM variable, you must first check
to see if there is a terminal attached to the current process. One way to do this is:
if tty -s ; then tset .... fi
Automatic Startup/Shutdown for Solaris 2.x
Solaris recognizes numerous run levels:
Run Level Purpose
s or S single user (used for administering the system)
2 standard level, non-networked
3 default level
4 standard level, user-defined
Which processes run at each level is determined by a set of scripts, /etc/rcS through /etc/rc6.
These scripts look in the directories /etc/rc#.d (where # = 0, 2, 3, etc.) for scripts that begin
with a K or an S. The K scripts are used to kill processes, and the S scripts are used to start
processes. When the system moves from level 3 to level 2, the K scripts in /etc/rc2.d are
executed first, then the S scripts. The scripts are run in ASCII collated sequence, so K02stop
is run before K04metoo. On shutdown or reboot, the system runs the scripts in /etc/rc0.d.
If you are using the default run level, you will need to put the PI startup in /etc/rc3.d. The
shutdown script for PI needs to be in /etc/rc2.d, so PI will be shut down if the system goes to
non-networked mode, and also in /etc/rc0.d, so PI will be shut down if the system is halted or
rebooted.
Note: Solaris systems should be restarted using shutdown -i 6. This will cause the
shutdown scripts to be run before running reboot. The reboot command simply
restarts the kernel, without taking the time to shut down processes properly. The
command shutdown -i 5 is for powering down.
Script files are actually kept in /etc/init.d, with links placed in the /etc/rc#.d directories. So, in
/etc/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to
change the lines that specify where to find PI on your system.
PI Server System Management Guide Page 7
Chapter 1 - Starting and Stopping PI
#!/bin/ksh
#
# Filename: /etc/init.d/PI
#
# become piadmin to start/stop PI
PATH=/sbin:/usr/sbin:/usr/bin
export PATH
case "$1" in
'start')
if [ -f /etc/init.d/PIstart ] ; then
su - piadmin -c "/etc/init.d/PIstart" > /dev/console 2>&1
fi
;;
'stop')
if [ -f /etc/init.d/PIstop ] ; then
su - piadmin -c "/etc/init.d/PIstop" > /dev/console 2>&1
fi
;;
*)
echo "usage: $0 {start|stop}"
;;
esac
#!/bin/ksh
#
# Filename: /etc/init.d/PIstart
# Make sure to set the directory in these
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistart.sh ] ; then
cd /opt/pi/adm
nohup ksh pistart.sh
fi
#!/bin/ksh
#
# Filename: /etc/init.d/PIstop
# Make sure to set the directory in these
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistop.sh ] ; then
cd /opt/pi/adm
ksh pistop.sh
fi
Next, set the owner, group, and permissions on these files to match the other files in this
directory:
root> chgrp sys /etc/init.d/PI*
root> chmod 755 /etc/init.d/PI*
Page 8
1.3 - Automatic Startup
Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on
the startup file is higher than the S## number for inetd, and that the K## number for the kill
file is lower than the K## number for inetd (in both directories).
root> ln -s /etc/init.d/PI /etc/rc3.d/S96PI
root> ln -s /etc/init.d/PI /etc/rc2.d/K04PI
root> ln -s /etc/init.d/PI /etc/rc0.d/K04PI
Verify that these files have the same owner, group, and permissions as other startup files in
those directories.
Finally, test your scripts before you restart your machine. To stop PI:
root> sh /etc/rc0.d/K04PI stop
Verify that PI processes shut down.
root> sh /etc/rc3.d/S96PI start
Verify that PI starts properly.
If there is any problem with stopping or restarting PI, remove the links in the /etc/rc#.d
directories until you've debugged and fixed the problems. The files in the /etc/init.d directory
will not affect your system as long as there are not links in the /etc/rc#.d directories.
Automatic Startup/Shutdown for HP-UX 10
HP-UX 10 recognizes numerous run levels:
Run Level Purpose
s or S Single user (used for administering the system)
1–6 standard levels (1 is single-user, 2 is default, 3 and up are user-defined)
Which processes run at each level is determined by the /sbin/rc script. This script looks in the
directories /sbin/rc#.d (where # = 1, 2, 3, etc.) for scripts that begin with a "K" or an "S". The
"K" scripts are used to kill processes, and the "S" scripts are used to start processes. When
moving down from a higher level to a lower level, all "K" scripts in all the intervening levels
are run. When moving up to a higher level, all "S" scripts in all intervening levels are run. So
when the system moves from level 4 to level 2, the "K" scripts in /sbin/rc3.d are executed,
then the "K" scripts in /sbin/rc2.d. The scripts are run in ASCII collated sequence, so
K002stop is run before K004metoo.
If you are using the default run level of 2, you must put the PI startup in /sbin/rc3.d. The
shutdown script for PI needs to be in /sbin/rc%.d, where % is the default run level, minus 1,
so PI will be shut down if the system goes out of the default run level to any other level, or if
the system is halted or rebooted. To determine your default run level, check the line in
/etc/inittab that reads "init:#:initdefault:." The # is the default run level for the system.
Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So,
in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to
change the lines that specify where to find PI on your system.
#!/bin/ksh
PI Server System Management Guide Page 9
Chapter 1 - Starting and Stopping PI
#
# Filename: /sbin/init.d/PI
#
# become piadmin to start/stop PI
PATH=/sbin:/usr/sbin:/usr/bin
export PATH
case "$1" in
'start')
if [ -f /sbin/init.d/PIstart ] ; then
su - piadmin -c "/sbin/init.d/PIstart" > /dev/console 2>&1
fi
;;
'stop')
if [ -f /sbin/init.d/PIstop ] ; then
su - piadmin -c "/sbin/init.d/PIstop" > /dev/console 2>&1
fi
;;
'start_msg')
echo "Starting PI"
;;
'stop_msg')
echo "Shutting down PI, please wait"
;;
*)
echo "usage: $0 {start|stop}"
;;
esac
#!/bin/ksh
#
# Filename: /sbin/init.d/PIstart
# Make sure to set the directory in these
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistart.sh ] ; then
cd /opt/pi/adm
nohup ksh pistart.sh
fi
#!/bin/ksh
#
# Filename: /sbin/init.d/PIstop
# Make sure to set the directory in these
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistop.sh ] ; then
cd /opt/pi/adm
ksh pistop.sh
fi
Next, set the owner, group, and permissions on these files to match the other files in this
directory:
Page 10
1.3 - Automatic Startup
root> chgrp sys /sbin/init.d/PI*
root> chmod 755 /sbin/init.d/PI*
Then, you'll need to set the links in the rc#.d directories. Make sure the S### number on the
startup file is higher than the S### number for inetd, and the K### number for the kill file is
lower than the K### number for inetd (in both directories). Note that HP-UX uses three
digits in the link file names as opposed to the two digits used by other varieties of UNIX.
Here, run level 3 is our default run level, so we're putting the start script in /sbin/rc3.d, and
the kill script in /sbin/rc2.d:
root> ln -s /sbin/init.d/PI /sbin/rc3.d/S960PI
root> ln -s /sbin/init.d/PI /sbin/rc2.d/K004PI
Verify that these files have the same owner, group, and permissions as other startup files in
those directories.
Finally, test your scripts before you restart your machine. To stop PI:
root> sh /sbin/rc2.d/K004PI stop
Verify that PI processes shut down.
root> sh /sbin/rc3.d/S960PI start
Verify that PI starts properly.
If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d
directories until you've debugged and fixed the problems. The files in the /sbin/init.d
directory will not affect your system as long as there are no links in the /sbin/rc#.d
directories.
Automatic Startup/Shutdown for PI on Compaq Tru64 and Tru64 UNIX 4.0x
This operating system was originally known as DEC UNIX.
Compaq Tru64 UNIX recognizes four run levels:
Run Level Purpose
0 shutting down
s single user (used for administering
the system)
2 local (non-networked)
3 default, networked
Which processes run at each level is determined by a set of scripts, /sbin/rc0, /sbin/rc2, and
/sbin/rc3. These scripts look in the directories /sbin/rc#.d (where # = 0, 2, 3) for scripts that
begin with a "K" or an "S". The "K" scripts are used to kill processes, and the "S" scripts are
used to start processes. When the system moves from level 3 to level 2, the "K" scripts in
/sbin/rc3.d are executed first if the system is not coming from single-user mode, then the "S"
scripts are run (remember the system goes to single-user on boot, then goes to the default run
level). The scripts are run in ASCII collated sequence, so K02stop is run before K04metoo.
On shutdown or reboot, the system will run the scripts in /sbin/rc0.d.
PI Server System Management Guide Page 11
Chapter 1 - Starting and Stopping PI
You should put the PI startup in /sbin/rc3.d. The shutdown script for PI must be in
/sbin/rc2.d, so PI will be shut down if the system goes to non-networked mode, and also in
/sbin/rc0.d, so PI will be shut down if the system is halted or rebooted.
Note: Compaq Tru64 systems should be restarted using shutdown to go to single-
user mode, then shutdown -r to reboot or shutdown -h to halt. This will cause the
shutdown scripts to be run. Using shutdown -r or shutdown -h from run level 3 or 2
will bypass the scripts and simply kill all processes, without taking the time to shut
down processes properly.
Script files are actually kept in /sbin/init.d, with links placed in the /sbin/rc#.d directories. So,
in /sbin/init.d, you need to create the following three files: PI, PIstart and PIstop. Be sure to
change the lines that specify where to find PI on your system.
#!/bin/ksh
#
# Filename: /sbin/init.d/PI
#
# become piadmin to start/stop PI
PATH=/sbin:/usr/sbin:/usr/bin
export PATH
case "$1" in
'start')
if [ -f /sbin/init.d/PIstart ] ; then
su - piadmin -c "/sbin/init.d/PIstart" > /dev/console 2>&1
fi
;;
'stop')
if [ -f /sbin/init.d/PIstop ] ; then
su - piadmin -c "/sbin/init.d/PIstop" > /dev/console 2>&1
fi
;;
*)
echo "usage: $0 {start|stop}"
;;
esac
#!/bin/ksh
#
# Filename: /sbin/init.d/PIstart
# Make sure to set the directory in these
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistart.sh ] ; then
cd /opt/pi/adm
nohup ksh pistart.sh
fi
#!/bin/ksh
#
# Filename: /sbin/init.d/PIstop
# Make sure to set the directory in these
Page 12
1.3 - Automatic Startup
# files to your PIHOME directory, in all
# places
#
if [ -f /opt/pi/adm/pistop.sh ] ; then
cd /opt/pi/adm
ksh pistop.sh
fi
Next, set the owner, group, and permissions on these files to match the other files in this
directory (check the setting on your system):
root> chown bin /sbin/init.d/PI*
root> chgrp bin /sbin/init.d/PI*
root> chmod 755 /sbin/init.d/PI*
Then, you'll need to set the links in the rc#.d directories. Make sure that the S## number on
the startup file is higher than the S## number for inet, and that the K## number for the kill
file is lower than the K## number for inet (in both directories).
root> ln -s /sbin/init.d/PI /sbin/rc3.d/S96PI
root> ln -s /sbin/init.d/PI /sbin/rc2.d/K04PI
root> ln -s /sbin/init.d/PI /sbin/rc0.d/K04PI
Verify that these files have the same owner, group, and permissions as other startup files in
those directories.
Finally, test your scripts before you restart your machine. To stop PI:
root> sh /sbin/rc2.d/K04PI stop
Verify that PI processes shut down.
root> sh /sbin/rc3.d/S96PI start
Verify that PI starts properly.
If there is any problem with stopping or restarting PI, remove the links in the /sbin/rc#.d
directories until you've debugged and fixed the problems. The files in the /sbin/init.d
directory will not affect your system as long as there are no links in the /sbin/rc#.d
directories.
Automatic Startup/Shutdown for IBM AIX
IBM AIX recognizes numerous run levels:
Run Level Purpose
s (S) or m (M) Single user (used for administering the system)
2 default multi-user run level
3-9 user defined levels
The system determines what processes should run at each level by reading the /etc/inittab file.
The lines in this file tell the system what scripts to run at what run levels. The line with the
initdefault in it (init:#:initdefault:, where # is some number 2-9) tells the system the default
PI Server System Management Guide Page 13
Chapter 1 - Starting and Stopping PI
run level. Each line with this number after the first colon is executed when entering the
default run level. Thus, we need to add a line to the /etc/inittab file:
pisystem:2:once:su - piadmin -c /etc/rc.pistart > /dev/console 2>&1 #
Start PI
Caution: Before editing /etc/inittab, you must save the original under another name. If
you do not and make an error while editing, your system will not boot.
If your initdefault level is not 2, you should replace the 2 with the appropriate number from
initdefault.
For shutdown and reboot, the system uses the /etc/rc.shutdown script. If this file does not
exist, you should create it. Otherwise, just add the last line below to your current file. If you
have to create the /etc/rc.shutdown file, you should give it the same owner, group, and
permissions as the /etc/rc file. As before, you are strongly advised to save a copy of the
original file under another name before editing this file.
#! /bin/ksh
#
# Filename: /etc/rc.shutdown
#
su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1
Now you'll have to create these two files you've told the system to use, /etc/rc.pistart and
/etc/rc.pistop. Be sure to change the directory in these files to the PI Server directory on your
system.
#!/bin/ksh
#
# Filename: /etc/rc.pistart
#
if [ -f /usr/PI/adm/pistart.sh ] ; then
cd /usr/PI/adm
nohup ksh pistart.sh
fi
#!/bin/ksh
#
# Filename: /etc/rc.pistop
#
if [ -f /usr/PI/adm/pistop.sh ] ; then
cd /usr/PI/adm
ksh pistop.sh
fi
You'll need to change the permissions on these files so that piadmin can run them:
root> chmod 755 /etc/rc.pi*
Finally, test your scripts before you restart your machine. To stop PI:
root> su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1
Verify that PI processes shut down.
Page 14
1.3 - Automatic Startup
root> su - piadmin -c /etc/rc.pistart > /dev/console 2>&1
Verify that PI starts properly.
If there is any problem with stopping or restarting PI, you'll need to restore the previous
versions of /etc/inittab and /etc/rc.shutdown until you can find and fix the problem.
Automatic Startup/Shutdown for HP-UX 9
PI Server is no longer supported on HP-UX Version 9.x. The information in this section is
provided as a reference in case you are still running a previous version of PI. You should be
aware that Hewlett-Packard no longer supports HP-UX 9.x and recommends upgrading.
HP-UX 9 uses the /etc/rc file to control system startup. An individual site may also have
additional scripts specified in the /etc/inittab file, to stop and start processes when moving
from one run level to another. If so, the PI System Manager needs to determine which run
levels should have PI running and which should not, and should put suitable entries in the
scripts to stop and start PI when moving from one run level to another. Here, we'll just deal
with the basic system, which uses only the standard /etc/rc file.
Caution: Before editing /etc/rc, save the original under another name. If an error is
made while editing, the system will not boot.
In /etc/rc, there is a section intended for use by the local PI System Manager, "localrc()". In
this section, add the following lines (be sure to add them before vuelogin, if you have it):
#
# start PI
#
su - piadmin -c /etc/rc.pistart > /dev/console 2>&1
There's another directory, /etc/shutdown.d, which has the shutdown scripts for applications on
the system. This directory may be empty.
In any case, you should create a file, /etc/shutdown.d/PIstop, that looks like this:
#! /bin/ksh
#
# Filename: /etc/shutdown.d/PIstop
# Stop PI gracefully
su - piadmin -c "/etc/rc.pistop" > /dev/console 2>&1
This file should have the same owner, group, and permissions as the /etc/rc file. For our
systems, that means running these commands:
root> chown bin /etc/shutdown.d/PIstop
root> chgrp bin /etc/shutdown.d/PIstop
root> chmod 555 /etc/shutdown.d/PIstop
Next create the two files in /etc. Make sure you set the directories in these files to point to
your PI Server directory.
#!/bin/ksh
#
# Filename: /etc/rc.pistart
PI Server System Management Guide Page 15
Chapter 1 - Starting and Stopping PI
#
if [ -f /export/PI/adm/pistart.sh ] ; then
cd /export/PI/adm
nohup ksh pistart.sh
fi
#!/bin/ksh
#
# Filename: /etc/rc.pistop
#
if [ -f /export/PI/adm/pistop.sh ] ; then
cd /export/PI/adm
ksh pistop.sh
fi
Again, you need to set the owner, group, and permissions:
root> chown bin /etc/rc.pi*
root> chgrp bin /etc/rc.pi*
root> chmod 555 /etc/rc.pi*
Then test these scripts before restarting your machine.
root> sh /etc/shutdown.d/PIstop
Verify that PI shuts down.
root> su - piadmin -c "/etc/rc.pistart" > /dev/console 2>&1
Verify that PI starts up properly.
If there is any problem with stopping or restarting PI, you will need to restore your original
/etc/rc file, and remove the new file from the /etc/shutdown.d directory.
1.4 Shutting Down an Individual Subsystem
Shutting down an individual subsystem depends on the operating system. On Windows, look
in the file adm\pisrvstop.bat for the shutdown procedure; on UNIX, adm/pistop.sh. For restart
procedure check adm\pisrvstart.bat and adm/pistart.sh onWindows and UNIX, respectively.
Page 16
Chapter 2. MONITORING PI SYSTEM HEALTH
2.1 Checking Key System Indicators
Each day, check the key elements of your PI System to make sure PI is working efficiently
and correctly. By checking the PI System daily, you can catch problems quickly and you also
familiarize yourself with the normal state of the system. This makes it easier to interpret
system metrics (such as I/O rates) and to find abnormal messages, when they occur.
Area What to check Tools
Backups Have PI System backups been run? piartool -al
Message Log Check the System Message Log to see pigetmsg
whether unusual events have occurred.
Update Manager Are the clients connecting to the pilistupd
PI Server normally?
Tag Data Does the Archive data for a reference tag pisnap.bat or pisnap.sh
look normal?
Snapshot data Is the Snapshot data flow normal? piartool -ss
flow
Archive data flow Is the Archive data flow normal? piartool -as and piartool -qs
Archive Shift Verify that the expected archives are piartool -al
registered and that you have prepared
for the next archive shift.
Interface Logs Check the interface logs to see whether
unusual events have occurred.
IO Rate Interfaces support writing snapshot rates PI Datalink or PI ProcessBook to
Counters to PI Points. The IO rate values and view or trend the IO rate points.
timestamps are a good indicator of
interface health.
Performance All Subsystems publish key performance Windows Performance Monitor.
Counters counters to Windows. Subsystem PI Performance Monitor
(Windows) counters are discussed in this chapter. Interface.
License limits Check the usage statistics and point piartool -lic
and usage counts for your system. Anticipate
license increase needs.
PI Server System Management Guide Page 17
Chapter 2 - Monitoring PI System Health
2.2 Viewing System Messages
During normal operation, the PI Message Subsystem maintains a central log file for messages
from all PI subsystems. PI creates a new log every day, on universal time coordinate (UTC)
time. PI puts the log files in the PI\log directory and names each log according to the date.
The file names are of the form, pimsg_YYMMDD.dat, where:
YYY is years since 1900 (for example,if the year is 2000, YY is 100)
MM is the month (for example, if the month is January, MM is 01)
DD is the day (for example, if it is the fifth of the month, DD is 05)
For example, the log file for January 5, 2000 is named pimsg_1000105.dat.
PI Message log files are binary files that you can view using the pigetmsg utility.The
pigetmsg utility lets you view messages according to time, subsystem, or sender’s identity.
The pigetmsg utility requires PI to be running.
2.2.1 Available Log History
The number of files left on the system determines the amount of log history available. PI
creates a new log file every day. PI keeps log files for 35 days, at which point it automatically
purges them from the system. If you want to keep the log files longer than 35 days, you can
back them up before PI deletes them. If necessary, you can restore the backed up files at a
later date for investigation.
Note: The message log can be written (but not read) using function calls in the PI
API. It can be both read and written using the function calls in the PI SDK.
You can also view the log files from PI SMT.
2.2.2 Viewing System Messages with pigetmsg
In general, the message source is a PI subsystem, but it can be a facility within a subsystem,
such as pipoint if a point database error is recorded. You can run pigetmsg in interactive or
non-interactive mode.
The pigetmsg utility is located in the PI/adm directory. To get help on usage of the pigetmsg
utility, type:
pigetmsg /?
Using pigetmsg in Non-Interactive Mode
When you use pigetmsg in non-interactive mode, you specify all necessary parameters on the
command line when you call pigetmsg. In this mode, There are no defaults for the start time
(-st), end time (-et), or maxcount (-mc) options because the utility requires that at least two of
these three parameters (start time, end time, max count) be defined.
If start time and end time are specified, the utility returns messages from the start
time to the end time.
Page 18
2.2 - Viewing System Messages
If start time and max count are specified, the utility returns the number of messages
specified by the max count beginning from the start time.
If end time and max count are specified, the utility returns the number of messages
specified by the max count up to and including the end time.
If start time, end time, and max count are all specified, the utility returns messages
beginning at the start time and finishing when either the number of messages
specified in the max count or the end time is reached.
All the command line options for pigetmsg are listed in the following table.
Argument Description
-st Start time. This should be entered in PI time format.
-et End time. This should be entered in PI time format.
-mc Max count. This is an integer the total number of messages to return.
-id This is an integer that represents the specific message identification number
from the text-file: 0 for the free-format messages. The default is all messages.
-pn This is the message source, either a specific program name (pinetmgr) or a wild-
card mask (* for all programs, *arc* for all archive related sources, etc.). The
default is all programs.
-msg A string mask selection for the message text. The default is * (show everything).
-dc Number of message to display at one time. The default is to display all
messages.
Using pigetmsg in Interactive Mode
When you run pigetmsg without specifying at least two of the required parameters (-st, -et,
and -mc), the pigetmsg utility goes into interactive mode. In the interactive mode, you are
prompted to enter these parameters. The standard defaults for the parameters are obtained by
entering a carriage return, <Enter>, after each prompt.
In the interactive mode, there is a default for the start time, end time, and max count. The
default for the start time is *-15m, which is 15 minutes prior to the current time. The end time
is * which is the current time and the max count default is no limit.
Searching and Sorting the Messages
To list all messages received from a specific subsystem such as the Totalizer for today, use:
pigetmsg -st t -et "*" -pn pitotal
On UNIX systems, * on the command line is expanded to perform a directory search. Thus
for pigetmsg it must be specified either as \* or *. The same is true for any mask containing
*.
To list the last 100 messages that have the word “error” as part of the message and then
display these messages 10 at a time, use:
PI Server System Management Guide Page 19
Chapter 2 - Monitoring PI System Health
pigetmsg -et "*" -mc 100 -msg "*error*" -dc 10
To send pigetmsg results to a file, use the standard output redirection operator (>):
pigetmsg -st "*-1h" -et "*" > myfile.txt
Using pigetmsg Remotely
The pigetmsg utility also supports remote logins to other PI Server systems.
An interactive remote pigetmsg session is initiated with the -remote argument:
pigetmsg -remote
pigetmsg prompts the user for the required connection details: node name, TCP/IP port, user
name, and password. The term “node” refers to the TCP/IP host name or TCP/IP Address of
the PI Server.
Alternatively, you can initiate a remote passing all arguments on the command line.
Parameter Description
-username Remote PI Server username
-port TCP/IP port number
-node Remote PI Server node name
-password Remote PI Server password
For example, to begin an interactive session as the user, piadmin, with the password,
“buddy” on a remote NT host named Samson, use:
pigetmsg -remote -node Samson -username piadmin -port 5450 -password
buddy
2.2.3 Viewing Messages When the Message Subsystem Goes Down
If the Message Subsystem is not available, messages are written to the Windows error log (or
to standard output on UNIX). On Windows, use the Event Viewer to see messages when PI is
running as Services, or check the command windows if running interactively. The PI Server
messages that went to the event log messages are stored back to the PI Message Log on
system startup and on regular time intervals – every 3 minutes.
On UNIX, you will find a log file for each subsystem in the PI/log directory. On both
platform types, some startup messages may be written to these locations before the PI
Message Subsystem is active.
2.2.4 Viewing Message Log Files Generated on other Servers
There are times when it is useful to read message log files that were generated on a different
PI Server. The PI Message Subsystem executable can be run in an offline mode for this
purpose.
Running the PI Message Subsystem in offline mode is very similar to pigetmsg; the
significant difference is that the log file must be specified. Message log files are created
Page 20
2.2 - Viewing System Messages
daily; each file covers one day. The file naming convention contains the year month and date.
The log files are created in the PI\log directory.
Even though all messages will be read from the log file, pinetmgr must be running.
The PI Message Subsystem executable, pimsgss, is located in the PI\bin directory. Here is an
example of running pimsgss offline to view messages from February 27, 2003:
D:\PI\bin>pimsgss -file ..\log\pimsg_1030227.dat
Message ID [A], (0-n) (A)ll (H)ead (T)ail (Q)uit (?):
Once the log file is specified, the behavior is identical to pigetmsg. Only messages in the
time period covered by the specified file can be viewed.
Offline use also allows specifying all arguments on the command line, just like pigetmsg.
Messages that match the command line arguments are immediately displayed. Here is an
example:
D:\PI\bin>pimsgss -file ..\log\pimsg_1030227.dat -st "27-feb-03 12:00" -
et "27-feb-03 15:00"
0 pinetmgr 27-Feb-03 12:07:16
>> Connection accepted: Process name: piconfig(1696) ID: 88
0 pinetmgr 27-Feb-03 12:11:54
>> Deleting connection: Piconfig(1696), Shutdown request received from
piconfig(1696) (8), ID: 88
0 pinetmgr 27-Feb-03 12:35:20
>> Connection accepted: Process name: Piconfig(1484) ID: 89
0 pinetmgr 27-Feb-03 12:38:08
>> Deleting connection: Piconfig(1484), GetQueuedCompletionStatus
error: Broken Pipe [109] The pipe has been ended.
Connection: Piconfig(1484) (14, 109), ID: 89
0 pinetmgr 27-Feb-03 13:24:08
>> PInet accepted TCP/IP connection, cnxn ID 90 Hostname:
olive.osisoft.com, 208.243.230.129
2.2.5 Interpreting Error Messages (pidiag)
Sometimes the message log includes error messages. Use the pidiag utility to interpret error
codes:
pidiag -e errorcode
This will display the associated error message. For example, if the error code is 10722, you
would type:
pidiag -e -10722
[-10722] PINET: Timeout on PI RPC or System Call
You can also use the pidiag utility to translate operating system error codes, which are
always positive numbers. Note that the error code translation takes place on the operating
system running pidiag. For example, on Windows, you could issue the command:
pidiag -e 2
[2] The system cannot find the file specified.
PI Server System Management Guide Page 21
Chapter 2 - Monitoring PI System Health
Avoid reading error codes from the PI Server message log on one operating system and
translating them with pidiag -e on another.
2.2.6 Subsystem Healthchecks (RPC Resolver Error Messages)
Every few minutes, the pinetmgr sends a healthcheck message to each of the PI subsystems.
If one doesn’t respond within a given amount of time, pinetmgr will report the following
message and the subsystem (RPC resolver) is marked off-line.
>> Deleting connection: pisnapss, Subsystem Healthcheck failed.
If an RPC is made to a subsystem that is marked off-line, the following message is generated.
[-10733] PINET: RPC Resolver is Off-Line
The following message indicates that the first part of a message was retrieved. This contains
the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout
occurred.
>> Deleting connection: pisnapss, Connection lost(1),
[-10731] PINET: incomplete message
2.3 Monitoring Snapshot Data Flow
Windows-based PI Server exposes the Snapshot data displayed by piartool -ss as Windows
Performance Counters. These counters may be viewed with the Windows Performance
Monitor or recorded to the PI Server with the OSI Performance Monitor Interface.
2.3.1 Listing Current Snapshot Information with piartool -ss
The piartool -ss command lists the current Snapshot information every 5 seconds until you
type <CTRL-C>. This utility is a quick way to view the overall state of the PI System. It
shows the total number of events received and sent to the archive. (The third column gives
the difference in the counters over 5 second periods.)
Under normal steady state conditions, the Snapshot event count as well as archive posts
should increase regularly. Events in overflow queue and Event Queue record count should be
zero.
Output of piartool -ss should look similar to listing below.
$ piartool -ss
Counters for 7-Aug-03 14:35:56
Point Count: 10033 0
Snapshot Events: 1228011 0
Out of Order Snapshot Events: 130 0
Snapshot Event Reads: 392 0
Events Sent to Queue: 771952 0
Events in Queue: 0 0
Number of Overflow Queues: 0 0
Total Overflow Events: 0 0
Primary Capacity Remaining: 2540349 0
Page 22
2.3 - Monitoring Snapshot Data Flow
Each of the counters in the output is explained in the following sections.
Note: The piartool utility can monitor a remote PI Server by specifying the -remote
argument after all other arguments. piartool prompts the user for remote connection
information.
Point Count
The Point Count is the number of points that are currently defined in the Point Database. It is
incremented when a point is created and decremented when a point is deleted.
Snapshot Events Counter
An “Event” is the fundamental PI data element. It represents a value or status of a unique data
source at a specific time. Specifically an event is a Value, Timestamp, and PointID. Most
events come from PI API- or PI-SDK-based interfaces. The PI Subsystems (“Applications”)
PI Batch, PI Performance Equations, PI Total, and PI Alarm, as well as manual input and
laboratory systems are also event sources.
Every Snapshot event increments the Snapshot Events Counter. The PI Snapshot Subsystem
applies a compression algorithm to every event. The compression algorithm determines if the
previous Snapshot event is passed on to the archive.
Out of Order Snapshot Events Counter
Events older than the current Snapshot event are out-of-order events. These events bypass
compression and are sent directly to the archive. This counter shows the number of times this
has occurred. The Archive Subsystem maintains a similar counter; see the Monitor Archive
section in this chapter.
Large out of order event counts might indicate a problem with the PI Server; this may lead to
poor performance. A common cause is an erroneous system clock changes of the server
machine or a data source machine. To identify the tags receiving out of order data use:
piartool -ooo
This gives a list of all the tags with any out of order events since the Snapshot Subsystem
started or since the out of order flags reset. To reset the flags use:
piartool -ooo -r
When the -r flag is used, only tags that received an out-of-order event since the last piartool -
ooo query are listed. The utility can run repeatedly with or without the -r flag by specifying a
wait time (in seconds) between repeats. This is useful for catching the offending tags as new
events come in:
piartool -ooo 10
Whenever a repeat time is specified, a current timestamp appears in the output each time the
utility writes data.
When using repeats, the utility is stopped with <CTRL-C>.
$ piartool -ooo -r 10
PI Server System Management Guide Page 23
Chapter 2 - Monitoring PI System Health
7-Aug-03 14:42:12> The following points had out-of-order Snapshot
events:
15: pitot1
17: pitot3
18: pitot4
19: pitot5
20: pitot5run
21: pitot5ramp
22: pitot5est
23: pitot_avg
24: pitot_max
25: pitot_min
26: pitot6count
27: pitot6time
28: pitot6timeNE
29: pitot_1
7-Aug-03 14:42:22> No out-of-order Snapshot events found
7-Aug-03 14:42:32> No out-of-order Snapshot events found
Snapshots Events Read Counter
Count of all Snapshot reads. This is a simple measurement of how many Snapshot values are
read by all applications.
Events Sent to Queue Counter
Events that pass compression, or are out of order are sent to the Event Queue, and thus
increment this counter. Under normal operating conditions this count indicates the number of
events that passed the compression test (that is, the events were different from existing events
and could not be eliminated) and are being sent to the archive.
The ratio of Snapshot events to Events Sent to Queue is the system aggregate compression
ratio. This ratio gives a quick view of overall system compression tuning. Ratios less then 2:1
indicate low compression; a compression tuning evaluation should be performed. Ratios
greater than 10:1 indicate over compression; a compression tuning evaluation should also be
performed.
Three Point Database attributes affect compression: CompDev, CompMin, and CompMax.
These are known as the compression specifications.
If a point has its Compressing point attribute set to FALSE, all new events are sent to the
Archive Subsystem.
Events in Queue Counter
Events passed to the EventQueue are put in First-In-First-Out order. The Events in Queue
Counter is incremented when the event is put in the Queue; it is decremented when the
Archive Subsystem successfully retrieves and processes an event.
When the system is shutdown, the Event Queue is preserved in the file PI\dat\pimapevq.dat.
This assures no data loss when the system shuts down or when the archive subsystem is not
processing events at the same rate as they come in.
Page 24
2.4 - Monitoring the Event Queue
Number of Overflow Queues Counter
If the queue PI\dat\pimapevq.dat becomes completely full, a new queue is created. This
should not occur under normal circumstances and this number will be 0. However, if the
archive is not processing events, a number of such queues (up to 65536) can be created. This
counter shows how many queues were created. These additional queues are automatically
deleted after the archive subsystem processes them.
Note: When multiple Event Queues exist, the file pimapevq.dat is renamed to
pimq0000.dat and additional queues are named pimq<id>.dat where id is the queue
number in hexadecimal representation (from 0000 to FFFF). The piartool -qs
command always shows information from the queue to which the Snapshot
Subsystem is writing (primary queue).
Total Overflow Events Counter
This is the total number of events in all Overflow Queues. The sum of this counter and the
Events in Queue counter are all the events not yet processed by the archive.
Primary Capacity Remaining Counter
This counter shows the estimated number of additional events that can be placed in the
primary queue.
2.4 Monitoring the Event Queue
After installation and regularly after significant changes, the System Manager should verify
the proper sizing and functioning of the Event Queue. The command piartool -qs allows you
to look at internal counters and statistics about the queue activity.
2.4.1 piartool -qs
The piartool -qs command lists the Event Queue statistics every 5 seconds until you type
<CTRL-C>.
The column at the right margin gives the difference in the count since the previous 5 seconds.
The counters are reset to 0 when the Archive Subsystem is started.
$ piartool -qs
Counters for 7-Aug-03 17:22:45
Physical File Size (MB): 64 0
Page Size (KB): 1024 0
Total Data Pages: 63 0
Write Page Index: 0 0
Read Page Index: 0 0
Total Page Shifts: 0 0
Available Pages: 63 0 (100.0%)
Average Events per Page: 40330 1
Estimated Remaining Capacity: 2540790 63 (2.2 hr)
Total Bytes Written (MB): 0 0
Total Event Writes: 14476 8007 (579/sec)
PI Server System Management Guide Page 25
Chapter 2 - Monitoring PI System Health
Total Event Reads: 14476 8007 (579/sec)
Current Queue Events: 0 0
Overflow Queues: 0 0
Total Overflow Events: 0 0
Current Queue Id: 0 0
Queue Size
The Physical File Size shows the current size of the Event Queue on disk (the file
pimapevq.dat or any overflow queues). The Page Size is the portion of the file that is loaded
into memory for faster access. The Event Queue is a circular buffer of pages and each page is
a circular buffer of events. When a page is full, the Snapshot Subsystem tries to write into the
next one and the Archive Subsystem reads the pages in the same order they were written. The
Total Data Pages shows the number of pages, obtained by dividing the queue size by the
page size (minus one for the queue header).
Page Activity
The Write Page Index shows the page the Snapshot Subsystem is currently writing to.
Similarly, the Read Page Index indicates the page from which the Archive Subsystem is
reading. Under normal conditions, these two numbers are identical. If the Archive Subsystem
is not reading at the same pace the Snapshot is writing, page shifts will occur and the Total
Page Shifts counter will increment. At any time, the Available Pages counter shows how
many free pages are left in the current queue.
Queue Capacity
Based on the average size of all events, the Snapshot Subsystem maintains the number of
Average Events per Page. From this it derives an Estimated Remaining Capacity in number
of events (also shown by piartool -ss).
Total Bytes Written shows the volume of data that transited through the Event Queue since
the Snapshot Subsystem was last started.
Note: A System Manager should try to configure the queue so that it is big enough to
hold a few days worth of data. To configure the queue size, see Tuning the PI Server
in Chapter 3, Troubleshooting and Repair.
Event Rates
Every time the Snapshot sends an event to the archive, the Total Event Writes counter gets
incremented. Similarly, when events are read by the Archive Subsystem, the Total Event
Reads is incremented. The difference between these counters shows the Current Queue
Events (total events per queue).
Overflow Queues
When the current queue is entirely full, the Snapshot Subsystem creates additional queue files
of the same size. The Overflow Queues counters and Total Overflow Events (same as in
piartool -ss) indicates how many queues exist and how many events they hold. The Current
Page 26
2.5 - Monitoring the Archive
Queue Id shows the sequence number of the primary queue (always 0 under normal
conditions).
2.5 Monitoring the Archive
On a daily basis, the System Manager should look at the internal counters for the Archive
Subsystem. This enables you to predict the next archive shift as well as to monitor ongoing
system behavior and performance. You can use piartool -as and piartool -al for this purpose.
Other piartool commands are discussed in the chapter, Managing Archives.
Note: Windows-based PI Server exposes the Archive data displayed by piartool -as
as Windows Performance Counters. These counters may be viewed with the
Windows Performance Monitor or recorded to PI Server with the OSI Performance
Monitor Interfaces. This subject is covered in detail later in this chapter.
2.5.1 piartool -as
The piartool -as command lists the Archive Subsystem (piarchss) internal counters every 5
seconds until you type <CTRL-C>.
The column at the right margin gives the difference in the count since the previous 5 seconds.
The counters are reset to 0 when the Archive Subsystem is started.
$ piartool -as
Counters for 7-Aug-03 14:51:10
Archived Events: 1050621 1485
Out of Order Events: 0 0
Events Cascade Count: 0 0
Events Read: 5 0
Read Operations: 0 0
Cache Record Count: 0 0
Cache Records Created: 6 0
Cache Record Memory Reads: 5 0
Cache Clean Count: 0 0
Archive Record Disk Reads: 146342 219
Archive Record Disk Writes: 152737 226
Unflushed Events: 12431 -203
Unflushed Points: 3131 -48
Point Flush Count: 133491 211
Primary Archive Number: 5 0
Archive Shift Prediction (hr): 1 0
Archiving Flag: 1 0
Archive Backup Flag: 0 0
Archive Loaded Flag: 1 0
Shift or System Backup Flag: 0 0
Failed Archive Shift Flag: 0 0
Overflow Index Record Count: 0 0
Overflow Data Record Count: 5082 4
These counters are explained below.
PI Server System Management Guide Page 27
Chapter 2 - Monitoring PI System Health
The piartool utility can run remotely by specifying some additional parameters on the
command line as described in Table 3–1. Options for Use with piartool on page 37.
Archived Events Counter
The Archived Events counter is incremented for every new event written to the archive (via
the archive cache). This count includes delete and edit events.
Out-of-Order Events Counter
The Archive Subsystem receives events from the Snapshot Subsystem. If the timestamp of
the event is older than the last event in the target record, it is considered an out-of-order event
and is added to this counter.
Excessive out-of-order events might lead to system problems such as excess CPU
consumption, excessive disk I/O, and archives filling faster than expected.
Events Cascade Count
Out of order events are inserted into the target record. The insert requires moving other
events within the record. If the record is full, one or more events are forced out of the record
into the adjacent record. This counter is incremented each time an insertion forces an event
out of a record. This counter is an indication of the impact of out of order events on the
archive.
Events Read Counter
Number of events read by all applications. For example, a trending application requests an
array of events over a specified time period. This counter is incremented for each event
returned.
Read Operations Counter
Number of archive read requests. Each archive read request increments this counter once,
regardless of the number of events returned.
Archive Memory Cache Counters
The Archive Subsystem uses a memory cache when handling events sent to the archive disk
file.
During routine operation, the cache is automatically flushed to disk at least every 15 minutes.
Abrupt system shutdowns, such as power loss, should lose no more than the last 15 minutes
of data. This value may be changed via a configurable timeout table parameter.
The data archive cache architecture provides large performance gains over reading and
writing directly to disk. The cache even provides significant performance over the Operating
System file cache. As with all file cache designs, the disk image will often be slightly
inconsistent; therefore archive backup cannot be performed without coordination with the
Archive Subsystem. The utility piartool -bs places the archive in a safe consistent state for
backups; piartool -be returns the archive to normal operation. This is discussed in detail in
the system backup section in Chapter 3, Troubleshooting and Repair.
Page 28
2.5 - Monitoring the Archive
The cache consists of archive records loaded into memory. Records are added as needed; they
are deleted when unused for a certain length of time. Cache Record Count yields the current
count. Cache Records Created is incremented when memory is allocated for a new record.
When archive data is requested (for example, the user is trying to trend a point in PI
ProcessBook), the Archive Subsystem goes to the cache to retrieve the event data. If the
record is not there, the Archive Subsystem loads the record from disk to the cache; Archive
Record Disk Reads is incremented.
When writing events to the archive, they are stored first in memory. Unflushed Events
Counter indicates the total number of events not yet flushed to disk. Unflushed Points counter
indicated the number of points with any number of events not yet flushed.
Archive Record Disk Writes is incremented each time a record is written to disk. This occurs
during the regular cache flush every 15 minutes. It also occurs when the number of un-
flushed events for a point exceeds the configured maximum.
Cache Record Memory Reads is incremented for each read access.
Cache Clean Count indicates the number of records that were removed from the cache. The
archive cache contains a finite number of records. Old or low use records are removed from
memory to make room for most recently accessed records.
Primary Archive Number
The Primary Archive Number is an internal identifier and should be ignored. It is not to be
confused with the sequence number of the archive, as listed by piartool -al.
Archive Shift Prediction
Archive Shift (hr) estimates the predicted time to the next archive shift. Use piartool -al to
list the target archive file for shift. The target archive will be initialized on shift; if it contains
data, make sure it is backed up. If this data is required to remain online, a new archive of
adequate size should be created and registered.
When the current archive is less then 20% full, the estimate is 0. In order to determine
whether a zero estimate means the archive is nearly full or not, run piartool -al. The message
will tell you if there is not enough data for a prediction.
Shift Time: Not enough information for prediction
The shift prediction in piartool -as differs slightly from the one in piartool -al. The piartool
-al figure is calculated when called. piartool -as shows the latest 10 minutes average. The
latter number is available as a Windows Performance Counter.
Archiving Flag
Indicates whether or not events may be written to the archive; a value of 1 indicates events
may be written, a value of 0, events may not be written. The Archiving Flag is set to 1 when
there is a mounted Primary Archive. A Primary Archive may be registered but not mounted,
for example during an archive shift. In this case, the Archiving Flag would be set to 0. This
flag is also set to 0 when in backup mode.
PI Server System Management Guide Page 29
Chapter 2 - Monitoring PI System Health
All registered archives may be viewed using piartool -al. The Archive Flag is set to 0 if the
Primary Archive becomes full and there is no other archive file available into which to shift.
Note that the Primary Archive will never overwrite itself.
Archive Backup Flag
This flag is set to 1 when the archive is in backup mode. Backup mode indicates the archive
file is in a consistent state unlocked state and may be backed up. The value is 0 when the
archive is available for normal access.
Backup mode is entered and exited by running piartool -bs and piartool -be, respectively.
Archive Loaded Flag
This flag is 1 when a valid primary archive is mounted. 0 if the primary archive is not
mounted.
Shift or System Backup Flag
This flag is 1 when the archive is in shift mode or the Archive Subsystem has been placed in
backup mode. Shifts occur automatically or can be forced via piartool -fs. System backup
mode is entered with piartool -systembackup.
Failed Archive Shift Flag
Set to 1 when a shift should occur but no shiftable archive exists. Under normal conditions
this flag is 0.
Overflow Index Record Count
Number of index records. Index records speed up access to overflow records. Index records
are created when two overflow records for a point are full and third one is being created. This
counter is a measurement of archive file consumption.
Overflow Data Record Count
Number of non-primary data records. Each archive has a primary record for each point. When
this record is full, data is written to overflow records. This counter gives a measurement of
archive consumption.
2.6 Monitoring the Update Manager
The Update Manager provides change notification of Snapshot events, Point Database,
Module Database, Batch Database and Archive changes for applications such as PI
ProcessBook, Interfaces, and other PI API or PI-SDK-based applications. For example, a
trend application can request Snapshot update notification on points being trended. The
Update Manager queues all new Snapshots for these points. Periodically the trend application
retrieves and plots the new events.
Page 30
2.7 - System Date and Time
2.6.1 Adjusting the Pending Update Limit
By default, the PI Update Manager maintains up to 4095 pending updates per consumer.
Similarly, TotalUpdateQueue parameter sets the maximum events queued in the entire
update-manager database. The default is 100,000.
If either these limits is reached, a message is sent to the PI Message Log. Another message
sent when the level goes back below 99% of the limit and queuing is resumed. Messages for
consumers using less then 0.1% of the TotalUpdateQueue limit (100 for the default) are still
queued even when the total limit is reached.
It is possible to change this number by adding an entry named MaxUpdateQueue to the
PITimeout Table using piconfig:
C:\PI\adm>piconfig
* (Ls - ) Piconfig> @tabl pi_gen,pitimeout
* (Ls - PI_GEN) Piconfig> @mode create
* (Cr - PI_GEN) Piconfig> @istr name,value
* (Cr - PI_GEN) Piconfig> maxupdatequeue,6000
*> maxupdatequeue,6000
* (Cr - PI_GEN) Piconfig> @ends
When to Change the Pending Update Limit
The default is suitable for most systems, with the following exceptions:
The number should be increased on systems with very large physical memory, high
frequency of updates (normally snapshots) and applications that might retrieve these
updates slowly. Changes to the MaxUpdateQueue parameter take effect only after
the PI Server restarts.
If a PINet node or PItoPI interface is connected to the PI Server, the default
MaxUpdateQueue value is too small. It should be increased to at least the point
count of the PI Server. This value ensures that all point updates requested by PINet
can be queued on the PI Server if a system manager performs an edit operation on
every point.
How to Change the Maximum Number of Events in the Queue
It is possible to change this number by adding an entry named TotalUpdateQueue
parameter in the PITimeout Table sets the maximum events queued in the entire update-
manager database. The default is 100,000. You can use piconfig to change the limit.
2.7 System Date and Time
The PI server uses the Windows clock, including the time zone and Daylight Savings Time
(DST) settings to track time. If the system clock isn't right, the PI data isn't right either. You
might even lose data if the system clock is wrong.
As the PI System Manager, you must:
Check the system clock regularly
PI Server System Management Guide Page 31
Chapter 2 - Monitoring PI System Health
Adjust the clock toward the correct time
Adjust the clock only in small increments (for example, one second per minute)
Keep a record of all adjustments you make
Internally, PI stores all data in UTC time and translates back to local time when serving the
data to a client application. If you set all the Windows machines involved to the correct time,
time zone, and DST settings, PI can seamlessly handle clients in multiple time zones as well
as DST transitions.
Challenges a PI system administrator may face when configuring the clock on a PI server
include irreconcilable differences in the clocks of the PI server, the data systems from which
the data is being collected, and the clocks of the PI users on the corporate LAN or WAN.
Complications will most commonly arise when data is collected from legacy systems with
clocks that have been configured inaccurately or allowed to drift. The best thing to do in this
case is to set all clocks to the correct time. If this is not possible, you need to decide on a
workaround. may be available depending on the data collection interface process being used.
The most common workaround is for the interface process to read the current values from the
legacy system and send them to the PI with the current PI server time as the timestamp.
Page 32
Chapter 3. MANAGING ARCHIVES
3.1 Tasks for Managing Archives
PI Archive Management includes significant tasks for the PI System Manager, including:
Archive creation and deletion
Archive sizing
Archive shifting
Archive backups
Archive splitting/combining/compressing
Archive repair
3.2 About Archives
The PI System stores your data in Archives, which are just files for holding PI data. Archive
files can be either fixed or dynamic. Fixed archive files are always the same size, regardless
of how much data they contain. Dynamic archive files grow in size as they get data. (See
About Fixed and Dynamic Archives for a complete explanation.)
The archive receiving current data is called the Primary Archive. When the Primary Archive
becomes full, an Archive Shift occurs and the next available archive becomes the new
Primary Archive.
3.2.1 About Archive Shifts
PI actually performs the archive shift before the Primary Archive is completely full. This
leaves some extra space in the archive file so that you can add data later, if you need to. For
an archive file to be eligible to be the new Primary Archive, it must be writeable, and large
enough to handle the current size of the Point Database and it must also be registered.
Registering an archive file is how you make an archive file accessible by PI. When an archive
file is registered, it is made visible to the PI Server. The data in unregistered archives are not
accessible by the PI Server or its client applications. See Registering an Archive on page 56
for more information.
PI Server System Management Guide Page 33
Chapter 3 - Managing Archives
If no eligible archives are available for an Archive Shift, PI uses the oldest available filled
archive as the new Primary Archive, overwriting the data in the old archive. For example in
the preceding illustration, after the shift from piarch.003 to piarch.004, no empty registered
archives are left on the Server. If the System Manager does not create new archives on this PI
Server, then at archive shif piarch.001 becomes the next Primary Archive and the PI Server
overwrites the existing data in that archive.
It takes PI a few minutes to complete an Archive Shift. During that time, you are not allowed
to add, edit or delete points. PI stores incoming data in the Event Queue until the shift is
complete and then writes the queued events into the new Primary Archive.
3.2.2 About Archive Files
Each archive file contains events for a time period specified by the archive start time and end
time. The archive files on each PI Server should cover all time ranges, without overlapping
time ranges or gaps in time. Archives range in size from 2 megabytes to 2 terabytes (2,048
gigabytes) on Windows NT. On UNIX, the maximum size is 2 gigabytes
About Archive Gaps
Archive gaps are times for which no archive file exists. If an event is sent to the Archive and
no archive file with the appropriate time range exists, the event is discarded and an error is
logged. If data retrieval is attempted for a time range that is not covered by the set of
registered archives, an error or a no data status is returned.
About Archive Records
PI archive files stores events as data records. Data records are either primary records or
overflow records. Each point in the Point Database has one primary record allocated in every
archive file. Primary records are stored at the very beginning of the archive file. When the
primary record for a point fills up, the data for that event goes to an overflow record in the
Page 34
3.2 - About Archives
archive file. Overflow records start at the end of the archive file and are filled backwards.
Each record is one kilobyte.
A point can have as many overflow records as needed. Points that receive events at a slow
rate might never need to allocate an overflow record, whereas points that receive events at a
fast rate might need to allocate many overflow records. (PI uses index records to keep track
of multiple overflow data records for a point).
Note: When the Archive allocates a new overflow record for a point, it writes the new
record to disk immediately, along with any existing records that reference the new
record.
About Index Records
Index records are records that index a point’s data records by time. After one overflow record
is full for a point, PI creates an index record for the point, along with a new overflow record.
An index record can hold between 150-160 record points. When the record index is full, PI
creates a second record index and these are chained. Archive access for points with chains of
index records are marginally slower than for points with zero or one index record.
3.2.3 About Primary Archives
The Primary Archive is the archive file that covers the current time range. The Primary
Archive has a defined start time but no defined end time (it is always assumed to be “now.”)
The end time for the Primary Archive is defined when an archive shift occurs. An archive
shift is the process of replacing the primary archive with a new or cleared archive.
If it exists, an empty archive is selected to be the new Primary. If no empty archive exists,
then the oldest archive becomes the Primary and its existing data is overwritten.
Another option is automatic creation of archives. If this is in effect, a new archive file with
the same characteristics as the current Primary Archive is created during the shift.
PI ensures that some space is still available at the time of the shift. This way, out-of-order
events can still be stored in the archive after it is no longer the primary archive. For more
information, see the Archive Shift section in this Chapter.
3.2.4 About Fixed and Dynamic Archives
There are two types of Archive files, fixed and dynamic.
PI Server System Management Guide Page 35
Chapter 3 - Managing Archives
Fixed Archives
The default archives that are installed with a PI System are fixed archives. They have the
following characteristics:
Fixed archive files have all of their disk space allocated at creation time. An empty
archive and a full archive take the same amount of disk space.
Fixed archives may or may not participate in archive shifts, depending on the point
count to archive size ratio and the state of the shift and write flags.
New points may be added to a primary fixed archive.
Use fixed archives for all normal operations.
Filling up Fixed Archives
It is possible for a fixed (non-primary) archive to get completely filled up. Once an archive is
full, incoming data events for that time range have nowhere to go, and are discarded. This can
occur if a large quantity of old data is to be added to the Data Archive, and go to an old
archive which is already full.
In such cases it is best to stop the Archive Subsystem to prevent any further data loss. Then
create a new, larger, fixed archive with the same time range of the full archive and copy the
contents of the full archive to the new large archive using the Offline Archive Utility. When
the new large archive is registered in place of the full archive, incoming data events for that
time range is no longer discarded.
Dynamic Archives
Dynamic archives have the following characteristics:
Like fixed archives, dynamic archives are for a specific time range.
Dynamic archives that already contain data are not eligible for Archive Shift. Newly-
created dynamic archives participate in the standard shift algorithm, if they are
registered.
Dynamic archives do not contain unallocated space waiting to be used for overflow
records. Rather, the file grows as overflow records are added. Dynamic archives have
a maximum archive size (specified at archive creation). The default maximum
archive size is 1 Gbyte or 10% less than the maximum available disk space,
whichever is less.
Dynamic archives are initialized with a fixed number of primary point records. Once
a dynamic archive is created, the number of primary records cannot grow beyond the
initial allocation, even if there is space in the file.
Note: You can create dynamic archives with a number of primary records higher
than the current number of points. This allows users to create additional points in a
dynamic primary archive. Users can add new points as long as the number of points
does not exceed the number of primary records specified when you created the
dynamic archive. To create this type of dynamic archive, use the piarcreate -acd
command.
Page 36
3.3 - Tools for Managing Archives
Using Dynamic Archives
To understand the usage of dynamic archives, consider this example. A PI System Manager
wishes to combine the data in two old archives into a single archive file. The Offline Archive
Utility is run twice: once to copy data from the earlier archive and again to add data from the
second archive. Assuming that the Offline Archive Utility is allowed to create the archive file
on its first pass (or piarcreate was used to create a dynamic archive in advance), the resulting
archive contains data from the two input archives and has no free records. This potentially
makes the new archive smaller than the combined size of the input archives and able to
accommodate additional data as long as the maximum growth size is not exceeded.
3.2.5 About Read-Only Archives
Archive files that have a read-only file-system attribute, or files on a read-only device (CD
ROM) are mounted as read-only. Their status will show up on the piartool -al display as not
writable. Read-only files cannot participate in archive shifts.
New events in the time range of such an archive go into the archive cache, but when flushed
to disk, an error message is logged for each event. This includes attempts to edit, delete or
annotate events in a read-only archive.
3.3 Tools for Managing Archives
There are three main command line tools for managing archives:
piartool: The main archive management utility. You can use it to create, register and
unregister archives, force archive shifts, list details of archive files, and much more.
You can use piartool only when PI is running.
piarchss: The Archive Subsystem, piarchss, includes an Offline Archive Utility.
You use this utility to process existing “offline” archives. For example, you use
piarchss to combine multiple archives into one, to divide large archives into multiple
archives, to recover corrupted archives, and so on.
piarcreate: Use thie piarcreate utility to create new archives.
3.3.1 Using the piartool Utility
The following table lists the command line options for the piartool utility. You can only use
piartool when PI is running.
Table 3–1. Options for Use with piartool
Option Name Action
-aag Archive Activity Enable/Disable the archive activity grid, and list the
Grid Archive access information.
-ac Archive create Create an archive for specified period
-acd Dynamic archive Create a dynamic archive for specified period.
create
PI Server System Management Guide Page 37
Chapter 3 - Managing Archives
Option Name Action
-ads Archive disable Removed specified archive from shift participation.
shift
-aes Archive enable Add specified archive to shift participation.
shift
-al Archive list List all registered archives
-ar <path> Archive register Register a specified archive
-as Archive statistics Archive Subsystem activity monitor and statistics
-au <path> Archive unregister Unregister a specified archive
-aw Archive walk List details of the records in an archive file
-Backup ['path'] [- Perform a System Start/End/Query a backup of the PI system. The
component <comp>] Backup path points to where the resulting backup files are
[-numarch <number>] placed. The optional component specifies which
part of the PI system is backed up. The numarch
[More Options listed option specifies how many archives (starting from
under Action] the current archive and working backupwards) are
backed up. By default all archives are backed up.
Additional options include:
-query [-verbose] Inquire about the current
backup status.
-abort Abort a running backup.
-identify [-numarch <number>] [-cutoff <date>] [-
verbose] Identify files able to be backed up. In
verbose mode the individual components are
listed. The numarch and cutoff options override
default until next backup.
-test <freeze,component|thaw> Test but don’t
actually perform a PI system backup.
-block Block Wait for a specified subsystem to become
responsive. Used in PI start scripts.
-cad 'tagname' [-reset] Archive cache Archive cache diagnostics for a specified point.
diagnostics Display the events sitting in the read and write
cache.
-cas ['tagmask'] Archive cache Display a summary of the contents of the archive
summary cache, including the number of events in the Read
and Write caches for every point that matches the
tagmask.
-cs PINetmgr PI Network Manager connection stress test.
[For troubleshooting connection stress
only] test
-de <path> Dump eventqueue Dump specified Event Queue file.
[-pt tagname] [recno] Optionally select a specific tag and/or specific
record in the file.
Page 38
3.3 - Tools for Managing Archives
Option Name Action
-disconnect - Force Subsystem Force the specified subsystem to disconnect from
subsystem <name> [- Disconnect pinetmgr, or if pinetmgr is specified, instruct
id <id>] pinetmgr to disconnect the connection based on
[For troubleshooting the connection ID passed.
only] The -graceful option causes a disconnection notice
to be first sent by pinetmgr or the target
subsystem.
-fs Force shift Force an archive shift.
-idci <in file> ID conversion file Create ID conversion file from specified input file.
-idco <outfile> creation
-lic [Options listed Licensing Usage List options for viewing license info
under Action] Information Def List all licenses
User List all licenses in use
Lic List all licenses and users
AllowedApps <-List <type,type...>|-Check
<app,app,...>>
List the types of licenses or check whether a
specific feature is licensed
-mpt <0|1> Message protocol Log all communication coming to and from the
[For troubleshooting trace server.
only] To enable tracing run with -mpt 1. Call a second
time with -mpt 0 to stop tracing.
The resulting output file appears in the “\pi\temp
directory” with the .mpt extension.
The file can be read with the mptconsolveview
utility, which OSISoft provides on request, e.g.:
Mptconsolveview .\24-Aug-05_12-10-06.mpt
-msg "message" Message Sends a series of test messages to the PI
[-pro "procname"] Subsystem Test message log. Can emulate sending messages
from any process. Nrep sets how many messages
[-nrep m] are sent, nbuf sets how many messages are sent
[-nbuf l] at a time, nmps attempts to throttle how many
[-nmps n] messages are sent per second.
[For troubleshooting
only]
-msgtest <startsize in PINetmgr Send a series of test messages to the PInetmgr.
bytes> <endsize in Communications Message size increases by one byte increments
bytes> Test starting from startsize to endsize.
[For troubleshooting
only]
PI Server System Management Guide Page 39
Chapter 3 - Managing Archives
Option Name Action
-netstress PINetmgr stress Test PINetmgr subsystem by sending and
[-SendBlocks 1] [- test. receiving specified 4k blocks.
RecvBlocks 1] [-loops
1]
[For troubleshooting
only]
-ooo <-r><Sec> Out of order snap Show tags with Out of Order events. Optional
events Reset and Repeat.
-qs Queue statistics Monitor Event-Queue activity and statistics
-re [-subsystem Raise Exception Raise exception in specified subsystem (force a
<name> crash). This call only works locally; remote is not
|-pid <#> ] supported.
[For troubleshooting
only]
-remote Remote system Run utility against a remote system. When this
argument is included as the last argument in any
valid command the utility prompts for remote
system login information. If successful the utility
runs against the remote system.
-rpctest <subsystem> Inter-process Times the RPC round trip to the specified sub-
<count> Communication system.
[For troubleshooting Test
only]
-ss Snapshot statistics Snapshot Subsystem activity monitor and statistics
-standalone <n> Standalone mode Place PI Server in standalone mode. Possible
values for n are:
1 Enter standalone
0 Exit standalone
2 Query current state
-systembackup System Backup Start/End backup for a specified subsystem.
Deprecated in favor of -backup.
-thread 'subsystem' Subsystem Thread -info List a subsystem's threads
[Options listed under Control -id <Thread ID>
Action]
<-disable|-enable|-suspend|-resume|-terminate|-
hang|-add|-break|-priority <Direction>>
Perform an action on a particular thread
-v Version Get version and build information
3.3.2 Using the Offline Archive Utility (piarchss)
The Offline Archive Utility is actually the same Archive Subsystem executable, piarchss that
is a part of a running PI system. To use the archive utility functions of piarchss, you run it in
Page 40
3.3 - Tools for Managing Archives
console mode using special command line arguments. The offline archive utility can be used
even while PI is running.
You typically use the piarchss utility to work with archive files outside the context of a
running PI Server. This enables you to continue archiving current data on your PI Server,
while manipulating other archives “offline.” Typical applications of the offline tool include:
Combining a number of archives together
Dividing a big archive file into smaller archives
Extracting specific time period from an archive
Recovering a corrupted archive
Recovering events from an Event Queue file
Converting PI2 archive file to the PI3.x format.
Note: The archives that are created by the Offline Archive Utility may be either fixed
or dynamic. Their format is not different from any other archives created by piartool
-ac.
Running the Offline Archive Utility
When you run piarchss as the offline archive utility, you give it an input archive file and an
output archive file, along with relevant command parameters. The basic format is:
piarchss -if inputPath -of outputPath
where inputPath is the full path and filename of the input archive file and outputPath is the
full path and filename of output archive file.
The piarchss utility takes the input file, processes it according to the command parameters,
and then outputs the processed file to whatever location you specified. The piarchss utility
does not modify the input file under any circumstances.
The piarchss Utility Command-Line Parameters
This section provides a list of all the command line parameters for the piarchss offline
archive utility. Some of these options are discussed in more detail in the following
subsections. The parameters may be specified in any order.
Parameter Name Notes
-if <full path name> Input Archive Required. The full path, including drive letter is
File required. This is true for all file arguments passed.
-of <full path name> Output Archive Required.
File
-ost <option> Output file Options: Input, Event, <time>, NFE See “Specifying a
Start Time Start Time for the Output File (-ost).”
-oet <option> Output file End Options: Input, Event, <time>, NFE, Primary,
Time NoChange
PI Server System Management Guide Page 41
Chapter 3 - Managing Archives
Parameter Name Notes
See “Specifying an End Time for the Output File (-oet).”
-f <size in Mbytes> Make output If size = 0, the input file size is used. Default is dynamic
archive a fixed archive.
archive
-tzf <full path name> TimeZone Use when PI2 input different from standard DST - see
specification also the PI Server Reference Guide, Appendix D.
file
-filter <start end> Filter Process events only within the time range specified.
Both timestamps must be provided. See “Time Filtering
(-filter).”
-dup Duplicate Allow input archive records with duplicate times. By
Records default duplicates are ignored.
-tfix Time Fix Apply a specified time transformation to input data. See
“Transforming Event Timestamps (-tfix).”
-silent Silent Mode Suppresses warning messages.
-vah Validate Apply a validation algorithm. Multiple events
Annotation referencing a single annotation are detected and fixed.
Handles Batch Database annotations are checked for
consistency.
Specifying a Start Time for the Output File (-ost)
The -ost flag specifies the start time for the output file. The usage is as follows:
-ost option
Where option is one of the following:
input Sets the start time to the start time of input. This is the default behavior.
event Sets the start time to time of first event in input.
time Sets the start time to the specified time string. Times are specified in absolute PI
(where time is time format. Relative times are not supported. Times must be enclosed in double
specified in quotes when containing spaces. If only date is specified the time defaults to
absolute PI 00:00:00 (midnight)
time format) For example:
“22-JAN-02 23:59:59”
23-JAN-02
21-Feb
Output file start and end times must differ by at least one second.
NFE Sets the start time to time of first event which passes the time filter.
Page 42
3.3 - Tools for Managing Archives
Specifying an End Time for the Output File (-oet)
The -oet flag specifies the end time for the output file. The usage is as follows:
-oet option
Where option is one of the following:
input Sets the end time to the end time of input file.This is the default behavior.
event Sets the end time to the time of last event in input file.
time Sets the end time to the specified time string. Times are specified in absolute PI
(where time is time format. Relative times are not supported. Times must be enclosed in double
specified in quotes when containing spaces. If only date is specified the time defaults to
absolute PI time 00:00:00 (midnight).
format) For example:
“22-JAN-02 23:59:59”
23-JAN-02
21-Feb
Output file start and end times must differ by at least one second.
NFE Sets the end time to time of last event which passes the time filter.
primary Sets the end time to indicate the archive is a primary archive.
NoChange End time is not altered.
Time Filtering (-filter)
The -filter flag specifies a time range (inclusive) beyond which events are discarded. The
usage is as follows:
-filter starttime endtime
Start time must be before end time.
Specifying an ID Conversion File (-id)
Use the -id option to specify an ID conversion file (used to move a PI archive to a different PI
Server). The ID conversion file is a binary file that maps the source archive point ID into the
target system point ID. When ID conversion file is used, only points included in this file are
converted.
This is always necessary when archives are migrated from a PI2 system, or when data is
brought from another PI3 system.
The binary file is created from an input text using the piartool utility.
piartool -idci <id conversion input file>
-idco <id conversion binary file>
The ID conversion input file is the full path and file name to the input text file.
The ID conversion binary file is the full path and name to the binary file to be created.
piartool reports any point in the input file that does not exist in the target system.
PI Server System Management Guide Page 43
Chapter 3 - Managing Archives
ID Conversion Input File Format
Every record of the input file must have this format:
Point ID, Recno, TagName
On a foreign PI3 system you can create this file as follows:
e:\pi\adm>piconfig
* (Ls - ) Piconfig> @table pipoint
* (Ls - PIPOINT) Piconfig> @ostru pointid, recno, tag
* (Ls - PIPOINT) Piconfig> @output pointidconv.txt
@ends
Note: The piartool -idci input file does not allow for comment characters. The
comment character ( * ) generated by piconfig must be removed.
Transforming Event Timestamps (-tfix)
Offsets, as a function of time, are defined in the time conversion file. This can be used to
apply corrections to times on some systems that had incorrect timestamps due to run-time
library problems, or non standard DST setting.
This adds a given time offset to every event:
-tfix <conversion file>
Time Conversion File Format
Lines starting with # are comments.
Empty lines and white spaces are ignored.
Data lines have the format:
Starttime, offset
Start-time may be expressed as UTC - seconds since 1/1/70 or as PI local timestamp string:
dd-mmm-yyy hh:mm:ss
*
*-1s
UTC timestamps and strings cannot be intermingled, the first format is assumed for all
entries.
Offset is a number of seconds added to the timestamp of every event within the time range.
Fractional seconds are not supported. Offset applies from timestamp up to, but not including
the next timestamp.
Time Conversion File Examples
Move entire archive ahead by 1 hour:
0,3600
2000000000,3600
Move entire archive ahead by 1 hour (another format):
Page 44
3.3 - Tools for Managing Archives
01-Jan-70 00:00:00,3600
01-Jan-10 00:00:00,3600
Applies a missed DST conversion to an archive that covers the summer of 1997:
01-Jan-02 00:00:00,0
06-Apr-02 02:00:00,3600
26-Oct-02 02:00:00,0
31-Dec-02 23:59:59,0
A series of UTC values and offsets:
814953600,-61200
828871200,-57600
846403200,-61200
860320800,-57600
Tips for Using the Offline Archive Utilty
If you’re working with the piarchss offline archive utility, note the following:
The full path name of the input archive must be specified. (Note that piartool -al lists
only registered archives.)
If the input file is registered, the Offline Archive Utility un-registers it when
processing begins.
If the input archive is the Primary Archive, it cannot be unregistered. To work around
this, force an archive shift using piartool -fs or temporarily shut down the Archive
Subsystem.
If the output file does not exist, the utility creates it.
If a full path name is not specified for the output archive, the utility places the output
archive in the current directory.
At the end of processing, neither the input nor the output archives are registered.
By default, the piarchss offline archive utility creates dynamic archives. Use the -f
argument to specify a fixed archive. Note that dynamic archives become non-
shiftable once a single overflow record is generated, but remain shiftable if no
overflow records are generated.
You can run the piarchss offline archive utility while the PI System, including
piarchss itself, is running. At a minimum, the pinetmgr, pibasess, and pisnapss
subsystems must be running, because the utility needs to access the Point Database
during offline operations.
How the Offline Utility Works
During processing, two passes are made through the input archive file. On the first pass, the
utility checks all records in the input archive file. Every record containing valid data, and
within the specified time range, is added to a sorted list. The list is indexed by time and point
ID. This assures loading in chronological order. The point ID of the input record is verified.
Any required point ID conversion is performed using the specified conversion table. For
example, conversion is required when migrating archives from a PI2 or from another PI3
PI Server System Management Guide Page 45
Chapter 3 - Managing Archives
System to your PI Server. An error message is issued for every record for which a point could
not be found in the local PI Server. These messages can be suppressed if desired.
Statistics are displayed after every 200 records are processed, at the end of the first pass, and
at the end of the second pass.
During the second pass, records from the sorted list are written to the output file. The input
data is optionally filtered or modified. If the output archive file does not exist, it is created.
The archive header is initialized based on command line specifications. If the output file
already exists, the input data is added. If a primary record does not exist for a given point ID,
the data for that point ID is discarded.
The input data is converted to the output point type, if different from the input point type. All
auxiliary data, such as index records and record chaining, are recreated during the load. Only
actual data are read from the input, and thus, any errors in the input file auxiliary data are
repaired.
Piarchss Offline Archive Utility Exit Codes
To facilitate batch file processing, the offline utility returns an exit code to the operating
system:
Code What it Means
0 No errors – at least one input record processed
1 Errors during input phase
2 No processing errors – 0 records processed possibly an empty input file
<0 An error returned from the output processing check log messages
3.4 Listing the Registered Archives
Archives must be registered before the PI Server can use them. If an archive is not registered,
its data are not accessible. The piartool -al command lists the registered archives.
Archives are listed in reverse chronological order—archives with the newer data before
archives with older data. The first archive listed is the Primary Archive, which covers the
current time range. The dates that are spanned by each archive are also shown. There cannot
be an overlap in dates between archives. Attempting to register an archive that overlaps an
already registered archive will fail. Unused archives have start and end times shown as
Current Time. The display order of unused archives is arbitrary and may change.
Here is a sample archive listing:
D:\PI\adm>piartool -al
Archive shift prediction:
Shift Time: 5-Oct-05 19:42:01
Target Archive: e:\pi\arc\piarch-2GB.1
Archive[0]: e:\pi\arc\piarch-2GB.3 (Used: 53.4%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Page 46
3.4 - Listing the Registered Archives
Version: 7 Path: e:\pi\arc\piarch-2GB.3
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 2097152 Add Rate/Hour: 154207.3
Offsets: Primary: 253063/1048576 Overflow: 1231270/2097152
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 5-Oct-05 06:11:09
End Time: Current Time
Backup Time: Never
Last Modified: 5-Oct-05 13:26:21
The piartool -al, command displays the following information for every currently mounted
archive:
Label Description
Shift Prediction Provides estimated time for the next shift and the target archive. This is
important for backup planning.
Used Percentage of archive records used. This is an estimate, as only empty
records are considered in the calculation.
Version Identifier of the archive's internal architecture. This label allows PI Server
to mount and upgrade archives from older versions of PI.
Path Full path of the archive file.
State Current condition of the archive. In piartool -al, this will always be
displayed as 4, which means mounted and ready. All other states
correspond to unmounted states, in which case the archive is not visible in
piartool -al.
Type 0 = Fixed, 1 = Dynamic.
Write Flag 1 = Archive is currently writeable, 0 otherwise.
Shift Flag 1 = Archive is potentially a target for archive shift, 0 otherwise.
Record Size Size in bytes of one record. This is always 1024.
Count Number of records in the archive file.
Add Rate Average number of overflow-records added per hour, over the archive
lifetime.
Offsets: Primary Start and end record numbers for primary records. The end record number
is always 1/2 of the Record Count.
Offsets: Overflow Start and end record numbers for overflow records.
Annotations Number of annotations used and the maximum number available. The
archive shifts when this number is reached.
3.4.1 Determining an Archive Sequence Number from a Listing
Some piartool commands require an archive sequence number; for example, archive backup
(piartool -backup) and archive walk (piartool -aw). The archive sequence number is
PI Server System Management Guide Page 47
Chapter 3 - Managing Archives
chronologically assigned with zero being the primary archive. The archive sequence number
is shown in with the archive list command (piartool -al); it is the number in the brackets
immediately following “Archive.”
Here is a sample archive listing:
C:\pi\adm>piartool -al
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
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
Page 48
3.5 - Listing Archive Record Details
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
C:\pi\adm>
Archive sequence numbers are arbitrarily assigned to unused archives. Unused archives can
be recognized by both start and end time set to “Current Time.” When unused archives are
unregistered or specified for a backup, the assigned number will likely change on subsequent
reregister or backup end. Generally, there is no reason to back-up unused archives.
3.5 Listing Archive Record Details
Use piartool -aw to read the contents of an Archive directly from file. The key to reading
archive data this way is to understand that every PI point has a unique Record Number
(RecNo) which corresponds to a primary record in the Archive. This can be found through
piconfig or PI-SMT tools. When a new archive is created, data for each point flows into its
own separate primary record (archives are divided into fixed size records, the number of
which is either static or can grow dynamically.) When this primary record fills up, then an
overflow record is set aside for the data to flow into. The primary record points to the first
overflow record which can point to a second and so forth. It is following this chain of records
that is referred to as an Archive Walk. Finally when the number of free unused overflow
records in an archive gets down below a certain number, this is when an automated archive
shift will occur.
3.5.1 Performing an Archive Walk with piartool -aw
This command gives a detailed listing of archive records. After issuing this command, you
are prompted for the target archive number and the target record. The record is displayed.
You are then prompted to select another archive record to view.
You can determine the archive number by issuing piartool -al. Archives are listed in order,
starting with 0 for most current data.
Example Displaying Archive Records with Record Headers Only
The example below demonstrates how to use piartool to display archive record headers.
C:\pi\adm>piartool -aw
Enter Archive Number: 0
Enter Record Number: 40
PI Server System Management Guide Page 49
Chapter 3 - Managing Archives
Point ID: 18 Record Number: 40
Chain Record Mumber - Next: 80531 Prev: 0 Index: 0
Record Version: 3 Data type: 11 Zero: 600 Span: 500
Flags - Index:0 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 214
Storage (bytes) - Available: 990 Used: 987
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Understanding Event Data Displayed by piartool -aw
By default, the piartool -aw command displays only the record header. If you wish to view
the data in the record, enter the letter "e" when prompted for the next record ID. This toggles
on the display of event data. To toggle off the display, enter "h" at the Enter Record #, <CR>
next rec (p)rev (e)vents (a)rchive # (q)uit: prompt.
Event data will be displayed as shown in this example. Every archive record must contain at
least one event.
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit: e
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 68 $]::
Point ID: 4 Record Number: 59421
Chain Record Mumber - Next: 0 Prev: 71411 Index: 4
Record Version: 3 Data type: 101 Digital State Set: 3
Flags - Index:0 Step:1 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 121
Storage (bytes) - Available: 994 Used: 288
121 Event(s):
0: 9-Sep-05 18:57:04, S,O,A,S,Q [3,1,0,0,0]:
1: 9-Sep-05 18:58:14, S,O,A,S,Q [3,2,0,0,0]:
2: 9-Sep-05 18:59:24, S,O,A,S,Q [3,3,0,0,0]:
3: 9-Sep-05 19:00:34, S,O,A,S,Q [3,2,0,0,0]:
4: 9-Sep-05 19:01:44, S,O,A,S,Q [3,1,0,0,0]:
5: 9-Sep-05 19:05:14, S,O,A,S,Q [3,2,0,0,0]:
6: 9-Sep-05 19:06:24, S,O,A,S,Q [3,3,0,0,0]:
etc.
The S,O,A,S,Q array indicates values as shown in the table below.
Event Type Meaning
Coding
S StateSet
O Offset in StateSet; 248 corresponds to "No Data"
A Annotated (0=no, 1=yes)
S Substitute (0=no, 1=yes)
Q Questionable (0=no, 1=yes)
Page 50
3.6 - Estimating Archive Utilization
Index shows whether the values in the records are data values or pointers to data records,
where 0 indicates that it is NOT an index record. If they are pointers, the pointers are actually
record numbers corresponding to the start time. When events for a point exceed two records
in a single archive, an index record is created. An index record holds about 150 pointers to
data records.
RecNo (Record Number) is a read-only point attribute which contains a pointer to the point's
primary record in the archive. This is useful when using tools such as piartool -aw to
examine the archives. Do not confuse RecNo with the PointID attribute. If the point is
deleted, the RecNo will be reused but the PointID will not.
Data Type Meaning
8 Int32 (all records which have the index flag set will also show datatype 8)
12 Float32
101 digital
102 Blob
Broken Pointers
In rare cases of hardware failure, record chains can become inconsistent. The archive check
utility
pidiag -archk 'path'
can be used to examine archive integrity. For more details on this pidiag command, refer to
Verify the Integrity of Archive Files on page 272.
The archive offline utility will repair any chaining problem.
3.6 Estimating Archive Utilization
The space that a fixed archive uses is completely allocated at archive creation time. Use
piartool -al to list the registered archives. For each archive an estimate of the used space is
displayed.
3.7 Editing Archives
The piconfig utility, the PI API and the PI-SDK may be used to add, edit, or delete archive
values.
Note: Contrary to the above title “Editing an Archive”, all archive edits are first
handled by the Snapshot Subsystem. The Snapshot Subsystem performs some
security and data checks then, if appropriate, forwards the edit events to the Archive
Subsystem.
PI Server System Management Guide Page 51
Chapter 3 - Managing Archives
For large scale changes and repair use the Offline Archive Utility (piarchss). For example,
inadvertently moving the computer system clock ahead may cause considerable problems.
You can configure a time limit on insertion and editing of events. The Snapshot rejects events
with timestamps earlier than the limit. By default there is no limit, which is consistent with
earlier versions of PI.
To configure, add an entry to PITimeout Table:
EditDays, nnn
where nnn is the number of days (prior to current time) in which changes and additions are
allowed. The Snapshot Subsystem loads PI Timeout table parameters on startup, therefore,
this subsystem must be restarted for the changes to take effect.
3.8 Creating Archives
To create a new archive, use piarcreate, piartool -ac, or piartool -acd. These utilities allow
you to name the new archive, specify its location, create it, and initialize it. In general, use
piarcreate for all archive creation, unless you need to specify start and end times. piartool -
ac creates a fixed size archive, piartool -acd creates a dynamic archive.
With piarcreate, you may specify the size of the archive, but you will need to do a second
step to register it. This utility creates a dynamic archive if you use the -d flag.
With piartool -ac, the created archive size matches the current Primary Archive size, and
registration is automatic. The piartool utility allows you to optionally specify the start and
end times of the new archive. Option -ac specifies a fixed size archive, -acd specifies a
dynamic archive.
Every archive has a parallel annotation file that has the extension .ann. The file is created
automatically by either utility. It must remain in the same directory as its archive file at all
times.
3.8.1 Naming Archives
There are no limitations on the archive file name, other than being a valid file name for the
underlying operating system. The default archive file names are piarch.xxx, where xxx is 001,
002, 003 and so on. The location must have sufficient disk space.
The associated annotation file has the same full path name as its archive file with .ann
appended. For example, the annotation file for the piarch.001 archive file would be
piarch.001.ann.
3.8.2 Choosing an Archive Size
Archives have a maximum and minimum size:
Minimum Archive Size: Determined by point count. The minimum archive size, in
megabytes, is twice the number of points divided by 1000.
For example, to allow for 20,000 configured points, the minimum archive size is:
(20,000 x 2) / 1000 = 40 MB
Page 52
3.8 - Creating Archives
Maximum archive size is 2 Terabytes (2000 Gigabytes).
The archive size affects backups, frequency of shifting, and total number of points allowed
The general rule is to size your archives such that they last three to five weeks before shifting.
How Archive Size Affects Shifting Frequency
If the PI Server has larger archive files, the shift will occur less frequently. To decide what
archive size is optimal for your system, consider the backup device, available disk space and
average incoming data rate. These will determine the shift frequency.
How Archive Size Limits Point Count
It is important to note that the archive size limits the number of points that may be created.
No more than 1/2 of the archive records of a fixed archive can be primary records. If the
allotment of primary records gets used up, you will get an error if you try to create an
additional point, even though the primary archive is not full. To resolve this, force the
archives to shift into a larger archive in order to create additional points. Archive shifting can
be forced using the command piartool -fs.
3.8.3 Selecting an Archive Type: Fixed or Dynamic
By default, a fixed archive is created. If you specify the -d parameter, a dynamic archive will
be created instead. Dynamic archives grow as they get filled, up to the specified maxsize, but
not above two Terabytes. The difference between fixed and dynamic archives is discussed in
the section on About Fixed and Dynamic Archives.
3.8.4 Specifying the Number of Points in the Archive
This number, specified by the maxpoints parameter, should be taken from the piartool -al
listing for the Primary Archive. The primary archive is always listed first. Point count is equal
to the number of used primary records; in the example below it would be 253,063. One half
of all records are reserved for primary records. This also determines the maximum number of
points that can be created. The listing below is for a 2048 Mb archive; the maximum number
of configurable points for the archive is 1,048,576.
D:\PI\adm>piartool -al
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
PI Server System Management Guide Page 53
Chapter 3 - Managing Archives
3.8.5 Specifying the Maximum Archive Size
The parameter maxsize is usually specified to be equal to the size of the Primary Archive, in
megabytes, but it doesn’t have to be the same. A dynamic archive will not grow larger than
maxsize.
3.9 Creating Data Archives Prior to the Installation Date
Some sites may find it useful to make data available in PI that was collected prior to the PI
installation.
Several applications can be used for backfilling, including a PI API or PI-SDK application,
piconfig, or the batch file interface. This depends mainly on the way the data to be entered
into PI is currently stored.
Backfilling Data with Compression
The installation procedure is the following:
1. Install PI, start PI, create all points, Stop PI.
2. Isolate the PI Server from all incoming process data. This means shutting down PI
interfaces on all PI API and PINet nodes. Another way to do this is to disallow all PI
API connections at the server. To due this, start piconfig without starting PI (ignoring
messages about failure to connect) and issue the following commands:
@table pi_gen,pifirewall
@mode edit,t
@istr hostmask,value
"*.*.*.*",DISALLOW
Note: Entries that allow access to specific names or addresses override the
above “disallow”. Edit all other entries to “Disallow”. Local connections are not
affected by pifirewall entries; make applications that may write data are not
running.
3. Start PI with the -base parameter. This ensures that PI starts up with only the
minimum required subsystems.
On Windows hosts, issue the command:
pisrvstart.bat -base
4. Create and register archive files for the backfilling period (using piartool -ac or -
acd).
5. Insert one event for every point at the earliest time on-line.
6. Delete all the PointCreated events from the snapshot. This will bring into the
snapshot the old events. Steps 5,6 can be done with a PI API or PI-SDK program or
using the piconfig utility. Make sure that the old event is in the snapshot.
Page 54
3.10 - Creating a New Primary Archive
7. Backfill the archives by reading in the data In Time Sequential Order. This way the
data is compressed.
Caution: The Archive Subsystem assumes the archive end time is the most
recent time stamp written to any point. It is important to keep all current data
sources from writing to the PI Server. This is why Random, Ramp Soak,
Performance Equations, PI Total, PI Alarm, or any other interfaces cannot be
running.
8. If you used the technique of modifying the PIFIREWALL table in Step 4 above, run
piconfig to either change the hostmask value to Allow or to delete the above
hostmask altogether.
9. Start the interfaces using pisitestart.sh or pisrvsitestart.bat.
Backfilling Data without Compression
1. Install PI Server and create all points. The points that you want to backfill must be
created prior to the archive initialization, otherwise the archive has no primary
records for these points.
Note: An archive can be created with a start time prior to point creation time, as long
as the point exists when that archive is created. Reprocessing an old archive with
the offline utility adds to that archive all existing points, while preserving all the old
data.
2. Use piartool -ac to create and initialize back fill archives. The start and end times
must be specified (that is why piarcreate cannot be used). The start time should be
the timestamp of the oldest data to be backfilled; the end time should be just prior to
the oldest archive time specified using piartool -al.
3. Backfill the data. The data that you backfill will not be compressed, since it is prior
to the snapshot time.
4. If the backfill archive is filled before all of the backfill data is entered, you must
delete the backfill archive, and create two backfill archives, dividing the target time
range between the two, or creating a single larger archive, and then retry the data
backfilling.
3.10 Creating a New Primary Archive
In some situations it is useful to create and register a primary archive with specific start-time,
for example, when recovering from setting the time into the future, or when backfilling
archives, or after using pidiag -ar to recover from any situation of corrupted archives. To
create a new primary archive, use piartool -ac and specify the start time as required and the
end time as *. Note the following restrictions:
Registering a new primary archive will fail whenever there is a current valid primary
archive registered.
PI Server System Management Guide Page 55
Chapter 3 - Managing Archives
A valid primary archive must have a specified start time and null end-time, which
signifies current time.
3.10.1 Registering an Archive
The PI Server Archive Registry contains the name, location, size, count of records, and record
size for each archive file. This information is stored in the binary file, PI\dat\piarstat.dat.
piartool -ar <path>
This command allows new or old archives to be added to the list of registered archives. Once
an archive is registered it is available to the system, participating in shifts and storage and
retrieval of event data. The specified path must be a complete (not relative) path of an
existing archive file.
3.10.2 Unregistering an Archive
piartool -au <path>
Use this command to drop an archive from the list of registered archives. Any archive may be
unregistered except the Primary Archive (archive number 0), which stores the current data.
3.10.3 Deleting an Archive
To delete an archive, first unregister it using the piartool -au command, discussed below.
Delete the archive using the normal file deletion commands available on your operating
system. Then delete the related annotation file.
3.10.4 Moving an Archive
To move an archive you must unregister it, move it to a new directory, and then re-register it.
Remember to move the associated annotation file as well. Moving the primary archive
requires some additional steps, since you cannot unregister it while the PI archive process is
running.
To move the primary archive, do the following:
1. If any empty archives exist in the original directory, move them to the new directory
and register them there. One of these archives will become the new primary archive.
2. Verify that there is at least one empty archive registered in the new directory (create
one if there is not one).
3. Force an archive shift using piartool -fs. This will result in a new primary archive,
which is one of the empty archives in the new directory.
4. Move the previous primary archive to the new directory by the usual method:
unregister it, copy it to the new directory, and then re-register it.
Note: Renaming archive files is generally not necessary. If you must do this,
remember to rename the annotation file as well. Check the release notes for a
description of issues associated with archive file renaming.
Page 56
3.11 - Managing Archive Shifts
3.11 Managing Archive Shifts
When the primary archive file becomes full, the next empty (shiftable, writeable) archive is
used to store the new data. If none of the archives are empty, the archive file with the oldest
data (which is also shiftable and writeable) is cleared and used for new data. The start time of
this archive is set to the end time of the archive file that just became full.
The process of clearing the oldest archive and preparing it to be the new primary archive is
called an archive shift. It is important that all eligible archives are backed up prior to the
archive shift to ensure that no data is lost.
When an archive is assigned a start time, it is initialized. Archives are only initialized at
installation and during an archive shift.
The archive shift process takes a few minutes to initialize a new archive file. Adding, editing,
or deleting points is not allowed during archive shift. Events sent to the Archive during an
archive shift are queued. When the shift is complete, the queued events are written to the
Archive.
Which Archives are Shiftable
For an archive file to be eligible to be the new primary archive, it must be registered,
shiftable, writeable, and large enough to handle the current size of the Point Database. If an
archive does not meet these criteria, it will be skipped over during an archive shift. By
making an archive non-shiftable or read only, an archive may be excluded from the shift
cycle.
Predicting Time of Next Archive Shift
The command piartool -as is used to monitor archive activity, performance and to estimate
the next archive shift
The utility piartool -as predicts the time for the next archive shift. The prediction is based on
the average number of archive records consumed per hour, plus the rate of consumption. If
the primary archive is less than 20% full, the prediction is based on the previous archive
rates.
Archive Shift Enable Flag
Fixed archives of varying sizes can be shifted. However, archives that are too small to
accommodate the number of points in the Point Database are automatically excluded from
archive shifts. Used dynamic archives are never shiftable.
Both fixed and dynamic archives have a shift-enable flag. If the flag is 0 then the archive will
not participate in archive shifts. A user can view or set this flag using the piartool utility.
Failed Archive Shifts
If an archive shift fails for any reason, all further shifts are disabled and a message is sent to
the log. When the cause of the failure is resolved, restart the Archive Subsystem to enable
archive shifts. If the cause of failure was a lack of available archive to shift into, then
PI Server System Management Guide Page 57
Chapter 3 - Managing Archives
registering a new empty archive automatically resolves the situation and a shift into the new
archive will occur.
Failed shifts do not cause any data loss since the archive goes into read-only mode. All
incoming data is queued in the Event Queue by the Snapshot Subsystem.
3.11.1 Archive Shift Enable Flag
Each archive has a Shift Enable Flag. If the Shift Enable Flag is set to 1 then the archive is
eligible to participate in archive shifts. The status of the flag may be viewed using piartool -
al.
Archives can be excluded from shift participation by running piartool -ads 'path'. Shift
disabled archives can be re-enabled by running piartool -aes 'path'.
Dynamic archives that contain data do not participate in archive shifts. That is, newly created
dynamic archives may be shifted into, but they are shift disabled after the first archive event
is written to it. piartool -aes does not re-enable dynamic archives for shifting.
Archive shifts happen automatically whenever the Primary Archive nears full. An archive
shift normally begins when the Archive Subsystem detects that the primary archive is almost
full. It dismounts the last empty archive, or oldest shiftable archive if no empty archives are
available. It then initializes this archive. This can take some time, depending on the current
point count. Messages are written to the log during the initialization to indicate progress.
Once the new archive cleared, it is initialized to start at the current time and is mounted as the
primary archive.
Note: The oldest shiftable archive is the oldest writable archive large enough for the
current point count. Also, dynamic archives containing data are not shiftable.
3.11.2 Forcing Archive Shifts
The command piartool -fs forces an immediate archive shift. During normal operations, the
piartool -fs command should not be used. However, it may be useful to force an archive to
shift while testing your system or to do advance archive management.
For example, this command is sometimes useful if you are building a large number of new
points. Since primary records may occupy no more than one half of the records in an archive
file, it may be necessary to build a larger primary archive. You can then force an archive shift
to make the larger archive your primary archive.
For systems with large point counts, archive shifts may require a long time. As soon as the
shift starts, messages are written to the PI message log, such as:
0 piarcmgr 2-Apr-03 14:32:39
>> Forced archive shift requested.
0 piarcmgr 2-Apr-03 14:32:39
>> Beginning Archive Shift. Current Primary Archive:
d:\pi\dat\piarch.001
0 piarcmgr 2-Apr-03 14:32:39
>> Target Archive for Shift: d:\pi\dat\piarch.003
0 piarsrv 2-Apr-03 14:32:39
Page 58
3.12 - Combining and Dividing Archives
>> Clear and Initialize archive file: d:\pi\dat\piarch.003
0 piarsrv 2-Apr-03 14:32:48
>> Archive clear progress: 51200 records cleared.
0 piarsrv 2-Apr-03 14:32:58
>> Archive clear progress: 102400 records cleared.
0 piarsrv 2-Apr-03 14:33:08
>> Archive clear progress: 153600 records cleared.
0 piarsrv 2-Apr-03 14:33:19
>> Archive clear progress: 204800 records cleared.
0 piarsrv 2-Apr-03 14:33:28
>> Archive successfully cleared 256000 records
0 piarsrv 2-Apr-03 14:33:28
>> Archive successfully initialized 16285 points.
0 piarsrv 2-Apr-03 14:33:28
>> Archive file Clear and Initialize completion status[0] Success
0 piarcmgr 2-Apr-03 14:33:28
>> Completing Archive Shift. Current Primary Archive:
d:\pi\dat\piarch.001
0 piarcmgr 2-Apr-03 14:33:28
>> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary
Archive is d:\pi\dat\piarch.003
Do not shut down the PI Server until the shift has completed. To determine when this has
occurred, check the message log for a message like:
0 piarcmgr 2-Apr-03 14:33:28
>> Archive d:\pi\dat\piarch.001 shifted successfully. New Primary
Archive is d:\pi\dat\piarch.003
3.12 Combining and Dividing Archives
From a user perspective, archive files are organized according to their size and the time
ranges that they span. It is useful sometime to change the initial file organization of the
archive. The Offline Archive Utility can be used to accomplish each of the following tasks:
Combining archives with overlapping dates into one archive
Combining archives with adjacent time ranges into one archive
Dividing an archive into smaller archives, each covering a portion of the original
time span
3.12.1 Combining Archives into a Single Archive
To combine several archives, invoke the Offline Archive Utility once for each input file,
using the same output file for all these inputs. Start from the oldest input, going in ascending
time order.
Note: The Offline Archive Utility will not work in descending or random time order.
PI Server System Management Guide Page 59
Chapter 3 - Managing Archives
The end-time of the output file can be moved forward as required, but the start-time cannot be
changed after creation.
Archives with an unknown end time should be processed into a new archive to determine the
actual end time. The resulting archive can then be merged chronologically. Merging a series
of archives with overlapping dates requires processing the archive with the oldest start time
first, then process the remaining in chronological order based on the archive end times.
Example of Combining Archives
piarchss -if D:\pi\dat\oldest.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newer.dat -of D:\pi\dat\bigfile.dat
piarchss -if D:\pi\dat\newest.dat -of D:\pi\dat\bigfile.dat
In this example, bigfile.dat does not exist prior to the operation. It is created in the first
session and events are added to it in the second and third session. It is created as a dynamic
archive by default. After it is created, it may be registered using piartool -ar, and then events
may be added to the archive through the Snapshot Subsystem.
Any of the three input files that were registered prior to the operation are unregistered during
the operation. When the operation is complete, they may be registered using piartool -ar.
Dynamic archives, which is the default type created by the offline utility, are not shiftable.
Dividing an Archive into Smaller Archives
To break a single archive into smaller archives, invoke the Offline Archive Utility once for
each output file, using the same input file for all the outputs. Each time, a different start and
end time is specified. These times are specified in absolute PI time format.
Example of dividing an archive into two smaller archives:
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\january.dat -filter "1-jan"
"31-jan-02 23:59:59" -ost "1-jan" -oet "31-jan-02 23:59:59"
piarchss -if D:\pi\dat\bigfile.dat -of D:\pi\dat\february.dat -filter "1-feb"
"28-feb-02 23:59:59" -ost "1-feb" -oet "28-feb-02 23:59:59"
In this example, january.dat and february.dat do not exist prior to the operation. They are
created as dynamic archives by default. After they are created, they may be registered using
piartool -ar, and then events may be added to the archive files in the usual way. Both output
archives are not shiftable because they were created by the Offline Archive Utility as
dynamic archives.
The filter start time of january.dat is specified as 1-jan. This defaults to 1-jan, of the current
year, at 00:00:00. The filter end time is enclosed in double quotes because of the embedded
space character. The output archive start and end times are explicitly specified. Failing to
include the “-ost” and “-oet” flags will get the default behavior. See the above discussion of
output archive time settings for more information.
If the input file were registered prior to the operation, it would be unregistered during the
operation. When the operation is complete, it may be registered again using piartool -ar.
Page 60
3.12 - Combining and Dividing Archives
3.12.2 Event Queue Recovery
It might be desirable sometimes to remove an Event Queue file from the system. For example
when the system cannot manage the load of a large backlog of events.
To do this:
1. Stop the Snapshot and Archive Subsystems.
2. Rename PI\dat\pimapevq.dat to PI\dat\ pimapevq.save
3. Restart the Snapshot and Archive Subsystems.
Later, the renamed Event Queue file can be loaded into an offline archive. The input file is
the saved Event Queue data file. The argument -evq indicates the input file is an Event
Queue. The resulting output archive might have dates that overlap existing archives. Offline
processing, as discussed above, is required to combine these archives. Here is an example
command line using piarchss to recover an Event Queue:
piarchss -if D:\pi\dat\pimapevq.save -of D:\pi\dat\piarch099.dat -evq
Note: In most cases the Event Queue is the above file. But, it is possible to have
multiple Event Queues. The utility, piartool -qs, will indicate if your system uses
multiple queues. The queue naming convention, if multiple queues are used is
pimapNNNN.dat where NNNN is a four digit integer.
Prior to version 3.4, the Event Queue was pi\dat\pieventq.dat. PI 3.4 and newer does
not support processing this format. These files should be processed before
upgrading.
Also, the memory mapped file approach introduced in version 3.4 and other
enhancements allows PI to handle out of order data much more efficiently in most
cases offline processing of the Event Queue will not be necessary.
PI Server System Management Guide Page 61
Chapter 4. BACKING UP THE PI SERVER
It’s important to back up the PI Server at least once a day, so that you don't lose data and
configuration information if something goes wrong with your equipment. All backups of PI
that are done while the PI System is running are managed by the PI Backup Subsystem
(PI\bin\pibackup.exe).
4.1 Planning for Backups
4.1.1 Choosing the Backup Platform (VSS vs. Non-VSS)
Volume Shadow Copy Services (VSS) is available on Windows 2003 Server and Windows
XP. The role of the PI Backup Subsystem during an actual backup depends upon whether a
VSS or a non-VSS backup is being performed. Non-VSS backups are the only option on
UNIX, Windows NT Server, and Windows 2000 Server.
During a VSS backup, the PI Backup Subsystem takes appropriate actions by responding to
VSS events, but the actual files are backed up by a separate application such as NTBackup
(NTBackup.exe). During a non-VSS backup, the Backup Subsystem itself backs up the files
of the PI System.
Windows XP can be used to test VSS backups for staging purposes, but you should always
run PI on a server platform. For Windows 2003 Server, it is highly recommended to upgrade
to Windows 2003 Server Service Pack 1 which includes a large number of bug fixes related
to backups.
4.1.2 Choosing a Backup Strategy
The easiest backup strategy is to set up PI to automatically run the backup scripts every day
(see Automating PI Backups, on page 66).
You can also run the scripts manually (see Customize Your Backup, on page 68). The backup
script initiates backups via NTBackup on platforms that support VSS, and/or with the
piartool -backup command on platforms that do not support VSS. It is highly recommended
that you run PI on a platform that supports VSS because VSS backups cause minimal
disruption to the operation of PI.
On Windows 2003 server, as an alternative to using the backup scripts, you can backup PI
with any third-party backup application that supports VSS. Third-party backup applications
may support features that are not supported by NTBackup. For example, NTBackup currently
supports only non-component mode backups (see Selecting Files or Components for Backup,
on page 75).
PI Server System Management Guide Page 63
Chapter 4 - Backing up the PI Server
4.2 Other Backup Considerations
While PI is running, PI cannot be backed up with standard operating system
commands such as copy (Windows) or cp (UNIX) because PI opens its databases
with exclusive read/write access. This means that the copy commands will outright
fail. PI prevents access by the operating system because a lot of the information that
is needed to backup the databases of PI is in memory and a simple file copy would
most likely lead to a corrupt backup.
When PI is not running, PI can be backed up with standard operating system
commands such as copy (Windows) or cp (UNIX).
Do not try to include the PI folder in your daily system backup. The PI archives
typically consist of a large number of huge files that undergo frequent small changes.
The PI backup scripts are designed to back up the archive files efficiently.
Make sure you have enough space on the disk where PI creates the backup files.
Check the disk space regularly.
Run a trial backup and restore to make sure everything works correctly. Test your
backups in this way periodically. See the section, Restoring Archives from Backup.
To avoid losing incoming data while the backups are running, turn on PI API
buffering for your interfaces wherever possible. On VMS PINet nodes, buffering is
done automatically, so buffering does not need to be turned on for VMS PINet nodes.
After PI Server installations or upgrades, shut down the PI Server and make a
complete backup of all PI directories and archives. Note that archives may not be
located under the PI\dat directory. On Windows, include the registry entries under
HKEY_LOCAL_MACHINE/SOFTWARE/PI System/PI. On UNIX, include the
/etc/piparams.default file.
When you make a major change to PI, such as a major edit of the Point Database or
User Database, consider immediately making a backup that includes those changes,
rather than waiting for the automated backup.
4.2.1 Guidelines for VSS Backups
All archives to be backed up must be on the PI Server Node. The VSS backup will
fail if the archive to be backed up is on remote drive, such as a mapped network
drive.
Once a subsystem registers for backup, the subsystem must remain online during the
next VSS backup or else the backup will fail. The subsystems that are currently
registered for backup can be listed with piartool -backup -query. The list of
registered subsystems is reset when the Backup Subsystem is restarted. If the backup
fails because a subsystem is offline, the PI System Administrator should do one of
the following.
• Fix the problem with the faulty subsystem and do a backup manually. VSS
backups can be done during the middle of the day because they are not disruptive
to the PI Server.
Page 64
4.3 - Guidelines for Backing Up Before Upgrading
• Restart the PI Backup Subsystem, wait for all of the subsystems except for the
problematic subsystem to register for backup, and then do a backup manually.
During VSS backups, PI databases are unavailable for writes for a very brief period
of time, typically on the order of milliseconds. This time period is less than the
timeout period for write operations such as point edits. This means backups could
potentially be done several times a day without disrupting normal server operation.
Backups should not be done while configuration changes are being made since the
changes may not take effect properly.
Although the disruption from a Freeze/Thaw cycle is relatively small, unnecessary
Freeze/Thaw cycles should be avoided. It is possible to unintentionally put PI
through a Freeze/Thaw cycle if you are using a non-component mode VSS backup
application such as NTBackup to do backups on your system. If any file on a volume
is backed up with a non-component mode backup, any VSS writer that has files on
that volume will go through a Freeze/Thaw cycle. This means that PI may think that
it is being backed up when you are really backing up a file that is completely
unrelated to it but happens to share a volume that is common to the PI databases.
4.2.2 Guidelines for non-VSS Backups
Try to prevent users from making changes to the PI System during non-VSS backups.
At the very least, schedule backups to occur at a time when users do not typically
make changes to the PI System. This is because the PI databases are briefly
unavailable for writes during non-VSS backups, which could cause operations, such
as point edits, to fail. Also, non-VSS backups backup up one component at a time.
This means that a point edit could occur between backing up the primary archive and
the point database, which could cause an inconsistency between the PI databases in
the backup.
4.3 Guidelines for Backing Up Before Upgrading
Before and after an upgrade, do a complete backup of the PI Server by shutting PI down and
copying all PI files to a backup medium. Follow these steps.
Make sure that your Interface Nodes are buffering your data.
Shut down PI, so that all files are closed.
Back up all files in all subdirectories under the PI directory. Since PI is not running,
you can use any standard operating system utility such as copy or tar.
On UNIX, include the /etc/piparams.default file.
On Windows, include the registry entries under
HKEY_LOCAL_MACHINE/SOFTWARE/PI System/PI.
PI Server System Management Guide Page 65
Chapter 4 - Backing up the PI Server
4.4 Automating PI Backups
The exact instructions for automating PI backups depend on the operating system on which
your PI Server is installed. Refer to the appropriate section for your PI Server:
Automating Backups on Windows
Automating Backups on Windows with a 3rd Party Backup Application
Automating Backups on UNIX
4.4.1 Automating Backups on Windows
The procedure supplied below is an out-of-the box solution that works on Windows NT,
Windows 2000, and Windows 2003 server without needing to install any 3rd party software.
If you wish to implement a backup solution from a particular vendor, then follow the
guidelines under Automating Backups on Windows with a 3rd Party Backup Application on
page 72.
The procedure for automating the PI backup script can be summarized as follows.
Install PIBackup.bat as a scheduled task
View and edit the scheduled tasks
Customize your backup
Do a test backup
Do a test restore
Install PIBackup.bat as a scheduled task
The pibackup.bat script in the PI\adm directory can be used to start a backup from the
command line or to install backup task. The default backup task will run automatically every
day at 2 AM. On Windows NT and Windows 2000, the default task name will be Atn, where
n is an integer. On Windows 2003 Sever, the default task name will be PI Server Backup.
When the scheduled task is run, the PI\adm\pibackuptask.bat script is executed. The
pibackuptask.bat script calls the backup script pibackup.bat and redirects the standard output
to a log file with a name similar to pibackup_dd-mmm-yy_hh.mm.ss.txt in the PI\backup
directory. The pibackup.bat backup script will automatically determine whether or not VSS is
supported, and the script will perform either a VSS or non-VSS backup as appropriate.
The syntax for using the pibackup.bat file is as follows.
PIbackup.bat <path> [number of archives]
[archive cutoff date] [-install]
where < > indicates a required parameter and [ ] indicates an optional parameter. The
command line parameters must be specified in the above order. If the -install flag is not
specified, a backup is performed immediately. The more restrictive of [number of archives]
and [archive cutoff date] takes precedence. Regardless of [number of archives] and
[archive cutoff date] archives that do not contain data are not backed up.
Page 66
4.4 - Automating PI Backups
Parameter Example Description
<path> E:\PI\backup Path must be the complete drive letter and path to a
directory with sufficient space for the entire backup.
[number of archives] 2 The number of archives to backup. For example, "2"
will backup the primary archive and archive 1.
[archive cutoff date] *-10d The cutoff date is specified in PI time format. For
example, "*-10d" restricts the backup to archives
archives that contain data between 10 days prior to
current time and current time. The more restrictive
of [number of archives] and [archive cutoff date]
takes precedence.
[-install] Installs a scheduled task to run pibackup.bat daily
at 2:00 am. If the -install flag is not specified, then
a non-VSS backup is performed immediately.
For example, the following command installs a task to backup the primary archive, archive1,
and archive2.
PIbackup.bat e:PI\backup 3 1-Jan-70 -install
All archives contain data later than midnight on 1-Jan-70, so the number of archives to be
backed is not restricted by the cutoff date. Note, however, only archives that contain data are
actually backed up. This means that if archive1 and archive2 are empty archives, then these
archives are not backed up.
The next example installs a task to backup all archives that contain data for the last 60 days to
the current time.
PIbackup.bat e:PI\backup 99999 *-60d -install
The assumption above is that less than 99999 archives are mounted, so 99999 does not
restrict the number of archives to be backed up.
The next example installs a task to backup PI using the default number of archives and the
default cutoff date.
PIbackup.bat e:PI\backup -install
The default number of archives for backup is 3, unless otherwise specified by the
Backup_NumArchives timeout parameter (see Timeout Parameters on page 87). The default
cutoff date is “1-Jan-1970 00:00:00”, unless otherwise specified by the
Backup_ArchiveCutoffDate timeout parameter.
View and Edit the Scheduled Tasks
After installing the scheduled backup tasks with the pibackup.bat script, you might want to
edit the scheduled task to change the task name or to set the Run As user to a different
account. For example, renaming the task is necessary if you want to install multiple
scheduled tasks via the pibackup.bat script.
For VSS backups, it is recommended to change the Run As user for the PI Server Backup
scheduled task from NT AUTHORITY\SYSTEM to the account of the user who will be
PI Server System Management Guide Page 67
Chapter 4 - Backing up the PI Server
administering the backups. This recommendation is simply for convenience purposes for
viewing the NTBackup log file. This is discussed further in Do a Test Backup on page 69.
Scheduled tasks can be viewed and edited via the Scheduled Tasks control panel.
Alternatively, tasks can be viewed and edited via the command line.
On Windows NT and Windows 2000, the scheduled tasks can be displayed with the at
command.
C:\pi\adm>at
Status ID Day Time Command Line
-----------------------------------------------------------------
1 Each M T W Th F S Su 2:00 AM C:\PI\adm\pibackuptask.bat
c:\PI\backup." 3 "*-60d""
On Windows 2003 Server, the scheduled tasks can be displayed and edited with the schtasks
command. Although the at command is still available on Windows 2003 Server, the schtasks
command should be used instead. For example, any task created with the at command on
Windows 2003 server cannot be edited.
e:\pi\adm>schtasks
TaskName Next Run Time Status
==================== ======================== ===============
PI Server Backup 02:00:00, 7/29/2005
Customize Your Backup
Backups are customized by creating the pisitebackup.bat and pintbackup.bat file in the
PI\adm directory. These files do not exist by default. You should never customize your
backup by editing the pibackup.bat or the pibackuptask.bat files because these files are
overwritten during an installation or upgrade.
The pisitebackup.bat File
If the pisitebackup.bat file exists, then the pibackup.bat backup script calls it right before
exiting. If you have any tasks you want pibackup.bat to execute each day after the backup,
then add these tasks to a file called pisitebackup.bat in the PI\adm directory.
Typically, PI System Managers use the adm\pisitebackup.bat file to move the backup
directory to tape. PI System Managers may also use the script to back up specific files that
are not included in the PI Server backup.
The pintbackup.bat File
If the pintbackup.bat file exists, the pibackup.bat backup script will execute pintbackup.bat
instead of executing NTBackup. By default, the backup script will execute NTBackup with
the following command line.
ntbackup.exe backup "@%PISERVER%dat\pibackupfiles.bks" /d "PI Server
Backup" /v:yes /r:no /rs:no /hc:off /m normal /j "PI Server Backup" /l:f
/f "%BackupPath%\PI_Backup.bkf"
This command line causes the files of PI to be backed up to PI\backup\PI_Backup.bkf. Since
the /a flag is not on the command line, the PI_Backup.bkf will be overwritten every time the
Page 68
4.4 - Automating PI Backups
backup is performed. The second argument on the command line
@%PISERVER%dat\pibackupfiles.bks tells NTBackup to backup the files listed in the
PI\dat\pibackup.bks backup selection file. The backup selection file is re-created every time
that the piartool -backup -identify command is run.
If you want to use different command line options for NTBackup or if you want to execute a
different backup command, create a pintbackup.bat file in the PI\adm directory.
Note: If you want to do a non-VSS backup on a platform that supports VSS, you
would alter the pintbackup.bat file to specify your preferred backup tool, either
piartool -backup or some other backup tool.
4.4.2 Do a Test Backup
Unless overridden by a pintbackup.bat file, the PI backup script will do a VSS backup when
it is executed on Windows XP or Windows 2003 server. The PI backup script will perform a
non-VSS backup on Windows NT and Windows 2000.
The following procedure applies to both VSS and non-VSS backups except where noted.
1. Open a command prompt and type the command pigetmsg -f so that you can view
messages that are written to the message log during the course of the backup.
2. Open the Scheduled Tasks control panel, right-click on the PI Server Backup
scheduled task, and select Run.
For VSS backups, if the Run As user for the scheduled task is the same as your
account, you will see NTBackup being launched and you will be able to monitor the
progress of the backup via the NTBackup GUI.
3. Run the command piartool -backup -query. You should see information about
the current state of the backup. If the query command indicates that the backup was
not launched, the backup script may have failed to launch the backup. The output of
the script is written to a log file in the PI\backup directory with a name of the form
pibackup_dd-mmm-yy_hh.mm.ss.txt. If the backup script log does not reveal the
source of the error, there are two additional logs that can be examined as explained in
steps 5 and 6.
4. After the backup is complete, run the piartool -backup -query command. The
command should indicate that the backup completed successfully.
5. Examine the PI Message Log for backup related messages. Run pigetmsg and use
pibacku* as a mask when prompted for Message Source. If the backup started and
completed, you should at least see Backup operation started and Backup operation
completed in the log file.
6. For non-VSS backups skip to step 7. For VSS backups, examine the NTBackup
backup log for errors. The procedure for examining the NTBackup log is described
under Troubleshooting Backups.
7. After the backup is complete, verify that the files were successfully backed up. Files
are backed up to PI\backup\. For VSS backups, the backed up files will be in a file
called PI_Backup.bkf, which can only be opened by NTBackup. For non-VSS
PI Server System Management Guide Page 69
Chapter 4 - Backing up the PI Server
backups, the actual files will be copied to subdirectories of PI\backup\. For example,
if the original file was located in PI\dat\, the file will be backed up to PI\backup\dat\.
8. For VSS backups, run vssadmin list writers. The output should indicate that the
state of the OSISoft PI Server VSS writer is stable.
4.4.3 Do a Test Restore
General Considerations
The following files require special treatment during a restore.
File Name Special Treatment
Pisubsys.cfg This file contains the full path name to the rendezvous file
piv3.rdz. This path may be incorrect if the restore is not to
the original location. There is no need to restore the
pisubsys.cfg file after a new installation because this file is
installed by the installation kit.
Piarstat.dat The piarstat.dat file contains the full path names to all of
the registered archives and database security information
for the archives. If the destination directory of the archives
to be restored is different than the original, then you may
need to generate a new piarstat.dat file with the piartool -
ar command. You will need to re-register your archives and
re-create the database security.
Restoring from NTBackup
The NTBackup application keeps track of the files that is has backed up via a catalog that is
stored under
\Documents and Settings\All Users.WINDOWS\Application Data\Microsoft\Windows
NT\NTBackup\catalogs51
All NTBackup catalogs are stored in the above directory no matter which user account the
backup is run under. When NTBackup is run in advanced mode, these catalogs can be
browsed from the Restore and Manage Media tab.
Page 70
4.4 - Automating PI Backups
To test the restore, use the following procedure.
1. Change the Restore files to location to Alternate Location and typing in an alternate
location. Typically, it is a good idea to temporarily restore files to an alternate
location even if the final destination of the restored files is the original location.
2. Review the files to be restored by double-clicking on the Backup Identification Label
for your backup. Select all files for restore except possibly those files discussed under
General Considerations above.
PI Server System Management Guide Page 71
Chapter 4 - Backing up the PI Server
3. Review the options for the restore from the Tools > Option menu.
4. Click Start Restore. The files should be restored to the alternate location.
5. After the restore is complete, click Report… The report should indicate that all files
were restored successfully.
Restoring from NTBackup if the Catalog was Lost
All that is required to restore from NTBackup is the original PI_Backup.bkf file that was
saved during the backup. The catalogs are not essential for restoring from backup.
1. Run NTBackup in advanced mode.
2. Select Restore and Manage Media.
3. Select Tools > Catalog a backup file…
4. Browse to the PI_Backup.bkf file that you saved and click OK. The catalog should be
added to the Restore and Manage Media tab. Once the bkf file is cataloged again,
you can restore the files with the restoration procedure described above.
4.4.4 Automating Backups on Windows with a 3rd Party Backup Application
If your PI Server is installed on Windows 2003 Server operating system, then you can do
your PI backups with any third-party backup software that supports VSS. On Windows 2003
server, the PI Backup scripts use NTBackup to launch a VSS backup. The advantage of
Page 72
4.5 - Automating Backups on a Windows Cluster
using NTBackup is that it comes with Windows free of charge, which allows OSISoft to
provide a default backup solution without requiring a third-party backup application.
However, you might want to use a third-party backup application if, for example, you already
use a third-party backup application and you want to use the same backup strategy for all of
your applications. A second reason may be that the third-party backup application has
particular features that make it easier for you to maintain backups. However, in order to use
any third-party backup application, the backup application must support VSS backups.
One limitation of NTBackup is that it only supports non-component mode VSS backups,
which means that NTBackup cannot use the components of PI to select files for backup. A
list of file names must be provided to NTBackup via the backup selection file
PI\dat\pibackup.bks. A big disadvantage of non-component mode backups is that if any file is
backed up on a volume where there is a PI database, PI will think that it is being backed up
even though none of its files are actually affected by the backup.
Most third-party backup applications support component mode backups, which mean that the
backup application will be able to detect the PI Backup Subsystem as a registered VSS writer
and will be display the components of the PI System that are available for backup. The
backup components of PI might appear in a third-party backup application as discussed in
Selecting Files or Components for Backup on page 75.
4.5 Automating Backups on a Windows Cluster
If you are using the PI Backup Scripts for your backups, then the backups must be scheduled
to run on both nodes in the cluster. That is, the command
PIbackup.bat <path> [number of archives]
[archive cutoff date] [-install]
must be run on both nodes in the cluster. Installing the backup scripts as a scheduled task is
discussed in detail under Automating Backups on Windows on page 66. Only one of the
scheduled backup tasks will succeed at any given time because the pibackuptask.bat and
pibackup.bat files are on the shared drive.
Other than the need to schedule the backups on both nodes, backups on clustered and non-
clustered Windows nodes are the same.
4.6 Automating Backups on UNIX
Contact OSIsoft technical support for updated instructions, at www.techsupport.osisoft.com.
PI Server System Management Guide Page 73
Chapter 4 - Backing up the PI Server
4.7 How The PI Backup Subsystem Works
4.7.1 Principles of Operation
VSS Backups Overview
VSS backups are initiated by VSS requestors, which are backup applications such as
NTBackup. A VSS provider forwards the backup request in the form of COM+ events to the
appropriate VSS writer or writers that have registered with the provider. Windows XP and
Windows 2003 Server come with a default VSS provider, and a VSS writer is an application
that performs the necessary actions to back up a particular system. The PI Backup Subsystem
is an example of a VSS writer. Information is passed between the VSS requestor and the VSS
writer(s) over the course of the backup via a sequence of VSS events. The most important of
these VSS events for understanding the significance of VSS backups for backing up the PI
System are the Freeze and Thaw events.
During the Freeze event, the PI Backup Subsystem requests each of the PI Subsystems to
suspend data writes to disk. After all subsystems have suspended data writes, the PI Backup
Subsystem responds to the VSS provider. The VSS provider then takes a Snapshot of all of
the local disk volumes that are affected by the backup. The Backup Subsystem then receives
the Thaw event, which means that it is OK for all PI Subsystems to resume writing to their
databases. Although data writes are suspended between the freeze and thaw events, all PI
databases remain readable by client applications. This means that historical data,
configuration information, etc., can be read by client applications without any disruption
during a VSS backup even between the Freeze and Thaw events.
Even on busy systems, however, the disruption to data writes is minimal because the total
time between the Freeze and Thaw events is typically on the order of a few milliseconds, and
the duration must be less than 60 seconds or else the backup will be aborted. The disruption
to data writes is so short that users should not even notice that a backup has occurred. For
example, users should be able to edit, create, or delete PI Points without disruption because
the timeout period for these operations is less than the typical time period between the freeze
and thaw events.
After the Freeze event, the backup application begins to backup the files that were requested
for backup. Although data is being written to the files that are being backed up, the state of
the file at the time of the Snapshot is preserved via a difference file. After all files are backed
up, which may take hours, the difference file is discarded.
More information about Volume Shadow Copy Services can be found online at
http://msdn.microsoft.com/library then browsing the tree as follows.
WIN32 AND COM DEVELOPMENT
SYSTEM SERVICES
FILE SERVICES
VOLUME SHADOW COPY SERVICE
Page 74
4.7 - How The PI Backup Subsystem Works
Non-VSS Backups Overview
Whereas VSS backups are initiated via a backup application, non-VSS backups are initiated
via the piartool -backup commands, which are discussed in the next section. For non-VSS
backups, the PI Backup Subsystem itself is the backup application.
As with VSS backups, all PI Subsystems remain online, and all PI databases remain readable
over the entire course of the backup. However, some databases will remain in a read-only
state for a significantly longer period of time than for VSS backups. For example, archives
and annotation files can be very large and writes to all archives and annotation files must be
suspended for the duration of time that it takes to copy them for backup. Due to the
architecture of the PI Archive Subsystem, writes must be suspended to all archives no matter
which archive is being backed up.
4.7.2 Selecting Files or Components for Backup
The files in the PI System are divided into backup components. A backup component is a
convenient way to select a group of files for backup. Typically, there is one component per
subsystem, but the PI Archive Subsystem has multiple components because there is one
component per archive/annotation file pair. Some subsystems have no components either
because the subsystem has no files that need to be backed up (such as the Totalizer and Alarm
Subsystems) or because the files for the subsystem do not require a Freeze/Thaw cycle for the
backup (such as the SQL and Shutdown Subsystems).
Non-VSS Backups (Component Mode)
All non-VSS backups are considered to be component mode backups. The piartool -
backup commands allow you either to backup a particular component or to backup all
currently identify components. Typically, the PI Archive Subsystem identifies only a subset
of its archives, as determined by timeout parameters, by arguments to the piartool -backup
commands, and by the actual number of archives that contain data. This is discussed in more
detail below.
VSS Backups (Component Mode or Non-Component Mode)
VSS backups are either component-mode backups or non-component mode backups.
Individual files are selected for backup with non-component mode backups. To a certain
extent this is an advantage because you can control exactly which files you want to backup.
However, if any file is backed up on a disk volume where there is a PI database file, PI will
think that it is being backed up even though none of its files are actually affected by the
backup. This means if you backup a file that is completely unrelated to PI but shares a disk
volume with a PI database, PI will undergo an unnecessary VSS Freeze/Thaw cycle. This is
not as bad as it sounds because data writes are suspended only for a short amount of time
during a VSS Freeze/Thaw cycle, but you should be aware that PI could be unintentionally
put through a VSS Freeze/Thaw cycle when non-component mode backups are employed.
The default backup solution for PI on Windows XP and Windows 2003 Server uses
NTBackup, which supports only non-component mode backups.
A second disadvantage to non-component mode backups is that all VSS writers that have a
disk volume in common with PI will always be backed up at the same time as PI. This could
lengthen the time period between the Freeze and Thaw events because the Thaw event cannot
PI Server System Management Guide Page 75
Chapter 4 - Backing up the PI Server
occur until all participating VSS writers have been frozen. Since the system drive is
associated with several VSS writers, you should not install PI or any of its databases on the
system drive, especially if you plan to use a non-component mode backup application to do
your backups.
You can use any third-party backup application to backup PI as long as the backup
application supports VSS. Most third-party backup applications that support VSS also
support component mode backups. At the request of a backup application the, PI Backup
System identifies the files and components of the PI System. The backup application can use
this information to display the components in a graphical user interface. If the component of a
different application is selected for backup, then the PI system will not go through a
Freeze/Thaw cycle, even if that component has files on a disk volume that is common to the
PI databases.
A backup application that supports component mode backups has the following information
available to it for display purposes.
The registered name of the PI VSS writer. The registered name is OSISoft PI Server.
The friendly name of each component. Each component has a name and description.
The component description is intended to be used as a friendly name for display
purposes.
A component path. The component path provides a means of logically organizing a
group of components. The PI Archive Subsystem is the only subsystem that has a
non-null component path.
The PI System may appear as follows in a graphical user interface of a backup application
that supports component mode backups.
Each entry in the above tree view is a friendly name of a component except OSISoft PI
Server, which is the registered name of the PI VSS writer, and PI Archive Subsystem, which
is a component path. Typically, a backup application will use different icons to distinguish
between a registered writer, a component path, and a component, but this is dependent on the
particular backup application. Also, the component path PI Archive Subsystem may not be
selectable in some backup applications because there is no component at that point in the tree.
Page 76
4.7 - How The PI Backup Subsystem Works
A user can select one or more components for backup. However, for a typical, automated
backup one should configure the backup application to backup the OSISoft PI Server as a
whole because new archive components are added after each archive shift. These new
archives will not be selected for backup by default unless the OSISoft PI Server is selected for
backup as a whole.
4.7.3 The Backup Components of PI
The following table summarizes the backup components of PI.
Component Name Component “Friendly Name”
Path (Component Description)
SettingsAndTimeoutParameters NULL Settings and Timeout Parameters
Pilicmgr NULL PI License Manager
Pimsgss NULL PI Message Subsystem
Pibasess NULL PI Base Subsystem
Pisnapss NULL PI Snapshot Subsystem
Piarchss PI Archive Archive Registry and Archive Audit
Subsystem Database
Piarchive_<UTCprimary>_<GUID> PI Archive Archive0 dd-mmm-yy hh:mm:ss to
Subsystem Current
Piarchive_<UTCarch1>_<GUID> PI Archive Archive1 dd-mmm-yy hh:mm:ss to dd-
Subsystem mmm-yy hh:mm:ss
... … …
Piarchive_<UTCarchN>_<GUID> PI Archive ArchiveN dd-mmm-yy hh:mm:ss to dd-
Subsystem mmm-yy hh:mm:ss
Pibatch NULL PI Batch Subsystem
The Components in the Archive Subsystem
The Archive Subsystem has one component for each archive/annotation file pair. The name
has the form piarchive_<UTCTime>_<GUID>, where <UTCTime> is the start time of the
archive/annotation file in UTC seconds since midnight 01-Jan-70 and <GUID> is the GUID
that uniquely identifies each archive/annotation file pair. For example, the name of an archive
component with a start date of 5-Aug-05 17:56:08 might be:
piarchive_01123289768_{1a0fbff1-bfe4-45f3-82db-5cf5b64b088e}
The description of an archive component has the form Archive0 dd-mmm-yy hh:mm:ss to
Current for the primary archive and ArchiveN dd-mmm-yy hh:mm:ss to dd-mmm-yy hh:mm:ss
for all other archives. The name of an archive component stays the same for the lifetime of an
archive/annotation file pair, but the component description or “friendly name” changes every
time there is an archive shift. For example, in the above example, the archive will begin its
life as a primary archive with a friendly name of
PI Server System Management Guide Page 77
Chapter 4 - Backing up the PI Server
Archive0 5-Aug-05 17:56:08 to Current
If the above archive shifts at 25-Aug-05 14:23:01, the friendly name of the archive becomes
Archive0 5-Aug-05 17:56:08 to 25-Aug-05 14:23:01
The friendly names of all other components for the PI System do not change.
4.7.4 The Files and Components for each Subsystem
PIBackup
The PIBackup Subsystem has a single component called SettingsAndTimeoutParameters.
The Settings and Timeout Parameters component contains files that are owned by various
subsystems. The owning subsystems do not need to participate in backup because there is no
special need to suspend data writes to these files during a backup. The subsystems that are
associated with these files are not listed in the list of registered subsystems for backup with
the piartool -backup -query command. The file names are hard-coded in the PI Backup
Subsystem.
The files backed up with this component are:
File Name File Description
Pe314.dfa PI-Performance Equation Scheduler parsing rules database (1 of 2)
Pe314.llr PI-Performance Equation Scheduler parsing rules database (2 of 2)
Pifirewall.tbl Firewall database
Pipeschd.bat PI-Performance Equation Scheduler command file
pisql.ini Initialization settings for the SQL Subsystem
pisql.res Parsing resource for the SQL Subsystem
Pisubsys.cfg Inter-process communication information file used by PI Network Manager
PISysID.dat Server ID data file
Pisystem.res PI-Performance Equation Scheduler equation parsing symbol database
Pitimeout.tbl Timeout database
Shutdown.dat Shutdown event configuration file used by the Shutdown Subsystem
(pishutev)
Plicmgr
The Pilicmgr subsystem has a single component called Pilicmgr.
The files backed up with this component are:
File Name File Description
pilicense.dat License Information
Page 78
4.7 - How The PI Backup Subsystem Works
Pimsgss
The Pimsgss subsystem has a single component called Pimsgss.
The PI Message system contains all message log files from the PI\log directory. The message
file log names all begin with pimsg_ and end with .dat.
The files backed up with this component are:
File Name File Description
Pimsg_*.dat PI Message Log Files
Pibasess
The Pibasess subsystem has a single component called Pibasess.
The files backed up with this component are:
File Name File Description
pidbsec.dat PI Database Security Database
pidignam.dat Digital State Name Database
pidigst.dat Digital Set Database
PIModuleDb.dat PI Module Database
pipoints.dat PI Point Database
piptalia.dat PI Point Aliases Database
piptattr.dat PI Point Attributes Database
piptclss.dat PI Point Class database
piptsrcind.dat PI Point Source Index Database
piptunit.dat PI Point Unit Database
pitrstrl.dat PI Trust Table
piusr.dat PI User Database
piusrctx.dat User Context Database
piusrgrp.dat PI User Group Database
pibasessAudit.dat Base Subsystem Audit Database
Pisnapss
The Pisnapss subsystem has a single component called Pisnapss.
The files backed up with this component are:
PI Server System Management Guide Page 79
Chapter 4 - Backing up the PI Server
File Name File Description
piarcmem.dat Snapshot Information
pisnapssAudit.dat Snapshot Subsystem Audit Database
Piarchss
The Piarchss subsystem has a component called Archive Registry and Archive Audit
Database plus one component for each archive.
The files backed up with the Archive Registry and Archive Audit Database component
are:
File Name File Description
piarstat.dat PI Archive Manager Data File (Contains list of registered archives)
piarchssAudit.dat Archive Subsystem Audit Database
The following files are backed up with the archive components:
File Name File Description
Archive and Archive file names can be anything. The annotation file name is the same
Annotation (.ann) as the archive file name with “.ann” appended to it.
files for all
components
Each archive is contained in a separate component as described in The Components in the
Archive Subsystem on page 77.
PIBatch
The Pibatch subsystem has a single component called Pibatch.
The files backed up with this component are:
File Name File Description
pibaalias.nt Batch Alias Database
pibaunit1.nt PI Batch Unit Database
4.7.5 Lifetime of a Backup
Lifetime of a VSS Backup
During a backup, the PI Backup Subsystem receives a series of VSS events from the VSS
provider. The Backup Subsystem takes the appropriate actions and then asynchronously
forwards the VSS event to each subsystem that is participating in backups and then waits for
all subsystems to reply. The Backup Subsystem can veto the backup if a fatal error occurs
during any one of the events. If the backup is vetoed, then no further events will be sent to the
Backup Subsystem.
Page 80
4.7 - How The PI Backup Subsystem Works
The Identify event always occurs at the beginning of every backup, but it can also occur at
any time before or during a backup. The other VSS events always occur in the order specified
in the following table.
Backup Event Description
Identify The PI Backup Subsystem requests a list of files and components from each
subsystem that participates in backups. The PI Backup Subsystem returns the
compiled list to the VSS provider. During a non-component mode backup, this
information is simply not used by the backup application.
A backup application can use the information from the Identify event to
display the components of the PI System in its graphical user interface. If the
PI Backup Subsystem takes a long time to reply to a particular VSS event, a
backup application may send an Identify event to make sure that the PI
Backup Subsystem is still alive.
There is no way for the Backup Subsystem to be able to distinguish an identify
event at the beginning of a backup from an Identify event that occurs merely
for information gathering purposes.
PrepareBackup This event signifies the start of a backup. For a component mode backup, this
event is received only if one or more components of the PI System have been
selected for backup. The PI Backup Subsystem is told which of its
components have been selected. The event is forwarded to the subsystems
that are affected by the backup. For non-component mode backups, the event
is forwarded to every subsystem that participates in backups.
When this event is received by the PI Archive Subsystem, the subsystem sets
a flag to indicate that a VSS backup is in progress. The archive backup flag as
displayed by the piartool -as command will be set to 5.
For all other subsystems, the PrepareBackup event is ignored.
PrepareSnapshot For a non-component mode backup, the PI Backup Subsystem determines if
any PI databases are on one or more of the disk volumes that are affected by
the backup. This cannot be determined before the PrepareSnapshot event. If
none of the disk volumes corresponding to the PI databases are affected, then
PI vetoes the backup and no other backup events are received. Otherwise,
only those subsystems that are affected by the backup will receive
subsequent VSS events.
Freeze Each subsystem that is participating in the backup stops writing data to its files
when it receives the freeze event. For example, any data that is sent to the PI
archives will go to the queue and will not be readable until after the thaw
event. Data that is already in the archive remains readable between the
Freeze and Thaw events. Similarly, configuration information (such as point
configuration and the module database) also remains readable.
After the PI Backup Subsystem and all other VSS writers that are participating
in the backup have indicated that all files are frozen, the VSS provider will take
a snapshot of all disk volumes that are affected by the backup.
Thaw Each subsystem that is participating in the backup resumes writing data to
each of its files. The time between Freeze and Thaw is typically on the order
of a few milliseconds and cannot be greater than 60 seconds without timing
out.
The time period between Freeze and Thaw is typically short enough so that
database configuration operations should not time out. For example, a user
should be able to edit PI points during a backup without even noticing that a
PI Server System Management Guide Page 81
Chapter 4 - Backing up the PI Server
Backup Event Description
backup has occurred.
The time period between the Freeze and Thaw events can be affected by a
3rd-party VSS writer that is being backed at the same time that the PI System
is being backed up. The Thaw event will not occur until all VSS writers have
indicated that their files have been frozen. This means that a misbehaving
VSS writer or a VSS writer that simply takes a long time to freeze can
significantly increase the time period between the Freeze and Thaw events.
PostSnapshot No actions are taken during the PI Backup Subsystem for the PostSnapshot
event.
Backup applications back up files between the PostSnapshot and the
BackupComplete events. Although data is being written to the files that are
being backed up, the state of the files at the time the snapshot is preserved
via a difference file. The difference file is maintained by the operating system
and is completely transparent to the PI system.
After the backup is complete or aborted, the difference file is discarded.
Backup completion may take hours if large files are being copied.
BackupComplete This event indicates that a backup has completed successfully. The last
backup time will be updated for each of the PI System’s database files that
keep track of such information. A summary of last backup times can be
displayed with the piartool -backup -identify -verbose command. The last
backup time for archive files are displayed by piartool -al command.
When the PI Archive subsystem received this event, the output of piartool -as
should indicate that the archive backup flag has been reset to 0.
BackupShutdown If the PI Backup Subsystem gets the BackupShutdown event without getting
the BackupComplete event, then this means that the backup did not
complete successfully.
If the PI Archive Subsystem never receives a BackupComplete event, it will
turn its archive backup flag off if it gets the BackupShutdown event.
Lifetime of a non-VSS Backup
Data writes need to be suspended the entire time that a file is being backed up for non-VSS
backups. Like a VSS backup, data that is already on disk remains readable to all databases
while the databases are being backed up. Unlike a VSS backup, each component is backed up
one at a time, which means that there is one Freeze/Thaw cycle for each component.
Archiving is turned off to all archives whenever any of the archives are being backed up. This
is because there is no way to tell which archive will receive the data before the data is
processed. Time is allotted for the queue to be emptied between each archive component that
is backed up.
The PI Backup Subsystem sends the same backup events to each subsystem for a non-VSS
backup as for a VSS backup, except for the PrepareSnapshot and PostSnapshot events,
which the Backup Subsystem does not send. Another difference is that the Backup Subsystem
generates the events instead of responding to events from a VSS provider. Like a VSS
backup, the Identify, PrepareBackup, BackupComplete, and BackupShutdown events are
sent to each subsystem asynchronously. It is only the Freeze and Thaw events that are sent
one time for each component.
Page 82
4.8 - Launching Non-VSS Backups with piartool -backup <path>
The backup events are summarized in the following table.
Backup Event Description
Identify The PI Backup Subsystem requests a list of files and components from
each subsystem that participates in backups. The Backup Subsystem uses
the list of files to determine which files it should backup.
PrepareBackup When this event is received by the PI Archive Subsystem, the subsystem
sets a flag to indicate that a non-VSS backup is in progress. The archive
backup flag as displayed by the piartool -as command will be set to 21.
Currently, all other subsystems ignore the PrepareBackup event.
Freeze Like a VSS freeze, each subsystem that is participating in the backup stops
writing data to its files. Also like a VSS freeze, all PI databases remain
readable after the freeze event.
On Windows, each subsystem duplicates its handles for the files that it has
open so that the Backup Subsystem can copy the files. On UNIX, the
Backup Subsystem can copy the open files without a duplicate handle.
There is one Freeze event per component.
Thaw The Frozen component resumes writing data to each of its files. The time
between Freeze and Thaw can be long, especially for large archive files that
are being copied. If all selected components have been backed up, then the
BackupComplete event follows the Thaw event. Otherwise, the Freeze
event follows the Thaw event to backup the next component. There is a
delay between archive components that are backed up to allow the queue
to be emptied.
After each component is successfully backed up, the last backup time is
updated for the files of that component. This is different than for a VSS
backup, where the last backup time is updated for every component during
the BackupComplete event. A summary of last backup times can be
displayed with the piartool -backup -identify -verbose command. The last
backup time for archive files are displayed by piartool -al command.
BackupComplete This event indicates that a backup has completed successfully. When the PI
Archive subsystem received this event, the output of piartool -as should
indicate that the archive backup flag has been reset to 0. No action is taken
by other subsystems when the BackupComplete event is received.
BackupShutdown If the PI Backup Subsystem gets the BackupShutdown event without
getting the BackupComplete event, then this means that the backup did
not complete successfully.
If the PI Archive Subsystem never receives a BackupComplete event, it
will turn its archive backup flag off if it gets the BackupShutdown event.
4.8 Launching Non-VSS Backups with piartool -backup <path>
The syntax of the piartool -backup command for starting a non-VSS backup is
piartool -backup <path> [-component <comp>][-numarch <number>
[-cutoff <date>][-wait <sec>]
where <> indicates a required parameter and [] indicates an optional parameter.
PI Server System Management Guide Page 83
Chapter 4 - Backing up the PI Server
Argument Description
<path> Path must be the complete drive letter and path to a directory with
sufficient space for the entire backup.
-component <comp> Backup only component specified by <comp>. For example,
piartool -backup c:\pi\backup
-component pibasess
will only backup the files that belong to the PI Base Subsystem. A full
list of the components are available from the command
piartool -backup -identify -verbose
The -component flag overrides the -numarch and -cutoff flags, which
are used only to restrict the number of archive components that are
backed up. If the -component flag is not specified, all components are
backed up except for the archive components that are restricted from
backup by the -numarch and -cutoff flags.
-numarch <number> The number of archives to backup. For example, "2" will backup the
primary archive and archive1, provided that the primary archive and
archive1 contain data. In no case will an empty archive be identified for
backup. The default number of archives for backup is 3, unless
otherwise specified by the Backup_NumArchives timeout parameter.
-cutoff <date> The cutoff date is specified in PI time format. For example, "*-10d"
restricts the backup to archives that contain data between 10 days prior
to current time and current time. The more restrictive of -numarch
<number> and -cutoff <date> takes precedence. The default cutoff
date is 1-Jan-1970 00:00:00, unless otherwise specified by the
Backup_ArchiveCutoffDate timeout parameter.
-wait <sec> Wait up to <sec> seconds for the non-VSS backup to complete before
returning from the piartool -backup command. The progress of the
backup is reported every 15 seconds and when the backup is
complete, the status of the backup is reported via a piartool -backup -
query.
4.9 Managing Backups with piartool
4.9.1 Backup Command Summary
The piartool -backup commands are typically used for troubleshooting and for monitoring
the course of a backup. The piartool -backup commands can also be used to start a non-VSS
backup. The pibackup.bat script, for example, uses the piartool -backup commands to start
non-VSS backups when the script is run on an operating system that does not support VSS
backups.
The basic syntax for the piartool -backup command is
piartool -backup <Arg1> [Arg2] [Arg3] ...
where <> indicates a required parameter and [] indicates an optional parameter. If <Arg1>
does not begin with a hyphen (-), then <Arg1> is assumed to be the destination directory for a
Page 84
4.9 - Managing Backups with piartool
non-VSS backup. If <Arg1> begins with a hyphen (-), then <Arg1> is assumed to be a backup
command. The following backup commands are valid.
Backup Command Description
-abort Abort a current running backup.
Example:
piartool -backup -abort
-query [-verbose] The query command does the following.
Reports a list of subsystems that are currently registered for backup.
If a backup is not in progress, the query reports the status of the last
backup.
If a backup is in progress, the type of backup and the status of the
backup is reported.
Example:
piartool -backup -query
-identify [-numarch The identify command reports the list of files that PI will backup. If the -
<number>] [-cutoff verbose flag is specified, PI will report a list of files and components.
<date>] [-verbose] A component is a logical grouping of files. For example, all of the files for
the base subsystem are grouped under the pibasess component. The
purpose of a component is to identify a group of files for backup.
The -numarch and -cutoff flags have the same meaning as the backup
command for non-VSS backups, which is described below.
The identify command creates a \pi\dat\pibackupfiles.bks file. This file is
used in the pibackup.bat backup script to specify the list of files to backup
using NTBackup. NTBackup is used by the backup script for performing
VSS backups on Windows 2003 Server.
Example:
piartool -backup -identify -verbose
-trace <level> Debug messages are written to the log file when the trace level is non-
zero. The higher the trace level, the more messages that are written. The
maximum number of messages is written with a trace level of 100.
Tracing should be off unless you are troubleshooting a problem to avoid
unnecessary messages in the log file. If the trace level is non-zero, the
trace level is displayed by the piartool -backup -query command.
Example:
piartool -backup -trace 1
4.9.2 piartool -backup -query
When the PI System if first started and whenever the PI Backup Subsystem is restarted, the
output of a piartool -backup -query will appear as follows once all of the subsystems have
registered for backup.
e:PI\adm>piartool -backup -query
Backup in Progress: FALSE
Last Backup Start: NEVER
VSS Supported: TRUE
PI Server System Management Guide Page 85
Chapter 4 - Backing up the PI Server
Subsystems Registered for Backup
Name, Registration Time, Version, Status
pibatch, 29-Jul-05 12:09:36, 3.4.370.38, [0] Success
pilicmgr, 29-Jul-05 12:09:52, 3.4.370.38, [0] Success
piarchss, 29-Jul-05 12:10:37, 3.4.370.38, [0] Success
pibasess, 29-Jul-05 12:11:53, 3.4.370.38, [0] Success
pisnapss, 29-Jul-05 12:11:54, 3.4.370.38, [0] Success
pimsgss, 29-Jul-05 12:11:56, 3.4.370.38, [0] Success
Last Backup Start will appear as Never when the backup subsystem is restarted because the
backup subsystem does not keep track of previous backups between restarts. Pibatch may not
appear in your list of subsystems that are registered for backup if you are not licensed to use
the old batch subsystem.
If the PI System is started normally, then subsystems should appear as registered within about
30 seconds of the PI Backup Subsystem startup time. Normal startup is, for example, starting
the PI System with the pisrvstart.bat command file or letting the PI System services
automatically start after a reboot. However, if the PI Backup Subsystem is shutdown and
restarted, it may take up to 10 minutes for the individual subsystems to register for backup.
All of the following subsystems must be running in order for a backup to succeed.
PI Network Manager
PI Backup Subsystem
PI License Manager Registers for backup
PI Message Subsystem Registers for backup
PI Snapshot Subsystem Registers for backup
PI Archive Subsystem Registers for backup
PI Base Subsystem Registers for backup
PI Batch Subsystem Registers for backup if you are licensed to use the old PI Batch
Subsystem
The other subsystems either do not have files that need to be backed up or they do not need to
be running for a backup to succeed. The above subsystems that register for backup should
appear in the list of registered subsystems in the output of the piartool -backup -query
command.
After doing a backup, the query will show information about the last backup. The following
shows an example of a query that was done after a successful non-VSS backup.
e:PI\adm>piartool -backup -query
Backup in Progress: FALSE
Last Backup Start: 29-Jul-05 02:00:04
End: 29-Jul-05 02:01:11
Status: [0] Success
Last Backup Type: FULL, NON-VSS
Last Backup Event: BACKUPSHUTDOWN
Last Backup Event Time: 29-Jul-05 02:01:22
Page 86
4.10 - Timeout Parameters
VSS Supported: TRUE
Subsystems Registered for Backup
Name, Registration Time, Version, Status
pibatch, 28-Jul-05 16:09:18, 3.4.370.38, [0] Success
pisnapss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
piarchss, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
pilicmgr, 28-Jul-05 16:09:51, 3.4.370.38, [0] Success
pibasess, 28-Jul-05 16:09:52, 3.4.370.38, [0] Success
pimsgss, 28-Jul-05 16:09:53, 3.4.370.38, [0] Success
4.9.3 piartool -backup -identify
The piartool -backup -identify command displays the list of files that need to be backed up
for the PI system. The output has the form.
e:\pi\adm>piartool -backup -identify
<FileName_1>
<FileName_2>
<FileName_3>
...
Whenever the backup identify command is run, a backup selection file, PI\dat\pibackup.bks,
is created. This backup selection file can be read by NTBackup to determine which files it
should backup.
The piartool -backup -identify -verbose command identifies the components and files for
backup. A component is simply a logical grouping of files. If a component is selected for
backup, all of its associated files are backed up.
The verbose output of the backup identify has the following form.
e:\pi\adm>piartool -backup -identify -verbose
FileList
Name, ComponentName, LastBackup
<FileName_1>, <ComponentName_A>, <BackupDateFile_1>
<FileName_2>, <ComponentName_A>, <BackupDateFile_2>
<FileName_3>, <ComponentName_B>, <BackupDateFile_3>
...
ComponentList
Name, ComponentDescription, ComponentPath
<ComponentName_A>, <Description_A>, <ComponentPath_A>
<ComponentName_B>, <Description_B>, <ComponentPath_A>
...
The output should correspond to the expected components listed in the section The Backup
Components of PI on page 77 and the expected files listed in the section on page Error!
Bookmark not defined..
4.10 Timeout Parameters
The timeout parameters that are specifically related to backup operations are reproduced here
for convenience. For a full list of all timeout parameters, see PI Server Reference.
PI Server System Management Guide Page 87
Chapter 4 - Backing up the PI Server
Subsystem(s) Name Default Min Max Read Description
Value
Archive archive_back 1800 5 86400 On backup Number of seconds before the
upleadtime sec startup predicted archive shift that a non-VSS
archive backup may start. The PI
Backup Subsystem waits up to 30
minutes for the archive shift to
complete. This timeout parameter has
no effect on VSS backups.
Archive Archive_BSTi 1800 1 86400 Once a This timeout parameter is obsolete. It
meout sec minute is for internal use only.
Backup Backup_Num 3 1 1000000 Before If the number of archives to be backed
Archives every up is not explicitly specified in
backup arguments to the pibackup.bat backup
script, then this timeout parameter
defines the default number of archives
to back up.
Backup Backup_Archi 01-Jan- 01- N/A Before If the cutoff date is not explicitly
veCutoffDate 70 Jan- every specified in arguments to the
70 backup pibackup.bat backup script, then this
timeout parameter defines the default
cutoff date. Archives that contain any
data between
Backup_ArchiveCutoffDate and
current time are backed up. For
example, if "*-30d" is specified, then
at least 30 days of data is backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict
the number of archives for backup.
Whichever timeout parameter is most
restrictive takes precedence.
Backup Backup_Trac 0 0 1000 Startup The default backup trace level. Non-
eLevel only zero backup trace levels cause debug
messages to be written to the PI
Message Log. The default trace level
can be overridden while the PI Backup
Subsystem is running with the
piartool -backup -trace <level>
command.
Page 88
4.11 - Troubleshooting Backups
Subsystem(s) Name Default Min Max Read Description
Value
All <subsysname 60 sec 10 900 Startup PI internally keeps track of the last
>_WriteModTi only modified date of most of the files that it
mesToFilePer needs to back up. The last modified
iod times for each subsystem are updated
every WriteModTimesToFilePeriod.
The smaller the period, the more
accurate the last modified time is.
A complete list of backed up files
along with their last modified dates
can be listed with the piartool -
backup -identify -verbose command.
For archives, the last modified date
can also be viewed with piartool -al.
Note for archive files:
When a value is written to a PI point,
the value is not actually written to the
archive until the archive cache is
flushed. The maximum period
between archive flushes is set by the
Archive_SecondsBetweenFlush
timeout parameter. After the cache is
flushed, the last modified time is
updated within
WriteModTimesToFilePeriod
seconds.
All <subsysname 1800 30 86400 Periodically The maximum number of seconds to
>_BackupTim sec when in remain in system backup mode. This
eout system timeout parameter only pertains to the
backup piartool -systembackup command,
mode which is used to take the audit
databases offline. The parameter has
no effect for VSS backups or non-VSS
backups that are started with the
piartool -backup command.
4.11 Troubleshooting Backups
4.11.1 Log Messages
The following log files should be examined for errors.
The backup script log. The backup script log is written to the target directory of the
backup and the log file has a name of the form pibackup_dd-mmm-yy_hh.mm.ss.txt.
An example backup script log file name is pibackup_5-Aug-05_14.16.22.txt.
The PI Message Log. Messages from the PI Backup Subsystem have a message
source of pibackup. Backup-related messages from all other subsystems have a
message source of pibackup<subsysname>, such as pibackup_piarchss. You can
search for all backup related messages in the log by using pibacku* as a text mask
for Message Source.
PI Server System Management Guide Page 89
Chapter 4 - Backing up the PI Server
The NT Event Log. From the Application Log, look for messages from “VSS”,
“COM+”, and “ntbackup” sources.
The NTBackup.exe log file (VSS Backups only). If there was a problem creating a
VSS shadow copy during a backup, the reason for the failure is logged at the
beginning of the NTBackup.exe log file.
If the “Run As” user for the “PI Server Backup” scheduled task is the same as your
account, then you can view the NTBackup log from the Tools > Report… menu of
NTBackup. Launch NTBackup from a DOS command prompt and choose to run in
advanced mode.
If the PI Server Backup scheduled task was run under the system account, you must
browse to the NTBackup.exe log file with Windows explorer to the following directory.
C:\Documents and Settings\Default User.WINDOWS\Local
Settings\Application Data\Microsoft\Windows NT\NTBackup\data
If the scheduled task is run under a user name other than the system account, then replace
Default User.Winodows with the specific user name to get the path to which the
NTBackup.exe log file is written.
4.11.2 VSSADMIN
Vssadmin.exe is the Volume Shadow Copy Service administrative command line tool. You
can use the tool to view the status of the VSS writers, VSS Providers, and VSS shadow
copies on the system.
Page 90
4.11 - Troubleshooting Backups
VSSADMIN LIST SHADOWS
A shadow copy is created during the freeze event. If a backup is not currently in progress, the
output of vssadmin list shadows should look like the following output that was generated on
Windows XP.
e:\pi\adm>vssadmin list shadows
vssadmin 1.0 - Volume Shadow Copy Service administrative command-line
tool
(C) Copyright 2001 Microsoft Corp.
No shadow copies present in the system.
If there were problems create the shadow copy, look for errors in the NTBackup.exe log file
and run vssadmin list shadows to check the status of the failed shadow copy.
VSSADMIN LIST PROVIDERS
Windows XP and Windows 2003 server comes with a default VSS provider.
The following is sample output generated on Windows XP.
e:\pi\adm>vssadmin list providers
vssadmin 1.0 - Volume Shadow Copy Service administrative command-line
tool
(C) Copyright 2001 Microsoft Corp.
Provider name: 'MS Software Shadow Copy provider 1.0'
Provider type: System
Provider Id: {b5946137-7b9f-4925-af80-51abd60b20d5}
Version: 1.0.0.7
VSSADMIN LIST WRITERS
The following is sample output for the vssadmin list writers command. When a backup
is not in progress, the status of all writers should appear as stable. The name of the writer for
the PI System is OSISoft PI Writer. The PI Backup Subsystem registers as a VSS writer with
this name.
The following is sample output from Windows XP.
e:\pi\adm>vssadmin list writers
vssadmin 1.0 - Volume Shadow Copy Service administrative command-line tool
(C) Copyright 2001 Microsoft Corp.
Writer name: 'OSISoft PI Server'
Writer Id: {0fd0891d-b731-4e59-a35d-48f164383155}
Writer Instance Id: {cf8d5ded-e931-4692-91a0-6b3064c756c3}
State: [1] Stable
Writer name: 'Microsoft Writer (Bootable State)'
Writer Id: {f2436e37-09f5-41af-9b2a-4ca2435dbfd5}
Writer Instance Id: {c89ae65c-9f26-4bd4-8220-db66757defc7}
State: [1] Stable
Writer name: 'MSDEWriter'
Writer Id: {f8544ac1-0611-4fa5-b04b-f7ee00b03277}
Writer Instance Id: {190c16a5-d378-43d6-bdb5-712983abea2b}
State: [1] Stable
PI Server System Management Guide Page 91
Chapter 4 - Backing up the PI Server
Writer name: 'WMI Writer'
Writer Id: {a6ad56c2-b509-4e6c-bb19-49d8f43532f0}
Writer Instance Id: {26a1f92f-779d-45d1-900a-21b8af6f0590}
State: [1] Stable
Writer name: 'Microsoft Writer (Service State)'
Writer Id: {e38c2e3c-d4fb-4f4d-9550-fcafda8aae9a}
Writer Instance Id: {f8dd1e16-4e36-4ed2-9a53-ea4e05bacdb6}
State: [1] Stable
Page 92
Chapter 5. MANAGING INTERFACES
5.1 Introduction
This chapter is split into two sections. The first section covers basic principles of interface
operation. The second section describes the basic steps involved with installing, configuring,
and administering a typical interface.
There are several manuals in addition to this document that provide general information with
regard to interface configuration and management.
Manual Name Notes
PI API Installation On Windows, this manual is installed into the pipc\bin directory by
Instructions the PI SDK installation kit. The manual provides several important
post-installation details for configuring the PI API and buffering.
UniInt End User Manual Most interfaces are based on the OSIsoft Universal Interface
(UniInt) and therefore share a common set of features. Certain
UniInt features may be described in more detail in the UniInt End
User Manual document than in the interface-specific
documentation. However, not all features that are described in
UniInt End User Manual are supported by all UniInt interfaces.
PI Interface Configuration The Interface Configuration Utility provides a graphical user
Utility User Manual interface for configuring the interface command line, interface
services, and various PI points that are useful for monitoring
interface performance.
PI Performance Monitor The PI Performance Monitor interface, PIPerfMon, obtains
Interface Manual Microsoft Windows performance counter data and sends it to the
PI System.
PI Interface Status Utility The PI Interface Status Utility is an interface that runs on the PI
Server node. The utility writes events such as “I/O Timeout” to PI
Points that have not received values for a configurable period of
time from a particular interface.
PI AutoPointSync User Some interfaces, such as the OPC Interface, support auto-point
Manual synchronization. PI AutoPointSync (PI APS) is a utility that
synchronizes the PI Server points for an interface with the tag
definitions on the interface’s data source.
PI Server System Management Guide Page 93
Chapter 5 - Managing Interfaces
5.2 General Interface Principles
For the most part, this section discusses general interface principles that apply to interfaces
running on Windows, UNIX, and VMS. If a particular topic in this section applies to a
particular operating system, then this is mentioned up front. For example, interfaces can only
use the PI Software Development Kit (PI-SDK) on Windows, but the PI-SDK is such a
fundamental part of the PI System that it is discussed under general principles.
5.2.1 About PI Interfaces
PI interfaces are software modules for collecting data from any computing device with
measurements that change over time. Typical data sources are Distributed Control Systems
(DCSs), Programmable Logic Controllers (PLCs), OPC Servers, lab systems, and process
models. However, the data source could be as simple as a text file. Most interfaces can also
send data in the reverse direction, from PI to the foreign system.
Typically, interfaces use the PI Application Programming interface (PI API) to retrieve
configuration information from the PI Server and to write data to the PI Server. Many
interfaces also use the PI Software Development Kit (PI-SDK) to retrieve configuration
information from the PI Server and to create PI Points, Digital States, etc. A handful of
interfaces use the PI-SDK to write batch data to PI, the most notable of which is the PI Batch
Generator interface (PIBaGen). The PI API and the PI-SDK are described in more detail
below.
Most interfaces written by OSISoft are written using UniInt, OSISoft’s so-called Universal
Interface. UniInt performs many tasks that need to be performed by most interfaces such as
loading points, parsing command line, arguments, scheduling scans for data, etc. As a result,
most OSISoft interfaces have a common set of features that are configured in the same way.
UniInt uses the standard PI API and the PI-SDK to write and read data from the PI Server.
Although UniInt itself is not publicly available, customers could use the PI-SDK and PI API
to write their own custom interfaces that do the same tasks as UniInt.
5.2.2 About PI Interface Nodes
A PI Interface Node is a computer that runs one or more interfaces to collect data from a
foreign system and send that data to a PI Server. The Interface Node might be a computer that
is a part of the foreign data system, such as a Foxboro AW51 workstation; it might be a
stand-alone dedicated interface computer; or it might be the PI Server itself.
Typically, you should avoid running interfaces on the PI Server node. Running interfaces on
a separate node allows the PI Server to be taken down for maintenance while data is still
collected and buffered on the Interface Node. Also, you do not want interfaces competing for
computer resources with the PI Server. As discussed later in this document, there are a few
interfaces that are intended to run on the PI Server, but these interfaces are the exception.
From an administrative standpoint, the best thing about PI Interface Nodes is that they are
typically configured once, backed up, and then left to run indefinitely without human
intervention. Exceptions to this include software upgrades, security patches, network
infrastructure changes, and some configuration changes driven by a change in the foreign
data system. Interface nodes are the first line focus for data reliability and availability, so user
interaction with interface nodes is usually restricted to PI system administration only.
Page 94
5.2 - General Interface Principles
Interface Nodes on VMS
An Interface Node on an OpenVMS-based VAX or Alpha computer is also known as a PINet
Node. PINet is a stripped-down version of a PI 2 server. PINet does not contain a data
archive, but it does contain a local Snapshot Subsystem and a local point database. In
addition, PINet provides utilities to access the point configuration information and data that
reside on the PI Server. PINet automatically buffers data when it cannot connect to the PI
Server. PINet sends data to PI over a TCP/IP connection.
PIonPINet is similar to PINet in that it is a subset of PI that runs on OpenVMS. PIonPINet
includes all of the functionality of PINet. In addition, it includes analysis, reporting and
graphical display utilities.
5.2.3 About Data Buffering
Data flow from a typical interface to the PI Server can be summarized by the following
diagram.
When buffering is enabled, the data flows through the interface to the buffering service and
from there to the Snapshot Subsystem on the PI Server. On Windows and UNIX interface
nodes, data is buffered with the bufserv service, which must be installed and configured
separately from the interface. On VMS, data buffering comes built-in with the interface node.
The above diagram shows the buffering application sending data to only one PI Server node.
As of PI API version 1.6, buffering supports collecting data from one interface and
distributing the data to multiple PI Servers. On VMS Interface Nodes, buffering supports data
sends to one PI Server only.
Some interfaces do not require buffering because the data source itself is buffered. For
example, the Batch File Interface and the Event File interface do not require buffering. The
interface-specific documentation should be consulted to see if your interfaces require
buffering.
If the PI Server is not available for some reason (such as an upgrade on the Server) then the
data is stored in a file buffer on the Interface Node. The size of the file buffer is configurable
(up to nearly 2GB on Windows and UNIX). When the PI Server becomes available again, the
buffering application sends all the stored data from the buffer, in chronological order, back to
PI Server System Management Guide Page 95
Chapter 5 - Managing Interfaces
the PI Server. If you then look ProcessBook, for example, your data appears as a continuous
flow of data, with no gaps.
5.2.4 About the PI API
The PI Application Programming Interface (PI API) is a library of functions that allow you
to read and write values from the PI Server, and also let you retrieve point configuration
information. OSIsoft has used the API to create interfaces that run on a variety of platforms.
The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to
be taken offline for software or hardware upgrades without compromising data collection.
When PI becomes available again, the buffered data are then forwarded to PI.
API Nodes are UNIX or Windows workstations that run programs such as interfaces that are
based on the PI API. In practice, the term “API Node” is sometimes used as a synonym for
“Interface Node”, because historically, most interfaces are API based. This document does
not use the term “API Node”.
You can call PI API from C, Visual Basic, or other languages. A complete list of supported
platforms and functions is available in the PI API Manual.
5.2.5 About the PI SDK
The PI Software Development Kit, (PI-SDK), is an ActiveX in-process server that provides
COM access to OSI historians. The product provides an object-oriented approach to
interacting with PI systems in contrast to the procedural methods used in the PI API.
The PI-SDK can only be installed on Windows. Only interfaces that run on Windows can
take advantage of the functionality provided by the PI-SDK. All interfaces written for UNIX
or VMS must use the PI API exclusively for all communication with the PI Server.
Some interfaces use the PI-SDK because certain functionality is not provided via the PI API.
For example, the PI-SDK allows interfaces to create points, digital sets. Also, any interface
that writes batch data to PI, such as the PI Batch Generator Interface (PIBaGen), must use
the PI-SDK to write its data.
Any data that is written to PI via the PI-SDK is not buffered via the bufserv service. For this
reason all interfaces write time-series data to the PI Server via the PI API.
Interfaces that connect to the PI Server with both the PI-SDK and the PI API must maintain
two separate connections to the PI Server.
5.2.6 About UniInt-Based Interfaces
There are hundreds of different PI interfaces and each interface is fully documented in its
own dedicated manual. However, most interfaces are based on UniInt therefore share a
common set of features.
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-
developed template used by the OSI developers, and is integrated into many interfaces. The
purpose of UniInt is to keep a consistent feature set and behavior across as many of our
interfaces as possible. It also allows for the very rapid development of new interfaces. In any
UniInt based interface, the interface uses some of the UniInt supplied configuration
Page 96
5.3 - Basic Interface Node Configuration
parameters and some interface specific parameters. UniInt is constantly being upgraded with
new options and features.
5.3 Basic Interface Node Configuration
The steps outlined in this section describe the basic steps for interface configuration. The
steps are provided in a logical sequence for you to follow. However, there is nothing
preventing you from doing the many of the steps in a different order than specified below.
This discussion applies to VMS, UNIX, and Windows interface nodes. However, the majority
of the details are provided for Windows and UNIX Interface Nodes. Differences between the
platforms are pointed out as necessary. Also, for the most part, the configuration steps apply
whether the interface is on the PI Server Node or on a remote node. Distinctions are made as
necessary.
These basic interface configuration steps can be summarized as follows.
• Install the PI-SDK and/or the PI API
• Connect to PI with apisnap.exe
• Connect with AboutPI-SDK.exe
• Configure PI Trusts for the Interface Node
• Install the Interface
• Set the Interface Node Time
• Connect with the Interface
• Configure Points for the Interface
• Configure Buffering
• Configure Interface For Automatic Startup
• Configure Site-Specific Startup Scripts
• Configure the PI3 PointSource Table
• Monitor Interface Performance
• Configure Auto Point Synchronization
• Configure the Interface Status Utility
5.3.1 Install the PI SDK and/or the PI API
On a Windows Interface Node you must install the PI-SDK. The PI-SDK setup kit installs the
PI API. After installing the PI-SDK, you should consult the PI API Installation Instructions
manual that is installed in the pihome\bin directory. Look for the file API_Install.doc. This
manual has many helpful suggestions for post-installation configuration of the PI API and
buffering.
On a UNIX Interface Node you must install the PI API. See the document entitled PI API
Installation Instructions.
On a VMS Interface Node, the PI API comes installed with PINET.
PI Server System Management Guide Page 97
Chapter 5 - Managing Interfaces
5.3.2 Connect to PI with apisnap.exe
On Windows or UNIX Interface Nodes, one of the first things you should do is to try to
connect with apisnap.exe to the PI Server Node. On VMS, the corresponding program is
snap.exe. See the PI 2 documentation for details on use of snap.exe.
The apisnap.exe program is installed with the PI API in the pihome\bin directory. On
Windows, the pihome directory is determined by the pihome entry in the pipc.ini file, which
is always located in the Windows directory. On UNIX, the pihome directory is determined by
the $pihome environment variable.
The syntax for running the apisnap.exe program is
apisnap.exe HostName:5450
or
apisnap.exe IPAddress:5450
where HostName is the fully-qualified host name for the PI Server Node (i.e.,
apollo.osisoft.com). The “:5450” after the host name or IP address is optional. It specifies the
port for the connection. If you can connect with apisnap.exe, you should be able to establish
a PI API connection with your interface.
If you cannot connect to the PI Server Node with apisnap.exe, try the following
troubleshooting steps.
Make sure the computer running the PI Server is accessible. Ping by name in both
directions.
Try adding the Interface Node to the hosts file on the PI Server node if you are
having trouble connecting with apisnap.exe. For PI API connections, the PI Server
uses reverse name lookup on the IP Address in the connection to look up the host
name of the interface node. Most commonly, the lookup is done from a Domain
Name Server (DNS). Alternatively, the Interface Node name can be resolved from
the hosts file on the PI server node.
Check the Firewall security on the PI Server node (see the section, Managing
Security).
5.3.3 Connect with AboutPI SDK.exe
This step applies only to interfaces on Windows that require both PI API and PI-SDK
connections. You can start the AboutPI-SDK.exe program from Start >All Programs> PI
System >AboutPI-SDK.
5.3.4 Configure PI Trusts for the Interface Node
Once you establish that you can connect with apisnap.exe and AboutPI-SDK.exe, you must
configure PI Trusts for the interface node. An interface that connects without a PI Trust is
granted “world” access rights or no access rights depending on the DefaultUserAccess
timeout parameter. Since world access rights are read only by default, an interface that sends
data to PI without being granted a PI Trust will generate the following message in the
interface log on the Interface Node.
Page 98
5.3 - Basic Interface Node Configuration
[-10401] No Write Access - Secure Object
Connect with apisnap.exe from the Interface Node to the PI Server node. You will see
messages similar to the following in the PI Server Message Log on the PI Server Node:
New Pinet 1 connection: snapE No Trust established for:
apollo.osisoft.int|192.168.9.198|snapE using default login
and
Access Denied: [-10413] No trust relation for this request ID: 64.
Address: 192.168.9.198. Host: apollo.osisoft.int. Name: snapE
The log messages tell us the following. The application name of the connection was snapE.
The IP Address was 192.168.9.198. The host name was a fully-qualified host name
(apollo.osisoft.int). The exact application name, IP Address, and host name as displayed in
the message log must be used when configuring PI Trusts. Note that that application name is
snapE, not apisnap.exe. Also note that using apollo in the PI trust for the above connection
would not work. The fully qualified name apollo.osisoft.int must be used.
Connect with AboutPI-SDK.exe from the Interface Node. You will a message similar to the
following.
Trust request from: OSI\MATZEN|apollo|192.168.9.198|AboutPI SDK.exe
failed: [-10413] No trust relation for this request (110 ms)
Unlike the connection from apisnap, host name is apollo, not apollo.osisoft.int. This example
illustrates that configuring trusts is sometimes experimental in nature. You must examine the
credentials as displayed in the PI Message Log.
Below are basic guidelines for creating simple trusts for interface connections. For a
comprehensive understanding of trusts and security, read the chapter Managing Security in
the PI Server System Management Guide. The discussion below assumes that you are
familiar with the information in that chapter.
Interface Trusts for PI API Connections
When configuring a trust for an API connection, do not specify the Windows Domain or the
Windows Username because these credentials are not passed in the PI API connection
credentials because PI API connections can come from UNIX and VMS nodes as well as
Windows nodes. Trusts with these fields configured will not work for PI API connections. If
you use the PI System Management Tools to configure a trust for a PI API application, then
the trust configuration wizard will not let you specify these fields. That is, the wizard will
prevent you from over specifying the PI API trust.
Although it is possible to use the application name in trusts for PI API applications, it is not
part of the default recommendations. See the section Using the Application Name in Interface
Trusts if you are interested in using the application name in your trusts.
We recommend one of two options for configuring trusts from an API application. Option 1
involves configuring the following two trusts.
• One trust based on IP address and netmask
• One trust based on fully-qualified host name (i.e., apollo.osisoft.com) *
PI Server System Management Guide Page 99
Chapter 5 - Managing Interfaces
Option 2 provides slightly tighter security. Instead of configuring the above two trusts, set up
the following trust.
• One trust based on IP address, netmask, and fully-qualified host name
In Option 2 if the IP address or fully-qualified host name changes, the trust will fail, whereas
in Option 1, it will not fail.
Interfaces Trusts for PI API and PI SDK Connections
Check your interface-specific documentation to see if your interface requires PI-SDK
connections in addition to PI API connections. We recommend configuring trusts in one of
two ways for applications that require both connection types.
Option 1 involves setting up the following 3 trusts.
One trust based on IP address and netmask. This trust works for both PI API and PI-
SDK connections.
One trust based on fully-qualified host name (i.e., apollo.osisoft.com). The PI API
always uses the fully-qualified host name as opposed to an abbreviated form of the
name.
One trust based on the simple host name (i.e. apollo). The SDK typically uses the
abbreviated simple host name. To verify the host name the PI-SDK will use, run
pidiag -host on the Interface Node.
With these 3 trusts established, the interface first attempts to connect by IP address. If the IP
address changes, then a trust is granted based on the host name. Because the PI-SDK and PI
API host name processing may differ, you should set up two trusts, one for each form of the
host name.
Option 2 provides slightly tighter security. Set up just 2 trusts, one for the PI API and one for
the SDK. In each trust, include host name, IP address, and netmask as qualifications for
connection.
One trust based on IP address, netmask, and fully-qualified host (i.e., apollo.osisoft.com).
This trust works for the PI API connection.
One trust based on IP address, netmask, and simple host name (i.e. apollo). This trust works
for the PI-SDK connection. To verify the host name the PI-SDK will use, run pidiag -host
on the Interface Node.
Trusts for Interface Nodes with Multiple NICs
If your Interface node has multiple NICs, you must set up a trust for each IP address, even if
you just see the connection with one. To see all IP addresses for a given computer, type
ipconfig -all at a command prompt.
Using the Application Name in Interface Trusts
Although it is possible to use the application name in trusts for PI API applications, the
additional security gains is typically not warranted by the increase in complexity. Before
adding complexity to your trusts be aware that interfaces is only as secure as the room the
Page 100
5.3 - Basic Interface Node Configuration
interfaces are in. Interfaces are configured to allow writing data to the PI Server, so physical
access to the machine allows any user who can log on to that machine to run PI applications
that could write data to the PI Server and a malevolent user could use an application name for
which a trust is already configured.
Part of the complexity arises when buffering is configured on the Interface Node because a PI
Trust must be configured for the buffering application as well as the interface. For Windows
and UNIX, the buffering application (bufserv.exe) has an application name of APIBE. For
VMS, the buffering application has an application name of EXCP plus a 4-digit process
identifier.
There is additional complexity for interfaces that connect with both the PI API and PI-SDK
because the PI API and PI-SDK pass different Application Names in their connection
credentials. For example, the OPC interface uses opciE for the API and opcint.exe for the
SDK. The application name for PI API interface connections can be determined by
examining connection messages in the PI Message Log on the server, whereas the PI-SDK
uses the actual file name of the executable.
5.3.5 Install the Interface
The basic next step after configuring PI Trusts is to install the interface. The particulars of
interface installation are highly platform dependent. For example, on Windows most
interfaces can be installed from an installation kit. On VMS, most interfaces come pre-
installed on the VMS PINet node. Consult the interface-specific documentation for details.
On Windows the installation kit typically installs the PI Interface Configuration Utility (PI-
ICU), which is a GUI for making several interface configuration tasks easier. You can start
the PI-ICU from the Start > All Programs > PI System > PI-Interface Configuration
Utility.
On Windows interfaces are installed by default in a subdirectory of the pihome\interfaces
directory. As mentioned above, the pihome directory is defined by the pihome entry in the
pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the
Windows directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=D:\Program Files\PIPC
The above lines define the D:\Program Files\PIPC directory as the root of the pihome
directory tree. For example, an interface called MyInterface would be installed to
D:\Program Files\PIPC\interfaces\MyInterface by default.
5.3.6 Set the Interface Node Time
In order for PI to accurately store and retrieve data, interface computers must have the correct
settings for time, time zone, and Daylight Savings Time (DST). Most interfaces send correct
timestamps even if the Interface Node is located in a different time zone than the PI Server.
That is, for most interfaces you should set the clock to its correct local time, time zone, and
DST setting. Also, you should configure the clock to automatically adjust for daylight saving
changes.
PI Server System Management Guide Page 101
Chapter 5 - Managing Interfaces
If the interface-specific documentation does not give specific instructions for setting time,
time zone, and DST, these guidelines should typically result in the correct timestamps being
set to PI. Exceptions are noted in the documentation for each interface. The most common
exception is for Foxboro Interface nodes, which must have their time zone settings set to
GMT.
Caution: In all cases, the PI Server clock should be set to its correct local time, time
zone, and DST setting.
5.3.7 Connect to the PI Server with the Interface
The next step is to connect to the PI Server with the interface. PI Points do not need to be
configured before this is done. On Windows, it is best to try to connect by running the
interface interactively instead of trying to run the interface as a Service.
Successful execution of the interface requires that a certain minimum number of required
command line parameters be specified. The PI Interface Configuration Utility makes the task
of configuring these command line parameters considerably easier. Although the interface-
specific documentation must be consulted, the following command line parameters should be
mentioned because they are fundamental to most UniInt-based interfaces.
Parameter Description
/ps=x The /ps flag specifies the point source for the interface. x
required is not case sensitive and can be any single character. For
example, /ps=P and /ps=p are equivalent.
The point source that is assigned with the /ps flag
corresponds to the PointSource attribute of individual PI
Points. The interface will attempt to load only those PI
points with the appropriate point source.
Consult the PI3 PointSource table to make sure you are not
using a PointSource that is already configured for another
interface.
/id=x The /id flag is used to specify the interface identifier. For
sometimes required example,
/id=1
The interface identifier is a string that is no longer than 9
characters in length. UniInt concatenates this string to the
header that is used to identify error messages as belonging
to a particular interface.
Many interfaces also use the /id flag to identify a particular
interface copy number that corresponds to an integer value
that is assigned to one of the Location code point attributes,
most frequently Location1. For these interfaces, one should
use only numeric characters in the identifier.
/host=host:port The /host flag is used to specify the PI Home node. host
recommended parameter is the IP address of the PI Sever node or the domain name
of the PI Server node. port is the port number for TCP/IP
communication, which should always be specified as 5450
for communication to a PI 3 server.
Page 102
5.3 - Basic Interface Node Configuration
Parameter Description
/f=SS Each occurrence of the /f flag on the command line
or specifies a scan class for the interface. A particular PI Point
is associated with a scan class via the Location4 PI Point
/f=SS,SS attribute.
or The /f flag defines the time period between scans in terms
/f=HH:MM:SS of hours (HH), minutes (MM), and seconds (SS). The scans
or can be scheduled to occur at discrete moments in time with
an optional time offset specified in terms of hours (hh),
/f=HH:MM:SS,hh:mm:ss
minutes (mm), and seconds (ss). If HH and MM are omitted,
required for scan-based interfaces then the time period that is specified is assumed to be in
seconds.
/stopstat If the /stopstat flag is present on the startup command
recommended parameter line, then the digital state Intf Shut will be written to each
PI Point when the interface is stopped.
After starting the interface, do the following.
Examine the PI Message Log to make sure that the interface connects with a successful trust
logon.
Examine the message log on the interface node for error messages. On Windows, the
message log is pihome\dat\pipc.log. On UNIX, the message log is $pihome\dat\pimesslogfile.
On VMS, the message log is PIsysmgr:pimesslog.txt.
5.3.8 Configure Points for the Interface
Configure PI Points for the interface. Although you must consult the interface-specific
documentation to configure your PI Points, there are a few attributes that are configured in
the same way fore most UniInt-based interfaces.
Point Attribute Description
PointSource The PointSource is a single or multiple character sequence that
is used to identify the PI point as a point that belongs to a
particular interface. For example, you may choose the letter R to
identify points that belong to the Random interface. Note that
multi-character PointSources are supported only with PI API 1.6
and greater.
The PointSource attribute must correspond to the /ps flag in the
startup command line of the interface.
Consult the PI3 PointSource table to make sure you are not using
a PointSource that is already configured for another interface.
Location1 The Location1 attribute is used by many interfaces to identify an
interface number. When used in this fashion, the Location1
attribute must correspond to the /id flag on the startup command
line of the interface.
PI Server System Management Guide Page 103
Chapter 5 - Managing Interfaces
Point Attribute Description
Location4 For interfaces that support scan-based collection of data,
Location4 defines the scan class for the PI point. For example, a
PI Point with Location4=1 will be scanned according to the first
occurrence of the /f flag in the startup command file. A PI Point
with Location4=2 will be scanned according to the second
occurrence of the /f flag, and so on.
Scan If the Scan attribute is set to OFF for a UniInt based interface, the
point will be removed from the interface. This can be useful when
troubleshooting the interface.
Shutdown When PI is restarted, the default behavior of the PI Shutdown
Subsystem is to write Shutdown events to all PI Points that have
their Shutdown attribute set to 1 (true). Typically, it is undesirable
for the PI Server to write shutdown events for Interfaces Nodes
that have a buffered data source on a node that is remote to the
PI Server Node. The Shutdown attribute should be set to 0 for PI
Points that belong to these interfaces. These remote, buffered
interfaces should write their own shutdown events when the
interfaces are shut down. This is typically configured with the
/stopstat command line parameter for UniInt-based interfaces.
After configuring a few PI Points, do the following.
Restart the interface and examine the log file to make sure that the points are loaded by the
interface. For UniInt-based interfaces, you will see a message similar to the following.
07-Nov-05 23:10:44
Total Number of points matching pointsource 'R' is 5
Look for error messages in the interface log. If PI Trusts are not configured correctly for the
interface you will see the following error when the interface tries to write data to PI.
[-10401] No Write Access - Secure Object
Use apisnap.exe to verify that the interface is writing data to your PI Points.
5.3.9 Configure Buffering
Once you have demonstrated that you can collect data with your interface, it is time to
configure buffering. Some interfaces do not require buffering or work better without
buffering. You must consult the interface-specific documentation to determine this. On VMS,
there is no need to configure buffering because it comes as part of PINet. The information
below applies only to UNIX and Windows Interface Nodes. For more details see the PI API
Installation Instructions. On Windows, the PI API Installation Instructions is installed by
the PI-SDK setup kit in the pihome\bin directory. The file name is API_install.doc.
If buffering is enabled on UNIX and Windows, the pihome\dat\piclient.ini file will contain
the following two lines.
[APIBUFFER]
BUFFERING=1
Page 104
5.3 - Basic Interface Node Configuration
The file can be edited with a text editor. Setting buffering=0 turns buffering off. Any
changes that are made to the pihome\dat\piclient.ini will only take effect when bufserv is
restarted.
The default and maximum size limit of buffer files is 2,000,000 KB (~2GB). If there is not
2GB of disk space available, then the buffer will grow as large as possible before failing. The
maximum size limit can be set to a value less than 2,000,000 KB with the maxfilesize
parameter in the piclient.ini file. For a full list of configuration options, refer to the PI API
Installation Instructions.
The following applies to buffering for PI API version 1.6 and greater on Windows and UNIX.
In PI API version 1.6 and greater, data that is sent via the PI API can be buffered to
multiple PI server Nodes. The PI Server Nodes for which buffering is enabled is
configured in the pihome\dat\piclient.ini file in the [BUFFEREDSERVERLIST]
section. In addition to the parent process, one buffer server process will be spawned
for each buffered server specified in the list. See PI API Installation Instructions for
more details.
The connection name for the interface (usually specified in the /host parameter) must
exactly match the buffer server name configured in the pihome\dat\piclient.ini file.
For example, in order for buffering to work for a UniInt-based interface, the
IPAddress or HostName specified by the /host command line parameter would need
to be identical to a PI Server listed in one of the entries specified in the
[BUFFEREDSERVERLIST] section in the pihome\dat\piclient.ini file. The
IPAddress and HostName are not interchangeable in this case, if the IPAddress is
used in the interface and the HostName in the pihome\dat\piclient.ini file, then
interface connection via the IPAddress would be unbuffered.
Bufserv now supports event distribution to multiple PI servers. This is sometimes
referred to as n-way buffering or buffering to replicated servers. Event distribution to
multiple PI servers consists of the taking data sent to one buffered server distributing
of the same event to multiple buffer servers. The list of PI servers to receive
distributed events is configured in the [REPLICATEDSERVERLIST] section in the
piclient.ini file. The distributed event is not manipulated in any way, which means
that the event does not have the point ID or the timestamp altered. Therefore, the
replicated PI servers must all have synchronized point databases. PI servers in the
[REPLICATEDSERVERLIST] section must also be in the
[BUFFEREDSERVERLIST] section.
The following applies to versions of the PI API prior to version 1.6.
Prior to PI API version 1.6, buffering could only be enabled for the default PI Server
node. The default PI-Server node is specified in the pihome\dat\pilogin.ini on
Windows and in the pihome\dat\piclient.ini node on UNIX.
The connection name for the interface (usually specified in the /host parameter) must
exactly match the name of the default PI-Server node. configured in the
pihome\dat\piclient.ini file.
The following applies to Windows only, but it applies to all version of the PI API.
PI Server System Management Guide Page 105
Chapter 5 - Managing Interfaces
Buffering should be installed as an automatic service. This can be accomplished
though the Tools > API Buffering… menu in the PI Interface Configuration Utility.
You can enable and disable buffering from the PI-Interface Configuration Utility
from the Tools > API Buffering... menu. The PI-Interface Configuration Utility
makes all of the necessary changes to the piclient.ini file.
The interface service must be configured to depend on bufserv to ensure that
buffering starts first. Otherwise the interface might establish an unbuffered
connection to PI before bufserv starts.
Monitoring Buffering
To ensure that buffering is functioning properly, check the interface log each day. You can
also use the buffering utility, bufutil.exe, to check the buffering service. For example,
bufutil.exe can be used to list the number of events that are currently in the buffer. When
connected to the PI server, the number of unprocessed events should generally be zero, but
may show a finite number since events are streaming through the buffers.
For version 1.6 and greater of the PI API, when bufutil.exe is started, the currently selected
buffered server is listed. There is a menu option to change the selected server.
5.3.10 Configure Interface for Automatic Startup
Once you have demonstrated that you can collect data while running the interface
interactively, configure the interface for automatic startup. On Windows, this is done by
configuring automatic services. On UNIX, this can be handled by adding your interface to
sitestart.sh script and configuring pistart.sh for automatic startup as described in Chapter 1,
Starting and Stopping PI. Site-specific startup scripts are discussed later in this chapter.
It is recommended to install services with the Interface Configuration utility from the services
tab. If you plan to enable buffering, you should install the interface service to depend upon
the following services.
bufserv
tcpip
You can start and stop your interface service either though the Interface Configuration Utility
or though the command line. If the interface service is called MyInterfaceService you could
run the following command from a command prompt.
To start a service, type the command:
net start MyInterfaceService
To stop a service, type the command:
net stop MyInterfaceServic
When an interface starts as a service, the interface service opens the corresponding
MyInterfaceService<ServiceID>.bat file to determine its command line arguments.
ServiceID’s and the manner in which interface services get their command line arguments are
discussed in detail in the UniInt End User Manual. These details are managed by the PI
Interface Configuration Utility.
Page 106
5.3 - Basic Interface Node Configuration
5.3.11 Configure Site-Specific Startup Scripts
The following discussion has been limited to UNIX and Windows nodes. On each node, there
is at least one shutdown script that calls a site-specific shutdown script. Likewise, there is at
least one startup script that calls a site-specific startup script. You should only modify the
site-specific scripts because the main startup and shutdown scripts are overwritten by the
installation script when PI is upgraded. In all cases, the site-specific startup scripts must be
edited manually with a text editor.
PI Server Node on Windows
If for some reason you must run an interface on the PI Server, you can configure the interface
to start and stop with the PI Server by adding it to the site-specific startup and shutdown
scripts. For interfaces that connect only via the PI API, the scripts provide a convenient
means of shutting down all programs that use the PI API.
However, for an interface that depends on the PI-SDK, it is more important to add the
interface to the site-specific stop and start scripts because PI-SDK programs depend upon
pinetmgr.exe, and pinetmgr.exe cannot be shut down until all services that depend upon it
are shutdown. The most common PI-SDK interface that is configured to run on the PI Server
node is the PI Batch Generator Interface. By default, the PI Batch Generator interface
installed on the PI Server node, but the interface is configured as a manual service, and the
interface is not configured to be stopped and started by the site-specific scripts.
The startup scripts on the files are as follows.
Startup script Corresponding shutdown scripts and site-specific scripts
Shutdown Site-Specific Site-Specific stop Script
script startup script script location
pistart.bat None pisitestart.bat None \PI\adm
pisrvstart.bat pisrvstop.bat pisrvsitestart.bat pisrvsitestop.bat \PI\adm
On Windows the difference between pistart.bat and pisrvstart.bat is that the former is used to
start PI interactively and the latter is used to start PI as a service. To start your interface
interactively, add a line similar to the following to pisitestart.bat.
program files\pipc\interfaces\myinterface\myinterface.bat
To start your interface as a service, add a line similar to the following to pisrvsitestart.bat.
net start myinterface
PI Interface Node on Windows
The site-specific startup scripts are named differently on an Interface Node, than on the PI
Server node. The scripts provide a convenient means of shutting down all programs that use
the PI API and PI-SDK that communicate to the PI Server node.
PI Server System Management Guide Page 107
Chapter 5 - Managing Interfaces
Startup script Corresponding shutdown scripts and site-specific scripts
Shutdown Site-Specific Site-Specific stop Script location
script startup script script
pistart.bat pistop.bat sitestrt.bat sitestop.sh pihome\bin\
PI Server Node on UNIX
The following are the startup and shutdown scripts on a UNIX PI Server node.
Startup script Corresponding shutdown scripts and site-specific scripts
Shutdown Site-Specific Site-Specific stop Script location
script startup script script
pistart.sh pistop.sh pisitestart.sh pisitestop.sh $pihome/adm/
Interface Nodes on UNIX
The following are the startup and shutdown scripts on a UNIX Interface node.
Startup script Corresponding shutdown scripts and site-specific scripts
Shutdown Site-Specific Site-Specific stop Script location
script startup script script
pistart.sh pistop.sh sitestart.sh sitestop.sh $pihome/bin/
5.3.12 Configure PointSource Table
When you create a PI Point with a given PointSource, the PointSource is automatically
added to the PIPTSRC table. The PIPTSRC table tells you how many PI Points there are for
each PointSource. As mentioned above, you should consult the PIPTSRC table before
configuring points for a new interface because you want to make sure that you are not using a
PointSource that is already being used by another interface.
Automatically generated entries in the PIPTSRC table have a blank description. You should
edit the PIPTSRC with the piconfig utility to add a description.
5.3.13 Monitor Interface Performance
Most UniInt-based interfaces have built-in ways of monitoring interface performance. Most
of these require PI Points to be configured. However, performance summary log messages are
written to the interface log file by default.
For interfaces that run on Windows, all of the performance statistics for an interface can be
collected via Windows Performance Counters. That is, there are Windows performance
counters that correspond to the performance summary log messages, I/O Rate Points, and
Performance Points for Scan Classes. There are also additional Windows Performance
Counters that extend the number of interface statistics beyond that which can be gathered on
non-Windows platforms.
Page 108
5.3 - Basic Interface Node Configuration
Windows Performance Counters
Many UniInt based interfaces now support Windows Performance Counters. Without any PI
Point configuration, the counters for the interface can be viewed from the Windows Control
panel under Administrative Tools > Performance. The one restriction is that the interface
must be running as a service in order for the counter to be visible. The following diagram
shows how the counters may appear for the PI Random Interface on the PI Server node.
In order to save the Windows Performance Counter data to PI, you must configure the PI
Performance Monitor Interface, which is available as basic or full versions. The basic version
is installed on the PI Server Node by default. You can collect performance counter data with
the interface from local and remote interface nodes. For more information, see the PI
Performance Monitor Interface documentation.
The following performance counters are available for most UniInt-based interfaces that run as
a service.
Counter Name Description
Interface up-time The number of seconds since the interface has started. This counter is
(seconds) incremented once a second.
IO Rate The number of events per second received by the interface. If this
(events/second) counter is viewed from the NT performance monitor, one should
increase the update time of the performance monitor to the minimum
scan period for the interface. For example, say that the minimum
scanning period for the interface is 5 seconds (/f=5). One can set the
PI Server System Management Guide Page 109
Chapter 5 - Managing Interfaces
Counter Name Description
update rate of the performance monitor to 5 seconds by selecting the
“Chart…” command from the Options menu. In the dialog box, change
the periodic update time to 5 seconds. If the update time is left at 1
second, then the IO Rate will appear to go to zero between scans
because no events are received between scans.
Point Count Number of points loaded by the interface.
Scan Time Time in milliseconds to call developer function and to write values to
(milliseconds) PI. There is one “Scan Time” counter per scan class.
Scheduled Scans: Percentage of missed scans since starting the interface. If a scan
% Missed occurs more than 1 second after its scheduled time, the scan is
considered missed. There is one “Missed Scans” counter per scan
class.
Related counters:
Scheduled Scans: % Skipped
Scheduled Scans: Scans this interval
Scheduled Scans, Percentage of skipped scans since starting the interface. If a scan
% Skipped occurs 1 scan period or more after its scheduled time, then 1 or more
scans are considered skipped. There is one “Skipped Scans” counter
per scan class.
Related counters:
Scheduled Scans, % Missed
Scheduled Scans, Scans this interval
Scheduled Scans: The total number of scans in the current performance interval. This
Scans this interval total is the current sample size that is used to evaluate the % Missed
Scans and the % Skipped scans. The performance interval is 8 hours
by default, but this can be changed by the /perf command-line
argument. The minimum performance interval is 60 seconds (see the
/perf argument for more information). When the performance interval is
exceeded, the previous samples are discarded and the sampling starts
again from scratch.
Related counters:
Scheduled Scans, % Skipped
Scheduled Scans, % Missed
Log file message count Number of messages that have been written to the log file. Only
applies to the instance _Total.
Points edited in the Number of point edits that have occurred. Only applies to the instance
interface _Total.
Points added to the Number of point that have been added to the interface. Only applies to
interface the instance _Total
Points removed from Number of point that have been removed from the interface. Only
the interface applies to the instance _Total
Page 110
5.3 - Basic Interface Node Configuration
Performance Summary Log Messages
If the performance of a UniInt-based interface falls below a particular level, the interface will
periodically write a performance summary to the interface log file. For each scan class, the
summary shows the percentage of scans hit, the percent of scans missed, and the percent of
scans skipped.
Scans that occur on time are considered hit. If a scan occurs more than 1 second after its
scheduled time, the scan is considered missed. If a scan occurs 1 scan period or more after its
scheduled time, then 1 or more scans are considered skipped. Say that a particular scan class
has a period of 2 seconds. If a scan for this class occurs 1.1 seconds after its scheduled time,
then 1 scan has been missed. However, no scans have been skipped because the next scan still
has the opportunity to occur at its scheduled time, which happens to be 0.9 seconds after the
last scan in this case. For scans that have periods of 1 second or less, the above definition of a
missed scan does not make sense. In these cases, scans are considered either hit or skipped.
Since every skipped scan is also considered to be a missed scan, the scan performance
summary should indicate the same percentage of skipped and missed scans for scan classes
with periods of 1 second or less.
The performance summary is logged every 8 hours if the hit ratio (hit ratio = hits / (hits +
misses)) drops below 0.95. The frequency at which performance summaries are printed out
can be adjusted using the /perf command line argument.
Configure I/O Rate Points
I/O Rate Points are PI Points that record 10-minute averages of the number of events per
minute sent to the PI Server. Note that data collected by the I/O Rate Point is the same as the
data that can be collected from the I/O Rate counter with the PI Performance Monitor
Interface, except that the rate reported by the PI Performance Monitor Interface has units of
events per second and the period over which the rate is averaged depends upon the scan rate
of the Performance Monitor Interface. For example, the average will be taken over 10
minutes for a 10 minute scan class.
The I/O Rate Point, however, has the advantage that it can be configured for interfaces on
UNIX and VMS as well as Windows. Note that VMS and UNIX nodes use a separate iorate
program to maintain a list of rate tags. Windows nodes do the calculation within the interface
program. Thus, only one program can increment a Windows event counter.
Use the following procedure to create an I/O Rate Point. On Windows, the following is can
be done automatically from the PI Interface Configuration Utility.
Create a PI Point with the following attributes: PointSource = L; PointType =
Float32; Zero = 0; Span = 3000 (typically, but greater as needed); EngUnits =
Events/Min.
In the script file that starts the interface, use the /ec switch to assign an event
counter between 1-34 or 51-100. This counter must be unique within iorates.dat
(below). For example, to assign an event counter of 5, use this
line:....\interfaces\myint\myint /pa=X /ec=5 /id=1....
Locate the iorates.dat file or, if it does not exist, create it.
On Windows and UNIX, the iorates.dat file is located in the pihome\dat directory.
PI Server System Management Guide Page 111
Chapter 5 - Managing Interfaces
On VMS the iorates.dat file is located in the PISYSDAT directory.
Create an entry in iorates.dat to associate the event counter number with the tag. For
example, sychip01,5 would associate event counter '5' with a tag called sychip01.
Performance Points for Scan Classes
Performance Points for Scan Classes are PI Points that record the total number of seconds
required for an interface scan data from a device and subsequently send the data to the PI
Server. This number is updated after data is sent to the PI Server at the completion of each
scan. The closer the scan time is to 0 seconds, the better the performance. The data has
engineering units of seconds and is recorded to millisecond resolution if a PointType of type
float16, float32, or float 64 is used for the Performance Point. Performance can be configured
for interfaces on UNIX and VMS as well as Windows.
The Windows Performance Counter that corresponds to a Performance Point is the “Scan
Time” counter. Data that is collected from the “Scan Time” counter from the PI Performance
Monitor Interface will have units of milliseconds.
Performance points are an important tool for tuning scan classes, because if a scan takes too
long, it can cause the next scan to be skipped, resulting in data loss. The scan classes may be
tuned by changing the scan frequency, the scan offset, and the number of tags in the scan list.
For more information on configuring scan classes and scan lists, consult the interface-specific
documentation.
Performance points are configured as follows.
Set the extended descriptor (exdesc) to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the identifier that is specified with the /id flag on
the startup command line of the interface. The character string PERFORMANCE_POINT is
case insenstive. The interface_id does not need to be specified if there is only one
copy of an interface that is associated with a particular point source.
Set Location4 to correspond to the scan class whose performance is to be monitored. For
example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of
scan classes.
Set the PointSource attribute to correspond to the /ps flag on the startup command line
of the interface.
Set the PointType attribute to any of the floating-point point types that are supported by
the PI Server.
5.3.14 Configure the PI Interface Status Utility
The PI Interface Status Utility provides a convenient means to distinguish true flatlines in
data from disruptions in data collection. That is, the utility provides a means of indicating to a
user that data from a given interface is stale. Data becomes stale when no fresh data is sent
Page 112
5.3 - Basic Interface Node Configuration
from the interface to the PI Server. For example, stale data can occur under the following
scenarios.
The interface is running but the PI API node cannot send data to the PI Server.
The interface is not running and a system digital state was not written to indicate that
the interface has been shut down. This could happen if the interface crashes.
One PI Interface Status tag is configured per monitored interface, each tag monitors a
watchdog tag collecting data from the interface. If the watchdog tag’s value on the PI
server hasn’t updated after a user specified amount of time, the PI Interface Status
tag’s status changes to a bad digital state status.
If you decide to configure the PI Interface Status Utility, then the utility is always configured
to run on the PI server Node. For more information see the PI Interface Status Utility
documentation.
5.3.15 Configure Auto Point Synchronization
Many interfaces, such as the PI OPC Interface, support Automatic Point Synchronization
(APS). For example, PI Points on the PI Server can be automatically created based on the
points in the OPC server using a configurable set of rules. You must consult your interface
specific documentation to determine whether your interface supports APS. You can also
consult the PI AutoPointSync User Manual.
PI Server System Management Guide Page 113
Chapter 6. MANAGING SECURITY
Typically, PI Server is used in production systems where secure, correct, and reliable
operation is required. For this reason, a number of security mechanisms are available to
protect against both willful and accidental tampering with the system. These include:
Physical Security
Network Security
Operating System Security
PI Server Security
Firewall—Control at the IP Address Level
User Security—User Name and Password—Control for Individuals
Groups—Control for Separate Groups of Workers
Database Security—User, Group, and Access Rights to PI Point, PI User, and PI
Digital State Databases.
Point Security—for Point Attributes and Point Data
Trust-Login Security
6.1 Physical Security
Once a user is logged in, access is granted until the user logs out. It is not unusual for the PI
Server computer to be left unattended while a user is logged in. For this reason, physical
access to the PI Server Home Node should be restricted. It is recommended that the PI Server
computer be located in a lockable, temperature-controlled computer room with an un-
interruptible power supply.
Limiting the use of a single computer solely for data archiving can further enhance security
and reliability. Thus, it is recommended for data collection to be distributed on one or more
PI API or PINet Nodes.
6.2 Network Security
Even if physical access to the PI Server computer is limited, access is available over the
network. Network security is provided through several mechanisms. On TCP/IP, access to a
PI Server System Management Guide Page 115
Chapter 6 - Managing Security
given node is controlled via the host table, domain name server, or DHCP. See your
networking documentation for details.
The network router may also be configured to restrict traffic on specified subnets.
Network setup and security is very important for satisfactory PI System operation. The details
of this are broad, diverse, and beyond the scope of this manual.
6.3 Operating System Security
The PI Server files are protected by the hosting operating system security. On all platforms,
each executable, data file, and directory may independently be given read, write, and execute
access on a per-user or per-group basis.
The System Manager’s account is called “administrator” on Windows systems and “root” on
UNIX systems. Since the System Manager’s account is central to a secure system, it is
imperative that the account password be well chosen (to guard against password guessing),
periodically changed, and known only to a small group of trusted managers.
During installation, all the PI system files are created with the system’s default security, and
are owned by the installing user. This should be the System Manager.
The System Manager may change the ownership and the access rights to these files. This
might be done to assure that only selected users can have any access to the PI system. It is
mandatory to keep full access to the System Manager and to make sure that the PI services
have full access to the PI files. It is best to keep the file ownership as the System Manager. If
tighter security is required, limit the access for group and world, and allow full access to the
System Manager and to the Administrators group.
6.4 PI Server Security
It is typical for a PI System Manager to implement restricted access to the Data Archive and
the Point Database beyond what is provided by physical, network, and operating system
security.
In using PI Server security features, the System Manager is responsible for:
Restricting access via the PI firewall
Creating PI users accounts and groups
Assigning users to groups
Assigning an owner and a group to all databases and setting the access rights. Each
database can have a different owner and a different group.
The default owner and group is piadmin. The default access is “o:rw g:r w:r.” See
the section on Database Security below.
Note: Membership in the piadmin group does not automatically give special
privileges. The piadmin user account does give unlimited access.
Page 116
6.5 - Firewall Security
Assigning owners and groups to points
Setting the access permissions on each point, both for attributes and for data
Assigning owners and groups to modules. Module level security is only accessible
with the System Management Tools, which you can obtain from the OSIsoft support
Web site.
Maintaining the Trust Database for automated logins
6.4.1 Running applications on the system console
The piadmin user account has full privileges on all PI objects. Running any application from
the PI home console grants that application the piadmin status.
In high security environments, piconfig and pisetpass utilities can be forced to perform a
login. This is done with the timeout parameter CheckUtilityLogin set to 1. The user is
prompted to enter a PI username and password before being allowed to proceed when this
feature is enabled.
6.4.2 Running applications remotely
Most PI applications can run remotely and have the -remote set of flags for that purpose.
Login as piadmin grants the user full access to all PI objects.
Caution: Some operations are modifying local files and cannot be done remotely.
Specifically this applies to modifications of the timeout and firewall tables.
6.5 Firewall Security
The first level of PI access security is a firewall maintained by the pinetmgr subsystem. The
firewall allows the PI System Manager to control access to the PI Data Archive at the IP
address level.
The pinetmgr process manages all connections to PI, including subsystem connections and
TCP/IP applications. pinetmgr uses the PI Firewall Database to screen access based on the IP
address.
The database is a list of IP addresses and/or IP address masks. Each entry is associated with
the ALLOW or DISALLOW keyword, and this specifies whether or not pinetmgr completes
the connection request.
piconfig is used to maintain the PI Firewall Database.
Note: Requests from the local host (that is, the same computer on which pinetmgr
is running on) are always allowed.
PI Server System Management Guide Page 117
Chapter 6 - Managing Security
6.5.1 Firewall Database
The Firewall Database is a table with two fields. The first field is an IP address, IP address
mask, or host name. The second field defines whether access for that address, mask, or host
name is allowed.
IP address mask syntax consists of a portion of an IP address and asterisks. An asterisk in an
IP address field matches any number. Here are two examples:
192.168.149.55
192.168.177.*
New connection host names and IP addresses are checked against the Firewall Database in
the following order.
1. If the connection originates from the local host, the connection is always accepted.
2. Firewall Database is searched for an exact match of IP address entry or host name
entry. If an entry is found the search stops and the connection is treated according to
that entry.
3. Firewall Database is searched for a wildcard match, for example, the connecting
address of 192.168.168.22 matches a Hostmask of 192.168.*.*. A matching Disallow
has precedence over an Allow.
Here is an example:
Host/Mask Value
192.168.168.* ALLOW
192.168.168.67 DISALLOW
Only hosts within the 192.168.168.0 subnet are allowed connections. 192.168.168.67 is not
allowed to connect; even though it matches the first host mask.
Modifying the Firewall Database
Piconfig is used to modify the Firewall Database. PI will recognize modifications to the
Firewall Database within 15 minutes, or upon restarting PI, whichever comes first. The
Firewall Database can only be modified from a local piconfig session.
List Attributes and Entries Example
This piconfig example lists all entries:
Piconfig> @table pi_gen,pifirewall
Piconfig> @ostructure hostmask,value
Piconfig> @select hostmask="*"
Piconfig> @endsection
*.*.*.* ALLOW
The listing shows the default firewall setting - all connections are allowed.
Page 118
6.5 - Firewall Security
Limit Connections Example
The next example modifies the Firewall Database to only allow connections from the subnet
123.45.678.0.
Piconfig> @table pi_gen,pifirewall
Piconfig> @mode create,t
Piconfig> @istructure hostmask,value
Piconfig> 192.168.168.*, ALLOW
Disallow Specific Host Example
Host names may also be used to allow or disallow specific host machines. The host name
with domain name must be entered. For example to prevent connections from host “bobcat”
on domain “somewhere.com” the following must be entered:
Piconfig> @table pi_gen,pifirewall
Piconfig> @mode create
Piconfig> @istructure hostmask,value
Piconfig> bobcat.somewhere.com,DISALLOW
Rename an Entry Example
The attribute NEWhostmask is used to rename an entry in the Firewall Database. Here is an
example:
Piconfig> @table pi_gen,pifirewall
Piconfig> @mode list
Piconfig> @ostructure hostmask,value
Piconfig> @select hostmask=*
192.168.168.*,ALLOW
bobcat.somewhere.com,DISALLOW
Piconfig> @mode edit
Piconfig> @istructure hostmask,NEWhostmask
Piconfig> bobcat.somewhere.com, tomcat.somewhere.com
Connection attempts from tomcat will be disallowed. For example if apisnap run from that
host, it would behave as follows:
e:\pi\adm>apisnap tamarind:5450
PI API version 1.2.3.4
Attempting connection to tamarind:5450
Error 2, connecting to tamarind:5450
The pipc.log on host tomcat would have the following entry:
11-Dec-02 16:19:03
D:\piapi\piapi32\apicomm.c> recv: Error: 10054, Unknown error
A look at the PI Server message log, would have a message indicating the connection was not
allowed:
0 pinetmgr 11-Dec-02 16:29:37
>> PInet Refused TCP/IP connection, hostname: tomcat.somewhere.com,
192.168.168.129
PI Server System Management Guide Page 119
Chapter 6 - Managing Security
Modify the Hostmask *.*.*.* Example
If you wish to modify the hostmask *.*.*.*, you must use the following example.
Do not use a wild card selection.
Piconfig> @table pi_gen,pifirewall
Piconfig> @mode edit
Piconfig> @istructure hostmask,value
Piconfig> "*.*.*.*",DISALLOW
To delete the global mask entry use the following:
Piconfig> @mode delete
Piconfig> @istructure hostmask
Piconfig> "*.*.*.*"
Note: To disallow all network connection, make sure you have an entry with
“*.*.*.*”,Disallow, and all other entries are either deleted or set to Disallow.
Note: PIconfig loads the PIfirewall table in memory; all edits are to the in memory
image. Changes are written to disk when the new table is loaded or piconfig is
exited.
6.6 Database Security
Database level security controls access to the various PI server databases such as PI Point and
PI Module Database. PI Server installation sets the owners of these tables to piadmin.
Therefore, only the piadmin account can initially change the settings. After installation,
system administrators can alter the security settings to grant other users modification and
access privileges.
Following a brief description of all the security tokens in the DBsecurity table:
6.6.1 PIDBSEC
Only piadmin can change this token, which allows other users to view/change the
DBsecurity table itself. The PIDBSEC token also controls programmatic access to the
timeout table.
Other users or groups may still be assigned modify privileges in the DBsecurity table but any
changes to this token must be done by piadmin.
6.6.2 PIARCADMIN
Controls access to archive management functions: Archive creation and registration. Archive
shifts. To create new archives or change their attributes the user needs write access to this
token.
Archive backup operations require read access to this token.
Page 120
6.6 - Database Security
6.6.3 PIARCDATA
Controls access to archive data that is not point specific. Access to archive events is
controlled by individual point security. Such general data includes the list of archives
(piartool -al) archive counters, archive activity grid and cache information (piartool -as,
piartool -aag, etc.)
PIartool -aw is also controlled by this token although it does access actual archive events.
6.6.4 PIBatch
Controls the PIbatch database.
6.6.5 PICampaign
Controls the PIcampaign database.
6.6.6 PIDS
Controls the Digital States table. To create or edit sets or states the user needs write access to
this token.
6.6.7 PIHeadingSets
Controls the PIheadingsets database.
6.6.8 PIModules
Controls the creation and modifications of modules in the MDB. Note that each module has
its individual ownership and security specifications. This token controls access to the
database as a whole.
6.6.9 PIPOINT
Control the Point database. As with the MDB, there is individual point security
specifications. This token also controls access to the Point Source table.
6.6.10 PITransferRecords
Controls the creation and modification of transfer records in the MDB.
6.6.11 PIUSER
This token controls several tables: PIusers, PIgroups, PIContext and PItrust.
6.6.12 Individual Subsystem Tokens
Every PI subsystem has now a security token that controls access to that subsystem thread
table and auditing. Initially, this token is owned by piadmin and is not visible in the
Dbsecurity table.
This setting can be modified by adding the appropriate token to the table.
Note: See examples of managing the DBsecurity table in the PIconfig utility chapter
PI Server System Management Guide Page 121
Chapter 6 - Managing Security
6.7 Point Security
Security for points is assigned on two separate levels. Point attributes (zero, span,
descriptor, etc.) have one access level and the point data values (Snapshot and Archive data)
have another. Thus, you can have different owners and different access for point attributes
than for point data.
6.7.1 Point Data Access
When a point is created, the Archive and Snapshot data for the point are assigned a point data
owner and a data group. The data are also assigned various combinations of read and write
access for the data owner, group, and world.
6.7.2 Point Attribute Access
When a point is created, the attributes of the point (such as zero, span, compression
specifications, etc.) may be assigned to a different owner and different group than the point
data.
Note: Changing point ownership or security access is best done separately from
other point editing operations. For example, change the span and the compression
deviation first, and then change the security or the ownership.
There is not any relationship necessarily between the point owner and the point group.
Security Scenario for Users
In a typical facility, a control engineer may be assigned to be the owner of the point attributes
for the instruments that he or she is responsible for configuring. The point owner may be
assigned ownership and read and write access for the data as well.
On the other hand, the control room staff as a group, may be given read and write access to
the data but be limited to read only access for the attributes.
Interfaces usually need read/write access and use a trust login to obtain the privileges of a
particular user. See Trust Login, page 125.
System Manager Privileges
System Manager privileges allow changing access permissions for any point, without regard
to the point attribute owner (ptowner). The manager can override and change any setting,
even if access is restricted.
Note: The user piadmin is a special user. This account is the PI System super user.
It has full access to all databases and database records regardless of security
attribute settings. piadmin is the only user that has this level of privileges.
6.7.3 Access Algorithm
Whenever a user logs in, the following algorithm is used to determine what access to a point
is granted:
Page 122
6.7 - Point Security
1. If the requester is piadmin, then grant full privileges.
2. If the requester is the owner, then grant the privileges assigned to the owner.
3. Otherwise if the requester is a member of the group, then grant the privileges
assigned to the group.
4. If the requester is neither the owner nor a member of the group, then grant the
privileges assigned to the world.
Note: If a requester is a member of a given group, and group permission is more
restrictive than world permission, then world access to the point is granted.
6.7.4 Assigning and Changing Ownership and Access Permissions
Ownership and access permissions are assigned using the piconfig utility. The piconfig Utility
on page 171 explains how to use this utility.
The point owner or data owner can change the security attributes in the Point Database using
piconfig.
Changing the Point Attribute Owner Example
In this piconfig example, open the table and list the point access ownership for a tag. Then
change the owner for this point.
* (Ls) Piconfig> @table pipoint
* (Ls) Piconfig> @ostructure tag, ptowner
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,piadmin
* (Ls) Piconfig> @mode edit
* (Ed) Piconfig> @istructure, tag, ptowner
* (Ed) Piconfig> sinusoid, tom
* (Ed) Piconfig> @mode list
* (Ls) Piconfig> @ostructure tag, ptowner
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,tom
Changing the PtGroup, DataOwner, and DataGroup attributes works similarly.
Changing Point Attribute Access Permissions Example
In this piconfig example, open the table, list the attribute access permissions, and then change
them by adding group and world read permission:
* (Ls) Piconfig> @table pipoint
* (Ls) Piconfig> @ostructure tag, ptaccess
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,o:rw g: w:
* (Ls) Piconfig> @mode edit
* (Ed) Piconfig> @istructure tag, ptaccess
PI Server System Management Guide Page 123
Chapter 6 - Managing Security
* (Ed) Piconfig> sinusoid,o:rw g:r w:r
* (Ed) Piconfig> @mode list
* (Ls) Piconfig> @ostructure tag, ptaccess
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,o:rw g:r w:r
Changing the Point Data Owner and Group Example
To change a point owner and group, open the Point Database and list the DataOwner and
DataGroup for the tag. It shows that the data owner is piadmin and the data group is
piadmin. We want to change the owner to Operator1 and the group to the Operations
Group, so that they can put in lab values.
* (Ls) Piconfig> @table pipoint
* (Ls) Piconfig> @ostructure tag, dataowner, datagroup
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,piadmin,piadmin
* (Ls) Piconfig> @mode edit
* (Ed) Piconfig> @istructure tag, dataowner, datagroup
* (Ed) Piconfig> sinusoid, Operator1, OperationsGroup
* (Ed) Piconfig> @mode list
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,Operator1,OperationsGroup
Changing Data Access Permissions Example
To modify access permissions, open the Point Database and list the permissions for a tag. The
listing below shows that the owner, group members, and world all have read and write access.
* (Ls) Piconfig> @table pipoint
* (Ls) Piconfig> @ostructure tag, dataaccess
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,o:rw g:rw w:rw
Then, for example, modify the permissions by removing world access completely. Now only
the owner and group members can read and write data for this tag:
* (Ls) Piconfig> @mode edit
* (Ed) Piconfig> @istructure, tag, dataaccess
* (Ed) Piconfig> sinusoid, o:rw g:rw w:
* (Ed) Piconfig> @mode list
* (Ls) Piconfig> @ostructure tag, dataaccess
* (Ls) Piconfig> @select tag=sinusoid
* (Ls) Piconfig> @endsection
SINUSOID,o:rw g:rw w:
6.7.5 How to Make All Points Accessible
You can change all the access permissions on all points to world read/write access by
executing the following piconfig commands:
Page 124
6.8 - User Security
@table pipoint
@mode edit
@modify ptaccess=o:rw g:rw w:rw
@modify dataaccess=o:rw g:rw w:rw
@select tag="*"
@endsection
@exit
6.7.6 Security for Default Points in the PI Server
PI is distributed with all default points owned by user piadmin, and assigned to group
piadmin. Although they have the same name, the user and group have no special relationship
to each other. The user piadmin is the PI System Manager, but the group piadmin has no
special privileges.
6.8 User Security
As mentioned earlier, the PI Server has its own user identification and password security.
Client applications may obtain login credentials through a PITrust login, or by passing a user
name and password. A PITrust assigns a user to the login session based on a set of
credentials; this mechanism is discussed in the next section, Trust Login Security.
To log in to the PI Server from one of the PI client applications, such as PI ProcessBook or PI
DataLink, requires a PI user name and password or a valid PITrust. The user is also assigned
to one or more groups of users.
Note: The PI Server does support PI API based logins without supplying a user
name/password or a trust. This is the “default” user access that assigns world rights
to the connection. This feature may be disabled by adding the PITimeout table entry
“DefaultUserAccess” and setting the value 0. A non-zero value or no entry allows
default user access. If default user access is disabled no secure objects may be
accessed regardless of security attribute settings.
When a user accesses the PI Server, after the request passes the PI Firewall, the user ID and
password are used to determine what access to grant.
There are three types of user access: owner, group, and world. Owner access is typically read-
write privileges. Group access is often read-only. World access is by default, none.
Two user accounts are included in the installation of PI Server, piadmin and pidemo. The
piadmin user always has read/write access to all objects regardless of access settings. This is
similar to a super user account in UNIX. The pidemo user has read-only access to all objects.
Do not delete either account. You should establish passwords for both accounts. This does
not affect the trust login process.
6.8.1 Group Database
Access to data or to point attributes is normally granted to groups of users, such as instrument
engineers or operators, rather than to individuals. The PI Group Database is where all
PI Server System Management Guide Page 125
Chapter 6 - Managing Security
PI groups are defined. Every user is a member of one or more groups. This determines their
access to the various PI databases and their individual elements.
Adding a New PI Group
The piconfig utility is used to modify the PI Group Database.
The table name is PIGROUP. The primary key is GROUP.
The following attributes are defined:
GROUP group name
USERS users belonging to this group
DESCRIPTION free text
This piconfig example, opens the table and then lists all entries:
* (Cr) Piconfig> @table pigroup
* (Cr) Piconfig> @mode list
* (Ls) Piconfig> @ostructure group, description,users,...
* (Ls) Piconfig> @select group="*"
* (Ls) Piconfig> @endsection
piadmin,Administration,piadmin
piuser,User,pidemo
ptmaintenance,,
Next, a new group is added. In this example, the description attribute is used to specify the
group’s purpose. User is a read-only attribute.
Note: To add users to groups, use the User Database, NOT the Group Database.
* (Ls) Piconfig> @mode create
* (Cr) Piconfig> @istructure group, description
* (Cr) Piconfig> Section1, Section1 crew chiefs and engineers
*> Section1, Section1 crew chiefs and engineers
* (Cr) Piconfig> @mode list
* (Ls) Piconfig> @ostru group,description
* (Ls) Piconfig> @select group="*"
* (Ls) Piconfig> @endsection
piadmin,Administration
piuser,User
ptmaintenance,
Section1,Section1 crew chiefs and engineers
6.8.2 User Database
The PI User Database is where individual PI users are defined, and assigned to already
existing groups.
Passwords are also stored here. Users maintain their passwords using the pisetpass utility.
The table name is PIUSER. The primary key is USER.
Page 126
6.8 - User Security
The following attributes are defined:
USER user name
DESCRIPTION free text
GROUPS group(s) to which the user belongs
CONTEXT <reserved for future use>
Adding a New PI User
The piconfig utility is used to modify the PI User Database.
This piconfig example opens the table, and then lists all entries:
$ piconfig
* (Ls) Piconfig> @table piuser
* (Ls) Piconfig> @ostructure user, description, groups
* (Ls) Piconfig> @select user="*"
* (Ls) Piconfig> @endsection
piadmin,PI Administration,piadmin
pidemo,PI Demo,piuser
The description attribute is used to specify such information as the user’s full name,
telephone extension, and email address.
To add a new user, specify each group to which the user should be added. The user may be
added to one or more groups.
The default password is the same as the user name. A different password can be assigned
upon creation by appending /password to the user attribute.
* (Ls) Piconfig> @mode create
* (Cr) Piconfig> @istructure user, description, groups, ...
* (Cr) Piconfig> tom/mypassword, [email protected], piadmin, piuser
* (Cr) Piconfig> @mode list
* (Ls) Piconfig> @ostructure user, description, groups, ...
* (Ls) Piconfig> @select user=tom
* (Ls) Piconfig> @endsection
tom, [email protected], piadmin,piuser
Changing PI User Passwords
PI users may change their passwords by using the pisetpass utility in the PI\adm directory. PI
must be running for this utility to work. You must enter the current password in order to
change the password.
You can also set a password to a blank entry by using pisetpass, although this is not
recommended.
The manager can also specify the old password as "!" (exclamation mark) and new password
as required. This bypasses old-password verification when the user running pisetpass as
piadmin.
PI Server System Management Guide Page 127
Chapter 6 - Managing Security
6.9 Trust Login Security
When an application needs access to the PI Archive and does not have an explicit interactive
login, you can configure an automatic Trust Login, using piconfig. This login grants access
of an existing PI user as defined in the PI User Database, based on the current connection
attributes such as the IP address, the machine name or the Operating System user name. Trust
login work by comparing the connection credentials of the connecting application to the trust
records in the Trust Database. Human intervention is not required at the time of connection.
For example, interface processes must start, connect to PI Server, and achieve access rights
with sufficient privileges to write data to the Data Archive. To permit this access, a trust
record can be created in advance on the PI Server to allow the application to assume the
privileges of a valid PI user.
The Trust Database, which is maintained by the Base Subsystem, replaces the Proxy
Database used prior to PI version 3.3. The Trust Database maintains all the functionality of
the proxy mechanism while being more secure. It permits a unified login for PI API and PI-
SDK applications that is consistent with Windows security.
PI-SDK is limited to Windows clients. PI-SDK version 1.1 can use trust logins. Earlier
versions of the PI-SDK have no trust login support.
In the following sections, you will find:
A discussion of connection credentials
How to define trust records in the Trust Database
Evaluating the match between trust records and connection credentials
Examples
6.9.1 Connection Credentials
Trust records may be configured for three types of logins:
PI API applications
PI-SDK applications on Windows 98
PI-SDK applications on Windows
The three types of connection credentials, which are determined by the operating system
login of the connecting application, contain slightly different information.
PI Server determines the connection credentials for PI API applications based on the IP
address, the Host name, and a truncated application name.
PI-SDK applications on Windows 98 assemble their own credentials, based on the IP address,
the IPHost name, and a non-truncated application name.
PI-SDK applications on Windows assemble their own credentials, including Windows
Domain Membership, Domain User Name, IP address and/or host name, and Application
Process Name.
Page 128
6.9 - Trust Login Security
The three types of logins are discussed more fully in the following sections. Trust records are
discussed later, followed by examples.
Connection Credentials for PI API Applications
Connecting PI API applications that call piut_setprocname send a 4-character application
name to the PI Server. The application name is referred to as a “process name” in the PI API
User Guide. The PI Server uses reverse name lookup on the IP packet, to get the sender’s
address, and then looks up the host name.
PI Server can determine the IP Address of the connecting machine through a Reverse Name
Lookup. The name can come from a hosts file on the server machine, or, more commonly,
from a Domain Name Server (DNS).
The 4-character application name is determined by a call by the application to the PI API
routine piut_setprocname. When PI Server accepts a connection, PI Server logs this name
and adds a trailing “E.”
Thus, PI Server can assemble a 3-part set of connection credentials:
Application Process Name (4-characters + E)
IP Address
Host name of the connecting machine
Once PI Server assembles a set of connection credentials, PI Server compares these to each
trust record in the Trust Database. If a match is found, the connection is granted the same
access as the PI User defined in the trust record.
At connection, every PI API-based application attempts to receive a Trust Login
authorization. If the application has a subsequent user/password login, this subsequent login
overrides any trust authorization.
Connection Credentials for PI SDK Applications on Windows 98
The PI-SDK assembles connection credentials for an application internally on the connecting
client machine (Windows 98), including these attributes:
Application process name. This is the executable file name.
IP address
IPHost name
Run pidiag -host on the node where the application runs to view the connection credentials
as retrieved from the local operating system.
Domain and user name information cannot be obtained from Windows 98-based clients; the
connection credentials sent from PI-SDK applications on those operating systems will omit
those fields.
Once a set of connection credentials reach the PI Server, the Server compares these to each
trust record in the Trust Database. If a match is found, the connection is granted the same
access as the PI user identified in the trust record.
PI Server System Management Guide Page 129
Chapter 6 - Managing Security
Connection Credentials for PI SDK Applications on Windows
The PI-SDK assembles connection credentials for an application internally on the connecting
client machine (Windows), including these attributes:
Application process name. This is the executable file name.
IP address
IPHost name
Windows Domain Membership
OS User Name, as logged into the domain
Run pidiag -host on the node where the application runs to view the connection credentials
as retrieved from the local operating system.
Once a set of connection credentials reach the PI Server, the Server compares these to each
trust record in the Trust Database. If a match is found, the connection is granted the same
access as the PI User identified in the trust record.
6.9.2 Defining Trust Records in the Trust Database
The PI Trust Database is a table of trust records. Each record includes a unique name for the
trust, a PI user name, and a combination of at least one of the following: Application Name,
Domain name, IP address, Host, and Operating system user-name. Changes to the Trust
Database take effect immediately. There is no need to restart any PI subsystem.
For more information about the Trust Database, see PI Server Reference Guide, Chapter 2,
PI Server Databases.
The following table shows whether each field is required or optional and whether it may be
used for each type of connection credential.
Field in Req or PI SDK on PI SDK on WinNT
Trust Record Opt. PI API Win98 or greater
Trust name req
AppName opt yes yes yes
Domain opt no no yes
IPAddr1 opt yes yes yes
Netmask opt yes yes yes
Host name opt yes yes yes
OSUser opt no no yes
PIUser req
If IPAddr is used, Netmask must also be configured.
Page 130
6.9 - Trust Login Security
Before you configure records in the Trust Database, set up the entries in the User Database.
For more information, see Adding a New PI User, page 127. When you establish a new trust
record, if the PIUser you include does not already exist in the User Database, the trust record
will be rejected.
Note: Trust record with only Trust name and PIUser are not allowed. Always include
at least one optional entry.
PI Server does not allow two trust records that differ only in PIUser, because this would
create ambiguous trust login results.
Using Piconfig
Piconfig is the only tool that can modify the Trust Database. The key value of the Trust
Database is Trust.
D:\PI\adm>piconfig
* (Ls - ) Piconfig> @tabl pitrust
* (Ls - PITRUST) Piconfig> @?atr
1 - Trust String D: C:
2 - NEWTrust String D: C:
3 - AppName String D: C:
4 - Domain String D: C:
5 - IPAddr String D: C:
6 - IPHost String D: C:
7 - Netmask String D: C:
8 - OSUser String D: C:
9 - PIUser String D: C:
Suppose you wish to create a trust record that permits a PI-SDK application named
piperfmon.exe to connect as a User called Perfmon. You could name the trust record
perfmondefault. Use the following commands to create the record above:
@table pitrust
@mode create
@istru trust, appname, piuser
perfmondefault, piperfmon.exe, perfmon
Additional information about each field is given in the following sections.
Trust
The Trust field is required. It is a record name that must be unique within the Trust Table.
Any alphanumeric combination is acceptable.
AppName
A blank value indicates the match is not required. Otherwise, a case-insensitive match is
required.
For a PI API application to match the AppName, the AppName must be specified as the 4-
character application name plus an “E” at the end.
PI Server System Management Guide Page 131
Chapter 6 - Managing Security
For a PI-SDK application to match the AppName, the AppName must be specified as the
filename of the application executable with file extension and without the directory path.
Domain
Windows Domain name may be used only for trust logins for PI-SDK client applications
running on Windows operating systems. The domain must be the same for the PI Server and
the connecting application.
A blank value indicates the match is not required. Otherwise, a case-insensitive match is
required.
IPAddr and Netmask
The IPAddr and Netmask fields are optional and may be used for either PI API or PI-SDK
applications. This pair of fields allows matching exact machine IP Addresses or specific
subnets.
Setting both fields to 0.0.0.0 indicates that a match is not required. If these fields are left
blank, PI Server will store 0.0.0.0 in both fields in the trust record.
If you specify IPAddr, you must also explicitly provide a Netmask value. Failure to do so
will generate an error.
If you are requiring an exact match on an IP address, specify the Netmask as
255.255.255.255. If you are specifying a Class C subnet, specify the Netmask as
255.255.255.0 and the fourth field of the IPAddr as 0. Examples are given later in this
chapter.
Note: The relationship between IPAddr and Netmask in the Trust Database is the
same as the relationship between Network Destination and Netmask in a TCP/IP
routing table. The class C (24 bit) subnet is just an example—any valid subnet and
IPAddr is supported. If you use this mechanism to allow access to all addresses in a
subnet, you must set the bits corresponding to your subnet to zero.
IPHost
IPHost (sometimes called Host name or machine) is an optional field that may be used for
either PI API or PI-SDK connections. It refers to the name of the connecting machine.
Trust lookups based on IPHost are case-insensitive.
OSIsoft recommends that you verify the IPHost name as discussed below.
For PI API connections, the IPHost name is retrieved by PI Server using the IP address of the
connecting client. The lookup generally requires access to a Domain Name Server (DNS). If
a DNS is not used, the client IPHost name must be defined in the hosts table of the PI Server.
To check this name, ping the client machine from the PI Server. For example, the DNS might
provide JoePC.osisoft.com.
For PI-SDK connections, the IPHost name comes from the information sent by the client to
the PI Server. This name is the short IPHost name. You can confirm this name by running
pidiag -host on the client. For example, the name might be JoePC.
Page 132
6.9 - Trust Login Security
For PI-SDK connections, PI Server verifies domain membership of a client computer by
checking with a domain controller. If this field contains a dollar sign ($), it represents any
machine within the domain.
In the example above, one trust record with an IPHost entry would not match both PI API
and PI-SDK connection credentials.
OSUser
The OSUser (Operating system user) name field is used only for PI-SDK applications
running within a Windows NT or Windows 2000 Domain.
Leaving this field blank indicates a match is not required. Otherwise a case-insensitive match
is required.
Because Domain must be the same for both the PI Server and the connecting PI-SDK
application, it is recommended that you include Domain whenever you want to include
OSUser.
If this field contains a dollar sign ($), it represents any domain user. If the PIUser field in the
trust record is also $, then the OSUser name must match a name in the PIUser database.
If this field contains a dollar sign ($), and the PIUser field contains a specific PIUser, then
all domain users will be granted the access rights of that PI user.
OSUser Names for Services on Windows
Interfaces that run as automatic Windows Services have a default OSUser name on the host
machine. Unless overridden, this name is LocalSystem, which is not a Domain Username. If
you wish to include OSUser name as part of a trust login, you must change the default name
for the interface on the host machine to something that is defined in the Domain user
database.
User Manager in the Administrative Tools does not list the default LocalSystem name.
Instead, follow these steps to set a new OSUser Name.
Windows NT:
1. Open Services in the Control Panel.
2. Select the interface service name and click Startup….
3. In the dialog that appears, select Log on as This Account.
4. Type in a new User Name and Password (twice) or select a User Name from the
dropdown list. Click OK.
Windows 2000/XP:
1. In the Control Panel, open Administrative Tools and then Services.
2. Select the interface service name and click Properties.
3. On the Properties page, select the Log On tab.
4. In the dialog that appears, select This Account.
PI Server System Management Guide Page 133
Chapter 6 - Managing Security
5. Type in the Domain and a User Name and then a Password (twice) or select a User
Name from the dropdown list. Click OK. In the example below, the Domain is
“OSI” and the account User Name is piperfmon. The syntax is OSI\piperfmon.
Figure 6-1. Establishing PI Performance Monitor as a Windows Service
PIUser
Required field. PIUser must be a valid user defined in the PI User Database (with one
exception, described under OSUser). This field specifies the PI Server user whose privileges
will be assigned to the incoming connection when the connection credentials match the
specifications in the trust record.
Although you can choose the piadmin account for PIUser, it is preferable to reserve the use
of piadmin for installation and management of the PI System.
6.9.3 Evaluating the Match Between Trust Records and Connection Credentials
When connection credentials are compared to the Trust Database, each trust record is
considered. If only one record matches exactly, that record will be used to grant login. If
more than one record contains matching fields, then the record that matches most closely will
be used.
If incoming PI API connection credentials do not match any trust record, the application is
granted the default access rights, which is equivalent to having world access to any system
object. Whether points can be accessed depends on the Point Security configured for each
point.
Page 134
6.9 - Trust Login Security
If incoming PI-SDK connection credentials do not match any trust record, then the default
user for that server as configured on the caller’s machine is tried with a blank password. If
that fails, the PI-SDK application is not connected.
Scoring Criteria to Determine the Best Match
When more than one trust record matches an incoming credential, the best match is
determined by weighting the fields and calculating the total for each matching record. PI
Server selects the trust record with the highest score.
Weight Matching Field
163 application name
131 specific OS user
115 any Domain Machine ($)
107 any Domain user ($)
103 IP address
103 IPHost
101 Subnet
100 Domain match
Other Applications on the PI Server Machine
PI API or PI-SDK applications running on the same machine as the PI Server are
automatically established with trust logins at the time PI Server is installed or upgraded. The
PI System Manager may modify these login privileges in the trust table.
Logins through a Node Already Using a Trust Login
If an application using an explicit login connects to PI Server through a network node that is
already using a trust login, the trust login connection is unaffected. A trust login and an
explicit login are independent from each other unless they apply to the same application, in
which instance, the explicit login overrides the trust login.
Interaction with PI Firewall Security
You can block connections from certain addresses through the PI Firewall mechanism. See PI
Firewall Security, page 117, for more information. This takes precedence over trust, i.e. a
connecting application must pass the firewall before trying to get a trust login.
Protection of PI API Application Connections During Backups and Other
Shutdowns
Interfaces and the PI API BufServ rely on successful trust logins because they run as
Services on Windows or as processes on UNIX. PI Server will not allow PI API connections
while Trust Login services are unavailable.
PI Server System Management Guide Page 135
Chapter 6 - Managing Security
For example, whenever the Base Subsystem is shutdown for backups, existing connections
are maintained, but no new PI API connections are accepted. Interfaces and PI API BufServ
will attempt reconnections, typically every sixty seconds. Once the Base Subsystem is
running again, new connections can occur.
6.9.4 New PI Server Installations
PI System Managers who are directly logged into the server machine have unrestricted access
to PI through management utilities as well as PI-SDK and PI API applications. The
installation kit now generates four default entries for a new installation. These can be listed
with piconfig:
* (Ls - PITRUST) Piconfig> @ostr
trust,appname,domain,ipaddr,iphost,netmask,osuser,piuser
* (Ls - PITRUST) Piconfig> @select trust="*"
* (Ls - PITRUST) Piconfig> @ends
!Default_ServerIP!,,,28.62.163.161,,255.255.255.255,,piadmin
!Default_ServerMachine!,,,0.0.0.0,bilbo,0.0.0.0,,piadmin
!Proxy_127!,,,127.0.0.1,,255.255.255.255,,piadmin
!Proxy_localhost!,,,0.0.0.0,localhost,0.0.0.0,,piadmin
The initial entries are two with IP address and two with IPhost name:
The IP addresses are the TCP/IP standard local host address (127.0.0.1) and the
actual IP address of the server.
The IPhost names are the TCP/IP standard name localhost and the actual IPhost
name of the server, in this case bilbo.
These trust-logins allow access for local applications by host name and by address. All local
PI API applications are granted access. The PI System Manager may choose to delete or
modify these trust records, although this is not recommended.
6.9.5 Trust changes on System Startup
The four default trust records listed in PI Server installation section above are re-created or
edited every time the system starts. This guarantees access to all applications running on the
local machine – even if the address changes as a result of a new network card, changes in
network configuration or moving of the PI Server system to another machine. This behavior
also takes care of cluster configuration, when the actual server might be running on a
different machine after failure.
To prevent this behavior, set the following PITIMEOUT parameter:
RecreateServerTrust, 0
6.9.6 Multiple Network Cards
When applications run on machines with multiple network cards, it is unpredictable which
credentials are sent to the server for the trust authorization. It is thus recommended to avoid
such configurations, or create trust records for every IP address on the machine where the
application runs.
Page 136
6.9 - Trust Login Security
6.9.7 Examples
The PI Server compares incoming connection credentials with every Trust Login record.
Each field in a trust record is compared to the corresponding credential field. Every field that
is not blank in the Trust Record must exactly match the passed credentials. Otherwise, the
authorization is not granted. When an authorization is refused for one trust record, the PI
Server continues to search the other records until it has exhausted the possibilities.
You can create explicit individual trust records for each interface or you can group them
according to subnet, host machine, or username. A group of interfaces can share the same
privileges, based on matching a name in the User Database.
As explained previously, if IPAddr and Netmask fields are blank, they appear as 0.0.0.0.
Examples Restricted to Particular Client Applications or Remote Nodes
If a trust record includes only a truncated application name, only a PI API client application
may be authorized. It might be advisable to include an additional restriction on Host name
and/or IP address at the same time.
If a trust record includes only a full application executable file name, only a PI-SDK client
application may be authorized. It might be advisable to include some additional restriction as
well, based on one of the other optional fields.
A remote PI API node or PINet node may be specified by Fixed IPAddress or by IPHost
name.
Example 1. Restricted to a Particular PI API Client Application
The trust record shows only three entries:
Trust record name
AppName = randE
PIUser name = IFGroupA.
An AppName that is four characters and “E” indicates a PI API application. “Rand” is the
truncated name for the Random Interface.
The incoming credentials show:
AppName = randE, which matches the trust record
IPAddr and IPHost, which are blank in the trust record
Therefore, authorization to use the privileges of IFGroupA would be granted to the
connecting Random Interface.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust APIIF1
AppName randE yes AppName randE
PI Server System Management Guide Page 137
Chapter 6 - Managing Security
Trust Record Connection Credentials
Domain Domain
IPAddr 0.0.0.0 IPAddr 192.168.168.121
Netmask 0.0.0.0
IPHost IPHost Suzanne2
OSUser OSUser
PIUser IFGroupA
Example 2. Restricted to Particular PI SDK Client Applications
The trust record shows only 3 entries:
trust record name
AppName = piperfmon.exe
PIUser name = IFGroupB.
The incoming credentials show:
AppName = piperfmon.exe
IPAddr = 192.168.168.121
IPHost = Vaughan
This application name includes the .exe extension, indicating a PI-SDK application. The
application is running on Windows 98, because Domain and OSUser are blank.
Therefore, because AppName is the only specification in the trust record, and the incoming
credentials include a matching AppName, then authorization to use the privileges of
‘IFTypeB’ would be granted to the connecting Performance Monitor Interface.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust SDKIF1
AppName piperfmon.exe yes AppName piperfmon.exe
Domain Domain
IPAddr 0.0.0.0 IPAddr 192.168.168.121
Netmask 0.0.0.0
IPHost IPHost Vaughan
OSUser OSUser
PIUser IFTypeB
Page 138
6.9 - Trust Login Security
Example 3. Specific PI API Application from a Specific Remote Node
The following example trust (GTinterface) allows a specific PI API application (GTin) from a
particular remote IPHost (GT55) and IP address (123.123.123.22) the rights of a PI user
Operator1.
* (Ls - PITRUST) Piconfig> @mode create
* (Cr - PITRUST) Piconfig> @istru
trust,IPHost,ipaddr,netmask,appname,piuser
* (Cr - PITRUST) Piconfig> GTinterface,GT55,123.123.123.22,
255.255.255.255,GTinE,Operator1
Example 4. Any PI API Application from a Specific Remote Node with a Fixed
IP Address
The following example creates a trust record that would match any PI API application from a
remote PI API node or VMS-based PINet remote data collection node with a fixed IP
address.
The trust record would allow the interface from a data source to write to the PI Server, just as
the former Proxy Database did. Assume the entry in the User Database will be IFUser1.
@table pitrust
@mode create
@istru Trust,IPAddr,Netmask,PIUser
MyTrust1,206.79.198.12,255.255.255.255,IFUser1
@endsection
Example 5. Any PI API Application from a Remote Node by Node (IPHost)
Name
The following example creates a trust record that would match any PI API application from a
remote PI API server called Lychee.osisoft.com.
This trust record could be used, for example, to allow an interface to a data source to write to
the PI Server from a PI API remote data collection node or a VMS-based PINet remote data
collection node. This is similar to the old Proxy Database, used before PI Server 3.3. Assume
the user will be IFUser2.
@table pitrust
@mode create
@istru Trust, IPHost, PIUser
MyTrust2,lychee.osisoft.com,IFUser2
@endsection
Examples of PI SDK Client Applications on Windows
The Windows operating systems permit more secure logins, using domain and User name.
Example 6. Domains Match on Windows
The following trust record grants the rights of IFTypeC for any PI-SDK application run on
the Windows Domain OSI. In other words, only Domain is specified. This trust would not
authorize any PI API application or any PI-SDK application on Windows 98.
PI Server System Management Guide Page 139
Chapter 6 - Managing Security
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust NT/2000/XP
AppName AppName piperfmon.exe
Domain OSI yes Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.121
Netmask 0.0.0.0
IPHost IPHost Gerke
OSUser OSUser Suzanne
PIUser IFTypeC
The set of credentials at the right is sent by a PI-SDK application on Windows. This example
has Domain OSI and User Suzanne logged on to machine Gerke at IPaddress
192.168.168.121 running an application called piperfmon.exe.
Note: If you specify either a domain or OSUser in the trust record, the PI Server
must be in the same domain as the connecting application.
In this case, the credentials match the information in the trust record, because only Domain
OSI was specified in the trust record. The application would be granted access to PI as the
user IFTypeC. For greater restriction, you might also specify the application name and/or
OSUser name or IP Addr.
Example 7. Assigning Any OSUser on a Particular Domain to a PI User
Database Entry of the Same Name Using $
For PI-SDK applications, PI Server allows you to assign any OSUser on a particular Domain
to the PI User Database entry of the same name.
Note: If you specify a domain or OSUser in the trust record, the PI Server must be in
the same domain as the connecting application.
Using this feature requires a Trust Record with OSUser set to “$” and PIUser set to “$”.
Other fields are optional. The operating system for the client application must be Windows.
This trust would not authorize any PI API application or any PI-SDK application on
Windows 98.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust MatchUserName
Page 140
6.9 - Trust Login Security
Trust Record Connection Credentials
AppName AppName piperfmon.exe
Domain OSI yes Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.121
Netmask 0.0.0.0
IPHost IPHost Suzanne2
OSUser $ OSUser OSI\Perfmon
PIUser $
In the example above, if the User Database contains a user named Perfmon, the trust will be
granted.
Whenever there is a record in the User Database that matches the entry in OSUser, the trust
is granted.
You could restrict the trust record further by specifying more fields, such as IPHost, subnet,
or AppName.
Example 8. Assigning Any Machine on a Particular Domain to a PI User
Database Entry
A dollar sign in the IPHost field of the trust record causes any machine on the same domain
as the PI Server to be authorized with the same access as the OSI entry in the User Database.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust Matchmachine
AppName AppName piperfmon.exe
Domain Domain OSI
IPAddr 0.0.0.0 IPAddr 192.168.168.12
1
Netmask 0.0.0.0
IPHost $ yes IPHost Suzanne2
OSUser OSUser Perfmon
PIUser OSI
PI Server System Management Guide Page 141
Chapter 6 - Managing Security
Examples for Client Applications Using either PI API or PI SDK
PI API credentials specify AppName truncated and PI-SDK credentials do not. If you want
to build a trust record for both types of applications, do not specify AppName. Use IPHost
or IPAddr.
Using IPAddr and Netmask
The IPAddr and Netmask combination allows more flexibility than an all-or-nothing match.
The IP Address of the connecting machine is bitwise “ANDed” with the Netmask and then
compared to the IPAddr field of the Trust Record.
It is a match if the “ANDed” result matches the IPAddr field of the Trust Record. This
allows granting Trust Logins based connecting machine subnets, similar to IP Routing
algorithms.
Remember that you can use additional fields in the trust record to further limit access.
The following table gives some IPAddr/Netmask combinations and evaluation results:
Row Trust IPAddr Trust Netmask Machine Result of AND Trust IPAddr
IPAddr between Trust and result of
Netmask and AND match?
Machine IPaddr
A 0.0.0.0 0.0.0.0 192.168.168.121 0.0.0.0 Yes
B 192.168.168.0 255.255.255.0 192.168.168.121 192.168.168.0 Yes
C 192.168.168.0 255.255.255.0 192.168.175.004 192.168.175.0 No
D 192.168.168.176 255.255.255.240 192.168.168.178 192.168.168.176 Yes
E 192.168.168.176 255.255.255.240 192.168.168.121 192.168.168.112 No
F 192.168.168.22 255.255.255.255 192.168.168.22 192.168.168.22 Yes
G 192.168.168.22 255.255.255.255 192.168.168.20 192.168.168.20 No
In Row A, the trust IPAddr and the Trust Netmask are blank. The “ANDed” result is also
blank; these fields are ignored in the matching process.
In Row B, when you combine Trust Netmask with Machine IPAddr, you get a 0 in the last
field; this matches the Trust IPAddr. Use this when you want to authorize any PC on a
subnet. See Example 8. In Row C, the third field does not match (168, 175).
In Row D, the “ANDed” result of 240 and 178 is 176, and thus, matches the Trust IPAddr. In
Row E, the “ANDed” result process does not match. This type of Netmask restricts matching
to certain IP addresses on a network subnet.
Row F and G illustrate the situation described in Example 9. Using IPAddr and Netmask to
Specify a Particular Address.
Example 9. Using IPAddr and Netmask to Specify a Particular Address
You can specify a trust record with an explicit machine address, as shown below, and any
connecting application at that machine will be granted a trust login. This example is shown
Page 142
6.9 - Trust Login Security
above in Row F. Similarly, the results of the credential IPAddr and the Netmask in Row G is
not an exact match for the trust IPAddr and the trust is not authorized.
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust Matchmachine
AppName AppName piperfmon.exe
Domain Domain OS*I
IPAddr 192.168.168.121 yes IPAddr 192.168.168.121
Netmask 255.255.255.255
IPHost IPHost Suzanne2
OSUser OSUser Suzanne*
PIUser OpsPC15
* only included for PI-SDK applications
Example 10. Specifying a Subnet
This example limits the login trust to a domain (OSI) and a specific Class C IP subnet:
Trust Record Connection Credentials
Field Name Field Value Match? Name Value
Trust SubnetC1
AppName AppName piperfmon.exe
Domain Domain OSI*
IPAddr 192.168.168.0 yes IPAddr 192.168.168.121
Netmask 255.255.255.0
IPHost IPHost Suzanne2
OSUser OSUser Suzanne*
PIUser SubnetC1User
* only included for PI-SDK applications
This Trust Record grants the rights of SubnetC1User for any application run on any machine
on the Windows Domain OSI as long as the machine is in the Class C subnet 192.168.168.0.
PI Server System Management Guide Page 143
Chapter 6 - Managing Security
PI SDK Application on a Subnet
The following example allows PI-SDK application with a name MG.exe running in domain
plant1 and on any machine from the subnet 123.125.125.0 with a name MGr and logged with
a user named interface the access rights of PI user Mginter.
* (Cr - PITRUST) Piconfig> @istru trust,appname,domain,IPaddr,netmask,
IPHost,osuser,piuser
* (Cr - PITRUST) Piconfig> MGinterface, MG.exe, plant1, 123.124.125.0,
255.255.255.0, MGr0,INTERFACE, MGinter
6.10 Resolving Ambiguities
Example 11. Resolving Ambiguities—Closest Match for an IPAddr
A connecting application is granted the trust login that matches it most closely.
For example, in the following comparison chart, an application is running on host PIclient1
with IP address 123.123.123.3.
A trust record called Operator1 is defined for IPhost = PIclient1, IPaddr = 123.123.123.3,
and PIUser = Operator1.
Another trust record called Operator2 is defined for IPHost = PIclient1, IP address =
123.123.123.0, and PIUser = Operator2.
Trust Records Connection Credentials
Field Name Field Value Field Value Name Value
Trust Operator1 Operator2
AppName AppName piperfmon.exe
Domain Domain OSI
IPAddr 123.123.123.3 123.123.123.0 IPAddr 123.123.123.3
Netmask 255.255.255.255 255.255.255.0
IPHost PIclient1 PIclient1 IPHost PIclient1
OSUser OSUser perfmon
PIUser Operator1 Operator2
Operator1 Trust Record matches the connection credentials exactly.
Operator2 also matches, because the result of ANDing the Netmask and the Connection
Credentials IPAddr gives 123.123.123.0, which matches the Operator2 Trust Record IPAddr.
The application will be granted the rights of Operator1, not Operator2, because the combined
IPAddr/Netmask results match the Operator1 record more closely.
Page 144
6.10 - Resolving Ambiguities
Example 12. Resolving Ambiguities—Scoring System
In the event of multiple valid trust records, PI Server applies a scoring equation. In the
example below, a set of credentials is compared to two trust records.
Trust OSUsermatch has a blank in the IPHost field, HW6 in the OSUser field, and User6 in
the PIUser field.
Trust IPHostmatch has crabapple in the PIHost field, a blank in the OSUser field and User7
in the PIUser field.
Trust Records Match? Connection Credentials
Field Name Field Value Field Value Name Value
Trust OSUsermatch IPHostmatch
AppName AppName piperfmon.exe
Domain Domain OSI
IPAddr 0.0.0.0 0.0.0.0 IPAddr 123.123.123.3
Netmask 0.0.0.0 0.0.0.0
IPHost Crabapple yes IPHost Crabapple
OSUser HW6 yes OSUser HW6
PIUser User6 User7
The PI Server weighting factor for the OSUser field is higher than the weight of the IPHost
field. Consequently, the connecting application would receive the trust login for User6.
Example 13. Resolving Ambiguities—Other Problems
Sometimes ambiguities in trust records may be created inadvertently. For example, assume
the following trust record AddedFirst exists, pointing to UserA in the User Database:
Field Name Field Value
Trust AddedFirst
AppName
Domain OSI
IPAddr 192.168.168.0
Netmask 255.255.255.0
IPHost
OSUser
PIUser UserA
PI Server System Management Guide Page 145
Chapter 6 - Managing Security
Now suppose you add another trust record called NewNetmask and point to UserB like this:
Field Name Field Value
Trust NewNetmask
AppName
Domain OSI
IPAddr 192.168.168.0
Netmask 255.255.255.240
IPHost
OSUser
PIUser UserB
The PI Server would accept the NewNetmask Trust Record because the two NetMask fields
are different.
Notice that the IPAddr in both records has “0” in the last field.
The first Netmask has a 24-bit Netmask, the second has a 28-bit Netmask. Unfortunately, any
match with NewNetmask would also match with AddedFirst.
There is no predictable rule as to which trust will be assigned if ambiguous Trust Records are
created in the database.
Page 146
Chapter 7. MOVING PI SERVERS
PI Servers are designed for platform independence. All the databases and tables are stored in
a format that allows you to move a Server to a different computer or a different location on
the same computer. The programs and scripts themselves are platform-specific so a proper
installation is needed for any host platform.
This chapter provides the information necessary to move a Windows- or UNIX-based PI
Server. To move a VMS-based PI Server, you must first migrate it to either Windows or
UNIX. Refer to the OSIsoft support Web site for details on migrating VMS Servers.
These instructions assume that the PI Server System that is being moved is release 3.2 or
greater. If your PI System is an earlier release, upgrade it before continuing.
7.1 Preparation
Before attempting to move a PI Server, ensure that the PI Server and all related processes
have been stopped. Make a backup copy of the entire PI Server and all of the archive files (if
they do not reside in the PI directory.) On UNIX hosts, back up the /etc/piparams.default file.
On Windows hosts, back up the Registry.
7.2 Different Computer
To move a PI Server onto a different computer, you install the PI Server software on the new
computer and then copy the databases, tables, and archives over to the new PI Server. This
section describes the steps for moving the PI Server and explains which files and directories
you need to copy to the new Server.
This section refers to the original PI Server as the source and to the new PI Server as the
target. The pihome directory is the top-level PI directory (C:\PI\ for example). These
instructions use the backslash (\) for path names, but the steps are the same for all platforms.
Before starting the procedure below determine if there are any tags with a Snapshot value
before the start time of the Primary Archive. Set the shutdown attribute to 0 for these tags.
When the target PI system is first started, setting shutdown to 0 for these points will prevent -
11043 errors because only the primary archive will be registered.
To move the PI Server:
1. Perform a new installation on the target (new) host using the same release and build
number as the source (original) host’s PI Server. Select the default archive sizes
PI Server System Management Guide Page 147
Chapter 7 - Moving PI Servers
during the installation, because you delete them anyway, in one of the following
steps. Ensure that the new PI Server is functional before you continue to the next
step.
2. Identify the Primary Archive on the source PI Server using the administrative utility
pidiag -ad or piartool -al or the Archive Manager plug-in in the PI System
Management Tools (SMT).
3. Stop both the source and target PI Servers.
4. Copy the entire pihome/dat directory from the source PI Server to the pihome/dat
directory of the target PI Server, excluding the following files:
• Pisubsys.cfg
• PISysID.dat (you can include PISysID.dat if you are moving the server to a
computer with the same host name and IP address as the original server.)
• Archive files
This overwrites most of the files in the target PI Server dat directory.
5. Copy the entire pihome/log directory from the source PI Server to the pihome/log
directory of the target PI Server.
6. Copy the pipeschd.bat file from the pihome\bin directory of source PI Server to the
pihome\bin directory of the target PI Server.
7. Delete the target PI Server’s archives and copy the source PI Server’s primary
archive to the desired location on the target PI Server.
8. On the target PI Server, update the archive location file (piarstat.dat) by running the
pidiag -ar utility. Specify the full path to the copied Primary Archive when
prompted.
9. Restart the new PI Server and verify that it is working correctly.
10. Move and register the remaining archive files. This should be done while the new PI
Server is running.
11. Move or install any platform or site specific interfaces or programs as needed.
12. Back up the new PI Server once it is stable.
7.3 Same Computer
Moving the install location of a PI Server is nearly identical to moving from one computer to
another. The procedures are identical except for the following steps:
1. Isolate your PI Server from the network. This will force buffering of data on the
interface nodes.
2. Run piartool -qs monitor until the Event Queue is empty.
3. Run piartool -al redirecting the output to a text file. This is a record of all registered
archives.
Page 148
7.3 - Same Computer
4. Shut down your PI Server.
5. Save your dat directory, log directory and archives to a safe location.
6. Uninstall the PI Server.
7. Follow the instructions in the following sections; except, skip step 2 since this was
already done in step 3 above.
PI Server System Management Guide Page 149
Chapter 8. COPYING A PI SERVER
If you want to create a second PI Server by moving an existing PI Server as described in
Moving PI Servers on page 147, the server ID on the destination server must be deleted and
recreated so that the second server has a unique ID.
8.1 Understanding the Server ID
All PI Servers are identified by a ServerID. The Server ID is stored in the binary file
PI\dat\PISysID.dat. The ID is used to uniquely identify a PI Server; basically, it augments the
PI Server's host computer's name. For example, a PI Point may only be uniquely identified by
including all four of these parameters:
Server ID
Computer Name (the computer name is the handle as set in the Known Servers table)
Tag Name
Point ID
Originally the PI System ID was assigned at system installation with an algorithm the used
the computer name to generate a 32-bit integer. This approach could create ambiguous IDs—
two unique computer names could generate the same ID. PI Servers with 32-bit IDs must
continue to use these IDs otherwise client applications that reference the ID may not be able
to resolve resources.
PI Servers installed starting with version 3.3.?.? use GUIDs for the System ID. This ID is
assigned at PI Server installation and is guaranteed to be unique.
Note: The 32-bit ID is still generated on the PI Server for legacy purposes. For
example, PI API based applications may only support the 32-bit ID.
8.2 Situations where Server ID must be Addressed
The Server ID is only an issue when you move or copy the PI Server to another computer.
There are three basic scenarios:
1. Moving to a new host computer and retiring the original computer as described in
Moving PI Servers on page 147. In this case the Server ID file is copied to the new
computer as part of the moving process. No other action is needed.
PI Server System Management Guide Page 151
Chapter 8 - Copying a PI Server
2. Copying the PI Server to a new machine where the copy may be accessed
simultaneously with the source PI Server. In this case, although the data may be
nearly indentical, the two PI Servers must be assigned unique ID values. Therefore,
the copied PI Server must have a Server ID different from the source PI Server. This
is kept unique by not overwriting the Server ID file on the destination server; that is,
keep the Server ID file that was created on initial PI Server installation on the
destination server. In this scenario, the two servers are unique: ProcessBook displays
that target the source PI Server will not resolve against the destination server.
3. Copying the PI Server to a new machine that will not be accessed simultaneously
with the source PI Server. This scenario is used when it is desirable to access the
destination PI Server with existing displays, etc., created against the source PI Server.
Client applications that attempt to access both machines will have problems: the PI-
SDK knows the server table will be ambiguous. Attempting to do this is not
supported and will result in confusion.
In summary:
Copy the source PI Sever ID file to the destination PI server if the source PI Server is
being retired.
Leave the destination PI Server ID file in place if the source and destination PI Server
may be accessed simultaneously.
Note: The existence of two PI Servers with the same ID is problematic. This
approach should only be used in special circumstances. Specifically, attempts to
access both servers from the same client machine will result in confusing problems.
Page 152
Chapter 9. MERGING TWO PI SERVERS
The offline archive utilities can be used to merge two PI Server Systems. A merge is used
when a PI Server System is to be retired and the data from the retired system is preserved in
an existing system. The basic steps and an example merger follow.
9.1 Server Merging - Procedures
Transfer Points
Install all points from the retired system onto the destination system.
Digital State Table and Digital Tags
Make all changes to the digital state table before making any changes to the points.
Review the retired system digital-state table. Use piconfig to extract any missing digital-sets
and create them on the target system. If a set from the retired system already exists in the
target system, make sure both have the same states.
Digital points created on the target system are assigned a digital set by name.
During archive conversion, only the offset is preserved, thus the data is interpreted according
to the point’s current digital-set.
Point Editing / Creation
Use piconfig to dump all required point attributes from all points to be merged to the
destination system. Required point attributes are interface specific. If in doubt, dump all point
attributes for all points, except the PointID and RecNo attributes. Remember that point
attributes depend on the point class, therefore, not all points have the same attributes.
All points do not have to be merged - just the points whose history is to be preserved.
Tags names issues must be addressed. If a tag name is the same on both systems, for
example, sinusoid, which is a standard simulation point, no special steps are required. If the
tags are not the same a rename is required. Normally the conflicting retired tag is renamed;
although either tag may be renamed. Required renames should be done before starting the
merger.
On the destination system, use piconfig and the retired system's point listing to create the
points.
PI Server System Management Guide Page 153
Chapter 9 - Merging Two PI Servers
PI Batch Subsystem Considerations
Special steps are necessary for systems running pibatch. Batches are stored in automatically
created points. The points are in the format of pibaN, where N is an integer unique to the
unit. These points must not be converted to the destination system.
Batches must be moved independently of the points. The piconfig utility may be used to
move the batches. First, use piconfig to dump all existing batches and unit configuration.
Unit name conflicts between the two systems will require renaming the references to the
conflicting units in the piconfig dumps.
Use the PIBatch unit table listing to create the units on the destination system. The batches
are created after the archives are converted. All pertinent unit configuration information must
be listed.
Details of these steps are shown below in the example merger.
Create a Point ID Conversion Table on the Retired System
Converting the retired archives to the destination system requires mapping the retired record
numbers to the destination system record numbers. The mapping is established with a text
file, which relates the retired system PointIDs, RecNos, and tags. The following piconfig
script creates the input for the conversion table:
@table pipoint
@ostr pointid,recno,tag
@select tag=*
@ends
@exit
Running this script with output redirected to a file is all that is required. This example
assumes all tags are being merged. If all tags are not merged, edit the output file or use a tag
selection of other than "tag=*".
The ID conversion input file must only have entries of the format:
pointid,recno,tag
Any other entries, such as comments, are not allowed and will cause errors. Therefore, edit
the file to remove any piconfig informational messages at the end of the file. Also, a new line
must follow the last entry.
If PIUnitBatches are being migrated, rename the UniqueID’s of the old PIUnit to the
UniqueID’s of the destination PIUnit as described above.
Cutover Interfaces
At this time, interfaces feeding data to the retired system should be stopped. If appropriate,
restart the interfaces pointing to the destination system. If the interfaces are restarted against
the destination system, check interface output for errors--address any problems before
proceeding.
On the retired system run pishutev to put shutdown events into the Snapshot. This will force
the Snapshot value into the Archive.
Page 154
9.1 - Server Merging - Procedures
Force a Shift on the Retired System
Force a shift on the retired system. This puts a clean end time on the retired system, and
makes management of the Archive merge easier.
Run piartool -al to get a listing of all archives. Save this listing for reference when
converting the archives.
At this point the retired system is no longer needed. Shutdown the retired system. Move all
retired archives to the destination system. For Unix systems this might mean using binary ftp.
Create Binary ID Conversion Table on Destination System
The text file created in the above step is the source for creating the ID conversion table. This
table maps the tags from the old system into the new one. The piartool utility creates the ID
conversion table; the syntax is:
piartool -idci <full path to text file>
-idco <full path to binary file to be created>
This command is run on the destination system.
Convert the Retired Archives
The offline archive features of piarchss are used to convert the archives from the retired
system. The syntax is:
piarchss -id <id conversion binary file>
-if <retired archive path>
-of <converted archive path>
There are a few things to consider when converting archives. If the retired system and
destination system were running simultaneously, there will be overlapping archive dates.
Overlapping archives must be combined using offline archive techniques. Also, by default,
offline output archives are created as dynamic type. That is, they are not shiftable. The "-f"
argument may be used to force output archives to a fixed size.
Convert one archive and register it. If necessary, unregister any overlapping existing archives.
Use piconfig or a client product to view data from this archive. Compare the data with the old
system and assure correct conversion before proceeding with other archives.
Proceed with the archive processing. This may be time consuming; especially if there are
many overlapping archives. Register and view archives as they are completed.
Add Batches from Retired Systems
The text file from the PI Batch dump is now input via piconfig into the system. If all archives
were merged, there should be an archive on line to receive the batch. If not all archives were
migrated, batches for those dates will not be created.
Details of this step are shown in the following example.
PI Server System Management Guide Page 155
Chapter 9 - Merging Two PI Servers
9.2 Server Merge Procedure - Example
The following example retires a small NT Intel PI System and merges it with an existing
HPUX PI System. Both systems consist of example points provided with installation. The
tags on the retired system were edited to create unique tags.
Here is the archive list and point list of each system before starting the merge:
Retired System
BA:Active.1
BA:CONC.1Retired
BA:LEVEL.1Retired
BA:PHASE.1Retired
BA:TEMP.1Retired
batchid-1Retired
CDEP158Retired
CDM158Retired
CDT158Retired
piba1
pipe:sine2Retired
pipe:sine2tRetired
pipe:sine3Retired
pipe:sine4Retired
pipe:sine5Retired
pipe:sineRetired
pitot1Retired
pitot2Retired
pitot3Retired
pitot4Retired
pitot5estRetired
pitot5rampRetired
pitot5Retired
pitot5runRetired
pitot6countRetired
pitot6timeNERetired
pitot6timeRetired
pitot_1Retired
pitot_avgRetired
pitot_maxRetired
pitot_minRetired
productid-1Retired
sin:h2Retired
sin:hourRetired
SINUSOIDRetired
SINUSOIDURetired
t_minRetired
t_state1Retired
Archive: D:\PI\dat\piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: D:\PI\dat\piarch.002
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Page 156
9.2 - Server Merge Procedure - Example
Record Size: 1024 Count: 2048
Offsets: Primary: 39/512 Overflow: 2025/2048
Start Time: 2-Mar-98 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-98 12:50:27
End Time: 2-Mar-98 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-98 12:50:27
Backup Time: Never
Destination System:
BA:ACTIVE.1
BA:CONC.1
BA:LEVEL.1
BA:PHASE.1
BA:TEMP.1
batchid-1
CDEP158
CDM158
CDT158
piba2
pipe:sine
pipe:sine2
pipe:sine2t
pipe:sine3
pipe:sine4
pipe:sine5
pitot1
pitot2
pitot3
pitot4
pitot5
pitot5est
pitot5ramp
pitot5run
pitot6count
pitot6time
PI Server System Management Guide Page 157
Chapter 9 - Merging Two 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: /opt/PI/dat/piarch.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21
Version: 4 Path: /opt/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-98 12:21:11
End Time: Current Time
Backup Time: Never
Archive: /opt/PI/dat/piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21
Version: 4 Path: /opt/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: /opt/PI/dat/piarch.003
Page 158
9.2 - Server Merge Procedure - Example
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21
Version: 4 Path: /opt/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
Start Time: Current Time
End Time: Current Time
Backup Time: Never
Point and PI Batch Configuration on Retired System
Notice that the tag BA:Active.1 on the retired system conflicts with destination system. This
tag must be renamed before proceeding. This tag is also used as the batch active tag for
Reactor1. When adding the unit Reactor1 to the destination system, this change must be
accounted for. Here's the dialog of the tag rename:
D:\PI\adm>piconfig
* (Ls - ) PIconfig> @table pipoint
* (Ls - PIPOINT) PIconfig> @mode edit
* (Ed - PIPOINT) PIconfig> @istr tag,newtag
* (Ed - PIPOINT) PIconfig> ba:active.1,ba:active.1Retired
*> ba:active.1,ba:active.1Retired
Also, the tag piba1 exists on both systems. This is a PI Batch point and must not be migrated.
In this example, the original piconfig files used to create the points on the retired system are
used to create the points on the destination system. If original piconfig files do not exist for
the retired system, use piconfig to dump appropriate data.
The retired system has one PI batch unit that will be merged. The unit is a demo unit, but will
be treated as a unique unit in this case; it will require some modification to prevent conflicts
with the demo unit on the destination system.
First step is to dump the unit configuration to a text file:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @?atr
1 - UnitName (D) (C)
2 - NEWUnitName (D) (C)
3 - ActiveTag (D) (C)
4 - ActiveType (D) pulse (C)
5 - BIDExpr (D) (C)
6 - DataAccess (D) o:rw g:r w:r (C)
7 - DataGroup (D) piadmin (C)
8 - DataOwner (D) piadmin (C)
9 - Description (D) (C)
10 - EvalDelay (D) 0 (C)
11 - ProdExpr (D) (C)
12 - UnitAccess (D) o:rw g:r w:r (C)
13 - UnitGroup (D) piadmin (C)
14 - UnitOwner (D) piadmin (C)
* (Ls - PIBAUNIT) PIconfig> @Ostr
unitname,activetag,bidexpr,description,prodexpr
* (Ls - PIBAUNIT) PIconfig> @ends
PI Server System Management Guide Page 159
Chapter 9 - Merging Two PI Servers
*piconfig Err> Wild-card specs. missing, default to '*'...
Reactor1,ba:active.1,'batchid-1',Reactor 1,'productid-1'
For this unit, several attributes are set to default values; only attributes unique to this unit are
dumped. Since this unit's configuration conflicts with a unit on the destination system the
attributes require editing before input. Here's the content of the input file after editing:
@table pibaunit
@mode create
@istr unitname,activetag,bidexpr,description,prodexpr
Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'", "Retired
Reactor 1","'productid-1Retired'"
Create ID Conversion Text File
The ID conversion text file is created on the retired system by running the following piconfig
script:
@table pipoint
@ostr pointid,recno,tag
@select tag=*
@output retiredidconv.txt
@ends
@exit
D:\PI\adm>type retiredidconv.txt
9,9,ba:active.1Retired
8,8,BA:CONC.1Retired
7,7,BA:LEVEL.1Retired
10,10,BA:PHASE.1Retired
6,6,BA:TEMP.1Retired
11,11,batchid-1Retired
5,5,CDEP158Retired
4,4,CDM158Retired
3,3,CDT158Retired
13,13,piba1
34,34,pipe:sine2Retired
35,35,pipe:sine2tRetired
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
Page 160
9.2 - Server Merge Procedure - Example
26,26,pitot_avgRetired
27,27,pitot_maxRetired
28,28,pitot_minRetired
12,12,productid-1Retired
16,16,sin:h2Retired
14,14,sin:hourRetired
1,1,SINUSOIDRetired
2,2,SINUSOIDURetired
15,15,t_minRetired
17,17,t_state1Retired
The text file requires modification. The PI Batch tag, piba1, cannot be migrated and
therefore, must be removed. Here are the contents after the edit:
9,9,ba:active.1Retired
8,8,BA:CONC.1Retired
7,7,BA:LEVEL.1Retired
10,10,BA:PHASE.1Retired
6,6,BA:TEMP.1Retired
11,11,batchid-1Retired
5,5,CDEP158Retired
4,4,CDM158Retired
3,3,CDT158Retired
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
PI Server System Management Guide Page 161
Chapter 9 - Merging Two PI Servers
Dump the PI Batch Database
As mentioned above, batches must be merged with piconfig scripts. Start by dumping all
batches to be merged. To do this first dump all the units to a text file, then use this text file to
dump all desired batches. In this example, all batches will be merged. Here is the script and
procedure for dumping the units:
@table pibaunit
@ostr unitname
@sele unitname=*
@output unitlist.txt
@ends
@exit
Edit the text file to include the start time and end time for each unit and add an exit command
to the end. In this example, there is only one unit, and all the batches will be merged;
therefore setting a very wide start and end time ensures that all batches are dumped. Here's
the file after editing:
D:\PI\adm>type unitlist.txt
Reactor1,*-1000d,*
@exit
The script and procedure for dumping the batches follows:
D:\PI\adm>type pibatchlist.dif
@table pibatch
@mode list
@ostr unitname,bid,prodid,starttime,stoptime
@ostr ...
@istr unitname,searchstart,searchstop
D:\PI\adm>piconfig input pibatchlist.dif input unitlist.txt >
pibatchlist.txt
@exit
D:\PI\adm>type pibatchlist.txt
*> Reactor1,*-1000d,*
Reactor1,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20
Reactor1,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20
Reactor1,XYZ3,Green,3-Mar-98 12:24:23,12:44:00
* End Repeat...
* (Ls - PIBATCH) PIconfig> PIconfig 1 Data lines
8 Command lines
0 Records in error...
3 Records Listed
Pibatchlist.txt requires editing before input to the destination system. The unit name,
Reactor1 must be changed to the migrated name Reactor1Retired. Also, the piconfig creation
commands can be added to the top of the file. Here is the file after the edits:
@table pibatch
@mode create
@istr unitname,bid,prodid,starttime,stoptime
Reactor1Retired,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20
Reactor1Retired,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20
Page 162
9.3 - Shut Down the Retired System
Reactor1Retired,XYZ3,Green,3-Mar-98 12:24:23,12:44:00
9.3 Shut Down the Retired System
At this point we have piconfig text files of the point and batch databases and the ID
conversion text file. This is required to reproduce the point and batch configuration on the
destination system. Before shutting down the retired system, stop the interfaces and other data
sources, write shutdown events to all the points, and force a shift.
In this example, all interfaces are on the localhost rather than a remote node. On your system,
make sure any API node and PINet node interfaces are shut down. Also shut down
PI Totalizer, PI PE Scheduler, and PI Batch Subsystems.
Before forcing the shift, make sure an empty archive is available for the shift.
Here is the dialog from these steps:
D:\PI\adm>pisrvsitestop
D:\PI\adm>echo Stopping Site Specific PI System Services...
Stopping Site Specific PI System Services...
D:\PI\adm>..\interfaces\rmp_sk\rmp_sk -stop
Stopping service rmp_sk
rmp_sk Stopped Successfully.
D:\PI\adm>..\interfaces\random\random -stop
Stopping service random
.
random Stopped Successfully.
D:\PI\adm>net stop pibatch
The PI Batch Subsystem service is stopping....
The PI Batch Subsystem service was stopped successfully.
D:\PI\adm>net stop pitotal
The PI Totalizer service is stopping...
The PI Totalizer service was stopped successfully.
D:\PI\adm>net stop pipeschd
The PI Performance Equation Scheduler service is stopping..
The PI Performance Equation Scheduler service was stopped successfully.
D:\PI\adm>..\bin\pishutev -verbose
Shutdown input file: D:\PI\dat\shutdown.dat.
Shutdown events will be written for tag mask *
Point attributes:
shutdown, 1
Shutdown Events at 3-Mar-98 11:04:09 sent for 37 Points
Service Manager requested shutdown of pishutev
D:\PI\adm>piartool -fs
Attempting to force an archive shift...
An archive shift has been initiated on the server.
Completion time will vary from a few minutes to hours,
depending on the machine and archive size. During this
time the archive subsystem will be unavailable and the
PI System should not be stopped until the shift is
complete.
PI Server System Management Guide Page 163
Chapter 9 - Merging Two PI Servers
The status of the shift can be found in the message
log using pigetmsg.
The current primary archive is D:\PI\dat\piarch.002
and the target archive for shift is d:\pi\dat\piarch.004
The current primary archive has 2048 records
and the target archive for shift has 2048 records.
D:\PI\adm>pisrvstop
At this point the retired system is no longer required. All the text files must be copied to the
destination system. The archives to be merged must be copied to the destination system in
binary mode. In this example, the following archives will be merged:
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-98 12:51:41
End Time: 3-Mar-98 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-98 12:50:27
End Time: 2-Mar-98 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-98 12:50:27
Backup Time: Never
9.3.1 Add Retired Point Configuration to Destination System
This is just a matter of inputting the scripts into piconfig. In this example, all tag
configuration is in one file called retired.dif. The following command executes this script,
only a portion of the output is shown:
$ piconfig < retired.dif
*> SINUSOIDRetired, 12 Hour Sine Wave, , float32, 0.0, 100.0, 50.0, 0, R, 2, 1, 0,
*> SINUSOIDURetired, UTC 12 Hour Sine Wave, , float32, 0.0, 100.0, 50.0, 0, R, -2, 1, 0,
*> CDT158Retired, Atmospheric Tower OH Vapor, DEG. C, float32, 50.0, 200.0, 140.0, 0, R,30
, 1, 1,
*> CDM158Retired, Light Naphtha End Point Control, STATE, digital,3.0, 4.0, 3.0, 1, R, 3,
1, 1,
*> CDEP158Retired, Light Naphtha End Point, ,int32,0.0, 400.0, 290.0, 0, R, 5, 1
Page 164
9.3 - Shut Down the Retired System
9.3.2 Add PI Batch Unit Configuration to Destination System
The example has unit configuration in the text file retiredunit.dif. Use piconfig to input this
file:
$ piconfig < retiredunit.dif
*> Reactor1Retired,ba:active.1Retired,"'batchid-1Retired'", Retired
Reactor 1,"'
productid-1Retired'"
PIconfig 1 Data lines
3 Command lines
0 Records in error...
1 Records Created
9.3.3 Convert the Archives
Converting the retired systems archive requires the binary ID conversion file. This is created
from the ID conversion text file created on the retired system - retiredidconv.txt:
$ piartool -idci /opt/PI/adm/retiredidconv.txt -idco
/opt/PI/adm/retiredidconv.bin
Creating new conversion table: /opt/PI/adm/retiredidconv.bin...
37 input lines processed
37 names in table
The offline archive utility is used to convert the archives from the retired system. For this
example, one archive will be converted and registered. Other archives are handled in a similar
manner. Here is the dialog from the conversion:
$ ../bin/piarchss -id /opt/PI/adm/retiredidconv.bin -if
/opt/PI/dat/piarchretired.002 -of /opt/PI/dat/piarchconv.002
PIarchss offline archive utility
Input file type: PI 3
Archive input file: piarchretired.002
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-98 12:51:41
Archive indicated end time: 3-Mar-98 11:09:30
Archive indicated recordcount: 2048
Processing record 1 ...
Invalid ID Conversion on input Point ID 13 . Record not processed.
Primary record load completed.
Records processed: 38
Records with data: 21
Empty records: 17
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Overflow record load completed.
Records processed: 157
Records with data: 155
Empty records: 0
Records with errors: 0
Records out of time range: 2
PI Server System Management Guide Page 165
Chapter 9 - Merging Two PI Servers
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 will not be processed. The above dialog shows a message
indicating records for PointID 13 are not processed - this is the PI Batch point that was
intentionally not merged.
Note the times on the archive converted. The times overlap the primary archive on the
destination system. This problem must be addressed before the converted archive can be
registered. The solution is to force a shift, and combine the converted archive with the
destination archive. After the shift, the destination system's archives are as follows:
$ piartool -al
Archive shift prediction:
Shift Time: 18-Jan-38 19:14:07.7930
Target Archive: /opt/PI/dat/piarch.002
Archive: /opt/PI/dat/piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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-98 16:32:27
End Time: Current Time
Backup Time: Never
Archive: /opt/PI/dat/piarch.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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-98 12:21:11
End Time: 3-Mar-98 16:32:27
Backup Time: Never
Archive: /opt/PI/dat/piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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
will be made into a dynamic size. If converting into a fixed size archive, there must be
Page 166
9.3 - Shut Down the Retired System
enough space for all used records in both archives being combined. If in doubt use dynamic
archives--they can always be moved into a fixed size archive later.
In the following dialogs, the ID conversion file is not required:
$ ../bin/piarchss -if /opt/PI/dat/piarch.001 -of
/opt/PI/dat/piarchcomb.001
PIarchss offline archive utility
Input file type: PI 3
Archive input file: /opt/PI/dat/piarch.001
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-98 12:21:11
Archive indicated end time: 3-Mar-98 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
Records with errors: 0
Records out of time range: 0
Records with duplicate time range: 0
Begining Output pass. Output archive: /opt/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 /opt/PI/dat/piarchconv.002 -of
/opt/PI/dat/piarchcomb.001
PIarchss offline archive utility
Input file type: PI 3
Archive input file: /opt/PI/dat/piarchconv.002
Beginning first pass. Sorting input archive.
Archive indicated start time: 2-Mar-98 12:51:41
Archive indicated end time: 3-Mar-98 11:09:30
Archive indicated recordcount: 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
PI Server System Management Guide Page 167
Chapter 9 - Merging Two PI Servers
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: /opt/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 /opt/PI/dat/piarchcomb.001
Attempting to register archive file: /opt/PI/dat/piarchcomb.001
Successfully registered archive file: /opt/PI/dat/piarchcomb.001
peach piadmin$ piartool -al
Archive shift prediction:
Shift Time: 18-Jan-38 19:14:07.7930
Target Archive: /opt/PI/dat/piarch.002
Archive: /opt/PI/dat/piarch.003
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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-98 16:32:27
End Time: Current Time
Backup Time: Never
Archive: /opt/PI/dat/piarchcomb.001
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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-98 12:21:11
End Time: 3-Mar-98 16:32:27
Backup Time: Never
Archive: /opt/PI/dat/piarch.002
PIarcfilehead [$Workfile: piarfile.cxx $ $Revision: 21 $]:
Version: 4 Path: /opt/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
Page 168
9.3 - Shut Down the Retired System
$ piconfig
* (Ls - ) PIconfig>
* (Ls - ) PIconfig> @Input piarc.dif
* (Ls - PIARC) PIconfig> sinusoidRetired,2-mar-98,*,
*> sinusoidRetired,2-mar-98,*,
87.71619,GOOD,2-Mar-98 13:37:56
99.23527,GOOD,2-Mar-98 14:39:56
96.20524,GOOD,2-Mar-98 15:44:56
75.77717,GOOD,2-Mar-98 16:57:56
14.20552,GOOD,2-Mar-98 19:31:26
1.545739,GOOD,2-Mar-98 20:31:26
1.869217,GOOD,2-Mar-98 21:31:26
18.17325,GOOD,2-Mar-98 22:40:56
86.39859,GOOD,3-Mar-98 01:33:26
99.15742,GOOD,3-Mar-98 02:38:56
96.37012,GOOD,3-Mar-98 03:43:56
75.96362,GOOD,3-Mar-98 04:57:26
14.35799,GOOD,3-Mar-98 07:30:56
0.7647065,GOOD,3-Mar-98 08:39:56
3.794814,GOOD,3-Mar-98 09:44:56
24.22295,GOOD,3-Mar-98 10:57:56
Digital State,Shutdown,3-Mar-98 11:04:09
Digital State,Pt Created,3-Mar-98 14:29:48
98.3448,GOOD,3-Mar-98 14:30:26
98.2471,GOOD,3-Mar-98 15:30:26
82.16194,GOOD,3-Mar-98 16:39:56
79.05913,GOOD,3-Mar-98 16:48:56
End Repeat...
Take a good look at several points before proceeding.
9.3.4 Merge the PI Batches
Batches are stored in the Archive; therefore, all archives should be converted before
processing the batch text files. Once again, piconfig is used to add the batches:
$ piconfig
* (Ls - ) PIconfig> @input pibatchlist.dif
*>Reactor1Retired,XYZ3,Green,2-Mar-98 11:58:20,2-Mar-98 13:09:20
*>Reactor1Retired,XYZ25,Yellow,2-Mar-98 13:19:20,2-Mar-98 14:30:20
*>Reactor1Retired,XYZ3,Green,3-Mar-98 12:24:23,12:44:00
This completes the merger.
PI Server System Management Guide Page 169
Chapter 10. THE PICONFIG UTILITY
The piconfig utility maintains and configures PI Server databases such as the Point Database
and the Digital State Table.
The piconfig command line application runs on the PI Home node. You can work
interactively with piconfig or you can supply text files that contain commands and data.
Using piconfig, point information can be configured in a spreadsheet or database tool,
exported to a text file, and then applied to the Point Database.
The piconfig utility can also be used for troubleshooting. If you suspect that you have some
tags that are not configured correctly, you can search for tags that match a certain list of
attributes.
10.1 PI TagConfigurator & PI SMT Point Builder plug-in
While piconfig is often used for building PI points, there are other utilities that can be
obtained from OSIsoft to make this task easier:
PI Tag Configurator, is an Excel spreadsheet add-in that can facilitate creating
many new tags and modifying the attributes of existing tags in the Pipoint Table.
The PI System Management Tools (PI SMT) includes a PI Point Builder Plug-in
which is useful for editing or creating a small number of tags. PI SMT is available
from the Download Center at the technical support web site, and documentation is
included in the online Help file.
10.2 A Note to Pidiff Users
The piconfig utility includes the features of the PIDIFF utility of OpenVMS PI Systems. It
also includes many more features, such as the ability to edit tables other than the Point
Database.
Conversion information for upgrading from PI2 to PI3 may be found on the OSIsoft Web
site.
PI Server System Management Guide Page 171
Chapter 10 - The piconfig Utility
10.3 Key Concepts for Using Piconfig
10.3.1 Starting and Stopping Piconfig
The piconfig utility is a console application. To start, type piconfig at the command prompt.
If you are on a UNIX system, be sure to type all lower-case characters, because the operating
system is case-sensitive.
$ piconfig
In general, piconfig should be used only when PI is running.
To end the piconfig session, use the exit command.
piconfig> @exit
The command character must precede every command.
By default, the command character is @.
Data are on separate lines that are not preceded by the command character.
10.3.2 Interactive Session vs. Batch Method
At startup, piconfig checks whether the input is coming from an interactive terminal session
or from a piconfig script file. When run interactively, piconfig issues a prompt after each
command.
It is possible to turn prompting on and off by using the following commands:
@prompt yes
@prompt no
When turned on, the prompt indicates the piconfig mode and the current table name in
parentheses. The table name in the prompt is set when you issue the @table command:
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @help
Modes and tables are explained later in this chapter.
10.3.3 Selecting PI Tables
Whether you are using an interactive session or a script file, the first step is to specify the PI
table of interest. These are the PI tables that can be viewed and edited with piconfig:
Table 10–1. PI Tables Accessible Through piconfig
Database Table Names Primary Key
Points PIPOINT TAG
Digital states PIDS SET
Digital State Strings PISTATE STATE
Users PIUSER USER
Page 172
10.3 - Key Concepts for Using Piconfig
Database Table Names Primary Key
User Groups PIGROUP GROUP
Snapshot PISNAP or PISNAP2 TAG
Archive PIARC TAG
Batch Unit PIBAUNIT UNITNAME
PI Batch PIBATCH UNITNAME
Batch Alias PIBAALIAS ALIAS
Trust Logins PITrust TRUST
Firewall PI_GEN, pifirewall HOSTMASK
Timeout Database PI_GEN, pitimeout NAME
Attribute Sets PIATRSET SET
Point Classes PIPTCLS CLASS
Point Source PIPTSRC PTSRC
PI Subsystem Information PISubsys,<subsystem> Not Applicable
PI Subsystem Statistics PISubsysStats,<subsystem> Not Applicable
PI Net Manager Statistics PINetMgrStats ID
Database Security Dbsecurity DBName
Subsystem Threads PIThread,<subsystem> ID
The tables PI_Gen, PISubsys, PISubsysStats, PIThread and DBsecurity all require a second
argument. This argument specifies the owner subsystem, or, for PI_Gen, the actual database
file.
?tbl Command to List Table Names
The list of table names can be viewed using the ?tbl command.
Table Command to Select a Table
Tables are selected using the table command. The currently selected table is indicated by the
prompt.
No table is selected until the first table command is issued. The table remains selected until
the next table command.
Status Commands
The current setting of piconfig can be viewed using the status command.
PI Server System Management Guide Page 173
Chapter 10 - The piconfig Utility
Example of ?tbl, Table, and Status Commands
These commands are illustrated in the example below:
* (Ls - ) piconfig> @?tbl
1 - PIPOINT
2 - PIDS
3 - PISTATE
4 - PIUSER
5 - PIGROUP
6 - PISNAP
7 - PIARC
8 - PIBAUNIT
9 - PIBATCH
10 - PIBAALIAS
11 - PITRUST
12 - PI_GEN
13 - PIATRSET
14 - PIPTCLS
15 - PISubsys
16 - PISubsysStats
17 - PINetMgrStats
18 - DBSecurity
19 - PITHREAD
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @status
---- piconfig Status at 18-Mar-02 10:46:51 ----
Mode: List Decimal digits displayed: -7
Characters: Command: <@> Delimiter: <,> Comment: <*> Quote: < >
Struc. Type IN: <Delim.> OUT: <Delim.>
Error count: 2 Max: 10
Current table: <PIPOINT> Cur. Prim.: <#####> Def. Prim: < >
Nesting level : 0
Node: <127.0.0.1,piadmin>
10.3.4 Table Attributes
Once the table is specified, the attributes of that table can be displayed.
In this example, PIPoint refers to the Point Database Table. The first column shows the
attribute names and data types, the second column shows the default values, if any and the
third column, the values of the last retrieved record.
* (Ls - PIPOINT) piconfig> @?atr
1 Tag String D: !#!#!# C: SINUSOID
2 NEWTag String D: C:
3 archiving BYTE D: 1 C: 1
4 changedate TimeSta D: 0 C: 21-Dec-02 01:03:0
5 changer String D: C:
6 compdev Float32 D: 2. C: 2.
7 Compdevpercent Float32 D: 2 C: 2.
8 compmax Uint16 D: 28800 C: 28800
9 compmin Uint16 D: 0 C: 0
Page 174
10.3 - Key Concepts for Using Piconfig
10 compressing BYTE D: 1 C: 1
11 creationdate TimeSta D: 2. C: 17-Nov-02 18:39:5
12 creator String D: C:
13 DataAccess String D: o:rw g:r w:r C: o:rw g:rw w:rw
14 DataGroup String D: piadmin C: piadmin
15 DataOwner String D: piadmin C: piadmin
16 descriptor String D: C: 12 Hour Sine Wave
17 DigitalSet String D: system C:
18 displaydigits BYTE D: -5 C: -5
19 engunits String D: C:
20 excdev Float32 D: 1. C: 1.
21 Excdevpercent Float32 D: 1 C: 1.
22 excmax Uint16 D: 600 C: 600
23 excmin Uint16 D: 0 C: 0
24 exdesc String D: C:
25 PointID Uint32 D: 0 C: 2009
26 pointsource String D: Lab C: R
27 pointtype String D: Float32 C: Float32
28 PtAccess String D: o:rw g:r w:r C: o:rw g:rw w:rw
29 PtClassName String D: base C: classic
30 PtGroup String D: piadmin C: piadmin
31 PtOwner String D: piadmin C: piadmin
32 Recno Int32 D: 1 C: 116
33 scan BYTE D: 1 C: 1
34 shutdown BYTE D: 1 C: 1
35 SourceTag String D: C:
36 span Float32 D: 100. C: 100.
37 step BYTE D: 0 C: 0
38 typicalvalue Float32 D: 50. C: 50.
39 zero Float32 D: 0. C: 0.
Each of the table attributes can be viewed, set, or modified. Conceptually, each table in the
piconfig utility has several columns, where the column headers are the attributes. Each row is
a table record. For the PIpoint Table, each row corresponds to a particular tag.
10.3.5 Records
Piconfig views its tables as a collection of records. A record is a collection of fields or
attributes. One of these attributes is the primary key, which uniquely identifies the record
within the current table. This data representation is done for convenience and standardization.
It is not always an accurate image of the actual data.
Consider the following entries in the Snapshot Table:
CDM158 Auto 14-Jun-03 10:39:34
SINUSOID 68.973 14-Jun-03 10:00:00
SINUSOIDU 11.184 14-Jun-03 11:04:00
Attributes
In this example, there is a record for each Snapshot, and each record contains three attributes.
The attributes in this example are tag, value, and time.
PI Server System Management Guide Page 175
Chapter 10 - The piconfig Utility
Primary Key
Every record contains one attribute that is defined as the primary key, which uniquely
identifies the record. The primary key is the first attribute listed when using the ?atr
command.
When using the select command to specify a record, the primary key must always be used. If
it is not specified piconfig assumes * (all records). Other attributes may be selected in
conjunction.
For example, the primary key for the Pipoint Table is tag. When selecting the subset of tags
with point source F, the primary key needs to be included as follows:
@select tag=*, pointsource=F
Modifying the Primary Key
Most table attributes can be modified in edit mode, using modify or istructure commands.
The primary key is an exception. If you wish to change the primary key itself, you must
provide the new key value using a special attribute:
Use the newtag attribute for the Pipoint Table
Use the newset attribute for the Pids Table
For example, to rename the point “sinusoid” to “mysinusoid,” you would issue the
commands:
$ piconfig
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @mode edit
* (Ed - PIPOINT) piconfig> @istructure tag,newtag
* (Ed - PIPOINT) piconfig> sinusoid,mysinusoid
The attribute for the new primary key is always:
new<primary-name>
Note: Some tables do not support renaming of records, for example piarc and
pisnap tables. Tag is the primary key of these tables. Since Tag is actually a point
attribute, the rename must be down from the pipoint table. Other tables have similar
relationships.
10.3.6 Piconfig Commands
Once a table is selected, the next step is to use piconfig commands to retrieve and possibly
change the data in the table.
There are also piconfig commands that change the operational mode of piconfig. For
example, you can use the modify command to change from list mode (read only) to create
mode, delete mode, or edit mode.
To see a list of piconfig commands, use the help command, as shown in the following
example:
* (Ls - PIPOINT) piconfig> @help
Page 176
10.3 - Key Concepts for Using Piconfig
*piconfig> ? - This menu
*piconfig> BYE - Exit piconfig
*piconfig> CASE - Case sensitivity
*piconfig> CD - Change working directory (for in/out files)
*piconfig> CLEA - Clear selection and modifications specs
*piconfig> COMM - Define comment character
*piconfig> COMC - Set the command character
*piconfig> DATA - Input data (redundant)
*piconfig> DEFR - Primary key of default record
*piconfig> DELI - Set delimiter character
*piconfig> ECHO - Define echo: Data, Command, All, None
*piconfig> ENDR - Mark end-of-record
*piconfig> END-REPEAT - Mark end of data repetition
*piconfig> ENDS - End of processing section
*piconfig> ERROR - redirect error
*piconfig> EXIT - Exit piconfig
*piconfig> FLAG - Set table specific flags
*piconfig> FLUS - Flush changes to table
*piconfig> HELP - This page
*piconfig> INPU - redirect input
*piconfig> ISTR - Define input structure
*piconfig> ISTY - Input structure type
*piconfig> LINE - Increase input-line length
*piconfig> LOGI - Connect to another PI host
*piconfig> MAXE - Maximum errors allowed
*piconfig> MODE - Mode: Create, Edit, List, Compare, Convert, Delete
*piconfig> MODI - Modification specs
*piconfig> OUTP - redirect output
*piconfig> OSTY - Output structure type
*piconfig> OSTR - Define output structure
*piconfig> PROM - Prompt user for input
*piconfig> PTCL - Default Point class
*piconfig> QUIT - Exit piconfig
*piconfig> QUOT - Set Quotation character
*piconfig> RECS - Record separator Yes/No
*piconfig> REFE - Reference by Name or Index
*piconfig> SELE - Select (must include primary key specs.)
*piconfig> SIGD - Set number of significant digits for real numbers
*piconfig> STAT - Show current status: table, mode etc...
*piconfig> STRU - Define structure (input/output depending on mode)
*piconfig> STYP - structure type Delimited, Keyword, Fixed
*piconfig> SYST - Execute any operating system command (dir, notepad...)
*piconfig> STYP - structure type Delimited, Keyword, Fixed
*piconfig> TABL - Set table (?TBL- to see all tables)
*piconfig> TIMF - Number of decimal digits and Time zone name in
timestamps
* (Ls - PIPOINT) piconfig>
PI Server System Management Guide Page 177
Chapter 10 - The piconfig Utility
Example for Listing Point Information
In this example, points are selected where the attribute tag starts with the letter S and have
the point source R. R is the default point source for the random interface. All the tags that
match these criteria will have their tag, point source, and point type displayed.
$ piconfig
* (Ls - ) piconfig> @table pipoint
* (Ls - PIPOINT) piconfig> @mode list
* (Ls - PIPOINT) piconfig> @stype delimited
* (Ls - PIPOINT) piconfig> @ostructure tag, pointsource, pointtype
* (Ls - PIPOINT) piconfig> @select tag=s*, pointsource=R
* (Ls - PIPOINT) piconfig> @endsection
SINUSOID,R,Float32
SINUSOIDU,R,Float32
SQF100,R,Float32
SQF101,R,Float32
* (Ls - PIPOINT) piconfig>
*> @exit
0 Data lines
7 Command lines
0 Records in error
4 Records Listed
The Pipoint Table is specified because we want to view the Point Database. The other
commands are explained in the following paragraphs.
10.3.7 Mode
Within piconfig, there are six possible working modes, as follows:
(Ls) List mode (read only) Output formatted records from a table to screen or file
(Cr) Create mode (add) Create new records in a table
(Ed) Edit mode (modify) Modify or rename existing records
(Dl) Delete mode Delete records from a table
(Cv) Convert mode Convert input data from one format into another
(Cm) Compare mode Compare file data to table data
Create or Edit
The character t (for true) may be specified with either create or edit mode. This combines the
create and edit modes such that existing records are modified as specified while non-existent
records are created as specified:
@mode create, t
@mode edit, t
The specified mode persists until the next mode command is issued.
Page 178
10.3 - Key Concepts for Using Piconfig
Check Only
The character c (for check) may be specified with either create or edit mode.
@mode create, c
@mode edit, c
Note: Check modifier is applicable only to the PIpoint Table
In this mode points are validated and errors are reported but no changes are made to the point
database.
For all other tables this mode is identical with the normal edit or create mode.
Check mode can also be specified for Create/Edit.
@mode create, t, c
@mode edit, t, c
The specified mode persists until the next mode command is issued.
10.3.8 Structure Type
The structure type (stype) indicates the format of the data structure used to specify input and
output.
The possible structure types are:
Delimited
Fixed
Keyword
In situations where the output structure type is different from the input structure type, the
ostype and istype commands may be used instead of the stype command.
The specified structure type persists until the next stype, ostype, or istype command.
The default structure type is delimited format.
Delimited Format
In delimited format, one or more lines of comma-separated attributes describe the format of
the data. One or more lines of comma-separated data values follow. These lines correspond to
the attributes. For example:
@istructure tag, pointsource,pointtype
SINUSOID,R,FLOAT32
As shown above, the command is preceded by the command character (@) while the data are
not.
PI Server System Management Guide Page 179
Chapter 10 - The piconfig Utility
Changing the Delimiter
If you prefer, you may change the delimiter character to be any single (non-alphanumeric)
character using the delimiter command. For example, to change the delimiter character to
backslash ( \ ), issue the command:
@delimiter \
Note: The same delimiter character is used between piconfig attributes, between
elements of a piconfig command and between both input and output data fields.
Fixed Format
In fixed format, we describe the data structure by one or more lines specifying the attribute,
line number, starting position on the line (counting from 1), and field width. One or more
lines of data values that correspond to the given format follows. For example:
@istructure tag, 1, 1, 12
@istructure pointsource, 1, 14, 1
@istructure pointtype, 1, 19, 7
*
*234567890123456789
SINUSOID R FLOAT32
NEXTPOINT Lab FLOAT16
The lines starting with the asterisk (*) are comment lines and are ignored. Their only purpose
is to improve readability.
The format lines come first and are all grouped together. This defines a record. If there are
more data lines than are specified in the record, piconfig interprets these as additional records
of the same format. This example shows two input records.
Fixed format is the same as used in the OpenVMS PI System PIDIFF utility.
Changing the Comment Character
If you prefer, you may configure the comment character to be something other than an
asterisk. To do this, use the comment command (comm).
Keyword Format
In keyword format, every input line contains only two parts: the attribute and the value for
that attribute, separated by the delimiter character. The default delimiter character is a
comma ( , ).
The istructure command is not used with this format, as each line contains both data and its
description. For example:
tag, SINUSOID
pointsource, R
pointtype, FLOAT32
To select output attributes in keyword format, use the ostructure command. A single
attribute is specified on each line, as shown below:
Page 180
10.3 - Key Concepts for Using Piconfig
@ostructure tag
@ostructure pointsource
@ostructure pointtype
To output all attributes for the current table, issue the command:
@ostructure *
This works in both keyword and delimited formats.
Note: The command @ostructure is meaningful only in list mode. A warning is
issued if this command is executed in create, edit or delete mode.
Structure Specifications Persistence
Structure specifications for both input and output remain in effect until the table is changed.
Before any data is processed, new structure specifications are added to previous
specifications. After some data was processed, new structure specifications replace the
previous ones.
You can check which structure specification is in effect as follows:
@ostructure ?
@istructure ?
10.3.9 Select Command
The select command is used to select the records of interest. Any combination of attributes
may be used. In list mode only, the primary key specification defaults to * (all records). In
edit or delete modes the primary key must be included in select specifications. A record must
match all selection criteria to be selected.
Select specifications remain in effect until the mode or table is changed. Until a command is
processed, select specifications are added to previous specifications. After that, a new select
specification replaces the previous ones.
You can check the select specifications in effect at any time as follows:
@select ?
10.3.10 Operators
The following comparison operators are available:
= equal
<> not equal (!= also works)
> greater than
>= greater than or equal to
< less than
<= less than or equal to
PI Server System Management Guide Page 181
Chapter 10 - The piconfig Utility
These operators can be used for date, numeric or text fields. Text comparison is based on
ASCII values.
10.3.11 Wildcards
Wildcards, * and ?, may be used in text fields. * matches all characters; ? matches a single
character.
10.3.12 The Ellipsis (…) Construct for Repeating Attributes
Structure specifications may contain table attributes followed by an ellipsis (…). The ellipsis
indicates that the last attribute may be repeated a variable number of times within a single
record. If the ellipsis (…) is on a separate line, it indicates that the last (previous) structure
line may be repeated a variable number of times.
In most cases, Delimited format is more suitable for repeatable attributes.
In fixed format only complete lines can be repeated. A single field cannot be repeated on the
same line in fixed format because its field length is fixed.
The ellipsis construct can be used for both input and output.
Example Using Ellipsis Construct
List the states in the MODES state set using ellipsis. This means that multiple states will be
listed in comma-separated format.
* (Ls - PIDS) piconfig> @ostructure set,state,...
* (Ls - PIDS) piconfig> @select set=modes
* (Ls - PIDS) piconfig> @endsection
MODES,Manual,Auto,Cascade,Program,Prog-Auto
The ellipsis is useful where the same attribute can occur more then once in a single record.
For example, a state set contains variable number of states. A point class contains a variable
number of attributes and their defaults.
10.3.13 Endsection
The endsection command triggers the processing of selected records. It is not always
necessary to use an endsection command. An endsection is assumed when the end of file is
reached or when a command follows lines of data.
When an input structure is specified, every record is processed as data is entered.
The following example demonstrates how processing occurs in both ways:
d:\pi\adm>piconfig table pisnap
* (Ls - PISNAP) piconfig> ostru tag,value,time
*> ostru tag,value,time
* (Ls - PISNAP) piconfig> @sele tag=sinusoid
* (Ls - PISNAP) piconfig> @ends
SINUSOID,86.71634,20-Nov-02 16:25:30
* (Ls - PISNAP) piconfig> @istru tag
* (Ls - PISNAP) piconfig> sinusoid
*> sinusoid
Page 182
10.3 - Key Concepts for Using Piconfig
sinusoid,86.71634,20-Nov-02 16:25:30
10.3.14 Exit
Exit is the command that terminates the piconfig session. It is not necessary to use this
command when running piconfig in batch mode because the end of file causes piconfig to
execute the current commands and then exit. Quit and Bye has the same effect.
10.3.15 Batch Methods
Preparing Input Files
Entering commands by hand in interactive sessions can be prone to errors. It is often easier to
enter the commands in a text file, save it, and then use that file as input to later piconfig
sessions.
This is particularly useful for maintaining the point database using a spreadsheet. See the
example in the section, Adding Tags to the Point Database Using Excel.
Comments can be added to the text file for better readability.
For example, suppose you decided to list points with names starting in S and pointsource=R,
including tagname, pointsource and pointtype. You could specify delimited output structure.
To do all this, you could prepare and save an ASCII file named list.inp:
*************
* list.inp *
*************
* This piconfig script file lists the tagname,
* pointsource, and
* pointtype for all tags that start with "S" and
* which have point source R
*
@table pipoint
@mode list
@stype delimited
@ostructure tag, pointsource, pointtype
@select tag=s*, pointsource=R
@endsection
Start piconfig and run this input file using the input command:
$ piconfig
* (Ls - ) piconfig> @input list.inp
The following output is generated:
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
* (Ls - PIPOINT) piconfig>
PI Server System Management Guide Page 183
Chapter 10 - The piconfig Utility
Passing an Input File as a Parameter
An alternative is to pass the input file as a parameter on the command line.
The piconfig utility takes each pair of input parameters and treats the first as a command and
the second as the command parameter:
$ piconfig input list.inp
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
* (Ls - PIPOINT) piconfig>
Redirection of an Input File
Another alternative is to use the standard UNIX or Windows I/O redirection from the
command line:
$ piconfig < list.inp
SINUSOID,Float32,R
SINUSOIDU,Float32,R
SQF100,Float32,R
SQF101,Float32,R
piconfig 0 Data lines
6 Command lines
0 Records in error...
4 Records Listed
Input files may contain all data, all commands, or mixed commands and data. Input files may
be nested; that is, an input file can refer to other input files.
Capturing Output and Errors in Files
The piconfig utility output and errors are displayed by default on the computer screen. Use
the output and error commands to redirect this output in a file.
$ piconfig
*>@output list.out
*>@error errors.out
By default piconfig echoes the input commands and input data in the file, as well as the
output data. If you wish to see only the output data in the file, use the echo command with the
data option:
*> @echo data
Passing Commands as Parameters
You can pass the commands on the piconfig command line. PIconfig takes each pair of input
parameters and treats the first as a command and the second as the command parameter:
$ piconfig input list.inp output list.out
Page 184
10.3 - Key Concepts for Using Piconfig
Redirection of Output
An alternative is to use standard UNIX or Windows I/O redirection from the command line:
$ piconfig < list.inp > list.out
Re-using an Output File as an Input File
Redirecting the output to a file is very useful because you can reuse the output file as an input
file with other piconfig commands. For example, suppose you want to create a tag that is
similar to another tag that already exists on the PI Server. For example, the tagname and the
hardware address are the only differences; the descriptor, zero, span, pointtype, pointsource,
and engineering units are the same.
You can accomplish this task by listing all of the point attributes of the existing tag to a file.
Then the tagname and hardware address are modified using a text editor. Finally the file is
used as input to piconfig to create the new tag.
10.3.16 Security on Piconfig Sessions
Users of the piconfig utility can be required to login into the PI database by specifying a user
name and a password. This option is turned on by setting the PItimeout parameter
CheckUtilityLogin to 1.
By default this option is off.
10.3.17 Remote Piconfig Sessions
The piconfig utility running on one PI Server or PI-SDK node may connect a PI Server
running on a different computer. There are two ways to do this.
Using the Login Command
If you already have a piconfig session in progress, you can switch to a different PI Server
using the login command. The login command takes four parameters:
1. Remote PI 3 host name, or IP address
2. Remote PI Server user name
3. Remote PI password
4. Remote PI port ID (usually 5450)
For example;
@login figaro, piadmin, myadminpassword, 5450
Once the login command is issued, all subsequent commands are executed on the remote PI
Server.
Note: The PI_Gen tables are accessed only on the local machine. Even during a
remote session. This means that modifying PI_Gen tables must be done locally.
Attempting to modify these tables during a remote session will produce a warning
message.
PI Server System Management Guide Page 185
Chapter 10 - The piconfig Utility
Invoking Piconfig for Remote Connection
You can invoke the piconfig utility with the -remote command line option. After this option,
specify the connection information using other command line switches. If you are passing
any piconfig commands on the command line, enter them before the -remote option. For
example:
piconfig input piarc.dif -remote -node figaro -port 5450 -username
piadmin -password myadminpassword
You may specify the parameters -node, -port, -username and -password in any order, after -
remote.
10.4 Piconfig Commands and Tables
This section contains details on piconfig commands and tables.
Table 10–2. Piconfig Commands
Command Parameters Defaults Description
? None None Lists all commands
?Atr None None Lists all attributes for current table
?Tbl None None Lists all tables known to piconfig
Case Flag All (case- Sets case-sensitivity-ignore mode. Flag may be:
insensitive Data, Names, or All.
) This affects only tables accessed vie the PI_GEN
table – i.e. timeout and firewall.
Cd Directory None Change directory for input/output files
Clear None None Clears Modify and Select specifications
Comchar C @ Changes the command character to c
Comment C * Changes the comment character to c
Delimiter C , Changes the delimiter to c
Echo Flag Data Specifies if input commands and data are echoed
to the output file. Flag may be: Data, Commands,
All, Verbose or None.
End-repeat None None Marks end of repeated field
Endrecord None None Terminates input of one data record. Required in
keyword format. May be used in other formats to
terminate input before all data fields were entered
Endsection None None Marks the end of processing section
Error File None Redirect error messages to file
Page 186
10.4 - Piconfig Commands and Tables
Command Parameters Defaults Description
Exit None None Exits piconfig. (Quit and Bye work the same way.)
Help None None Lists all commands
Input File None Redirects input from file.
Istructure Structure None Specifies format of input data.
Istype Flag D Selects input data format structure type: Fixed,
Delimited, or Keyword. (F,D,K)
Line N 1024 Input line buffer size
Login PI 3 node, PI None Connect to a remote PI 3 home node using the
user name, given PI username, password, and TCP/IP port ID.
password, port
ID
Maxerr N 10 Sets the error tolerance. piconfig will exit when
the number of errors reaches n. However, piconfig
exits only when in non-interactive mode.
A Maxerr value of -1 causes piconfig to exit upon
the first error and display the line number of the
input file.
Mode Flag List Specifies mode of operation: Create, Edit, Delete,
List, Compare, Convert, Create, and Edit mode
can be modified to include both. Specify the mode
flag as Edit,t or Create,t.
For check only specify Edit,c or Create,c.
Modify Modification None Defines field modifications.
Ostructure Structure None Specifies format of output data. Only useful when
in list mode. A warning is issued if this command is
used in mode edit, create, or delete.
Ostype Flag D Selects output data format structure type: Fixed,
Delimited, or Keyword. (F,D,K)
Output File None Redirect output to file. If <file> not specified, the
output is directed back to standard output.
Prompt Flag No Sets prompt mode: yes (for interactive sessions) or
no (for batch sessions)
Ptclassname Classname Base Specifies the point class: base or classic. Pipoint
Table only.
Quote C None Tells piconfig to enclose output fields with quote
Must be ‘ or “ character ‘c’ if they contain the delimiter character.
Recsep Flag Yes Tells piconfig to separate multi-line output records
with a comment line.
PI Server System Management Guide Page 187
Chapter 10 - The piconfig Utility
Command Parameters Defaults Description
Select Selection Key=* Defines record selection criteria.
Sigd N 5 Number of significant decimal digits in number
display
Status None None Report piconfig current configuration: table, mode,
structure type, etc.
Structure Structure None Specifies either input or output according to mode.
Output in list and convert modes. Input in all other
modes.
STYP Structure Type Delimited Set structure type. Valid types are Delimited,
Keyword, and Fixed.
SYST System None Execute OS console command. For example “Syst
dir”
Table Table None Sets the PI table to Pipoint, Pids, etc.
Timformat Dig,TZ 5,F Time format. Number of decimals on sub-second
timestamps and whether or not to include time-
zone indication
10.4.1 Point Database Table
The table name is Pipoint. The primary key is TAG.
Point Classes in the Point Database
The Pipoint Table (Point Database) has several different point classes. The point class
determines the attribute set for each point. The Base class attributes are included in all other
point classes.
Accessing Point Class Attributes
To access the attributes of another point class, change the point class using the ptclassname
command. For example, to change to the Classic point class:
@ptclassname classic
Optionally the ptclass can be specified at Pipoint Table load; the syntax is:
@table pipoint,<ptclass>
This example selects the Pipoint Table and classic ptclass:
@table pipoint,classic
When listing classic point attributes of non-classic points, attributes unique to classic will
appear to be blank.
Page 188
10.4 - Piconfig Commands and Tables
Listing Attributes in the Classic Point Class Example
To see which additional attributes are available using the Classic point class, select the
Classic point class with the ptclass command and list the attributes using the ?atr command.
(Ls - ) piconfig> @table pipoint
(Ls - PIPOINT) piconfig> @?atr
(Ls - PIPOINT) piconfig> @ptclassname classic
(Ls - PIPOINT) piconfig> @?atr
Modifying an Attribute in the Point Database
With the exception of point class and point type, the user-configurable point attributes in the
Point Database may be modified using piconfig. The syntax is:
@modify <attribute>=<newvalue>,<attrib2>=<newvalue2>,...
Example to Modify the Span Point Attribute
In this example, the modify command is used to change the span for all tags starting with
“MyTag”:
@table pipoint
@mode edit
@modify Span=150
@select tag=MyTag*
@endsection
Example Using Operators for Modifying Point Attributes
Values may be modified arithmetically by using the following operators:
attribute += value
attribute -= value
attribute *= value
attribute /= value
This example changes all tags with a point source of X to have a zero that is 10 units less
then its current value and increases the span to 110% of its current value:
@table pipoint
@mode edit
@select tag=*, pointsource=X
@modify zero-=10, span*=1.1
@endsection
Modify specifications remain in effect until a table is changed. New modify specifications
are added to previous specifications until data is processed. After this, new specifications
replace previous ones.
Modifying a Nonexistent Attribute
If you attempt to modify an attribute that a tag does not have (such as a Classic attribute for a
point in the Base class), you will get an error message:
PI Server System Management Guide Page 189
Chapter 10 - The piconfig Utility
[-12001] Name Not Found in PInt]
Adding Tags to the Point Database Using Excel
The TagConfigurator is a utility that should be used to configure PI points using Microsoft
Excel. It can be obtained from the OSIsoft Technical Support Web site at
http://techsupport.osisoft.com.
This section outlines a technique that can be used if you wish to develop a point configuration
spreadsheet yourself.
The spreadsheet should contain a row for each tag and a column for each attribute, such as
tag, Pointsource, and pointtype.
Save the spreadsheet as an ASCII file with comma-separated values. Precede any non-data
lines in the file with an * comment character. That way piconfig will ignore them.
Here’s an example data file, taglist.dat, generated from a spreadsheet in Comma-Separated
Variable format (CSV):
RealTag1,Lab,float16
RealTag2,Lab,float16
Modify the following example structure file so that the attributes listed in the istructure line
match the contents of the ASCII data file. Note that the tagname, as specified by the Tag
attribute, is the only attribute that is required. Attributes that are not specified will be given
default values.
Use create mode to create new tags; use edit mode to modify existing tags. Use create, t or
edit, t mode to create the tag if it does not exist and to modify it if it does exist.
*Example piconfig input structure file
*File name: example3.str
*
*Create or modify tags from input file
taglist.dat
*
@table pipoint
@mode create, t
@istructure tag, pointsource, pointtype
@input taglist.dat
@endsection
*
*List tags to verify creation or modification
*
@mode list
@ostructure tag, pointsource, pointtype
@select tag=*, pointsource=Lab, pointtype=float16
@endsection
@exit
Run piconfig using the structure file as input.
piconfig < example3.str
Page 190
10.4 - Piconfig Commands and Tables
10.4.2 PI Attribute Set Table
The Attribute Set Table contains sets of attributes used to build point classes. An attribute
defines a point attribute; it is comprised of a name, data type and default value. An attribute
set contains a list of attributes. Attribute sets are the building blocks of point classes. Point
classes are made up of a list of attribute sets.
Note: Changing existing attribute sets – except for changing default values, should
be done with great care, in standalone mode.
The table name is PIATRSET. It has the following attributes:
Attribute Description
SET name of attribute set
ATTRIB Attribute name; a set has many of these
DEFAULT Default value of the attribute
TYPE… Data type of the attribute. For example, String, Float32
Note: An attribute set has many of the “Attrib, Default, Type” triplet. The ellipsis (…)
following “TYPE” indicates those three may be repeated.
The following piconfig session demonstrates listing the attribute sets on the PI Server:
* (Ls - PIATRSET) PIconfig> @table piatrset
* (Ls - PIATRSET) PIconfig> @ostr set
* (Ls - PIATRSET) PIconfig> @ends
*PIConfig Err> Wild-card specs. missing, default to '*'.
alarmparam
base
classic
sqcalm_parameters
totals
* (Ls - PIATRSET) PIconfig>
Now listing the entire classic then base attribute sets; note use of the ellipsis to repeat the
output:
* (Ls - PIATRSET) PIconfig> @table piatrset
* (Ls - PIATRSET) PIconfig> @ostr attrib, default, type
* (Ls - PIATRSET) PIconfig> @ostr ...
* (Ls - PIATRSET) PIconfig> @istr set
* (Ls - PIATRSET) PIconfig> classic
*> classic
location1,0,Int32
location2,0,Int32
location3,0,Int32
location4,0,Int32
location5,0,Int32
PI Server System Management Guide Page 191
Chapter 10 - The piconfig Utility
filtercode,0,Int16
squareroot,0,Int16
totalcode,0,Int16
convers,1.,Float32
srcptid,0,Int32
instrumenttag,,String
userint1,0,Int32
userint2,0,Int32
userreal1,0.,Float32
userreal2,0.,Float32
* End Repeat...
* (Ls - PIATRSET) PIconfig> base
*> base
descriptor,,String
exdesc,,String
typicalvalue,50.,Float32
engunits,,String
zero,0.,Float32
span,100.,Float32
pointtype,12,UBYTE
pointsource,Lab,String
scan,1,BYTE
excmin,0,Uint16
excmax,600,Uint32
excdev,1.,Float32
shutdown,1,BYTE
archiving,1,BYTE
compressing,1,BYTE
step,0,BYTE
compmin,0,Uint16
compmax,28800,Uint32
compdev,2.,Float32
creationdate,31-Dec-69 16:00:00,TimeStamp
creator,0,Uint16
changedate,31-Dec-69 16:00:00,TimeStamp
changer,0,Uint16
displaydigits,-5,BYTE
* End Repeat...
Users familiar with classic PI Points will recognize all these attributes. These two attribute
sets, Classic and Base, make up the classic point class.
10.4.3 Point Class Database
The Point Class Database contains all the point classes defined on a PI Server. A point class
defines the attributes of a PIPOINT. This approach allows points to have attributes specific to
the point's role. For example, Totalizer points use a point class designed specifically for the
Totalizer needs.
Note: Editing existing Point Classes should be done with great care – in standalone
mode.
Page 192
10.4 - Piconfig Commands and Tables
The table name is PIPTCLS. It has the following attributes:
Attribute Description
Class name of the class
SET The attribute set where attribute in the class were defined. This attribute is only
used in create mode. It is used to specify the attribute sets which comprise the
point class.
ATTRIB Attribute name; a class has many of these
DEFAULT Default value of the attribute
TYPE… Data type of the attribute. For example, String, Float32
The following piconfig session lists the point classes on the server:
* (Ls - PIPTCLS) PIconfig> @ostr class
* (Ls - PIPTCLS) PIconfig> @ends
*PIConfig Err> Wild-card specs. missing, default to '*'.
Alarm
base
classic
SQC_Alarm
Totalizer
Now listing classic point class; this class is built from the classic and base attribute sets:
* (Ls - PIPTCLS) PIconfig> @tabl piptcls
* (Ls - PIPTCLS) PIconfig> @mode list
* (Ls - PIPTCLS) PIconfig> @ostr attrib,default,type
* (Ls - PIPTCLS) PIconfig> @ostr ...
* (Ls - PIPTCLS) PIconfig> @istr class
* (Ls - PIPTCLS) PIconfig> classic
*> classic
descriptor,,String
exdesc,,String
typicalvalue,50.,Float32
engunits,,String
zero,0.,Float32
span,100.,Float32
pointtype,12,UBYTE
pointsource,Lab,String
scan,1,BYTE
excmin,0,Uint16
excmax,600,Uint32
excdev,1.,Float32
shutdown,1,BYTE
archiving,1,BYTE
compressing,1,BYTE
step,0,BYTE
compmin,0,Uint16
compmax,28800,Uint32
PI Server System Management Guide Page 193
Chapter 10 - The piconfig Utility
compdev,2.,Float32
creationdate,31-Dec-69 16:00:00,TimeStamp
creator,0,Uint16
changedate,31-Dec-69 16:00:00,TimeStamp
changer,0,Uint16
displaydigits,-5,BYTE
location1,0,Int32
location2,0,Int32
location3,0,Int32
location4,0,Int32
location5,0,Int32
filtercode,0,Int16
squareroot,0,Int16
totalcode,0,Int16
convers,1.,Float32
srcptid,0,Int32
instrumenttag,,String
userint1,0,Int32
userint2,0,Int32
userreal1,0.,Float32
userreal2,0.,Float32
* End Repeat...
* (Ls - PIPTCLS) PIconfig>
10.4.4 Point Source Database
The Point Class Database is actually a view into the point source index of the point database.
It provides the ability to add a descriptor for each point source and to quickly view the
number of points per point source.
The table name is PIPTSRC It has the following attributes:
Attribute Description
Ptsrc The point source character or string
Code The internal code, used for point source update signup
Count Number of points in this point source
Desc… Free format descriptor
The following piconfig session lists the point sources on the server:
* (Ls - PIPTSRC) PIconfig> @ostru ptsrc,code,count,desc
* (Ls - PIPTSRC) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
#,15,26,
*,13,1,
1,7,5589,
9,2,11,
?,14,1,
@,10,4,
Page 194
10.4 - Piconfig Commands and Tables
C,4,22,
G,9,18,
L,3,15,
Lab,5,4056,
PIBatch-InternalUse-1,11,2,
PICampaign-InternalUse-1,19,1,
PITest,16,1,
PIUnitBatch-InternalUse-1,8,109,
R,1,9865,
T,6,15,Totalizer Points
U,12,2,
10.4.5 Digital States Table
The Digital State Table contains the digital state sets. A state set has a name and a list of
states (digital state strings). The system is limited to 16383 sets with up to 16383 states in
each set.
The table name is PIDS. The primary key is SET. The following attributes are defined:
Attribute Description
SET name of digital state set
SETNO digital state set number (read only)
STATE… digital state strings in the set
The default set is called system and contains all the default system states found in a PI2.x
Digital State Table. The System Digital State Set number, SetNo, is 0 (zero).
Once created, a digital state set cannot be deleted.
Listing all State Sets in the Digital State Table
The next example shows how to list all state sets in the Digital State Table. The defaults are
list mode and delimited format.
In the example below, first we ask piconfig to list the attributes of the pids table. Then we
ask to see all of the sets in the table; four are listed.
$ piconfig
(Ls - ) piconfig> @table pids
(Ls - PIDS) piconfig> @?atr
1 - SET (D) Setxxx
2 - SETNO (D) 0
3 - STATE (D) Statexxx
4 - OLDCODE (D) 0
5 - NEWSET (D)
(Ls - PIDS) piconfig> @ostructure set
(Ls - PIDS) piconfig> @select set=*
(Ls - PIDS) piconfig> @endsection
SYSTEM
BATCHACT
PI Server System Management Guide Page 195
Chapter 10 - The piconfig Utility
PHASES
MODES
Adding a Digital State Set
To add a digital state set to the Digital State Table, use piconfig as follows:
1. Select the Digital State Table
(Ls - PIDS) piconfig> @table pids
2. Prepare to write to the table
(Ls - PIDS) piconfig> @mode create
3. Specify an input data format of a digital state set name followed by any number of
states in the set. Follow this with a data line.
(Cr - PIDS) piconfig> @istructure set, state, ...
(Cr - PIDS) piconfig> ValveStateSet, Open, Closed
4. Next, list the new state set in order to verify that it was properly created. Select only
those sets that start with “V.” Use an endsection command to force processing:
(Cr - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set, state, ...
(Ls - PIDS) piconfig> @select set=V*
(Ls - PIDS) piconfig> @endsection
VALVESTATESET,Open,Closed
(Ls - PIDS) piconfig>
The endsection command is not needed when creating the state set because data lines are
processed as they are entered.
Adding a Digital State Set Using Multiple IStructure Lines
This method uses multiple istructure command lines.
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 that consists of a digital state set name followed by any
number of states in the set.
(Cr - PIDS) piconfig> @istructure set
(Cr - PIDS) piconfig> @istructure state
(Cr - PIDS) piconfig> @istructure ...
The input lines are the set name followed by any number of states:
ValveStateSet
Open
Closed
Page 196
10.4 - Piconfig Commands and Tables
Subsequent lines are treated as input until the next piconfig command is issued.
Modifying a Digital State Set
If you want to modify an existing digital state set by adding a state, deleting a state, or
renaming a state, you must specify all of the states in the state set. Individual states cannot be
edited.
For example, add another state to the ValveStateSet as follows:
1. Select the Digital State Table
(Ls - PIDS) piconfig> @table pids
2. Prepare to write to the table
(Ls - PIDS) piconfig> @mode edit
3. Specify an input data format that consists of a digital state set name followed by any
number of states in the set.
(Ed - PIDS) piconfig> @istructure set, state, ...
4. The next line is pure input data (no commands)
(Ed - PIDS) piconfig> ValveStateSet, Open, Closed, Stuck
5. Next, list the new state set in order to verify that it was properly created:
(Ed - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set, state, ...
6. Select only those sets that start with “V”
(Ls - PIDS) piconfig> @select set=V*
7. Start processing
(Ls - PIDS) piconfig> @endsection
VALVESTATESET,Open,Closed,Stuck
(Ls - PIDS) piconfig>
Note: For sets with more then a few states it is advisable to use an output file, edit
the file, and then use it as input file. As mentioned above, the state must be added or
edited as a whole. See the following explanation about editing the system set.
Modifying the System state Set
The System State Set is always set number 0. It cannot be deleted. Renaming it is allowed,
yet not recommended. As with any other set, it must be edited in its entirety.
The System State Set usually includes some blank states. To preserve these, make sure that
blank state are enclosed in quotes, or use the oldcode attribute. The oldcode attribute can
help keeping reference to state offsets within a set during editing. It has no other use.
@istru set
@istru oldcode,state
@istru ...
PI Server System Management Guide Page 197
Chapter 10 - The piconfig Utility
system
0,??????????
1,
2,?2
3,
4,?4
@istru set
@istru state
@istru ...
system
??????????
""
?2
""
?4
Both examples show only the first 5 states in the system set, and in both cases states 1 and 3
are blank.
Changing Capitalization of a Digital State String
PI maintains a list of all digital state strings in use. This means that if a given digital state
string is used in more than one digital state set, both sets refer to the same state string.
System managers need the ability to edit the digital string in the event that an error is made
when the string is first added to PI. The PIstate Table is used for this purpose. For example,
to correct the digital state string error “AUto” to “Auto”, you would issue the following
piconfig commands:
(Ls - ) piconfig> @table pistate
(Ls - PISTATE) piconfig> @mode edit
(Ed - PISTATE) piconfig> @istr state,newstate
(Ed - PISTATE) piconfig> AUto,Auto
AUto,Auto
(Ed - PISTATE) piconfig>
The only processing mode supported by the Pistate Table is edit, which means that you
cannot use this table to create, delete or list digital state strings. To modify or list digital state
sets or the strings that belong to them, use the Pids Table.
You should not use the PIstate Table to substantially change the meaning of any digital state
string. This would affect any digital state set that uses the state string.
Changing the Digital State Set Name - Example
In the digital state table, the primary key is SET, so the NEWSET attribute is used to change
the value of the primary key:
(Ls - ) piconfig> @table pids
(Ls - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set
(Ls - PIDS) piconfig> @select set=*
(Ls - PIDS) piconfig> @endsection
SYSTEM
Page 198
10.4 - Piconfig Commands and Tables
BATCHACT
PHASES
MODES
VALVESTATESET
(Ls - PIDS) piconfig> @mode edit
(Ed - PIDS) piconfig> @istru set,newset
(Ed - PIDS) piconfig> ValveStateSet,NewValveStateSet
(Ed - PIDS) piconfig> @mode list
(Ls - PIDS) piconfig> @ostructure set
(Ls - PIDS) piconfig> @select set=*
(Ls - PIDS) piconfig> @endsection
SYSTEM
BATCHACT
PHASES
MODES
NEWVALVESTATESET
Creating a Digital Tag Example
A digital tag is defined by specifying point type Digital in the Point Database.
The digital state set will default to System. To specify a different state set, enter the digital
state set name in the tag’s DigitalSet attribute in the Point Database.
In the example below, the tagname, the point type, and the digital state set are explicitly
defined, while all the other point attributes use the defaults.
1. Select the Point Database Table.
(Ls - ) piconfig> @table pipoint
2. Prepare it for writing
(Ls - PIPOINT) piconfig> @mode create
3. Specify the input data format
(Cr - PIPOINT) piconfig> @istructure tag, pointtype, digitalset
*> istructure tag, pointtype, digitalset
4. Specify the data
(Cr - PIPOINT) piconfig> ValveStateTag, Digital, ValveStateSet
*> ValveStateTag, Digital, ValveStateSet
5. Next, list the new state set in order to verify that it was properly created:
(Cr - PIPOINT) piconfig> @mode list
(Ls - PIPOINT) piconfig> @ostructure tag, pointtype, digitalset
6. Select only those tags that start with “V”
(Ls - PIPOINT) piconfig> @select tag=V*
7. Now force processing
(Ls - PIPOINT) piconfig> @endsection
ValveStateTag, Digital, ValveStateSet
PI Server System Management Guide Page 199
Chapter 10 - The piconfig Utility
Sending a Digital State to the Snapshot Database
Next, send a digital state Value to the Snapshot to verify that the new tag you have created
can retrieve the value.
1. Select the Snapshot Table
(Ls - ) piconfig> @table pisnap
2. Prepare for writing
(Ls - PISNAP) piconfig> @mode edit
3. Specify the input data format:
(Ed - PISNAP) piconfig> @istructure tag, time, value
4. Specify the data. The timestamp is *, which indicates that the current time should be
used.
(Ed - PISNAP) piconfig> ValveStateTag, *, Open
5. Next, list the new state set in order to verify that it was properly created:
(Ed - PISNAP) piconfig> @mode list
(Ls - PISNAP) piconfig> @ostructure tag, time, value
6. Select only those tags that start with “V:”
(Ls - PISNAP) piconfig> @select tag=V*
7. Now start processing:
(Ls - PISNAP) piconfig> @endsection
ValveStateTag, 26-SEP-03 15:45:32, Open
10.4.6 Snapshot and Snapshot2 Tables
The Snapshot and Snapshot2 tables provide access to the PI Snapshot, both for listing or
editing.
The table name is Pisnap. The primary key is TAG.
The following attributes are defined:
Table 10–3. Snapshot and Snapshot2 Tables Attributes
Attribute Description Comment
TAG The tagname (Read only)
PointID The point ID (Read only)
Type The point type (float32 …) (Read only)
Value
TIME Event timestamp in the format DD-MMM-YY hh:mm:ss.ssss
TimeNum Timestamp as a number in seconds past 01-Jan-70 (Read only)
Page 200
10.4 - Piconfig Commands and Tables
Attribute Description Comment
Status The value status (Read only)
Flags (Q)uestionable (M)odifed (A)nnotated Only Q is
read/write
Annot Annotation
To read Snapshot data, use list mode. To change the data, use edit mode. Other modes are not
applicable.
If a numerical Snapshot value is invalid, the PI Server shows the value as “Digital State” and
the status attribute shows the digital state that describes the status. If a numerical value is
valid, the actual value is shown and the status attribute shows the digital state “GOOD.”
To change a digital point value, you can specify either the digital state name or the numeric
offset (digital state number.)
The file pisnap.dif is included with every system. It is a quick way to list Snapshot values.
$ piconfig input pisnap.dif
* (Ls - PISNAP) piconfig> @sele tag=c*
* (Ls - PISNAP) piconfig> @ends
CDEP158,2,GOOD,20-Nov-02 17:02:00
CDF144,Digital State,No Data,20-Nov-02 17:11:42
CDM158,Manual,GOOD,20-Nov-02 17:09:30
CDT158,53.03498,GOOD,20-Nov-02 17:10:00
A second table named Pisnap2 is useful for debugging classic PI API applications. It uses the
PI 2.x concepts rval and istat instead of Value and Status:
Attribute Description
RVAL real values; or 0 for other point types
ISTAT Positive integer value for integers, status for invalid real values, or set and state
number for digitals.
In PI 2.x, istat for digital tags is the negative of the state number. In the Pisnap2 Table, istat
contains a 32-bit number that represents both set and state. The set number is in the most
significant 16 bits and the state number is in the least significant 16 bits. The system set
number is 0. Be aware that some PI API functions truncate the most significant 16 bits. Refer
to the PI Server Reference Guide, Appendix B, PI API Limitations, for more information.
String values cannot be used in Pisnap2 Table.
Adding Events to the Data Archive Using the Snapshot Table
Events— “value/time pairs” —may be added to the PI Data Archive by using the Snapshot
Table. The Snapshot contains the most recent event for each tag. If you add an event to a tag
in the Snapshot Table, the previous event will be archived if it passes the compression tests.
Events with timestamps earlier then the current Snapshot timestamp bypass the Snapshot
PI Server System Management Guide Page 201
Chapter 10 - The piconfig Utility
Table and are sent directly to the Archive. You can only view the most recent event in the
Snapshot Table.
The tagname, time stamp, and value must all be specified. The time can be in any of the valid
PI time formats specified in the PI Server Reference Guide, Appendix A.
Select the Snapshot table and prepare for editing.
(Ls - ) piconfig> @table pisnap
(Ls - PISNAP) piconfig> @mode edit
Specify the format of the input data.
(Ed - PISNAP) piconfig> @istruc tag, time, value
The following lines are input data.
RealTag, 13-Aug-03 10:00, 3.81
RealTag, 13-Aug-03 10:05, 2.45
IntTag, *, 5
DigTag, T+8h, CLOSED
Adding Data Using Pisnap2 Table
In the Pisnap2 Table, use the rval and istat attributes instead of the value attribute:
In this example, a good and a bad value are added to PI:
(Ls - ) piconfig> @table pisnap2
* (Ls - PISNAP2) piconfig> @mode edit
* (Ed - PISNAP2) piconfig> @istru tag,time,rval,istat
* (Ed - PISNAP2) piconfig> sinusoid,*,50.0,0
> sinusoid,,50.0,0
* (Ed - PISNAP2) piconfig> sinusoid,*,0,-254
> sinusoid,*, 0,-254
Using the Pisnap2 Table to add values to integer and digital tags would require setting the
istat attribute.
10.4.7 Archive Table
The Archive Table provides access to the PI Data Archive. Events can be listed, added,
modified, and deleted.
The table name is Piarc. The primary key is TAG.
The following attributes are defined:
Table 10–4. Archive Table Attributes
Attribute Description Comment
TAG the tagname (read only)
PointID the point ID (read only)
Type the point type (float32 …) (read only)
Page 202
10.4 - Piconfig Commands and Tables
Attribute Description Comment
Value
TIME Event timestamp in the format DD-MMM-YY
hh:mm:ss.ssss
TimeNum Timestamp as a number in seconds past 01-Jan-70 (read only)
Status the value status (read only)
Flags (Q)uestionable (M)odifed (A)nnotated Only Q is read/write
Annot Annotation
NewValue New value for specific replacement
These attributes are the same as the Pisnap attributes. In addition there are some auxiliary
attributes that affect retrieval and editing:
Attribute Description
Count Maximum number of events to retrieve in list mode
Mode Archive editing mode – see below
Starttime Start time for events retrieval
Endtime End time for events retrieval
Starttime and endtime can define both a forward and a backward search.
Events can be added to the Snapshot using the Piarc Table. Events are placed in the Snapshot
if they are more recent than the current Snapshot event; otherwise, they bypass compression
and go straight to the Archive according to the archiving mode specified. When a new
Snapshot event is stored, the previous Snapshot event is sent to the archive, compressed
according to the compression specifications.
List Mode Attribute for Piarc
In list mode, the Piarc Table mode attribute can be one of the following:
Attribute Description
COMP Compressed events
EVEN Interpolated events. The number of evenly spaced events returned between
starttime and endtime is given by the “Count” parameter.
Listing Archive Values
The piconfig input file PI\adm\piarc.dif is provided with every PI Server. It is a quick way to
view archive data from within piconfig:
@input piarc.dif
PI Server System Management Guide Page 203
Chapter 10 - The piconfig Utility
Next, enter data with the format:
tagname, starttime, endtime, count
For example, to view four hours of data for the tag sinusoid, with a maximum of 100 values,
enter:
@input piarc.dif
sinusoid, *-4h, *, 100
@endsection
The Piarc Table can be used also to view interpolated data by specifying the “even” mode. In
this example, 5 evenly spaced values will be retrieved:
* (Ls - PIARC) piconfig> @table piarc
* (Ls - PIARC) piconfig> @istru tag, starttime, endtime, count, mode
* (Ls - PIARC) piconfig> @ostr value,status,time
* (Ls - PIARC) piconfig> @ostr ...
* (Ls - PIARC) piconfig> sinusoid,*,*-4h,5,even
*> sinusoid,*,*-4h,5,even
71.32876,GOOD,20-Nov-02 17:52:51
77.07982,GOOD,20-Nov-02 16:52:51
Digital State,Shutdown,20-Nov-02 15:52:51
Digital State,Shutdown,20-Nov-02 14:52:51
Digital State,Shutdown,20-Nov-02 13:52:51
* End Repeat...
Edit Mode Attribute for PIArc Table
In edit mode, the MODE attribute can be one of the following:
Attribute Description
noreplace add unless event(s) exist at same time (PI 2.x)
append add event regardless of existing events
replace add event, replace if event at same time
replacex Replace existing event (fail if no event at time)
replaceSp Replace a specified value when multiple values at the same time
remove Remove existing event
appendx as append + no compression; that is, if this is the Snapshot, force into Archive
Note: Do not confuse the Piarc Table mode attribute with the piconfig mode
command. To delete archive events, use the Piarc Table mode attribute=remove in
piconfig edit mode.
Changing and Deleting Events in PIArc Table
The following commands can be used to add, edit, and delete events.
Page 204
10.4 - Piconfig Commands and Tables
Note: In remove mode, both value and time must exactly match the existing event. If
the timestamp contains sub-seconds, it might be necessary to expand time
resolution with the timf command in order to make an exact match.
Similarly, the number of decimal digits might need to be increased for floating point
values using the sigd command.
@table piarc
@mode edit,t
@istructure tag, value, time, mode
string1,some text,11:45, append
realtag,12.5,10:44, replace
inttag, 10, t, remove
When adding a new archive event with the edit modes above, you must use:
@mode edit,t
or
@mode create,t
The piconfig selection and modification may be used. For example one might create an input
file (input.txt) with the following command lines
@istructure tag, starttime, endtime, count
@ostructure tag, value, status, time
@ostructure ...
@output labevents.txt
labtag,t,y,100
then redirect this input file into piconfig in order to list some events to an output file called
labevents.txt:
* (Ls - PIARC) piconfig < input.txt
Now one can change or delete all these events. For example:
@mode edit
@istructure tag, value, status, time
@modify value*= 1.1, mode=replace
@input labevents.txt
This will increment all the previously selected events by 10%.
To delete all events for a specified time range (last 7 days in this example) for a given tag you
can place the script below in a file called delevents.dif.
@table piarc
@mode list
@istructure tag, starttime, endtime, count
@ostructure tag, time, value
@ostructure ...
@timf 9
@sigd 9
@output tmpdelevents.dat
PI Server System Management Guide Page 205
Chapter 10 - The piconfig Utility
%1%,%2%,%3%,10000
@output
*@exit - uncomment this to exit and review before deleting
@mode ed,t
@modify mode=remove
@istructure tag, time
@input tmpdelevents.dat
@exit
Then invoke piconfig as follows:
* (Ls - PIARC) piconfig input delevents.dif,mytag,t-7d,t
Note, in order for the input file and it’s parameters to be taken as one parameter, it’s
important to have no spaces between parameters, as show in the example. Also, note that this
script will delete up to 10000 events, but it can be changed in the script.
Changing Events when there are Multiple Events at the Same Time
The following commands show how to modify a specific value out of several at the same
time using replacesp mode. Note the use of NewValue attribute.
The replace mode would cause the last value at the time to be replaced.
* (Ed - PIARC) PIconfig> @input piarc.dif
* (Ls - PIARC) PIconfig> rpflt1,*,y,100
*> rpflt1,*,y,100
123.,GOOD,24-Jun-03 17:43:01
1123.,GOOD,24-Jun-03 01:00:00
112.,GOOD,24-Jun-03 01:00:00
11.,GOOD,24-Jun-03 01:00:00
1.,GOOD,24-Jun-03 01:00:00
* End Repeat...
* (Ls - PIARC) PIconfig> @mode edit,t
* (Ed - PIARC) PIconfig> @istru tag,value,newvalue,time,mode
* (Ed - PIARC) PIconfig> rpflt1,11,0.11,t+1h,replacesp
*> rpflt1,11,0.11,t+1h, replacesp
* (Ed - PIARC) PIconfig> @input piarc.dif
* (Ls - PIARC) PIconfig> rpflt1,*,y,100
*> rpflt1,*,y,100
123.,GOOD,24-Jun-03 17:43:01
1123.,GOOD,24-Jun-03 01:00:00
112.,GOOD,24-Jun-03 01:00:00
0.11,GOOD,24-Jun-03 01:00:00
1.,GOOD,24-Jun-03 01:00:00
* End Repeat...
Using the TimeFormat Command
The TimeFormat command can be used to adjust the number of sub-second digits displayed
in timestamps, and whether or not time zone information is displayed. The default number of
sub-second digits to display is 5. No time zone information is normally displayed. This
command affects the display of timestamps from the Snapshot and Archive only.
Page 206
10.4 - Piconfig Commands and Tables
To set the number of sub-second digits to 4 and turn on time zone information display, you
would enter the command:
@timf 4,t
The time zone information displayed with every Snapshot and archive timestamp is the short
label of time zone and current standard/daylight status. For example, in Pacific Standard
Time, this label would be PST. You can check the labels for your time zone with the pidiag -
tz command.
If you issue the timeformat command with the number of sub-second digits only, time zone
information display will be turned off.
Using Sub-second Timestamps
You can put events with sub-second timestamps in the Snapshot and Data Archive using the
piconfig utility. The Time attribute has the format
DD-MMM-YY hh:mm:ss.sssss
The Timenum attribute is the equivalent floating point representation of the time in number
of seconds past January 1, 1970 00:00:00.0000. The archive preserves the timestamp with
accuracy of 15.25 microseconds.
Note: The default time accuracy of 5 digits might compromise a sub-second time-
stamp. Expand to 6 or 7 digits before editing or deleting such events.
Using Annotations
Since release 3.3, piconfig supports annotation to archive values, in both pisnap and piarc
tables. We recommend using piconfig only for reading annotations. Annotations should be
added using PI-SDK applications that are designed for that purpose.
10.4.8 PI Batch Unit Table
The Batch Subsystem monitors batches that run on units in a manufacturing plant. This table
contains configuration of the units. See Batch Subsystem in the PI Server Applications Guide
for details on how to manage data in this table.
The table name is Pibaunit. The primary key is Unitname.
The following attributes are defined:
Table 10–5. PI Batch Unit Table Attributes
Attribute Definition
UNITNAME Defines the UNIT name. UNITNAME is the primary index of the Pibaunit
Table.
Cannot include the \ character.
NEWUnitName Used to rename an existing unit.
ActiveTag PI Tag which indicates batch activity on Unit.
PI Server System Management Guide Page 207
Chapter 10 - The piconfig Utility
Attribute Definition
ActiveType Interpretation of ActiveTag values. Pulse, the default, starts on batch on
transition from 0 to 1 or greater. Step, starts a new batch on any value
change.
BIDEXPR Defines an expression consisting of PI Tags and text to generate a
BATCHID when a batch begins on a unit.
The value of the evaluated expression cannot contain a \ character.
DataAccess Security attribute, which specifies access to batches created on the unit.
DataGroup Group membership of the batches created by the unit.
DataOwner Owner of batches created by the unit.
Description Description of unit.
EvalDelay Specifies delay, from batch start, before evaluating product and batch ID
expressions.
MergeConsecutive If non-zero, treats short batch stop and restarts as one contiguous batch.
PRODEXPR Defines an expression consisting of PI Tags and text. This expression is
used to generate a PRODUCT name when the batch begins on a unit.
The value of the evaluated expression cannot contain a \ character.
UnitAccess Security attribute, which specifies access to the unit.
UnitGroup Unit group membership.
UnitOwner Unit owner.
10.4.9 PI Batch Alias Table
Aliases are defined and maintained by the PI Batch Subsystem. An alias is used to define a PI
tag that corresponds to an attribute (generally, the name of some measured quantity) of a
process unit. The table is simple—it consists of two columns—an alias name and a PI tag
name. The alias name has two components: a unit name and an attribute name. Alias syntax
is:
\\unit name\common name
For example:
\\Reactor1\temperature
The unit name must be a defined PI Batch unit, that is, an entry for it must exist in the
PIbaunit Table. The PI tag name must also be valid.
See Batch Subsystem in the PI Server Applications Guide for details on how to manage data
in this table.
The table name is Pibaalias. The primary key is Alias.
Page 208
10.4 - Piconfig Commands and Tables
Table 10–6. PI Batch Alias Table Attributes
Attribute Description
Alias Unit name and attribute. The syntax for alias names in this table is:
\\unitname\attribute.
Tag PI tag corresponding to the attribute.
NEWAlias Used to rename an existing alias.
10.4.10 PI Batch Table
The Batch Subsystem records information about each batch in this table, whether the batches
are in progress or terminated. See PI Server Applications Guide, Chapter 5, Batch
Subsystem, for details on how to access data in this table.
The table name is Pibatch. The primary key is Handle. It is rarely used in batch searches.
The following attributes are defined:
Table 10–7. PI Batch Table Attributes
Attribute Description
UnitName Unit name to search
Handle Unique identifier for a single batch entry
BID Batch ID
ProdID Product ID
StartTime Batch start time
StartStatus Status of batch start time
StopTime Batch end time
StopStatus Status of batch end time
BIDsearch Wild card search string for batch IDs
ProdIDsearch Wild card search string for product IDs
SearchStart Time to search from
SearchStop Time to search to
Count Maximum number of batches to retrieve
NEWUnitName Changing the unit on which a batch is run by altering attribute is not supported.
Note: The PI Batch Subsystem refers to the older PI Server Batch support. The PI
Module and PI Batch Database approach is replacing the PI Batch Subsystem. The
PI SDK contains the best documentation of the Module and Batch Databases.
PI Server System Management Guide Page 209
Chapter 10 - The piconfig Utility
10.4.11 PI Subsystem Table
The PI Subsystem Table shows subsystem-specific attributes and statistics. This read-only
table is useful for troubleshooting. To load this table, the subsystem in question must be
specified. The table name is Pisubsys. For example, to view attributes associated with
pisnapss, enter the following command:
piconfig> @table pisubsys,pisnapss
Note: This table has no real primary key since there is only one record.
The set of attributes available on this table varies with the platform type. The table attributes
are:
Table 10–8. Subsystem Table Attributes
Attribute Description Operating System
PISubsysName Subsystem Name All
IDNumber Unique ID of Computer UNIX (Not all versions of UNIX support this
attribute)
Machine Hardware ID UNIX
OSNodeName TCP/IP host name UNIX
OSRelease Operating system release UNIX
OSBuild Operating system build Windows
OSSysName Operating system name All
OSVersion Operating system version All
PIStartupTime Subsystem startup time All
PIVersion Subsystem version All
Viewing PI Subsystem Information
Here’s an example listing attributes of the Subsystem Table.
To list the record, use the ostructure command and specify pisubsysname as *
(Ls - PISUBSYS) piconfig> @ostr pisubsysname
(Ls - PISUBSYS) piconfig> @ostr osbuild, osversion
(Ls - PISUBSYS) piconfig> @ostr pistartuptime, piversion
(Ls - PISUBSYS) piconfig> @selec pisubsysname=*
(Ls - PISUBSYS) piconfig> @ends
pisnapss
Service Pack 6,4.0.1381
4-May-03 17:08:20,PI 3.3.361.43
The operating system attribute names may vary because they are operating system dependent.
Page 210
10.4 - Piconfig Commands and Tables
10.4.12 PI Subsystem Statistics Table
The PI Subsystem Statistics Table shows detailed subsystem statistics. This read-only table
also requires subsystem specification. The table name is Pisubsysstats. For example, to view
statistics for pisnapss enter the following command:
piconfig> @table pisubsysstats,pisnapss
The table attributes are:
Table 10–9. PI Subsystem Statistics Table Attributes
Attribute Description
PISubsysName Subsystem Name
BytesRecv Number of bytes received since startup.
BytesSent Number of bytes sent since startup.
MsgRecv Number of messages received since startup.
MsgSent Number of messages sent since startup.
RecvErrors Number of receive errors since startup.
SendErrors Number of send errors since startup.
StartTime Subsystem startup time.
The bytes and messages received and sent refer to all inter-process communications.
Viewing PI Subsystem Statistics
The following example lists the statistics for pisnapss. There is no primary key so simply
specify pisubsysname name as *
(Ls - PISUBSYSSTATS) piconfig> @ostr PIsubsysname
(Ls - PISUBSYSSTATS) piconfig> @ostr bytesrecv, bytessent
(Ls - PISUBSYSSTATS) piconfig> @ostr msgrecv, msgsent
(Ls - PISUBSYSSTATS) piconfig> @ostr recverrors, senderrors
(Ls - PISUBSYSSTATS) piconfig> @ostr starttime
(Ls - PISUBSYSSTATS) piconfig> @select pisubsysname=*
(Ls - PISUBSYSSTATS) piconfig> @ends
pisnapss
99626,57637
434,432
0,0
4-Sep-02 17:08:19
Some SUBSYSSTATS tables also contain subsystem specific data. This data is usually
presented for troubleshooting purposes. After setting a SUBSYSSTATS table always show
the available attributes with the @?atr command.
PI Server System Management Guide Page 211
Chapter 10 - The piconfig Utility
10.4.13 PINet Manager Statistics Table
The PINet Manager Statistics Table displays information on active connections as well as
some information specific to pinetmgr. This table is read-only.
The attributes of this table are:
Table 10–10. PINet Manager Statistics Table Attributes
Attribute Description
ID Connection ID. This is the primary key.
BytesRecv Bytes received by the connection.
BytesSent Bytes sent by the connection.
ConStatus Connection status.
ConTime Time connection was established.
ConType Connection type
PI API connection PI API or VMS PINet node
Local connection PI SDK or PI Subsystem directly connected to pinetmgr
Remote Router Connection from PINS to PI server
Remote Resolver Connection to a PINS (other end of the above connection)
MsgSent Messages sent by connection.
Name Connection name.
NetType Connection network type
WIN32 named pipes, UNIX, or TCP/IP
OSBuild Operating system build.
OSSysName Operating system name.
OSVersion Operating system version.
PeerAddress IP Address of connecting machine.
PeerName Host name of connecting machine.
PIVersion Version of PI Network Manager.
PIPath PI Server root directory on the server. This item is the same for all connections.
ProtocolVersion PI Protocol version of connecting application.
RecvErrors Number of receive errors on the connection.
SendErrors Number of send errors on the connection.
The table name is Pinetmgrstats. The Connection ID is assigned based on order of
connection. Since connection names are not required to be unique, the ID is the primary key.
Page 212
10.4 - Piconfig Commands and Tables
Viewing PI Connection Information
Specifying the ID as pinetmgr accesses statistics associated with pinetmgr. Specifying ID as
* will list all connection statistics and pinetmgr statistics. ID, Name, and ProtocolVersion
are the only attributes that apply to pinetmgr. ConTime refers to startup time of pinetmgr.
The following example lists all attributes of all current connections:
* (Ls - PINETMGRSTATS) piconfig> @ostr ID, BytesRecv, BytesSent,
ConStatus
* (Ls - PINETMGRSTATS) piconfig> @ostr contime, contype, msgsent, name
* (Ls - PINETMGRSTATS) piconfig> @ostr nettype, peeraddress, peername
* (Ls - PINETMGRSTATS) piconfig> @ostr
protocolversion,recverrors,senderrors
* (Ls - PINETMGRSTATS) piconfig> @selec id=*
* (Ls - PINETMGRSTATS) piconfig> @ends
6,24,132447,[0] Success
4-Sep-02 17:08:05,Local connection,759,pimsgss
WIN32 Named pipe,,
3.1,0,0
*----------
7,24,108008716,[0] Success
4-Sep-02 17:08:12,Local connection,1794287,piupdmgr
WIN32 Named pipe,,
3.1,0,0
*----------
8,24,3710706,[0] Success
4-Sep-02 17:08:19,Local connection,64851,pisnapss
WIN32 Named pipe,,
3.1,0,0
*----------
9,24,1974873,[0] Success
4-Sep-02 17:08:27,Local connection,24266,piarchss
WIN32 Named pipe,,
3.1,0,0
*----------
10,24,102724,[0] Success
4-Sep-02 17:08:34,Local connection,1072,pibasess
WIN32 Named pipe,,
3.1,0,0
*----------
16,24,372707,[0] Success
4-Sep-02 17:09:13,Local connection,2059,PIPESCHD
WIN32 Named pipe,,
3.1,0,0
*----------
12,24,60055,[0] Success
4-Sep-02 17:08:49,Local connection,672,pisqlss
WIN32 Named pipe,,
3.1,0,0
*----------
13,24,9420677,[0] Success
PI Server System Management Guide Page 213
Chapter 10 - The piconfig Utility
4-Sep-02 17:08:57,Local connection,198466,pitotal
WIN32 Named pipe,,
3.1,0,0
*----------
14,24,154881,[0] Success
4-Sep-02 17:09:04,Local connection,2828,pibatch
WIN32 Named pipe,,
3.1,0,0
*----------
15,20,12987712,[0] Success
4-Sep-02 17:09:12,Local connection,1618340,PipeE
WIN32 Named pipe,127.0.0.1,localhost
1.8,0,0
*----------
20,20,33340,[0] Success
4-Sep-02 17:43:44,Local connection,2715,RmpSE
WIN32 Named pipe,127.0.0.1,localhost
1.8,0,0
*----------
21,20,50446,[0] Success
4-Sep-02 17:43:45,Local connection,3349,RandE
WIN32 Named pipe,127.0.0.1,localhost
1.8,0,0
*----------
23,24,38287,[0] Success
5-Sep-02 15:01:35,Local connection,6,piconfig
WIN32 Named pipe,,
3.1,0,0
*----------
PINetMgr, , ,
, , ,PINetMgr
, ,
3.1, ,
*----------
10.4.14 PI Users Table
This table defines PI users and records their assignment to groups. For details, see PI System
Management and PI Server Databases in the PI Server Reference Guide
The table name is Piuser. The primary key is User. The table attributes are:
Table 10–11. PI Users Table Attributes
Attribute Description
User User name
Description User description
Groups List of groups to which the user belongs
Context Reserved for future use
Page 214
10.4 - Piconfig Commands and Tables
Attribute Description
NEWUser Used to rename an existing user
The description attribute is used to specify any type of user information, such as address or
title. The user may be added to multiple groups.
Note: Users are assigned to groups using the Piuser table. Attempting to change
the group membership of users via the pigroup table has no affect.
10.4.15 PI Group Table
This table defines groups to which PI users may be assigned. It is discussed in PI Server
Reference Guide Chapter 3, PI Server Databases.
The table name is Pigroup. The primary key is GROUP. The table attributes are as follows.
Table 10–12. PI Group Table Attributes
Attribute Description
Group Group name
Description User description
Users List of users belonging to the group
NEWGroup Used to rename an existing group
10.4.16 PI Thread Table
Table 10–13. PI Thread Table Attributes
Attribute Description
ID Operating system thread ID
Action Edit only – see table below
ActValue Edit only – value for the action performed
Calls Number of calls served by the thread
Handle Subsystem handle
PoolName Every thread belongs to a thread-pool. We are mainly interested in the RPC
thread pool, which serves client calls to a subsystem.
Priority The thread priority
State The thread state – generally “Wait” or “InUse”
PI Server System Management Guide Page 215
Chapter 10 - The piconfig Utility
Table 10–14. PI Thread Table Actions
Action Description Action Value
Priority Change thread priority 1 to increase -1 to decrease
Suspend Temporary suspensions of thread execution
Resume Resume a thread previously suspended
Terminate End this thread
* (Ls - ) PIconfig> @table pithread,piarchss
* (Ls - PITHREAD) PIconfig> @ostru
id,calls,handle,poolname,priority,state
* (Ls - PITHREAD) PIconfig> @ends
1500,7,212,RPC,0,Wait
1596,9,216,RPC,0,Wait
1504,11,220,RPC,0,Wait
1116,18,224,RPC,0,InUse
2124,9,228,RPC,0,Wait
3664,8,232,RPC,0,Wait
2592,9,236,RPC,0,Wait
3812,7,240,RPC,0,Wait
1216,0,816,EVQ,0,Wait
2488,0,820,EVQ,0,Wait
2736,0,824,EVQ,0,Wait
3140,0,828,EVQ,0,Wait
3012,0,832,EVQ,0,Wait
2356,0,840,Shift,0,Wait
3336,655015,0,Main, ,
3888,166401,248,Message, ,
3016,190,260,Read, ,
Note: The PIThread table is primarily a monitoring tool. We recommend using it only
with in-depth understanding of threads. Specifically, avoid using it for any
modification or thread creation.
10.4.17 PI Database Security Table
Database level security controls the access rights of users and groups to the various system
databases; for example, create a point. Earlier releases required user “piadmin” to edit a
database.
Database security is accessed through the Dbsecurity Table. This is a general database
security table—its structure applies to all databases. The record structure looks like this:
Table 10–15. PI Database Security Table Attributes
Attribute Description
DBName Database name
Page 216
10.4 - Piconfig Commands and Tables
Attribute Description
Access Security attribute, which specifies access to the table
Group Group name
Owner PI user name declared to be the owner of the table. Defaults to Piadmin.
The following examples shows how to access and modify the DBsecurity table.
C:\pi\adm>PIconfig table dbsecurity
* (Ls - DBSECURITY) PIconfig> @ostru dbname, owner,group,access
* (Ls - DBSECURITY) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
PIARCADMIN,PIadmin,PIadmin,o:rw g:r w:r
PIARCDATA,PIadmin,PIadmin,o:rw g:r w:r
PIBatch,PIadmin,PIadmin,o:rw g:r w:r
PICampaign,PIadmin,PIadmin,o:rw g:r w:r
PIDBSEC,PIadmin,PIadmin,o:rw g:r w:r
PIDS,PIadmin,PIadmin,o:rw g:r w:r
PIHeadingSets,PIadmin,PIadmin,o:rw g:r w:r
PIModules,PIadmin,PIadmin,o:rw g:r w:r
PIPOINT,PIadmin,PIadmin,o:rw g:r w:r
pisnapss,PIadmin,PIadmin,o:rw g:r w:r
PITransferRecords,PIadmin,PIadmin,o:rw g:r w:r
PIUSER,PIadmin,PIadmin,o:rw g:r w:r
* (Ls - DBSECURITY) PIconfig> @mode ed,t
* (Ed - DBSECURITY) PIconfig> @istru dbname, owner,group,access
Modify the access to archive data and allow the operator group
* (Ed - DBSECURITY) PIconfig> PIARCDATA,PIadmin,operators,o:rw g:rw w:
*> PIARCDATA,PIadmin,operators,o:rw g:rw w:
Modify the access to base subsystem auditing and thread table
* (Ed - DBSECURITY) PIconfig> pibasess,PIadmin,operators,o:rw g:rw w:r
*> pibasess,PIadmin,operators,o:rw g:rw w:r
Modify the access to Update Manager thread table (no auditing in Update Manager)
* (Ed - DBSECURITY) PIconfig> piupdmgr,PIadmin,operators,o:rw g:rw w:r
*> piupdmgr,PIadmin,operators,o:rw g:rw w:r
* (Ed - DBSECURITY) PIconfig> @mode list
* (Ls - DBSECURITY) PIconfig> @ends
*PIconfig Err> Wild-card specs. missing, default to '*'.
PIARCADMIN,PIadmin,PIadmin,o:rw g:r w:r
PIARCDATA,PIadmin,operators,o:rw g:rw w:
pibasess,PIadmin,operators,o:rw g:rw w:r
PIBatch,PIadmin,PIadmin,o:rw g:r w:r
PICampaign,PIadmin,PIadmin,o:rw g:r w:r
PIDBSEC,PIadmin,PIadmin,o:rw g:r w:r
PIDS,PIadmin,PIadmin,o:rw g:r w:r
PIHeadingSets,PIadmin,PIadmin,o:rw g:r w:r
PIModules,PIadmin,PIadmin,o:rw g:r w:r
PI Server System Management Guide Page 217
Chapter 10 - The piconfig Utility
PIPOINT,PIadmin,PIadmin,o:rw g:r w:r
pisnapss,PIadmin,PIadmin,o:rw g:r w:r
PITransferRecords,PIadmin,PIadmin,o:rw g:r w:r
piupdmgr,PIadmin,operators,o:rw g:rw w:r
PIUSER,PIadmin,PIadmin,o:rw g:r w:r
* (Ls - DBSECURITY) PIconfig>
Refer to the chapter Managing Security for a detailed discussion of database security and this
table.
10.4.18 PI Trust Database
This table is used to allow a client application to connect to the PI Server as a specific PI user
without requiring that the client application explicitly log in. This is required for unattended
client applications such as interfaces.
The client and PI Server obtain the client’s credentials from the operating system, domain
controller, and network software. These include any of the following: domain name, IP host
name, IP address, and username.
Select this table using the command:
@table PITRUST
The primary key is TRUST. The table attributes are:
Table 10–16. Trust Table Attributes
Attribute Description
Trust A name for this trust relationship
Domain The domain name for the client machine
IPAddr IP address of client machine
NetMask Network address mask in the format (255.255.255.255)
IPHost Name of client machine
OSUser User name under which the client is running
AppName Application name
PIUser Associated PI user
Any field specified as NULL string (“”), is ignored when incoming connection are matched
against the table.
Domain, IPHost, AppName, and OSUser must be specified exactly or not at all.
IPAddr and NetMask must be specified together. If you provide a value for one, you
must also provide the other.
PIUser must always be specified as either a currently existing PI user in the User
Database or as a dollar sign ($). The dollar sign must be paired with a $ in either
OSUser or IPHost. If the trust matches incoming credentials and there is no PIUser
Page 218
10.4 - Piconfig Commands and Tables
with the same name, an error occurs at run-time. This method of specification
matches any user or any machine that passes the domain controller validation of their
login credentials.
10.4.19 PI General Table Interface
piconfig has a General Table interface, which includes the Timeout, Firewall, and Trust
databases. Select the table using the command:
@table PI_GEN,tablename
Note: Piconfig cannot access remotely the General Tables, only on the local
machine. However, the SMT tools have remote access.
PI Timeout Database
This table contains the PI Server timing parameters as well as many other configurable
parameters. Adjustment of these parameters should be done by the PI Server Administrator.
Select this table using the command:
@table PI_GEN, pitimeout
The primary key is NAME. The table attributes are:
Table 10–17. PI Timeout Table Attributes
Attribute Description
Name Timing attribute name
Value Timing value as a string
NEWName Used to rename an existing name
The PI Timeout database cannot be modified remotely.
PI Firewall Database
This table is used by the System Manager to control general access to the PI Server by
network address.
Select this table using the command:
@table PI_GEN, pifirewall
The primary key is HOSTMASK. The table attributes are:
Table 10–18. PI Firewall Table Attributes
Attribute Description
HostMask The name or IP address of a client computer
Value ALLOW or DISALLOW
PI Server System Management Guide Page 219
Chapter 10 - The piconfig Utility
Attribute Description
NEWHostMask Used to rename an existing HostMask
The PI Firewall Database cannot be modified remotely.
PI Proxy Database
As of release 3.3, the Proxy Database is no longer in use. During upgrade, its contents are
converted to PI Trust Database records.
10.5 Helpful Hints
10.5.1 Abbreviations
All piconfig commands can be abbreviated to four characters.
10.5.2 Case-sensitivity
In UNIX systems, program and file names are case-sensitive. This includes HP-UX, Digital
UNIX, Solaris, and AIX.
Windows program and file names are case preserving, but not case-sensitive.
The piconfig commands, attribute names and table names are not case-sensitive, but the data
are case-sensitive. The case-sensitivity on PIGEN tables may be changed for both of these
parameters by using the case command.
10.5.3 Command Input Files
The piconfig commands and data can be placed in any number of files and executed using
the input command.
If the input file contains many lines, all of which have the same command, the following
construct may be useful:
@command @command_file
In this construct, the command specified will be prepended to every line in the command file.
This is useful, for example, when a file with input structure lines have been generated from
another program, such as PIDIFF, or when the same complex structure is used for both input
and output.
10.5.4 Input Line Length
By default, piconfig reads from its input up to 1024 characters. This is sufficient in almost all
cases.
If the input contains lines longer than 1024, reset the input buffer using the line command, for
example:
@line 4000
Page 220
10.5 - Helpful Hints
10.5.5 Using Quoted Strings
There are two main reasons to use quotes (single or double) with piconfig data:
The data contains an embedded delimiter character that will confuse correct parsing
either on input or on output that will be used in the future by piconfig itself or by
other applications (Microsoft Excel, for example).
The specific table requires certain data to be enclosed in quotes (single or double) for
its own further processing. Examples include the pibatch tables and the Performance
Equations expressions configured in the extended-descriptor of a point.
Piconfig attempts to parse incoming data into fields using the delimited character. If a field
starts with a quote (either single or double) piconfig ignores any delimiter until a matching
quote is found.
When an already quoted string must contain embedded quotes, there are two options:
Enclose strings containing double quotes in single quotes and vice versa
Escape the embedded quotes with a backslash ( \ )
Note: A field containing the delimiter character must be quoted. A field that starts
with a quote should be quoted using the other type of quote. A field that starts with
one type of quote and contains the other type as well should be quoted, and the
embedded quotes must be escaped. ?
For example, a field containing:
unit,function
should be specified as
"unit,function"
Or
'unit,function'
The expression
'sinusoid' > 'tag33'
should be specified as
"'sinusoid' > 'tag33'"
Or
('sinusoid' > 'tag33')
The expression
'sinusoid' + "t-1d" + "ABC"
Should be specified as
"'sinusoid' + \"t-1d\" + \"ABC\""
PI Server System Management Guide Page 221
Chapter 10 - The piconfig Utility
When the output from piconfig is used in another session or by another program such as
Excel, make sure that fields containing the delimiter character are quoted (on output). Using
the quote command does this:
@quote "
or
@quote '
10.5.6 Sending Values as Strings
Piconfig sends all table values as strings. When sent to the Snapshot (Archive values go via
the Snapshot), it is interpreted in the following way:
For a string tag:
Use the incoming string without change.
For a digital tag:
Look for a state in the tag’s state-set.
Look for a state in the System digital-set.
Interpret the string as a numeric offset and check if within range of the tag’s set.
For all other tag types:
Look for a state in the System digital-set.
Convert the string to a value of the tag’s type.
10.5.7 Boolean Values
When a field in any table is a Boolean flag, for example the Step flag in the pipoint table, the
input data can be specified as:
1 / 0
Yes / No
True / False
Piconfig always sends the data to the table as a string as explained above.
The table owner, in this example the Base Subsystem, will interpret the incoming string as a
Boolean value 1 / 0.
This can cause some confusion in the digital-states table when states are defines as the strings
“1”, “2”, “3”,…We recommend that you configure digital states like this: “One, Two,…” or
“State1, State2”,…
Similarly, if you want to define the states “true”,”false”, make a set with “false” in the 1st
position followed by “true” to correspond to 0 and 1. Alternatively, modify these names: “S-
true S-false”.
Page 222
10.5 - Helpful Hints
10.5.8 Configuration Persistence
Table specifications remain in effect until the next table command. Mode specifications
remain in effect until the next mode command.
For all structure formats, the structure specifications remain in effect until a table is changed.
New structure specifications are added to previous specifications until they are used to
process data. After this, new specifications overwrite previous ones. Select, and modify
specifications behave similarly. These two commands are also cleared on mode and table
changes.
10.5.9 Command Line Parameters
The piconfig commands may be specified as command line parameters when invoking
piconfig. Each pair of parameters is assumed to be a command. These commands will be
executed before the first prompt is issued. Some examples are:
$ piconfig comchar ?
$ piconfig table pipoint stype fixed
$ piconfig help
10.5.10 Changing Special Characters
The special characters in piconfig can be customized to be any single, visible character that is
not a number or a letter. These special characters include:
command character (ComChar)
comment character (comment)
delimiter character (delimiter)
quote character (quote)
Specifying a quote character causes any field containing the delimiter character (comma by
default), to be enclosed with the specified quote character. Use this option any time the output
is being re-used for input, for example when the extended descriptor contains commas and
you want to create a comma-separated file.
In this example, the comment character is changed:
$ piconfig
*piconfig> * This is a comment.
*piconfig> * Change the comment character to !
*piconfig> @comment !
*piconfig> ! Now we have a new comment character.
*piconfig> !Change back to the original comment character.
*piconfig> @comment *
*piconfig> * Now we have our original comment character.
Similarly, you can change the delimiter used in delimited format to be a different character
than comma (,). To display the currently assigned characters, mode, and table, use the status
command.
*piconfig> @status
---- piconfig Status ----
PI Server System Management Guide Page 223
Chapter 10 - The piconfig Utility
Mode: List
Characters: Command: <@> Delimiter: <,> Comment:<*> Quot:<>
Struc. Type IN: <Delim.> OUT: <Delim.>
Error count: 3 Max: 10
Curent table: <PIPOINT> Cur. Prim.: <> Def. Prim: < >
Nesting level : 0
Node: <127.0.0.1,piadmin>
10.5.11 Convert Mode Example
The following is a simple example of converting fixed format data into delimited format. This
can be helpful in PI2 to PI3 conversions. Convert mode can be used to reorder fields in a
record or to apply modifications to data.
e:\PI\adm>type fixed.dat
*123456789012345678901234567890
Tag1 0 100
tag2 -5 555
e:\PI\adm>piconfig mode convert
* (Cv - ) piconfig> @isty fixed
* (Cv - ) piconfig> @osty delim
* (Cv - ) piconfig> @istru tag,1,1,10
* (Cv - ) piconfig> @istru zero,1,10,5
* (Cv - ) piconfig> @istru span,1,20,5
* (Cv - ) piconfig> @ostru zero,span,tag
* (Cv - ) piconfig> @echo none
* (Cv - ) piconfig> @input fixed.dat
0 , 200,Tag1
-5 , 655,tag2
10.5.12 Converting Point Database Information from PI2 to PI Server
To transfer information from a PI OpenVMS Point Database to a PI Server Point Database,
see the OSIsoft support Web site for more information.
10.5.13 Hexadecimal and Octal Numbers
By default, piconfig uses decimal notation (base 10). To specify numbers in octal, precede
them with “0”. To specify numbers in hexadecimal, precede them with “0x”. For example,
the numbers 10, 012, and 0xA specify the same number.
A few PI 2.x pidiff attributes are not used in piconfig. See the OSIsoft support Web site for
more information.
Page 224
Chapter 11. PI TROUBLESHOOTING AND REPAIR
Data passes through many steps on the way into and out of the Archive. The main strategy to
apply when troubleshooting is to determine which parts of the data path are malfunctioning,
and also, which parts are functioning correctly.
The first step is to isolate the problem to a single computer, either client or server, or to the
network. Follow the steps in the Troubleshooting Checklist to isolate the problem area. A
table of error messages is available in Appendix A: PI Messages on page 281.
The second step is to isolate the problem further to a particular client program or PI
subsystem. See Verifying PI Processes on page 228, and PI System Data Files on page 235,
for help with this.
The third step is to determine the exact cause of the problem. This will lead to a good
understanding of what is needed to fix the problem, repair the damage, and prevent a
recurrence. If needed, go to the Repairs section to repair data files such as Archives or Point
Database.
After working through the Troubleshooting Checklist, you may still not have resolved your
problem. In this case, you will want to call OSIsoft Technical Support for some help. The
technical support engineer will ask for some key information and also may ask to dial into
your system in order to do some hands on troubleshooting.
11.1 Troubleshooting Checklist
Determine which computers exhibit the problem:
1. Determine which computers exhibit the problem:
• Client computer(s)
• Server computer(s)
• Interface computer(s)
The best test is to run the questionable system against a known good system. If all
computers exhibit the problem, it is more likely a network problem. If all clients
exhibit the problem, it indicates a server problem.
2. Is PI the only program having trouble? If other programs on the same computer are
giving trouble, this indicates a hardware or networking problem. Telnet is a good
program to try to run. If Telnet works correctly, the network is not likely to be the
problem.
PI Server System Management Guide Page 225
Chapter 11 - PI Troubleshooting and Repair
3. If there is a client problem, check security. Log in as the user piadmin. Check the
setup.log and pipc.log files in the c:\pipc\dat directory. Also check the server central
log file using the pigetmsg utility. A table of error messages is available in Appendix
A: PI Messages on page 281. If a trend in PI ProcessBook “flatlines,” see the section
on p. 255.
4. If there is a server problem, verify that all PI processes are running.
On Windows, type
net start
at the command prompt to list all processes running as Services.
On UNIX, use the piverify.sh utility.
PI Systems may take several minutes to start; loading the Point Database, Snapshot
and Archives takes most of the time. Utilities, such as piartool and piconfig, are not
fully operational until startup has completed.
5. Even if the process is listed as running, it may be in a state where it is not
communicating with pinetmgr. Verify that each PI process is communicating
properly by using the utilities listed in the Verifying PI Processes section below.
6. Try to get the exact error message. Error numbers may be translated to text using:
pidiag -e <errno>
There is a list of error messages in Appendix A: PI Messages on page 281.
7. Note the time of the problem and which subsystems have stopped running. Inspect
the message log using the pigetmsg utility, and the individual process log files. See
Appendix A: PI Messages on page 281.
8. On Windows, try running with pistart.bat, rather than as Services. There may be
additional status messages displayed in the command windows that may be helpful.
9. On HP-UX, verify SHLIB_PATH environment variable is defined correctly. It
should point to the directory /opt/PI/lib.
10. On Solaris, verify LD_LIBRARY_PATH environment variable is defined correctly.
It should point to the directory /opt/PI/lib.
11. If a subsystem crashes, there may be additional information that would be useful to
our developers.
Dr. Watson is the default just-in-time debugger for Windows systems. To install Dr.
Watson as default debugger, run the following command: drwtsn32.exe -i
Dr. Watson process traps unhandled process exceptions, also known as process
crashes. Dr. Watson captures the process state on crash and writes details to
drwtsn32.log. Optionally the entire process image is written to user.dmp. The
location of these files, as well as other Dr. Watson behavior, is configurable. Running
drwtsn32.exe interactively starts the configuration dialog. Recommended settings are
as follows:
• Log File Path: Default location is recommended.
Page 226
11.1 - Troubleshooting Checklist
• Crash Dump: Default name is recommended. Note this file may be over written;
after a process crash copy this file to a safe location.
Number of Instructions: 25
Number of errors to save: 25
Crash Dump Type: Full
Dump Symbol Table: Select
Dump All Thread Contexts: Select
Append to Existing Log File: Select
• Visual Notification: Do not select. Servers typically run unattended; therefore,
there is no user to see the notification.
Sound Notification: Do not select.
Create Crash Dump File: Select
On UNIX systems, look for a file called core in the PI\bin or PI\adm directories. This
is a binary file.
These files are useful only if they were created while running a debug version of PI.
Debug versions are not shipped by default. OSIsoft Technical Support will arrange
for a download of a debug build of PI if necessary.
12. If you have a pinetmgr problem, use:
netstat -a
to determine if there is any other process talking on port 5450. If so, this indicates
that at one time pinetmgr was communicating successfully.
You may need to use piconfig to adjust the timing parameters in the PITimeout
Table. Refer to the section called Tuning the PI System later in this chapter.
13. If you have an Archive or Snapshot problem, use the piartool -as and piartool -ss
utilities to gather more information about the data flow.
14. Next, try retrieving a Snapshot three different ways; the combined results of all three
tests helps pinpoint the source of the problem:
• apisnap from a remote node (uses API + network)
• apisnap from the home node (uses API)
• piconfig < pisnap.dif from the home node (uses internal communication)
To determine if the Archive has been corrupted, use piartool -aw.
15. If this is an Update Manager problem, use the pilistupd utility to see which processes
are signed up for events.
16. Determine if the problem is with all points on all interfaces or just a few points on
some interfaces.
17. Each PI System is distributed with a standard set of points including SINUSOID,
CDEP158, and CDM158. Each PI System is distributed with the Random and
RampSoak Simulators.
18. If this is an interface problem on a remote node, check security. There must be an
entry in the PI Trust Table for that node or specifically for that interface. Also check
PI Server System Management Guide Page 227
Chapter 11 - PI Troubleshooting and Repair
the Firewall database. Check the individual interface log files as well as the central
log file using the pigetmsg utility. See Appendix A: PI Messages on page 281. If an
API interface is not able to connect, be sure that the PI Base Subsystem, PI Archive
Subsystem, and PI Snapshot Subsystem are running.
19. If an installation or upgrade problem, check the log file:
• UNIX - /tmp/piinstall.log
• Windows – PIPC\dat\SetupPIServer.log and PIPC\dat\PIServerMaster.log. See
the Getting Started manual for more information.
20. Check ownership and execute permissions on files that are giving trouble. Try
running as Root (UNIX) or Administrator (Windows). If the trouble goes away when
you run as the System Administrator, then you have a permission problem.
21. Read the PI release notes to determine if this is a known problem. Another source of
information is the OSIsoft Technical Support Web site, http//techsupport.osisoft.com,
which has technical notes posted.
If you haven’t solved the problem after working through this checklist, you will need to
phone or email OSIsoft Technical Support.
11.2 Verifying PI Processes
When PI is running, all of the PI processes should be running. When PI is stopped, all of the
PI processes should be stopped. The exception is pishutev, which only runs briefly at PI
startup.
Even if a process is listed as running, it may be in a state where it is not communicating with
pinetmgr. You can verify that each PI process is communicating properly by using the
utilities outlined in this subsection.
11.2.1 Verifying PI Processes on Windows Systems
On Windows systems, you can list all processes that are started as Services by typing at the
command prompt:
net start
PI processes or interfaces that are running interactively will each have a separate command
window that is labeled with the process name.
11.2.2 Verifying PI Processes on UNIX Systems
On UNIX systems, there is a utility called piverify.sh, which reports on the running status of
all of the PI processes, including the interfaces that are shipped with PI. Change to the adm
subdirectory and type:
piverify.sh
Page 228
11.2 - Verifying PI Processes
11.2.3 Communication with PINet Manager
The PInet Manager process is the communication router for PI. All client processes
communicate with PI Subsystems via pinetmgr. All of the PI processes in PI Server
communicate with each other via pinetmgr. None of the PI utilities will work if pinetmgr is
not running properly.
The TCP/IP port for communicating with PI defaults to 5450. This is a change from PI
OpenVMS systems, which default to port 545. The change is important because it allows PI
to run without superuser privileges and thus provides a foundation for a more secure system.
You should not need to change the TCP/IP default port. The only reason for doing so would
be to resolve a port number conflict with other software. Contact OSIsoft Technical Support
if you are affected by this problem.
11.2.4 Pimsgss
All PI processes send messages to the PI Message Subsystem process, which writes messages
to the PI Message Log.
A simple way to test pimsgss is to run the pigetmsg utility. If pimsgss is not working
correctly, you will see the following:
D:\PI\adm>pigetmsg
Message ID [A], (0-n) (A)ll (T)ail (F)lush (Q)uit (?):
Message Source [*], (?):
Start time in PI format [*-15m], s(K)ip (?):
End time in PI format [*], s(K)ip (?):
Maximum count [], (0-n) (?):
Text mask [*], (?):
Display count [], (0-n) (?):
[-10733] PINET: RPC Resolver is Off-Line.
At PI System startup, there is a short time when pimsgss is not yet running. During this time,
and at any other time when pimsgss is not functioning, PI Systems running on Windows will
direct messages to the system event log. You can read this messages using the Event Viewer
application in the Administrative Tools group. When the pimsgss starts, it will merge
messages from the Windows Event Log into the PI Server Message Log.
The behavior on UNIX differs from the above. PI Systems running on UNIX will send
messages to the individual subsystem ASCII message logs in the PI/log directory when the
pimsgss is not available. These are:
Pinetmgr.log
Pibasess.log
Piarchss.log
Pibackup.log
Pisnapss.log
Piupdmgr.log
Random.log
PI Server System Management Guide Page 229
Chapter 11 - PI Troubleshooting and Repair
Rmp_Sk.log
Pipeschd.log
Pibatch.log
Pishutev.log
PIsqlss.log
Pitotal.log
Pialarm.log
11.2.5 PI Update Manager
The Update Manager process provides event notification services. For example, ProcessBook
trends subscribe to Snapshot event updates to keep trends current; interfaces subscribe to
point database changes such as addition of new points.
A simple way to test piupdmgr is to run the pilistupd utility. If piupdmgr is not working
correctly, you will see the following:
C:\PI\adm>pilistupd
pilistupd -h for help
[-10727] PINET: RPC is Non-Existent
Producer Consumer Qual. Flags Pending
--------- --------- ------ ------ --------
status: [-12150] not registered in updmgr
11.2.6 PI Base Subsystem
The PI Base Subsystem process manages the Point and User Databases. It performs all
security authorization.
A simple way to test pibasess is to run the pisnap and piconfig utilities. If pibasess is not
working correctly, you will see the following:
$ pisnap.sh
PI API version 1.3.9.4
Attempting connection to localhost:5450
Error -994, connecting to localhost:5450
$ piconfig
* (Ls - ) piconfig> @table pipoint
*PIConfig Err> Table initialization error (PIPOINT
*@table pipoint
*[-10733] PINET: RPC Resolver is Off-Line
11.2.7 Snapshot Subsystem
The Snapshot Subsystem manages the Snapshot and the Event Queue. It handles compression
and sends events to the Archive.
A simple way to test pisnapss is to run the piartool -ss and pisnap utilities. If pisnapss is not
working correctly, you will see the following:
Page 230
11.2 - Verifying PI Processes
$ piartool -ss
Getsnaptablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line
$ pisnap.sh
PI API version 1.3.9.4
Attempting connection to localhost:5450
Enter tagname: sinusoid
Error: pisn_getsnapshotsx 3745992
Error: piar_getarcvaluex 3745992
Error: piar_getarcvaluesx 100
Tag = SINUSOID Point Number = 1 Type = Real-32
13 Hour Sine Wave!
Snapshot value
Value = ERROR ERROR
Status = ERROR
Latest archive value
Value = ERROR ERROR
Status = ERROR
11.2.8 Archive Subsystem
The Archive Subsystem, piarchss, manages the archives. It stores new events received from
the Snapshot Subsystem and responds to requests for Archive access. These might be
requests for compressed, interpolated or calculated data. The Archive Subsystem handles
archive shifts.
A simple way to test piarchss is to run the piartool -al, piartool -as and pisnap utilities. If
piarchss is not working correctly, you will see the following:
$ piartool -al
Getarchivefilelist Failed: [-10733] PINET: RPC Resolver is Off-Line
$ piartool -as
Getarcmemtablestatistics Failed: [-10733] PINET: RPC Resolver is Off-Line
$ pisnap.sh
PI API version 1.3.9.4
Attempting connection to localhost:5450
Enter tagname: sinusoid
Error: piar_getarcvaluex 0
Error: piar_getarcvaluesx 100
Tag = SINUSOID Point Number = 1 Type = Real-32
13 Hour Sine Wave!
Snapshot value
Value = ERROR ERROR
Status = ERROR
Latest archive value
Value = ERROR ERROR
Status = ERROR
Archive events are queued when piarchss is not operating correctly. The Event Queue count
is visible from B and piartool -qs.
11.2.9 Pishutev
This PI Subsystem inserts shutdown events into the PI Archive. Although it runs on PI start,
the shutdown events are time stamped with the previous shutdown time. PIShutev exits after
PI Server System Management Guide Page 231
Chapter 11 - PI Troubleshooting and Repair
completion; therefore, this process will not be present on systems that have been running for
a while.
11.2.10 Random Interface
The Random simulator provides simulated data for default PI points, such as sinusoid. On
Windows systems, Random is installed and started as a service; pisrvsitestart.bat starts the
service. On UNIX systems it is started by random.sh, which is called from pisitestart.sh,
which in turn is called from pistart.sh. See the OSIsoft Web site for current interface
documentation.
11.2.11 RampSoak Interface
The batch ramp-soak simulator, rmp_sk, creates batch-like data. On Windows systems
rmp_sk is installed and started as a service; pisrvsitestart.bat starts the service. On UNIX
systems, it is started by rmp_sk.sh, which is called from pisitestart.sh, which in turn is called
from pistart.sh. See the OSIsoft Web site for current interface documentation.
11.2.12 Running PI Processes Independently
Under normal operation, all of the PI processes are started up together using the pisrvstart
script, and are stopped together using the pisrvstop script. It is sometimes useful in
troubleshooting to run a subset of the PI processes. On Windows, pisrvstart.bat starts each
subsystem interactively in its own command window.
There are inter-process dependencies with the PI System. All PI Subsystems rely on
pinetmgr. The PI Update Manager provides key services; therefore most subsystems require
it to be running. Also, the Archive Subsystem requires the Snapshot Subsystem for normal
startup. In general, for troubleshooting, the following subsystems should be started in the
order listed:
• pinetmgr
• pimsgss
• piupdmgr
• pibasess
• pisnapss
• piarchss
Stopping a Windows Process
To stop and start processes on Windows, use the Services dialog in the Control Panel. You
can also do this from a command prompt using the net stop command.
For example, to stop the PI Message Subsystem, issue the command:
net stop pimsgss
Stopping a UNIX Process
The pistop_ss.sh and pistart_ss.sh are used to stop and start subsystems on UNIX. The
following example shows how piarchss is stopped and restarted.
Page 232
11.3 - UNIX Process Quotas
pistop_ss.sh piarchss
pistart_ss.sh piarchss
Alternatively, the kill -2 command can be used to stop any PI process. The following
example shows how piarchss is stopped and restarted.
$ cd /export/PI/adm
$ ps -upiadmin
PID TTY TIME COMMAND
9313 ? 0:00 bufserv
834 ttyp4 2:16 random
9335 ? 0:00 iorates
794 ttyp4 0:22 pibasess
1507 ttys1 0:00 ps
760 ttyp4 10:31 PIsnapss
9330 ? 0:00 ioshmsrv
12578 ttyp4 0:00 ksh
726 ttyp4 0:05 pimsgss
777 ttyp4 4:03 piarchss
9320 ? 0:01 mqsrv
9325 ? 0:00 mqmgr
836 ttyp4 0:00 rmp_sk
743 ttyp4 0:09 piupdmgr
709 ttyp4 870:48 pinetmgr
838 ttyp4 0:02 pipeschd
1492 ttys1 0:00 ksh
$ kill -2 777
$ ../bin/piarchss &
[1] 1508
$
11.3 UNIX Process Quotas
Some UNIX systems set process quotas unsuitable for servers. These quotas are used to keep
rogue applications, such as student projects, from monopolizing system resources such as
memory. In general, for systems dedicated as a server, most limits can be set to maximum.
Two key UNIX parameters should be reviewed.
Maximum data segment. This is the maximum private virtual memory size of a
process. The PI Archive and Base Subsystems are memory-intensive. The value of
this parameter should be set to 2 gigabytes, the maximum for 32-bit computers.
Max files/descriptors. This number is the maximum number of file handles or
descriptors a process may open; including TCP/IP connections. This value should be
set well above the maximum number of PI Server connections expected.
If your system has a large process count, you may see errors recorded in the PI Message Log
that report conditions such as no more processes and no more file handles. This can be caused
by a maximum process count limit that is too low. The quota may seem sufficient, but UNIX
often uses spawned processes for operations such as logging in, listing files, network
communications, or just leaving Window sessions open and idle.
PI Server System Management Guide Page 233
Chapter 11 - PI Troubleshooting and Repair
Here are some observed behaviors that may be caused by insufficient process count:
Archive shift not completing
PI Archive Subsystem fails to resume normal operations after a shift
Subsystems lose connection with the PI Network Manager
Interfaces and clients lose connection with PI
UNIX commands return the error can’t fork, out of process quota
As a general rule of thumb, you can assume that PI might need as many as 70 processes at
once. Changing this quota varies with the UNIX platform. In all cases, you must log in as
root to do any system configuration.
11.3.1 IBM AIX
Run the smit utility. Select System Environments, then Change/Show Characteristics of
Operating System. Change the variable Maximum number of processes per user.
11.3.2 Compaq Tru64
If you are using dxWindows, click on the Application Manager icon on the front panel,
double-click on System_Admin, double-click on Monitoring Tuning, and double-click on
Kernel Tuner. Select the proc subsystem, and examine the max-proc-per-user attribute.
If not using dxWindows, the utility:
# sysconfig -q proc
will give a list of current settings. Of these, examine:
max-proc-per-user = 64
max-threads-per-user = 256
task-max = 277
thread-max = 552
To change a value, you will have to create a stanza file. For more information about stanza
files, issue the UNIX command man stanza.
This file might look something like this:
proc:
max-proc-per-user=70
Before you apply any stanza file, always copy your current /etc/sysconfigdb file so that you
can back out your changes if you need to. To apply the changes to the system, use the
command
# sysconfigdb -m -f yourfile.name proc
where yourfile.name is the name of the file you created. You will have to reboot the system
before this change will take effect.
Page 234
11.4 - PI Server Data Files
11.3.3 HP-UX
Run the sam utility. Select Kernel Configuration, then Configurable Parameters find
“maxuprc” (maximum number of user processes) and “nproc” (maximum number of
processes).
If you change either value, you will need to create a new kernel (sam will ask you about this
when you try to exit), and the new parameters will not take effect until you reboot.
11.3.4 Sun Solaris
Run the sysdef utility. It will give a long list of current parameters. Somewhere in the middle
is:
*
* Tunable Parameters
*
1298432 maximum memory allowed in buffer cache (bufhwm)
986 maximum number of processes (v.v_proc)
99 maximum global priority in sys class (MAXCLSYSPRI)
981 maximum processes per user id (v.v_maxup)
30 auto update time limit in seconds (NAUTOUP)
25 page stealing low water mark (GPGSLO)
5 fsflush run rate (FSFLUSHR)
25 minimum resident memory for avoiding deadlock (MINARMEM)
25 minimum swapable memory for avoiding deadlock (MINASMEM)
*
To change the max number of processes, you can only change maxusers and add memory.
By default, maxusers is set to
Maxusers = number of megabytes of memory - 2
Maxusers can be changed by modifying the /etc/system file. To set maxusers to 70, for
example, the entry would be
set maxusers = 70
The quotas max_nprocs and maxuprc are dependent on maxusers. The relationship is:
max_nprocs (maximum number of processes system-wide):
10 + (16 * maxusers)
maxuprc (maximum number of processes per user):
max_nprocs - 5
11.4 PI Server Data Files
The PI Server data files are located in the PI\dat directory. Archives are likely to be
elsewhere.
PI Server System Management Guide Page 235
Chapter 11 - PI Troubleshooting and Repair
Pidiag -fb
Internally, most PI Server data files have the same low-level structure and are referred to as
PIFileBase-type files. The most notable exceptions are PI archive files. However, the
annotation files that correspond to the PI archive files are of type PIFileBase. The pidiag -fb
utility dumps the PIFileBase-type files and can be used to check PIFileBase-type files for
correctness. Pass it the complete pathname of the PIFileBase-type file as a parameter. For
example:
pidiag -fb c:\pi\dat\pidignam.dat
If it returns an error, you can either try to fix it with the following command:
pidiag -fbf c:\pi\dat\pidignam.dat
Note that PI must not be running when you attempt to repair a file. It is enough in most cases
to shutdown the owning subsystem
Note: In some cases pidiag -fbf will report the following:
Error reading input record # nn [-10466] No Record Available for
Passed recno
This is normal for records between the actual last record and the maximum allocated
record. The warning disappears if the utility is run a second time.
Piarcmem.dat
This binary file is the Snapshot Database used by pisnapss. It contains the most recent values
that have been sent to PI the Snapshot value for each point when PI is shut down. Pisnapss
periodically writes the latest Snapshot values to this file. This is a pifilebase-type database so
its validity can be checked and restored using pidiag -fb and pidiag -fbf.
Piarstat.dat
This binary file keeps track of registered archives. It is required by piarchss. If you are
having trouble with archive file registration, do not delete this file. Instead, see How to
Repair the Archive Registry in this chapter.
Pidignam.dat
This binary file stores each unique digital state name. This is a pifilebase-type database so its
validity can be checked and restored using pidiag -fb and pidiag -fbf.
Pidigst.dat
This binary file stores the digital sets; it references names stored in the above file. This is a
pifilebase-type database so its validity can be checked and restored using pidiag -fb and
pidiag -fbf.
Page 236
11.4 - PI Server Data Files
Pimapevq.dat
PimaNNNN.dat
These are the memory-mapped Event Queues. Most systems use the default single file
pimapevq.dat. Certain situations require multiple Event Queues; in this case the files take the
naming convention of pimaNNNN.dat where NNNN is an integer.
The memory mapped Event Queue serves two purposes. First, it used for moving events from
the Snapshot Subsystem to the Archive Subsystem. PISnapss places events which pass
compression into this queue. PIArchss takes these events and writes them to the Archive.
Second, this file provides storage of events when the Archive Subsystem cannot process
events such as during archive shifts or when the archive process is shutdown.
This file, as the name implies is a memory-mapped file. Memory mapped files allow for high
speed in-memory access with the security of being safely backed up to disk.
Pilastsnap.dat
This binary file stores the timestamp of the last completed Snapshot flush to disk. On PI
System startup, this timestamp is assumed to be the shutdown time and is used as the
timestamp for shutdown events. On orderly shutdown, this file will contain the true shutdown
time. On a system crash such as a power failure the Snapshot may be as old as the Snapshot
flush cycle time period. The Snapshot flush cycle is controlled by the SnapFlushCycle
timeout parameter, which is 15 minutes by default.
Pimsgtxt.dat
This binary file stores formatted message strings used by the pigetmsg utility. This is a
pifilebase-type database so its validity can be checked and restored using pidiag -fb and
pidiag -fbf.
Pipoints.dat
This binary file stores the Point database. This is a pifilebase-type database so its validity can
be checked and restored using pidiag -fb and pidiag -fbf.
Piptalia.dat
This binary file contains alias information. This is a pifilebase-type database so its validity
can be checked and restored using pidiag -fb and pidiag -fbf.
Piptattr.dat
This binary file stores the point attributes. This is a pifilebase-type database so its validity
can be checked and restored using pidiag -fb and pidiag -fbf.
Piptclss.dat
This binary file stores the point classes. This is a pifilebase-type database so its validity can
be checked and restored using pidiag -fb and pidiag -fbf.
PI Server System Management Guide Page 237
Chapter 11 - PI Troubleshooting and Repair
Piptunit.dat
This binary file stores the units. This is a pifilebase-type database so its validity can be
checked and restored using pidiag -fb and pidiag -fbf.
Piusr.dat
This file stores the user database. This is a pifilebase-type database so its validity can be
checked and restored using pidiag -fb and pidiag -fbf.
Piusrctx.dat
This file stores the context database. This is a pifilebase-type database so its validity can be
checked and restored using pidiag -fb and pidiag -fbf.
Piusrgrp.dat
This file stores the group database. This is a pifilebase-type database so its validity can be
checked and restored using pidiag -fb and pidiag -fbf.
Shutdown.dat
This text file contains directives that tell the PI Shutdown Interface which points should
receive shutdown events.
11.5 Identifying the Update Manager Issues: the pilistupd utility
The pilistupd utility shows the size of the queues of events maintained by the Update
Manager. The utility requires that PI be running.
Note: Windows-based PI Server exposes Update Manager Counters as Windows
Performance Counters. These counters may be viewed with the Windows
Performance Monitor and stored as PI points using the OSI Performance Monitor
Interface. This subject is covered in detail later in this chapter.
From a command prompt at the PI\adm directory, execute the utility pilistupd. This will
show a simple, although sometimes large, table summarizing the current state of update
signups. The table has five columns:
Producer: This is the source of update notifications. Currently there are five producers.
PI Snapshot Subsystem is a producer of Snapshot events. PI Base Subsystem is a
producer of Point Database and Module Database changes. The Archive Subsystem is a
producer of archive changes. The Batch Subsystem is a producer of Batch Database
changes.
Consumer: Application currently signed up as a consumer of specified producer. For PI
API applications, the consumer name is usually the first 4 letters of the login name of the
user running the application. These names are not unique so the PI Update
Manager assigned ID is appended to the name. PI API applications also have the PI
Network Manager ID appended. These integers are appended to help find specific
Page 238
11.5 - Identifying the Update Manager Issues: the pilistupd utility
consumers. For the PI-SDK, the consumer name is the complete application name with a
colon and a PI-SDK supplied identifier followed by a pipe character and a PI Update
Manager assigned ID.
Qual: This is the qualifier. The qualifier is a producer-specific integer. For example,
Snapshots update stores the requested point ID in the qualifier.
Flags: A producer-specific field.
Pending: Number of events available for the consumer to retrieve. The value goes up and
down as events come in and the consumer pulls them out. Values that increase
continuously might indicate that the consumer is not working properly or disconnected.
Note: The Pending number shows a maximum of 4096 events, even if more events
are in the queue. The Update Manager might limit individual consumers from
accumulating too many pending events. This is a display limitation and does imply
data loss.
Command line Switches for pilistupd
pilistupd has the following command line switches:
-v Show version
-h Help
-c consumer Select a specific consumer
-p producer Select producer
-m min Show only events with pending >= min
-t Show only the total number pending for this selection (specific cons./prod.)
-d piupdmgr dump to pi\adm\updmgr.dmp
-r C <S> Repeat C times every S sec.
-g A list of registered producers/consumers
-sp Sort output by producers
Example 1. Point Updates Only
For example, the following command limits output to the Producer ptupdates:
e:\pi\adm>pilistupd -p ptupdates
Producer Consumer Qual. Flags Pending
ptupdates Pibatch|1 0 0 0
ptupdates Pitotal|2 0 0 0
ptupdates PipeE|14|3 0 0 0
ptupdates RandE|16|4 0 0 0
ptupdates RmpSE|17|5 0 0 0
PI Server System Management Guide Page 239
Chapter 11 - PI Troubleshooting and Repair
In the results, the first entry is PI Batch Subsystem registered as a consumer of Point
Database changes. The integer 1 indicates this is the first consumer to register with the PI
Update Manager.
The second registered consumer is the Totalizer Subsystem.
The third entry is a PI API-based application, probably Performance Equation Scheduler. PI
API applications always have a four-character name with “E” appended. The two subsequent
integers, separated by the pipe ( | ), are the PI Network Manager assigned connection ID and
the PI Update Manager assigned ID. The connection ID is useful in tracking down errant
client applications; for example a ProcessBook display that is not checking for updates. The
PI Network Manager Statistics table can be used to lookup the machine associated with an
ID.
Entries 4 and 5 are also PI API-based applications, probably the Random and RampSoak
interfaces, which are installed by default on the PI Server node. Random interface generates
“sinusoid” points. A trend of sinusoid can indicate whether the Server is providing updates to
the client normally.
Example 2. Running pilistupd with PI ProcessBook Display Open
The next table was generated by running pilistupd with an open PI ProcessBook display,
trending 5 points.
e:\pi\adm>pilistupd
Producer Consumer Qual. Flags Pending
ptupdates Pibatch|1 0 0 0
ptupdates Pitotal|2 0 0 0
ptupdates PipeE|14|3 0 0 0
ptupdates RandE|16|4 0 0 0
Ptupdates RmpSE|17|5 0 0 0
snapshots PiadE|33|9 1 0 1
snapshots PiadE|33|9 29761 0 2
snapshots PiadE|33|9 29763 0 0
snapshots PiadE|33|9 29764 0 0
snapshots PiadE|33|9 29766 0 0
The last 5 lines of results are all the same display—consumer piadE|33|9. The consumer
name indicates an application logged in under piadmin account and it’s a PI API
application—the first 4 characters of piadmin with an E appended. This consumer has a PI
Net Manager ID of 33 and a PI Update Manager ID of 9. The qualifier attribute shows the
point IDs being trended. There are three pending events, two for point ID 29761, and one for
point ID 1.
Example 3. Determining Whether Client Updates are Occurring
Running pilistupd several times should reveal changes in the pending numbers. This can be
done easily by using command line switches. The -m option, requests a minimum pending
value of 1. The -r requests that the command be run 100 times. In the example below, the
command is issued and then results appear for 4 runs before the command is stopped with
Ctrl C. For three of the runs, none of the producers have any pending updates, as indicated
by the No Matching entries output.
Page 240
11.6 - Repairs
e:\pi\adm>pilistupd -p snapshots -m 1 -r 100
No Matching entries
No Matching entries
Producer Consumer Qual. Flags Pending
--------- --------- ------ ------ --------
snapshots piadE|15|5 4 0 1
snapshots piadE|15|5 12 0 1
snapshots piadE|15|5 18 0 1
snapshots piadE|15|5 19 0 1
snapshots piadE|15|5 20 0 1
No Matching entries
^C
In a normal system, you would anticipate that the pending number would reach 1
occasionally as the pilistupd command was run before the consumer retrieved the update. If
the pending number never increases above 0, it may be that data is not arriving from the
source. If the pending number increases continually and does not shrink, the consumer is
probably not retrieving the updates.
11.6 Repairs
Occasionally a PI data file may become corrupt due to a power outage or some other unusual
circumstance. There are utilities available to rebuild corrupted Archives, the Archive registry,
and the Point Database.
11.6.1 Recovering Data from Corrupted Archives
Archive files have a header and a record structure. Data is put in the records, but there is also
auxiliary information that indexes the records and chains the records together for fast data
access.
If, for example, the Archive cache flushing is interrupted by a power outage, the index
records might be left in an inconsistent state. When Archive file corruption occurs and the file
becomes unreadable, it is desirable to recover as much data as possible from that file.
The Offline Archive Utility can be used to recover the data and rebuild the Archive header
and the record indexing and chaining information. For more information about the theory
behind the Offline Archive Utility, see PI System Management.
Recovering a Corrupted Non-primary Archive
To recover the data from a corrupted Non-primary archive, launch the Offline Archive
Utility, specifying the corrupted archive as the input file and a non-existing file as the output
file. By default, the start time and end time of the input archive will be used as the start time
and end time of the output archive that is created.
The data in a non-Primary Archive may be recovered while PI is still archiving data. The
Offline Archive Tool will unregister the archive during the recovery operation.
Here is an example command to recover a non-primary archive:
$ ../bin/piarchss -if /export/PI/dat/piarch.001 -of piarch1.fix -f 0
PI Server System Management Guide Page 241
Chapter 11 - PI Troubleshooting and Repair
...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 the -f 0 parameter was specified. After it
is created, it may be registered using the piartool -ar utility, and then data events may be
added to the Archive in the usual way.
If the input file were registered prior to the operation, it would be unregistered during the
operation. When the operation is complete, it may be registered again using the piartool -ar
utility.
Recovering a Corrupted Primary Archive
If the corrupted archive is the Primary Archive, then PI cannot archive data during the
recovery process. Further, the Primary Archive cannot be unregistered. Thus to recover the
Primary Archive, prior to recovery one has to either stop the Archive Subsystem or force a
shift so that the archive is no longer the Primary Archive. To force a shift, use the piartool -fs
utility.
To recover the Primary Archive:
1. Stop the Archive Subsystem.
2. Launch the Offline Archive Utility specifying the parameters:
• Output archive is fixed size (-f 0)
• End time left open (-oet Primary)
After recovery:
1. Remove the old Primary Archive (rename it)
2. Rename the output file to the same path and filename of the original Primary
Archive.
3. Restart the Archive Subsystem
Note: Every archive has a parallel annotation file, with an extension .ann. In PI
3.3.361.43, the annotation file will be identified incorrectly after renaming its
associated archive file. Since renaming is necessary in this case, unregister the
renamed file after initial registration, and re-register it.
Example of Recovering a Primary Archive
Here is an example of recovering a Primary Archive. In this example, the Failed to unregister
input archive message may be ignored. It occurs because the Archive Subsystem was stopped
prior to recovery.
$ ../bin/piarchss -if /export/PI/dat/piarch.005 -of piarch.005.fix
-f 0 -oet 0
Page 242
11.6 - Repairs
...First pass...
...Sorting input archive...
Failed to unregister input archive: [-10733] PINET: RPC Resolver is
Off-Line
Archive utility not running - or archive not registered
Continue processing...
...Output pass...
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 -et 0 parameter was specified.
11.6.2 Restoring a Complete Server from Backup
The following procedure guides you through restoration of a complete PI Server from backup
and the original installation disk. This is suitable for cases of disk crashes or disasters of
similar magnitude. If the problem is clearly only with the data, start from step 4.
1. This procedure assumes the operating system was reinstalled and has no knowledge
of previous installation.
2. Disconnect the PI Server from the network. This is an important step. Interfaces
buffer data when the PI Server is not available. This data is safely stored and
managed by the PI Buffer Server—bufserv. Bufserv attempts, once a minute, to
reconnect to the PI Server; immediately on reconnection all data is written to the PI
Server. In the recovery process the PI Server starts before full recovery; if the
buffered nodes are not isolated, data from these nodes are lost.
3. Reinstall PI. The same version of PI should be installed. Data file formats may
change between versions; it is important to install the same version that ran at time of
last backup.
4. Start PI, and then stop PI after proper startup is observed. This accomplishes the "run
once" functions performed after an installation.
5. Verify that PI is not running before proceeding to the next step.
6. With the exception of pisubsys.cfg, restore (using Windows Explorer or the copy
command) the files that were backed up from the original PI\dat\ directory to the new
PI\dat\ directory.
7. Restore all the message log files ("pimsg_xxxxxxx.dat") to the PI\log directory.
8. Restore (using Windows Explorer or the copy command) the archives that you have
backed up to tape (or to a different drive) to the proper directory (by default PI\dat).
9. Restore (using Windows Explorer or the copy command) any of the batch files from
the PI\adm directory that had been customized to start and stop PI (such as
pisrvsitestart.bat etc.).
PI Server System Management Guide Page 243
Chapter 11 - PI Troubleshooting and Repair
10. If you are uncertain which of your backed up archives was the Primary Archive
(archive 0) at the time you last made a backup, use pidiag -ahd and examine the
archive dates. The primary should have the latest start date and no end date:
e:\pi\adm>pidiag -ahd ..\dat\piarch001.dat
11. You will need to do the following steps to reconstruct your Archive Manager data
file. After step 9 above make sure no PI process is running, and then execute the
following command from the PI\adm directory:
pidiag -ar
12. This utility will prompt you for the path and filename of the archive that you want to
assign as the Primary Archive. Enter the name (including the full path) of the Primary
Archive (archive 0) before the crash.
13. If the backup was performed using PI Version 3.4.370 or greater, then skip this step
because the snapshot is backed up as of 3.4.370 and there is no need to rename the
piarcmem.dat file. Otherwise, if the backup was performed with a version of PI prior
to 3.4.370, rename the PI\dat\piarcmem.dat to PI\dat\piarcmem.dat.old.
14. If the backup was performed using PI Version 3.4.370 or greater, then skip this step.
Otherwise, execute the Base Subsystem found in PI\bin to re-create the snapshot file:
pibasess -snapfix
15. Restart PI.
16. You will have to manually register all of the other archives that you want mounted.
pidiag -ar only registers the specified primary archive. Register the other archives in
their new locations:
piartool -ar <path_and_archive_file_name>
17. Use piartool -al and the client tools (PI ProcessBook and PI DataLink) to verify that
all the data has been recovered. If the data is intact, you are done. Run the clients
locally, since the PI Server should be isolated from the network. It is very important
to confirm correct PI Server recovery before exposing the PI System to buffered data.
Failing to do so may cause data loss.
18. Connect the PI Server to the network. Verify the PI Server is reachable from clients
on the network. Monitor all buffered interface nodes.
11.6.3 Restoring Archives From Backup
To restore an archive from backup:
1. Copy the archive file to disk.
2. Unregister any archives whose dates overlap the archive to be restored. For details,
see Unregistering an Archive on page 56.
3. Use piartool -ar <path> to register the restored archive.
4. Use piartool -al to list the registered archives and their dates. The archive just
registered should be displayed.
Page 244
11.6 - Repairs
Note: The PI Server will not allow registering archives with overlapping dates. If you
find overlapping dates, you can use pidiag -ahd to check the exact start and end
times.
11.6.4 Restoring Subsystem Databases From Backup
Many databases are interconnected. For example, the Point Database must be synchronized
with the Snapshot and Primary Archive. Generally, if one database must be restored from
backup, all databases must be restored from backup, as well as the primary archive. Partial
backup restoration should be done under the advice of PI Technical Support.
To restore a database, shut down the PI System. Do another backup to a safe location.
Replace the existing database files and the Primary Archive from the most recent backup.
Restart the PI System.
11.6.5 Correcting Archive Event Timestamps
Offline archive processing may be used to transform event time stamps. This feature applies a
time offset to all events in an archive. The offsets, specified by a data file, define the offset as
a function of time.
Time transformation processing is typically used to fix an archive with incorrect times. For
example, a system with incorrect time setting or time zone setting will have all archive event
timestamps offset. Time transformation processing adds an equal but opposite offset to
correct this error.
Using Time Transformation Processing
Offline archive processing with time transformation differs little from standard offline
archive processing. All arguments, such as input file and output file, must be specified.
Additional arguments specify time transformation behavior. The additional arguments are:
-tfix <time conversion file> [-tfixend <time> -oeendtime <time>]
The argument -tfix followed by full file specification is required. The arguments -tfixend and
-oeendtime are optional.
The first option, -tfixend, followed by a timestamp specifies the time to perform no
transformations. All events with timestamps greater than or equal to this time will not be
transformed.
This option is used when only a portion of the archive has incorrect event timestamps. For
example, if a PI System was run for a period with incorrect system clock setting, then the
clock was set correctly and run for some period before applying a time transformation fix.
The second option, -oeendtime, followed by a timestamp specifies a timestamp to set as the
archive end time when conversion is complete. The archive end time is set to the passed value
if all events are older than this time; otherwise, the end time is set to the time of the oldest
archive event.
PI Server System Management Guide Page 245
Chapter 11 - PI Troubleshooting and Repair
Time Conversion File Format
The time conversion file is an ASCII file containing a list of timestamp/offset pairs. The
timestamp and offset are separated with a comma. Lines beginning with "#", and empty lines
are ignored. White spaces are ignored
The timestamp may be a local time string in PI Time format; either an absolute time in the
format "dd-mmm-yy hh:mm:ss" or a relative time, such as "*-300d" or *. Only one
timestamp format can be used in a given file. The first format encountered is assumed for all
timestamps.
The offset is the number of seconds to add to the event timestamps. Sub-second precision of
the time shift is not supported. The offset is applied to all events with timestamps greater than
or equal to specified timestamp but less than next timestamp in the conversion file.
Here are some examples:
The following example uses UTC seconds time format. The timestamp "0", is January 1,
1970, and 2000000000 is well into the 21st century. The offset is a positive 3600--one hour.
Therefore this data file will simply move all events ahead by one hour.
# Example 1, Moves entire archive ahead by 1 hour
0,3600
2000000000,3600
Example 2 is similar to example 1, but uses local time stamps to specify a suitably large time
range to cover all events. The offset is -3600. This data file will move all events back by one
hour.
# Example 2, Also moves entire archive back by 1 hour
01-Jan-70 00:00:00,-3600
01-Jan-30 00:00:00,-3600
Example 3 applies a missed daylight savings time conversion for the Northern Hemisphere
summer of 1997. The first timestamp is sufficiently in the past to cover all events up to the
daylight savings transition; no offset is applied up to, but not including 06-Apr-03 02:00:00.
From 06-Apr-03 02:00:00 up to, but not including, 26-Oct-03 02:00:00 one hour is added to
all events. No offset is applied from 26-Oct-03 02:00:00 to current time.
# Example 3, Applies a missed dst conversion to an
# archive that covers summer of 1997
01-Jan-97 00:00:00,0
06-Apr-97 02:00:00,3600
26-Oct-97 02:00:00,0
31-Dec-97 23:59:59,0
11.6.6 Repairing the Archive Registry
This archive registry information is stored in a binary file called piarstat.dat. If this file is
corrupted, it can be rebuilt using the pidiag utility. To do this:
1. Copy piarstat.dat to a temporary location. Do not overwrite the original—rename it
in case you need it later.
2. Stop PI.
Page 246
11.6 - Repairs
3. Run pidiag -ad and collect the dump of piarstat.dat, verifying the output.
4. If the results of the dump look good, attempt the automated recovery. Otherwise, use
the interactive one.
5. Restart PI.
6. Check the message log to see if all archives are loaded. If the interactive version is
used, only the Primary Archive will be loaded.
7. Register any remaining archives. If the interactive version was used, all other
archives will need to be registered.
Options for Running Pidiag
There are three ways to run the recovery tool:
-ad Dumps the current piarstat.dat file. This is used to review the data in the file.
-ar Provides an interactive recovery utility for renaming the old piarstat.dat to piarstat.old and
generating a new one with a single entry - the Primary Archive - provided by the user.
-ara Provides an automated recovery utility that renames the old piarstat.dat to piarstat.old and
generates a new one with all of the entries found in the original file. Any errors will cause the
automated version to abort, and the user should resort to the interactive version.
11.6.7 How to Repair the Snapshot
There are two types of possible damage to the Snapshot from which PI can recover:
Snapshot times in the future. Accidentally moving the PI Server system time into the
future can cause this; at a minimum all points collected locally will be in the future.
Snapshot events are replaced when a newer value is received; therefore these events
remain in the Snapshot until actual time catches up. Events earlier than Snapshot time
bypass compression. Bypassing compression can put a large load on your PI Server.
Damaged or corrupted Snapshot file, piarcmem.dat. Corruption may be caused by
disk or power failures.
This section describes techniques for repairing the Snapshot in both of these situations.
Recovering from Future Times in the Snapshot
The fix option is invoked by stopping pisnapss on a running PI System. Re-start pisnapss
from a command prompt, passing the -f command line argument. This must be done
interactively; not as a Windows service:
Pisnapss -f
PIsnapss on startup will look for all Snapshots more than 20 minutes in the future. These
future Snapshots will be overwritten with a NULL value. PIsnapss reports to the message log
the number of future events detected. No fix-up messages are written if no future Snapshots
were detected. New incoming data will immediately overwrite the NULL Snapshot, even if
the incoming value is out-of-order. If an out-of-order value is received when the Snapshot is
NULL, values in the archive later than the Snapshot will not be visible to client applications.
PI Server System Management Guide Page 247
Chapter 11 - PI Troubleshooting and Repair
Typically, this is not a problem because values are written in time order, but it is something to
consider when running pisnapss.exe with the -f option.
PIsnapss will continue to run normally after the fix-up. Control-C the interactive pisnapss
process and restart it as a service.
Note: Snapshots fixed by this procedure will remain set to NULL until a new
snapshot event is fixed. If a point does not receive events regularly the NULL
snapshot may cause problems with applications expecting normal values. A
Snapshot can always be written manually if needed.
ANY new event that is received for a point with a null snapshot will be absorbed into
the Snapshot, even if that event is an out of order event. If an out of order event is
received, then any data that was in the archive after the out of order Snapshot value
will not be visible.
Rebuilding the Snapshot File
If the PI System is unable to start because the Snapshot file, piarcmem.dat, cannot be loaded,
it will be necessary to generate a new Snapshot file.
Note: This procedure builds a new snapshot file with Shutdown events in it. The
Snapshot will be updated as the PI System receives new data. If you follow this
procedure when your snapshot file is normal, you will lose data. You should use this
command only when directed by OSIsoft Technical Support.
To do this, shut down pibasess, piarchss, and pisnapss. Rename the file
PI\dat\piarcmem.dat to another name. At a command prompt, change your current directory
to PI\bin and issue the command:
pibasess -snapfix
The PI Base Subsystem will write a message to the screen indicating that Snapshot recovery
mode has been specified and that recovery is in progress. When recovery is complete,
pibasess will write a final message to the screen and exit. You may then restart the PI
System.
This Snapshot recovery command can be run with the entire PI System shut down.
Removing Future Time Snapshots
The piconfig utility can be used to remove all or selected Snapshot events. When the
Snapshot event is removed, the Snapshot Subsystem attempts to retrieve the latest archived
event from the Archive and replace the Snapshot event with it. That event is removed from
the Archive. If there are no events for the point in the Archive, the Snapshot is deleted and
remains uninitialized until a new Snapshot event is sent.
The following piconfig script shows how to do that:
piconfig table pisnap
* (Ls - PISNAP) piconfig> @sele tag=*,time>"*+10m"
* (Ls - PISNAP) piconfig> @ostru tag,value,time
Page 248
11.6 - Repairs
* (Ls - PISNAP) piconfig> @sigd 8
* (Ls - PISNAP) piconfig> @output deletesnap.dat
@endsection
@output
* (Ls - PISNAP) piconfig> @table piarc
* (Ls - PIARC) piconfig> @mode ed,t
* (Ed - PIARC) piconfig> @modify mode=remove
* (Ed - PIARC) piconfig> @istru tag,value,time
* (Ed - PIARC) piconfig> @echo v
* (Ed - PIARC) piconfig> @input deletesnap.dat
The first part extracts all the events that are later than 10 minutes past the current time into a
file. The second part (using the PIARC table) removes all these events from the Snapshot.
The last archive event for each tag replaces then Snapshot.
Any combination of conditions can be used to select the events to be deleted, for example all
tags of a specific interface.
The “@sigd 8” command ensures that rounding errors do not cause events to not be found.
11.6.8 Recovering from Accidental Change to System Time
The PI Server handles automatically all changes to system time. Thus our recommendation is
to never manually change the system time. On Windows, always use the automatic DST
option.
However, occasionally such changes are required, and unfortunately, from time to time this
change leads to human errors. For example instead of moving the clock to 2 AM it is moved
to 2 PM. Time synchronization software, designed to keep computer clocks accurate without
error-prone human intervention, have also been implicated in moving system clocks
erroneously. As a result, the events are recorded in the future. Usually this is discovered after
many of these events were already stored in the Archive. To recover from such situation:
1. Stop the PI System.
2. Correct the system time and the time on all connected nodes.
3. Isolate the PI Server from interface nodes. The best technique is to disconnect the
server from the network. While fixing the PI Server, it is best to allow the data to
buffer until the system is verified up and running normally.
4. Rename the Event Queue file, pimapevq.dat for later processing. The Event Queue
may contain many future events. Rename the following files located in the dat
directory:
• pilastsnap.dat
• pilasttot_T.dat
• pilastalarm.dat
5. Create an empty archive file using piarcreate utility.
6. Run pidiag -ar and register only the new empty archive.
There are two options for fixing the Snapshot:
PI Server System Management Guide Page 249
Chapter 11 - PI Troubleshooting and Repair
1. If the erroneous future data can be discarded, start the Snapshot Subsystem with -f
flag as explained above.
2. Otherwise, keep the current file, and after the system startup, delete or edit individual
values using piconfig, as explained above.
3. Start the PI Server in base mode. This starts just the minimum required subsystems—
pinetmgr, pimsgss, piupdmgr, pisnapss, piarchss, and pibasess:
pisrvstart -base
4. Register all the old archive files but the previous primary (which contains future data)
pidiag -ahd can be used to examine unregistered archive file header.
5. Create a new primary archive using piartool -ac.
6. Specify a start-time before any events that might be coming in. Specify the end-time
as *. This instructs the Archive Subsystem to register the new archive as primary.
The start time specified must account for all buffered data. If in doubt set the start
time well before the time the problem was first encountered. Offline archive
processing can merge this data with existing archives if necessary.
7. Verify that the PI System is running correctly. Reconnect the Server to the network.
8. Reprocess the old Primary Archive using the offline tool to either filter out the future
data, or correct its time by the required difference.
9. Reprocess the Event Queue into an archive file and correct timestamps as required.
10. Optionally combine these two archive (old primary and result of Event Queue).
11. Register the corrected archive file.
11.6.9 How to Repair the Point Database
To perform a consistency check of the Point Database and fix any reported errors, run
pibasess with the fix option. This also synchronizes the Snapshot and Archive databases with
the Point Database, since they contain references to the point database.
The fix option is invoked by stopping pibasess on a running PI System and restarting it with
-f command line argument. This must be done interactively; you cannot pass command line
arguments when starting pibasess as a Windows Service.
The consistency check adds messages to the PI Message Log. Additional information may
also be presented in the command window. Once the consistency check is complete, the
subsystem continues normal operation. It does not need to be restarted without the -f
parameter. However, if you are running PI as Windows Services, you will need to shut down
pibasess in order to restart it as a service before logging off.
11.6.10 How to Repair the Module Database
A module database consistency/fix-up is performed by running the PI Base Subsystem from
the command line as follows:
pibasess -mdbfix
Page 250
11.7 - Tuning the PI Server
The following is performed:
Table and index entry count size checks are performed. The entry counts should be
the same.
Modules that have a record size of zero are removed. These modules would be
unrecoverable.
Parent and children references to non-existent modules are removed.
This utility may modify the Module Database. Therefore it is important to have a safe
backup.
11.7 Tuning the PI Server
Most PI Servers require no tuning and work well with default settings. In some instances, you
may need to make adjustments through the Timeout Database, discussed below.
11.7.1 Communications Layer of the PI Server
A fundamental part of the PI Server architecture is the communications layer. Each PI
subsystem or process communicates with the other subsystems using Remote Procedure Calls
(RPCs). The pinetmgr process manages the RPCs, and is thus involved in every
communication between PI processes. For example, if the Snapshot Subsystem (pisnapss)
sends an event to the Archive Subsystem (piarchss) for storage, the communication flows
from pisnapss to pinetmgr to piarchss. If the Archive Subsystem writes a message to the
System Message Log, the communication flows from piarchss to pinetmgr to pimsgss. Thus
the pinetmgr process can be viewed as the hub of the wheel, where each spoke connects to a
different subsystem.
All communication is asynchronous. ("non-blocking" on UNIX). Windows PI Servers use
advanced, Windows-specific, multithreaded I/O.
UNIX Inter-Process Communication
PI Subsystem inter-process communication, by default, uses UNIX Sockets protocol. UNIX
sockets is a simpler, thus faster, protocol than TCP/IP. Generally this works fine.
Heavily loaded systems, especially heavy file system activity, may encounter excessive
errors. If the errors shown in the following table occur regularly, switch to TCP/IP as
explained below.
Error Description
11 Resource temporarily unavailable.
-10731 PINET: Incomplete Message.
-10732 PINET: Corrupted Message.
-10745 PINET: Message verification failure.
PI Server System Management Guide Page 251
Chapter 11 - PI Troubleshooting and Repair
CP/IP for Subsystem Inter-process Communication
The PI System can be configured to use TCP/IP for inter-process communication. The text
file pisubsys.cfg, located in the /dat directory, defines the desired inter-process
communication protocol. By default this file looks as the following:
#
# File: pisubsys.cfg
# Created By: @(#)piinstall.cxx 1.47 1.47 10/03/95
#
Generic_local /opt/PI/dat/piv3.rdz
The last line specifies the UNIX Sockets rendezvous file. To use TCP/IP, make the changes
as shown below:
#
# File: pisubsys.cfg
# Created By: @(#)piinstall.cxx 1.47 1.47 10/03/95
#
# Generic_local /opt/PI/dat/piv3.rdz
Generic_local localhost:5451
The previous UNIX Sockets rendezvous file entry is commented out and replaced with a
TCP/IP specification of localhost on port 5451. The port number can be any unused port
greater than 1024; it cannot be the default listener port of 5450. 5451 should be used unless it
conflicts with another application. This example also assumes the host “localhost” is defined
in the /etc/hosts file.
The PI System must be stopped and restarted for these changes to take effect.
Note: This technique if only used for advanced troubleshooting. This should only be
done under the advice of OSI Technical Support.
11.7.2 Resolving Excessive CPU Usage by Utilities
The utilities piconfig, pigetmsg, pilistupd and piartool may use excessive CPU. You can fix
this problem by increasing the time-out values for these. This results in more emphasis being
given to listening for messages and during this listening period (select) the CPU is not used
and is available to other tasks. Increase the values as follows:
piconfig> @table pi_gen, pitimeout
piconfig> @mode edit
piconfig> @istructure name, value
piconfig> piartool, 100
piconfig> piconfig,1000
piconfig> pigetmsg,1000
piconfig> pilistupd,1000
piconfig> @endsection
On some UNIX platforms, pinetmgr may report an error 11 or 35. This message would
typically be viewed with pigetmsg or in log/pinetmgr.log. This error is due to insufficient
resources available to complete the transfer of a large message. The fix is to increase the
default time-out and the number of retries pinetmgr uses for message transfer. Read and
Page 252
11.7 - Tuning the PI Server
write time-outs default to 50,000 microseconds, read and write retries default to 250. We
recommend increasing the time-outs in increments of approximately 25% until the errors
disappear. If the errors persist when the timeout values are over 150,000 microseconds, call
OSI Technical Support.
To increase the time-outs:
piconfig> @table pi_gen, 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 OSI Technical Support.
Very short timeout values may cause specific utilities to “spin” faster and thus use
more CPU. Before making changes based on CPU consumption, isolate the CPU to
the offending processes. Use available tools to analyze each process. For example,
if pisnapss is in a high CPU state, run piartool -ss and look at Snapshot read and
write rates because excessive rates may be the true source of CPU load.
11.7.3 Identifying Abusive Usage
If the PI Server uses most of the CPU one needs to identify more specifically the cause. In
some cases it is wrong sizing, i.e., the configuration is too large for the available hardware,
such as CPU, memory or disk.
The introduction of threading in release 3.4 solves many performance issues; however, very
large archive queries can still affect performance.
The total number and size of queries can be monitored with piartool -as.
If the number of read access and number of events retrieved seem excessive, use the activity
grid as follows.
Also, the pinetmgrstats table in Piconfig can help identify network connections with the
highest traffic. This is explained in The piconfig Utility on page 171 of this guide.
Activity Grid
The Archive Subsystem provides a tool for monitoring the rate of read-access to the Archive.
This tool creates, over a finite time period, a grid of activity. The grid indicates which users
and points account for the most activity. This monitoring requires significant computing
resources and therefore is normally turned off. Start the activity grid to identify the users that
present the greatest load on the system and the points that are being queried most often. Once
the load on the system is identified, it is best to turn off the activity grid.
To start the activity grid:
Piartool -aag start
PI Server System Management Guide Page 253
Chapter 11 - PI Troubleshooting and Repair
To stop it, and remove all its memory
Piartool -aag stop
To temporarily stop the accounting yet allow querying of the current statistics
Piartool -aag pause
Each query requests the number of events retrieved or the number of retrieval calls made.
These can be arranged by points or by users. A yearly average might go through thousands of
events for a specified point, yet counts as a single call.
The following gets the number of events retrieved by point. This is since the activity grid was
started.
d:\pi\adm>piartool -aag point event
Name - Count - ID
SINUSOID 35 - 1
CDT158 100 - 3
CDM158 110 - 4
The following gets the number of event-retrieval calls, arranged by user.
d:\pi\adm>piartool -aag user access
Name Count ID
pidemo 3320 2
11.8 Solving Other Problems
11.8.1 Failed Backups
For tips on troubleshooting backups, see Troubleshooting Backups in the chapter Backing up
the PI Server.
11.8.2 Slow Reverse Name Lookup
The PI Network Manager looks up the host name of all computers connecting with PI API.
The name lookup is used to identify the connecting computer for trust login and firewall
access. A Reverse Name Lookup requests the Domain Name Server (DNS) to translate an IP
address to host name. This request must complete in a reasonable amount of time for PI to
function correctly.
Network systems with malfunctioning Reverse Name Lookup will experience slow
connections or failure to connect to PI. Often the symptoms may be isolated to a subnet or
computers connecting from outside the LAN. The standard TCP/IP utility, nslookup, can be
used to check Reverse Name Lookup. If nslookup reports a delay when resolving an IP
address to name, the network has DNS problems that should be addressed. Resolving this
problem is a system network configuration task and beyond the scope of this document.
If the problem cannot be resolved in a timely manner, the Reverse Name Lookup can be
disabled. First, add an entry reversenamelookupflag to the PI Timeout Table. Set the value
of this to zero to disable the lookup. Setting the value to a non-zero entry or removing the
reversenamelookup flag entry enables the lookup.
Page 254
11.8 - Solving Other Problems
Here is an example piconfig session which disables Reverse Name Lookup.
piconfig> @table pi_gen, pitimeout
piconfig> @mode create,t
piconfig> @istructure name, value
piconfig> reversenamelookupflag,0
If Reverse Name Lookup is disabled, trust login access by name would not work. You can
modify the trust record to use other credential information. Another way to speed up Reverse
Name Lookup is to create a local host file on the PI Server.
11.8.3 Slow Domain Controller Access
Trust logins from PI-SDK-based applications require access to the Windows Domain
controller or Active Directory. The lookup is required to authenticate client login credentials.
Slow access to these services will adversely affect the system.
The utility pidiag -host performs the same validation carried out by pibasess. Run this utility
from a command line on the server to get a measure of the access time and reliability.
Disabling the authentication feature defeats an important part of single user signon of PI
Client applications. Rather than disabling it, it is best to insure reliable access to the Domain
Controller or Active Directory.
If necessary, the timeout parameter WindowsAuthentication may be used to disable this
feature. A value of zero disables the authentication. Removing this timeout parameter or
giving it a value of other than zero enables this feature. The PI Base Subsystem must be
restarted for this change to take affect.
The utility pidiag -host performs the same validation carried out by pibasess. Run this utility
from a command line on the server to get a measure of the access time and reliability.
11.8.4 Flatline in a PI ProcessBook Trend
If a PI ProcessBook trend “flatlines,” you may have a problem with PI ProcessBook, with the
PI Server, with network performance/connectivity/configuration, or with the data source.
Here are some possible diagnostic steps to take:
1. Determine whether only one tag is affected or several are affected. Check another
trend in the ProcessBook to see if the problem is limited to only some points. If the
problem involves multiple points, go to step 2. If the problem involves only one
point, go to step 4.
2. Try retrieving the data from the PI Archive by closing and reopening the trend
window. If the trends appear normal, the problem may be in the update signup. Go to
step 3. If the trends still show no data, go to step 4.
3. If no tags are producing trends, run pilistupd on the PI Server to see if the flatline is
due to the PI ProcessBook program not being signed up for updates. See PIlistupd
Utility in the System Management chapter.
4. View the pending numbers in the results. Pending numbers represent the number of
events queued and not yet retrieved by the client such as PI ProcessBook. If data is
not arriving from the data source, the pending number remains at zero. If the client PI
PI Server System Management Guide Page 255
Chapter 11 - PI Troubleshooting and Repair
ProcessBook is not retrieving the updates, the pending number continually grows and
does not shrink. This indicates whether the problem is with the PI Server or with the
client application.
5. If the pending updates are growing, try restarting the PI System. If this does not fix
the problem, contact OSIsoft Technical Support for additional assistance. If the
pending updates remain zero, go to step 4.
6. If all the points are signed up for updates, and refreshing the data from the archive
still yields a flatline trend, the problem could be in the archive, in the data source, or
in communications to the data source.
7. To determine if the Server is working, create a trend for a point with data generated
on the Server, such as “sinusoid,” which is generated by the Random Interface on the
Server.
8. If the trend for sinusoid appears correctly, it means that the archive is working and
communication between Server and client is working. Then go to step 6.
9. If the trend for sinusoid does not appear correctly, go to step 5.
10. Verify that the archive program is working (piartool -as, piartool -al)
11. Try inserting data into a test point (using piconfig or PI DataLink) and try trending
this point. If this is successful, go to step 6. If not, contact OSIsoft Technical Support
for additional assistance.
12. If all these tests are successful, the data source for the flatlined points may not be
working. Examine the Source-point attribute of the point to find out which interface
is feeding data for the point in question.
13. Check the PINetstats Table (See Chapter 1, PI System Management) to verify that the
interface program is running and connected to the Server.
14. Verify that the interface program is communicating with the external data source
(DCS system, RDB system, etc.). The documentation for the specific interface should
explain how to do this.
15. If the data source is running successfully, go to step 7.
16. Security may be preventing the process at some point. Examine the interface log files
and the PI Server log files (pigetmsg). Verify that both the data source interface and
PI ProcessBook have the correct access to the system. Examine all messages about
trusts granted or refused.
17. If the points in question have some access restrictions, there must be established trust
logins. The interface must have access as a PI user with WRITE access to the points.
PI ProcessBook must have read access to all these points.
If none of the above steps have resolved the problem, contact OSIsoft Technical Support for
additional assistance.
Page 256
11.9 - COM Connectors
11.9 COM Connectors
Occasionally, errors are observed when OSI client applications fail to obtain process data. If
the errors are related to a foreign data historian, the applications generally receive error codes
in the range -11200 to -11209, instead of returning data. As usual, you can use the pidiag -e
utility to translate these errors to text.
The source of the error can be the Redirector or the specific COM Connector in use. Errors
may be logged in either the Windows Event Log or the PI Message Log. In general, the
distinction is this:
The Redirector logs information about its own activities to the Windows Event
Application Log. This includes startup, shutdown and loading of COM Connectors.
The PI Subsystems record errors in foreign system point lookup and data retrieval in
the PI System Message Log.
This section gives some guidelines for troubleshooting data retrieval problems from COM
Connectors. As new techniques become available, they will be posted on the OSI Technical
Support COM Connector page, available at http://techsupport.osisoft.com.
11.9.1 Redirector Troubleshooting
This subsection describes techniques for confirming the correct operation of the Redirector.
When troubleshooting a COM Connector problem, you should always begin with this
subsection.
Confirming Redirector Installation
The Redirector is not installed separately; it is installed as part of the PI Server. To confirm
that the Redirector was installed correctly, check the PI Server installation log file
piudsinst.log in the root of your system disk. Look for two lines reading:
Registering PI UDS Redirector.
Creating EventLog registry key for piudsrdr
You can use the Windows utility dcomcnfg to confirm installation and check the Redirector's
properties. Invoking dcomcnfg displays this dialog box:
PI Server System Management Guide Page 257
Chapter 11 - PI Troubleshooting and Repair
Figure 11-1. Distributed COM Configuration Properties
Once you have confirmed from this dialog that OSI PI Server Redirector is installed, continue
with the troubleshooting tips below until the problem is solved.
When you are able to clear the problem, you must restart the Redirector. This is done by
shutting down the Base, Snapshot, and Archive Subsystems and restarting them. There is no
method to restart the Redirector alone. The Redirector is not launched if there is no COM
Connector (a.k.a. mapped) points configured on the system.
Check for Mapped Points in the Archive
Mapped points should be correctly defined in the PI Point Database. A mapped point is one
that has the three identifying point attributes: ctr_progid, ctr_strmap and ctr_lmap.
Check using piconfig:
piconfig
@table pipoint,classicctr
@mode list
@ostructure tag, ctr_progid, ctr_strmap, ctr_lmap
@select ptclassname=classicctr
@ends
Point class "classicctr" can be created using the piconfig file classicctr.dif provided with the
PI Server installation kit. You may create your own point classes for PI Server mapped
Page 258
11.9 - COM Connectors
points. The point class may be of any name as long as it contains the above three point
attributes.
Check for the PI Redirector Process
If the PI Server mapped points are defined, a process called piudsrdr.exe should be running.
Check for this in the Windows Task Manager, Processes tab:
Figure 11-2. Windows Task Manager Processes
1.) Check the PI Message Log
If the Redirector is not running, check the PI Message Log using the pigetmsg utility. Check
for any messages related to the Redirector or a COM Connector. If this message appears:
0 pipoints 23-Jun-03 16:07:25
>> Error getting UDS Point interface. [-2147467261] Invalid pointer
it means that the Redirector is not installed correctly.
Attempt to reinstall by opening a command window, setting your default directory to the
PI\bin directory and issuing the command:
piudsrdr /RegServer
A Windows message will be displayed in an alert box if the registration fails. Issuing this
command if the Redirector is already correctly installed is harmless.
PI Server System Management Guide Page 259
Chapter 11 - PI Troubleshooting and Repair
2.) Check the Windows Event Log
Run the Windows Event Viewer and select the Application log. The PI Redirector may
write a message if it is able to start but not able to keep running.
The Redirector will also fail to start if the Windows Event Log is full. Choose Clear All
Events from the Log menu to clear the Application log.
To prevent this from recurring, you may wish to change the event log settings. To do this,
start the Application Log Properties dialog box.
The default settings are shown in Figure 11-3. Application Log Properties.
Figure 11-3. Application Log Properties
Note: This screenshot is from Windows 2000; the Windows Server Properties dialog
box is similar.
The default settings can become a problem if your system generates a log file of 512Mb of
messages within 7 days. You can avoid this problem by specifying a larger event log or by
choosing the Overwrite events as needed radio button.
Page 260
11.9 - COM Connectors
3.) Run the Redirector Dump Script
Every COM Connector implements a method for obtaining information on its mapped points.
A script for requesting this information can be obtained from OSIsoft Technical Support Web
site at http://techsupport.osisoft.com.
In order for this script to work correctly, identity of the Redirector should be set to This user
(a domain user with administrative privileges) in dcomcnfg. If the identity is set to The
launching user, any logged in user who runs the script is likely to launch another instance of
the Redirector. Such an instance of Redirector will not share information with the one
launched by PI Base which contains the mapped point information. If a change is made to the
identity setting, restart the Redirector by restarting Base, Snapshot, and Archive.
Also, if the identity of the Redirector is set to a specific user, you should make sure that all
out-of-process COM Connectors can be launched and accessed by this user.
11.9.2 COM Connector Troubleshooting
If a COM Connector is successfully loaded by the Redirector, a message like this will be
written to the Windows Event Log:
Figure 11-4. COM Connector Loading shows the result of the Redirector loading a simulator
COM Connector.
Figure 11-4. COM Connector Loading
PI Server System Management Guide Page 261
Chapter 11 - PI Troubleshooting and Repair
If the COM Connector cannot be loaded, a message to this effect will be logged.
Troubleshooting steps depend on how the COM Connector is implemented.
COM Connectors are of two different types: in-process or out-of-process. The manual for the
specific COM Connector you are using will tell you the Connector type.
In-Process COM Connector
An in-process COM Connector is implemented as a DLL. When the PI Base Subsystem loads
a point that references the COM Connector, this DLL is loaded into the process space of the
Redirector. You will not see a separate process running.
Check the Windows Event Log. If the COM Connector is not registered, the message will say
this.
In this case, attempt to re-register the COM Connector by opening a Windows command
window, setting your default directory to the location of the COM Connector DLL and
running the regsvr32 utility. If the COM Connector DLL were named myconn.dll, you would
issue the command:
regsvr32 myconn.dll
An alert box will be displayed if the COM object implemented by the DLL cannot be
registered. A common cause of inability to register is DLLs upon which the COM object
DLL depend are not installed. The missing DLLs may be those provided by the foreign data
historian vendor.
Note: In-process COM objects are not visible to the dcomcnfg utility. One way of
seeing the DLLs loaded by the Redirector is to use the ListDLLs utility available
from the SysInternals Web site http://www.sysinternals.com.
Out-of-Process COM Connector
This type of COM Connector will appear as a separate process in the Windows Task Manager
window.
You should also check the COM object properties using dcomcnfg. The Properties and
Identity should match those of the Redirector, unless the COM Connector’s manual says
otherwise.
If the COM Connector does not appear in the dcomcnfg list, it has not been successfully
registered. Attempt to re-register the COM Connector by opening a Windows command
window, setting your default directory to the location of the COM Connector executable and
running it with the /RegServer switch. If the COM Connector executable were named
myconn.exe, you would issue the command:
myconn.exe /RegServer
An alert box will be displayed if dependent DLLs are missing. Other errors are not displayed.
Page 262
Chapter 12. FINDING AND FIXING PROBLEMS: THE PIDIAG
UTILITY
The pidiag utility is a collection of tools for diagnostics, information, and simple repairs. It is
designed to help the PI System Manager and OSI Software technical support in gathering
information about a PI System, troubleshooting and solving some common problems.
The following sections explain in detail the various tools included in pidiag. To invoke
pidiag:
pidiag -xxx
where xxx identifies one tool. Depending on the specific tool, some additional parameters
might follow. The optional parameters are summarized in the following table and described
in this section, unless otherwise noted in the table.
Option Description
-ad Dump archive manager data file.
-adg <version> 'path' Downgrade archive file(s) to a specific version
-ahd 'path' Dump the archive file header.
-ar Recover archive manager data file.
-ara Auto recover archive manager data file. Described in this chapter.
-archk 'path' [complete] Archive integrity check utility.
-cid [ < ServerID > Create Server ID file optionally passing Server ID and PI API ID. The PI
< APIServerID> ] | API ID must be an integer. Server ID may be a GUID or an integer. -
upgrade option creates Server ID file for a system upgrade. Server ID
[-install] | [-upgrade] and PI API ID are set to integer based on host name. -install option
creates Server ID file for a new installation. Server ID is set to a UID.
The PI API ID is set to integer based on host name.
-crash Simulate a process crash.
-dapi [hostname] Create and display PI API Server ID based on supplied host name.
Machine host name is used if host name is not supplied.
-did Dump Server ID file.
-e code Translate error code.
PI Server System Management Guide Page 263
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
Option Description
-fb 'path' Dump file base data file.
-fbc 'path' Compact a file base data file.
-fbf 'path' <’outpath’> Recover (fix) file base data file index, optionally copying into a new file.
-gpc 'name' Gets performance counter path.
-host Display host information as used for Trust-Login.
-machine Machine and compile information.
-n number Format and display number as various types.
-qd [HeaderOnly| Dump header or all/filtered events from Event Queue file.
RecNo=n |PointId=<id>]
'path'
-qs 'path' Get offline queue file statistics.
-rgs [-?] [-u] 'path' Register or unregister COM component by running .rgs script in 'path'.
{ReplaceableParameter
="Value"}
-t time {U} Convert timestamp to string.
-tz {time} {TZ} Show timezone information.
[ -check | -dump
[-brief] | -full ]
-tz [ -if path | -ifrule [path] Special DST settings.
]
[-of path]
-udf 'path' Resets the piadmin (userid #1) password to blank.
-upc 'name' Uninstalls performance counters for named subsystem.
-uuid [count] Create and display "count" UIDs. 1 UID is created if "count" is not
supplied.
-v Version information.
-w msec Wait for passed milliseconds.
-xa <path> Export audit records. This option is documented in Auditing the PI
[ -st <start> Server.
-et <end>
[-uid <unique id>]
[-xh <schema url>] ]
The pidiag utility resides in the PI\adm subdirectory.
Page 264
12.1 - General Information
Tools that operate on files, such as compact and repair options should never be used with
open files. This means in general, that they should be used only when the system is down. If
in doubt, consult OSI technical support before using such tools. It is also advisable to make a
backup copy of the data file before compressing or repairing.
The following can be used to display a short help page with all the options.
pidiag -h
pidiag -?
12.1 General Information
12.1.1 Version Information
pidiag -v
Displays the version of pidiag utility itself. In general this is the same version for all PI
utilities and subsystems.
D:\PI\adm>pidiag -v
Version: PI 3.4.363.24
Program: pidiag
PI Path: D:\PI
12.1.2 Error Code Translation
To display text for a given error number, run:
pidiag -e errorcode
Positive numbers are operating system error codes, depending on the platform where the PI
Server is running. Negative numbers are PI errors.
C:\PI\adm>pidiag -e 2
[2] The system cannot find the file specified.
C:\PI\adm>pidiag -e -11002
[-11002] Record Header Data Mismatch
12.2 Time Utilities
12.2.1 Time Translations
pidiag -t time <U>
This provides translation between time string formats and internal formats:
If time starts with 0 (zero) an integer format (seconds since 1-jan-70) is translated to
string representation. pidiag assumes local time, unless the 3rd argument is “U” or
“UTC” in which case the argument is taken to be universal time (GMT).
If the first character is not 0, the time argument is treated as time string, absolute or
relative, and translated into an integer value. Both local time and UTC integer values are
displayed.
PI Server System Management Guide Page 265
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
Note: On UNIX systems, you generally cannot specify an asterisk ( * ) by itself to
mean current time unless you enclose it in double quotes. A single asterisk is
interpreted by the shell as a wildcard search character.
String to Integer Format
C:\PI\adm>pidiag -t 1-sep
1-Sep-02 00:00:00 PDT - Local: 904608000 UTC: 904633200
C:\PI\adm>pidiag -t t+1h
21-Oct-02 01:00:00 PDT - Local: 908931600 UTC: 908956800
C:\PI\adm>pidiag -t "*"
21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210
Integer Format to String
C:\PI\adm>pidiag -t 0909000010
21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210
C:\PI\adm>pidiag -t 0909025210 U
21-Oct-02 20:00:10 PDT - Local: 909000010 UTC: 909025210
12.2.2 Time Zone
To show time zone information, run:
pidiag -tz {time} {TZ} {-check|-dump}
Running pidiag -tz with no additional arguments shows
The setting for the TZ environment variable
The standard time zone name and the daylight time zone name in effect
The general rules for DST transitions.
The TZ environment variable should typically not be set. A StartYear, EndYear, Month,
Week, Day, Time, and Offset define the daylight and standard time transition rules.
C:\PI\adm>pidiag -tz
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
The transitions rules are defined as follows.
StartYear is the first year that the rule is in effect
EndYear is the last year that the rule is in effect
Month is the month (1-12) that the rule is applied.
Week is the week (1-5) that the rule is applied. If week is 5 and there are only 4 weeks in
the month, then 5 designates the last week in the month. If week is -1, then week is to be
ignored and day becomes absolute.
Page 266
12.2 - Time Utilities
If week is greater than 0, then day is the relative day (1-7) that the rule is applied. A day
of 1 represents Sunday, a day of 2 represents Monday, and so on. For example, a week of
1 and a day of 1 means the first Sunday in April. If week is -1, then day is an absolute
day (1-31).
Time is the time in seconds after midnight that the rule is applied.
Offset is the time in seconds to subtract from standard time to get the local time. For
example, daylight saving time is in effect, -3600 is subtracted from standard time.
Running pidiag -tz with the {time} argument will display the corresponding local and UTC
times in seconds and whether the passed time is in standard or daylight saving time. If the
time string is ambiguous, it is marked with an asterisk (*). Time strings are ambiguous if they
specify a time in the last hour of daylight savings time before the beginning of standard time.
In the northern hemisphere, this occurs in the fall. In the southern hemisphere, this occurs in
the spring.
C:\PI\adm>pidiag -tz "25-Oct-02 01:30:00"
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
Passed Time: 25-Oct-02 01:30:00 PDT Local: 1035509400 UTC: 1035534600
If your time zone does not observe daylight savings time, the utility will indicate this.
C:\PI\adm> pidiag -tz
TZ environment variable: <not set>
Standard Time Name: US Mountain Standard Time (UMST)
Daylight Savings Time: <not observed>
The -dump option dumps the whole time zone table. This includes fall/spring changes in
every year. The dump is in comma-separated variable (CSV) format and can be loaded
directly into a spreadsheet, providing all time-change information for the local time zone.
The -dump option can be combined with -brief. The output with this option includes the
year and spring and fall time changes, each marked with “D” or “S” to denote daylight or
standard time.
The -check option generates no output at all, unless the time zone settings on your system
are invalid. The utility is used this way in the installation script on UNIX systems.
Daylight Savings Time Changes
PI uses an internally constructed table to determine when changes between Standard Time
and Daylight Savings Time occur. On Windows, this table is built using the single time
change rule available from the operating system. UNIX systems tend to store more year-
specific rules, but there are still issues for time zones in which the change rule is different
from year to year.
PI Server System Management Guide Page 267
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
PI now supports the loading of a time zone information table from a binary file called
PI\dat\localhost.tz. If this file is present and valid, it is loaded and used for all time
translations. The table can be constructed as follows:
pidiag -tz -dump -brief > myzone.txt
The record of the resulting text file contains year, spring time change, and fall time change.
Edit the file to reflect the actual change times for your time zone. The file need not contain a
record for every supported year; years that are not specified use the operating system
generated rule. To install the new file, issue the command:
pidiag -tz -if myzone.txt -of test.tz
You can check the validity of test.tz by using pidiag to read it again, using the -if command.
pidiag assumes that any file ending in .tz is a binary file; all others are assumed to be text.
The -if command can be combined with any other. For example, to test the date 31-oct-02
01:30 using the new table, issue the command:
pidiag -tz "31-oct-02 01:30" -if test.tz
To dump the contents of a binary file to text, issue the command:
pidiag -tz -if test.tz -dump > test.txt
If the new timezone information table correctly represents the time transitions, copy the
binary file to PI\dat\localhost.tz and restart PI. Doing this does not affect the timestamps of
data already stored by PI, since these timestamps are stored as UTC. It affects only the
translation of these stored times to local times.
The timezone information now stores additional information such as the names of the
applications that created or modified it, and the first time the table was put into service. This
in-service time will be set on first system startup only if it was loaded from
PI\dat\localhost.tz. To see this additional information, issue the command:
pidiag -tz -full
Different Time Zone
If the TZ parameter is specified (in addition to time parameter), the transitions are shown as
they would appear if that TZ environment variable were in effect. Note that the TZ argument
follows the time/year argument, so you must provide a time string or year to use this feature.
The specified time zone can be different from the local time zone.
C:\PI\adm>pidiag -tz "*" GMT0BST
TZ environment variable: GMT0BST
Standard Time Name: GMT (GMT)
Daylight Time Name: BST (BST)
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
Note: On UNIX systems, this feature can be used to determine whether or not the
operating system recognizes your passed TZ string as valid. Displayed transition
Page 268
12.3 - File-base Utilities
times, however, tend to reflect your system’s current time zone settings. Changing a
UNIX system’s time zone settings requires platform-specific techniques. You should
reboot your UNIX system after changing its time zone settings.
12.3 File-base Utilities
Most of the PI System internal databases are stored as index files with specific internal
organization. We call this structure file-base. The following tools are provided for diagnostics
and repair of such database files. More information is available in PI Server Data Files in the
chapter PI Troubleshooting and Repair.
Caution: Do not use Compact or Recover tools on open files while the system is
running!
12.3.1 Dump File-base Data File
pidiag -fb <path>
This lists the inner structure of a file-base index.
OSI technical support can determine from this information if any errors occur in the structure
of the file:
C:\PI\adm>pidiag -fb c:\PI\dat\pidigst.dat
PIfilebaseheader::
File Name: C:\PI\dat\pidigst.dat
Major Version: 2
Minor Version: 0
Directory Location: 1024
Directory Size: 512
Record Count: 4
Last Recno: 0
Maximum Recno: 64
User Block Size: 512
Data Location: 1536
Data Size: 2724
PIsecureobject[@(#)pisecobj.cxx 1.27 09/30/96]::
User ID: 1 Group ID: 1 Access: [113] [o:rw g:rw:r]
Index Dump:
Record, Offset, Size: 0, 2994, 1266
Record, Offset, Size: 1, 2839, 29
Record, Offset, Size: 2, 2887, 51
Record, Offset, Size: 3, 2956, 38
12.3.2 Compact a File-base Data File
pidiag -fbc <path>
Following excessive add and delete operations, a file-base file might grow and contain some
holes. This tool is provided to rebuild the file and compress the holes, thus saving some disk
space. This occurs automatically for message files and the point database.
PI Server System Management Guide Page 269
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
12.3.3 Recover File-base Data File Index
pidiag -fbf <path> <outpath>
The internal directory of a file-base database can be rebuilt from the data itself.
This is needed in cases of index corruption. The optional outpath parameter instructs the
utility to write the recovered output to a new file. In some cases a more complete recovery is
possible that way.
12.4 Archive Management
The commands in this section assist with archive file management.
12.4.1 Dump the Archive Manager Data File
The Archive Manager data file contains the list of archive files currently known to the PI
Server. The contents of the file can be dumped using the command:
pidiag -ad
When the Archive Subsystem is running, use the following command:
piartool -al
to provide this information.
The file PI\dat\piarstat.dat contains information on all registered archives.
C:\PI\adm>pidiag -ad
Archive manager data file version is 1
Archive primary archive code is 1
Archive manager data file dump follows:
PInt [$Workfile: pinttmpl.cxx $ $Revision: 13 $]::
Table contains 3 entries, with 3 total slots allocated.
Extend size is 2 slots and the next iCode is 4.
1. C:\PI\dat\piarch.001
2. C:\PI\dat\piarch.002
3. C:\PI\dat\piarch.003
Alphabetical index:
C:\PI\dat\piarch.001
C:\PI\dat\piarch.002
C:\PI\dat\piarch.003
PIobject:
End of Dump
The -ad option may be used, for example, in a procedure to repair the archive registry. See
How to Repair the Archive Registry in the chapter PI Troubleshooting and Repair.
12.4.2 Automatic Recovery of the Archive Manager Data File
The command:
pidiag -ara
Page 270
12.4 - Archive Management
attempts an automatic recovery of the archive manager data file PI\dat\piarstat.dat.
Caution: Use only when the PI Server is shut down!
This option creates a new archive manager data file using the data in the existing data file. It
can be used if the index in the current file is corrupted.
12.4.3 Manual Recovery of the Archive Manager Data File
The command:
pidiag -ar
recovers the archive manager data file.
Caution: Use only when the PI Server is shut down!
This option creates a new archive manager data file. It prompts the user for the full path of
the Primary Archive file. Upon restarting PI, this file will be the only archive registered.
This option is useful when moving a PI Server to another machine, or when running the same
point configuration with different sets of archives.
If the archive manager file is corrupted, try first the -ara option. If that does not help, use -ar
option. More information on using the -ar and -ara options is provided in How to Repair the
Archive Registry in the chapter PI Troubleshooting and Repair.
Note: The command pidiag -ara can be also used to downgrade the format of the
archive registry from 3.4.370 to earlier versions of the PI Archive.
12.4.4 Information about Unregistered Archives
It is frequently necessary to obtain information about Archive files that are not currently
registered. To do this, use the command:
pidiag -ahd <path>
for example:
pidiag -ahd d:\pi\dat\piarch.001
The output is similar to the output from piartool -al for a single Archive file:
E:\PI\Adm>pidiag -ahd e:\pi\dat\piarch.001
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 47 $]::
Version: 6 Path: e:\pi\dat\piarch.001
State: 3 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 32768 Add Rate/Hour: 6614.0
Offsets: Primary: 8192/8192 Overflow: 28591/32768
Start Time: 4-Apr-03 18:19:41
End Time: 4-Apr-03 19:53:41
Backup Time: Never Annotations: 1/65535
End of Dump
PI Server System Management Guide Page 271
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
For examples on using the -ahd option, see Restoring a Complete Server from Backup,
Restoring Archive Files from Backup, or Recovering from Unintended Change to System
Time in the chapter PI Troubleshooting and Repair.
Note: This command can only be used if the archive file is not registered, or if the PI
Server is down. If you use it with a registered Archive file, pidiag will return an
access error.
12.4.5 Verify the Integrity of Archive Files
Command syntax:
pidiag -archk 'path' [complete]
The -archk command can be used to perform integrity checks or extract statistics from
archive files that are not registered. Below is an example report after running the command
on an archive file:
Analyzing archive: D:\PI\dat\piarch.001
-----------------------------------------------------------------------
recno: 1 id: 1 indices: 1 records: 5 events: 636 fr: 89.4%
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%
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
The above listing include for every point (sorted by record number or “recno”), the number
of index records (“indices”), the number of data records, the count of events in all records and
the average fill ratio (“fr”). Points receiving events in order and no edits or remove events
will typically have a fill ratio close to 100%. Note: Since the last record in a chain is rarely
full, the fill ratio is almost never going to be exactly at 100%.
Page 272
12.4 - Archive Management
Looking at archive statistics and in order to maintain best performance, points should not
have more than one or two index records on average. If this is not the case for many points,
compression parameters should be reviewed for these points or the archive files should be
made smaller. In the above example, points 4 and 17 (recnos 4 and 11 respectively) clearly
have an excessive number of index records.
The archive check command will detect and report any errors in the archive file. Errors are
summarized at the end of the report but when running the command, they are sent to the
“standard error” (stderr) stream. As a result, when redirecting the output to a file, the
following syntax should be used so that errors are inserted into the output file report.txt:
pidiag -archk "archive_file" > report.txt 2>&1
Alternatively, the following construct can be used to redirect the output to two different files:
pidiag -archk "archive_file" 1> report.txt 2> errors.txt
The archive errors or corruptions could be the result of failures (crash, unexpected
termination, power failure, etc) or software bugs. In the case this happens, the offline archive
utility can be used to reprocess the corrupted archive file, recover the data and fix all issues.
For more information, see Using the Offline Archive Utility (piarchss) on page 40.
The -archk command can also be run with the optional argument complete, in order to
extract detailed information about the archive file structure. This extra information is similar
to what is provided by the archive walk command (see piartool -aw). It notably includes
point types and statistics (start time, event count, fill ratio) for every index or data record and
for each point in the archive file. The archive header information (see pidiag -ahd above) is
also included at the beginning of the report.
Here is an example of the detailed mode:
D:\PI\adm>pidiag -archk D:\PI\dat\piarch.001 complete
Analyzing archive: D:\PI\dat\piarch.001
-------------------------------------------------------------------------------
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Version: 7 Path: D:\PI\dat\piarch.001
State: 3 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 1.7
Offsets: Primary: 20/65536 Overflow: 128665/131072
Annotations: 10826/65535 Annotation File Size: 434144
Start Time: 19-Oct-05 12:39:10
End Time: Current Time
Backup Time: Never
Last Modified: 19-Dec-05 18:09:15
recno: 1, id: 1, events: 636, annotations: 0, fr: 89.4% - (Float32)
index array size: 1
0: idxrec id: 1, record pointers: 5, total events: 636
record array size: 5
0: record id: 130516, start: 19-Oct-05 12:39:10, events: 142, fr: 99.4%
1: record id: 130811, start: 30-Oct-05 15:33:27, events: 142, fr: 99.7%
2: record id: 130515, start: 12-Nov-05 09:29:36, events: 142, fr: 99.9%
3: record id: 130210, start: 22-Nov-05 04:44:08, events: 142, fr: 99.9%
4: record id: 128814, start: 15-Dec-05 13:31:42, events: 68, fr: 47.9%
[...]
PI Server System Management Guide Page 273
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
12.4.6 Downgrade Archive File to Older Versions
Command syntax:
pidiag -adg <version> 'path'
The -adg command offers the ability to downgrade archive files, so they can be mounted by
older versions of the PI Archive. Archive file versions are displayed in the archive header
information (see previous section about pidiag -ahd). The following table shows the archive
file versions of the most recently released PI Servers:
PI Server Version(s) Archive Version
3.3 5
3.4.363/364 6
3.4.370 7
Note: PIdiag -adg accepts wildcard characters in the “path” argument (example:
“D:\PI\dat\piarch.*”). This allows performing easy downgrade of many archive files in
a single command.
Example, converting an archive file from PI 3.4.370 to 3.4.364:
D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Path: D:\PI\dat\piarch.005
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 0.0
Offsets: Primary: 17/65536 Overflow: 131071/131072
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 1-Jan-04 00:00:00
End Time: 1-Jan-05 00:00:00
Backup Time: Never
Last Modified: 15-Nov-05 18:37:37
Conversion command:
D:\PI\adm>pidiag -adg 6 D:\PI\dat\piarch.005
Processing: D:\PI\dat\piarch.005... [0] Success
D:\PI\adm>pidiag -ahd d:\pi\dat\piarch.005
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: 101 $]::
Path: D:\PI\dat\piarch.005
State: 3 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 0.0
Offsets: Primary: 17/65536 Overflow: 131071/131072
Annotations: 1/65535 Annotation File Size: 2064
Start Time: 1-Jan-04 00:00:00
End Time: 1-Jan-05 00:00:00
Backup Time: Never
End of Dump
Page 274
12.5 - Server ID Utilities
12.5 Server ID Utilities
As of PI 3.3 SR1, the Server ID of the PI Server is stored in the PI\dat\PISysID.dat file. The
first time that any PI-SDK application connects to a PI Server from a given node, the PI-SDK
caches this server ID in the client’s local Registry. On subsequent connections, PI-SDK
applications compare the cached Server ID to the actual Server ID of the PI Server during the
Server.Open call to make sure that a connection is being made to the same PI Server.
Although the PISysID.dat file did not exist before PI 3.3 SR1, the PI Server still returned a
Server ID to PI-SDK applications. The PI Server used a hashing algorithm to determine the
Server ID, which took the name of the machine as input and generated a number as output.
This number was not a globally unique identifier (GUID), which meant that the hashing
algorithm could generate the same numeric identifier from two different machine names.
If PI 3.3 SR1 or greater is installed as a new system, the Server ID is generated as a GUID
and stored in the PISysID.dat file. If PI 3.3 SR1 or greater is installed as an upgrade from a
system that is less than 3.3 SR1, then the Server ID is generated using the old hashing
algorithm and stored in the in the PISysID.dat file.
There are three pidiag options, -dapi, -cid, and -did, that can be used to troubleshoot or to
generate a PISysID.dat file. The -dapi option echoes a Server ID to the standard output using
the old hashing algorithm. The usage is:
pidiag -dapi [hostname]
If hostname is not passed, then the host name of the machine is used in the hashing algorithm.
Here is some example output from the -dapi option.
pidiag -dapi MyServer Host: MyServer API Server ID: 6239
The -cid option generates a new PISysID.dat file. The usage is:
-cid [ < ServerID > < APIServerID> ] |install] | [-upgrade]
The optional APIServerID that can be passed on the command line is not used by any
application. If the optional ServerID is passed on the command line, simply pass the same
identifier for the APIServerID. The -install option causes the Server ID to be generated as a
GUID. The -upgrade option causes the Server ID to be generated using the old hashing
algorithm.
The -did option dumps the contents of the PISysID.dat file.
pidiag -did
Dumping file E:\PI\dat\PISysID.dat
1. MajorVersion: 3
2. MinorVersion: 3
3. MajorBuild: 361
4. MinorBuild: 98
5. ServerID: 1eb5cdbe-0666-43a5-900d-235344ee43ea
6. APIServerID: 91049
A new PISysID.dat file would need to be generated in the following scenario: Suppose that
you have a pre-SR1, PI 3.3 Server that you want to move to a different node. The new
machine will be given the same name as the old machine after the migration is complete.
PI Server System Management Guide Page 275
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
Install PI 3.3 SR1 on the new node and copy the archive files from the old PI 3.3 system to
the new node. A PISysID.dat file on the new 3.3 SR1 Server will be generated with a GUID
as the Server ID because the 3.3 SR1 install was not an upgrade. It would be desirable to
create a PISysID.dat file with a Server ID that was generated with the old hashing algorithm
so that old PI-SDK applications will not complain when they are connecting to the new
server. This new file can be generated as follows.
pidiag -dapi MyServer Host: MyServer API Server ID: 6239
pidiag -cid 6239 6239
Alternatively, if the name of the new Server has already been changed to MyServer, the new
file can be generated as follows.
pidiag -cid -upgrade
12.6 Performance Counter Utilities (Windows Only)
12.6.1 Get Performance Counter Path
The -gpc option of pidiag can be used to help configure performance counter tags for use
with the PI Performance Monitor interface.
From a command prompt, type the command
pidiag -gpc
to bring up the Get Counter Path Dialog.
Select counters from the dialog and click the Add button. Clicking the Add button causes the
full path of the performance counter to be echoed to the command prompt. The format of the
path is the same format used by the PI Performance Monitor Interface.
Once all desired counters have been echoed to the command prompt, the output can be used
in conjunction with the PI TagConfigurator Excel Add-In for building PI Performance
Monitor Tags.
12.6.2 Uninstall Performance Counters
The -upc option of pidiag uninstalls performance counters for the specified subsystem for
debugging purposes. For example
pidiag -upc pinetmgr
removes the Registry key
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\pinetmgr\Performance
and all of its values. Stopping and starting pinetmgr as a service, re-installs the performance
counters.
12.6.3 Get Performance Counter Values
The -gmmf option of pidiag can be useful to check the definition or get the current values of
PI performance counters. These performance counters are exposed by all PI Subsystems and
are available through the standard Windows Performance Counter API. The PI Perf-Mon
Page 276
12.6 - Performance Counter Utilities (Windows Only)
Interface (the Basic version is included with the PI Server distribution) can easily be set up to
historize the value of these performance counters in the PI Archive, as well as the OS-
provided ones.
The following table shows the list of Performance Counter object names for the main PI
Subsystems:
Subsystem Main Counters Session Statistics Subsystem Statistics
PI Network Manager pinetmgr_Counters N/A N/A
PI Message Subsystem pimsgss_Counters PISession:pimsgss PISubsys:pismsgss
PI License Manager pilicmgr_Counters PISession:pilicmgr PISubsys:pilicmgr
PI Update Manager piupdmgr_Counters PISession:piupdmgr PISubsys:piupdmgr
PI Base Subsystem pibasess_Counters PISession:pibasess PISubsys:pibasess
PI Snapshot Subsystem pisnapss_Counters PISession:pisnapss PISubsys:pisnapss
PI Archive Subsystem piarchss_Counters PISession:piarchss PISubsys:piarchss
Important Notes
These object names are case sensitive. PIdiag will return a system error 2 when
mistyped.
These objects are all defined in the global namespace of Windows. As a result, their
names must always be prefixed by the string Global\ (case-sensitive).
Example:
C:\PI\adm>pidiag -gmmf Global\pibasess_Counters
Performance counters for MMF Global\pibasess_Counters
Point Count: 200558
Connector Point Count: 0
Point Create or Edit/sec: 0
Digital State Translations/sec: 165
Wild Card Searches/sec: 200
Point Accesses/sec: 200710
Module Count: 20
Heading Set Count: 0
Heading Count: 0
Module Database Record Count: 24
Module Create or Edit/sec: 0
Heading Set Create or Edit/sec: 0
Heading Create or Edit/sec: 0
Module Database Create or Edit/sec: 0
Module Accesses/sec: 94
Heading Set Accesses/sec: 0
Heading Accesses/sec: 0
Module Database Accesses/sec: 94
PI Server System Management Guide Page 277
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
12.7 Miscellaneous
12.7.1 Wait for Passed Milliseconds
The command to wait for passed milliseconds is:
pidiag -w msec
This is used in several PI command procedures.
12.7.2 Testing Crash Dump Capability of an OS
The command to crash the pidiag utility by accessing a non-existent element of an array is:
pidiag -crash
This is used to test the crash dump capability of a particular operating system: “Dr. Watson”
on Windows and “core” on UNIX.
PIdiag, when run with the -crash argument purposely raises an operating system exception;
in other words, it purposely crashes. This is used to test the installed just-in-time debugger.
Windows Only
Dr. Watson is the default just-in-time Windows debugger. Debuggers, including Dr. Watson,
rely on debug symbols to translate code addresses to line numbers and meaningful text. The
PI System installs these symbols in %SystemRoot%\Symbols\exe directory where
SystemRoot is typically C:\Windows. The system environment variable,
_NT_SYMBOLS_PATH, must include this full path. On a crash, if this path is not included
in _NT_SYMBOLS_PATH the crash symbols will not be correctly interpreted.
12.7.3 Reset Password to Blank
The command to reset the piadmin (userid #1) password to blank is:
pidiag -udf <path>
This is useful when the piadmin password is lost. Following this operation, the piadmin
password can be set to any given string using the pisetpass utility. For example,
e:\PI\adm>pidiag -udf e:\pi\dat\
The administrative password has been successfully reset.
The administrative account is piadmin.
Note: The PI Base Subsystem must be shut down for this command to succeed.
Also notice the path argument requires a trailing \ or / character.
12.7.4 Display Network Definitions
The command to display the network definitions of a computer is:
pidiag -host
This option may be used on nodes running client applications and interfaces, to help the
definition of trust login records. For example:
Page 278
12.7 - Miscellaneous
d:\pi\adm>pidiag -host
Domain <OSI>
Machine <bilbo>
User <Bagins>
IP Addr <205.171.76.181>
Primary Domain Controller: <\\MASTERDC>
This option also tests the availability of the Domain Controller. This call should complete is a
fraction of a second; if it hangs or takes more than a few seconds to return it indicates the
Domain Controller access may not be fast or consistent. Failure to have prompt access to the
Domain Controller will result in poor PI System performance.
12.7.5 Register a COM Component
pidiag -rgs
This registers a COM component by running the input registration script. The script should
have all the necessary registry information to launch and access the component. This utility is
useful if the COM component is to run remotely from a client node and the client node does
not have all the necessary .dll's in order to instantiate it locally, which is required in order for
the component to self-register.
The component should be provided with the script.
pidiag -rgs [-?] [-u] FILENAME.RGS
[Replaceable Parameter="Value"]
Arguments in square brackets [ ] are optional.
-? Displays this help dialog
-u Performs unregistration.
12.7.6 Replaceable Parameter
- Anything in the RGS file surrounded by % is a replaceable parameter. For example:
%MODULE%.
Value - You must provide a value for replaceable parameters. For example, to register an
RGS file that contains %MODULE% in the script as below:
HKCR
{
NoRemove CLSID
{
ForceRemove {8FC8B7BC-0C07-11D4-84C4-00C04F6102DF} = s
'UDSSim4 Class'
{
ProgID = s 'Demo4.UDSSim4.1'
VersionIndependentProgID = s 'Demo4.UDSSim4'
ForceRemove 'Programmable'
LocalServer32 = s '%MODULE%'
val AppID = s '{8FC8B7B0-0C07-11D4-84C4-
00C04F6102DF}'
PI Server System Management Guide Page 279
Chapter 12 - Finding and Fixing Problems: the pidiag Utility
'TypeLib' = s '{8FC8B7AF-0C07-11D4-84C4-
00C04F6102DF}'
}
}
}
pidiag -rgs MYOBJECT.RGS MODULE=
"c:\Program Files\MyProgram\myobject.exe"
12.7.7 GUID Generation
The -uuid options of pidiag can be used to generate globally unique identifiers, known as
GUIDs.
pidiag -uuid
43157bae-8156-403e-b0f6-a3c1581fe86a
12.7.8 Machine-specific Programming Information
The -machine option of pidiag can be used to print out machine-specific information that
may be useful for programmers. On Windows machines, this option also provides details
about the processor architecture of the local machine. The number of processors (both
physical and logical) is shown, as well as information on the presence of Intel® Hyper-
Threading Technology.
pidiag -machine
CPU Architecture: INTEL
Physical/Logical Processors: 1/2
Hyper-Threading Status: 1 (enabled)
System appears to be little endian.
PI System built as little endian.
long integers are 4 bytes.
TCHARs are 1 byte.
Pointers are 4 bytes.
Enumerations are 4 bytes.
int8s are 1 byte.
uint8s are 1 byte.
int16s are 2 bytes.
uint16s are 2 bytes.
int32s are 4 bytes.
uint32s are 4 bytes.
int64s are 8 bytes.
uint64s are 8 bytes.
float32s are 4 bytes.
float64s are 8 bytes.
Page 280
APPENDIX A: PI MESSAGES
This chapter discusses the messages that PI writes to its message logs during normal
operation. Messages are written to the message log by the PI Message Subsystem. Use the
pigetmsg utility in the PI\adm directory to retrieve messages.
Normal Startup Messages
The following messages are typical when the PI System is started:
0 pinetmgr 27-Oct-05 16:23:12
>> WorkingSet Parameters changed, Current settings: 0.195313, 1984MB,
Previous settings: 0.195313, 1.34766MB
0 pinetmgr 27-Oct-05 16:23:12
>> Local listener opened
0 pinetmgr 27-Oct-05 16:23:12
>> Starting main control loop.
0 pimsgss 27-Oct-05 16:23:14
>> PI Message subsystem starting
0 pimsgss 27-Oct-05 16:23:14
>> Starting PI process pimsgss.
0 pinetmgr 27-Oct-05 16:23:14
>> Connection accepted: Process name: pimsgss(3852) ID: 0
0 pimsgss 27-Oct-05 16:23:14
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pinetmgr 27-Oct-05 16:23:15
>> Servertablelist received from: pimsgss(3852). 3 entries: PImsg|1
pimsgss_subsysquery|1 pimsgss_dbsecurity|1
0 pinetmgr 27-Oct-05 16:23:15
>> Connection accepted: Process name: pilicmgr(3228) ID: 1
0 pilicmgr 27-Oct-05 16:23:15
>> Starting PI process pilicmgr.
0 pinetmgr 27-Oct-05 16:23:16
>> Servertablelist received from: pilicmgr(3228). 3 entries: pilicmgr|1
pilicmgr_subsysquery|1 pilicmgr_dbsecurity|1
0 pinetmgr 27-Oct-05 16:23:17
>> Connection accepted: Process name: piartool(2568) ID: 2
0 pilicmgr 27-Oct-05 16:23:17
>> PI subsystem pilicmgr is now running, version: PI 3.4.370.52
0 pilicmgr 27-Oct-05 16:23:17
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
PI Server System Management Guide Page 281
0 pilicmgr 27-Oct-05 16:23:17
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:23:20
>> Connection accepted: Process name: piartool(3772) ID: 3
0 pinetmgr 27-Oct-05 16:23:23
>> Connection accepted: Process name: piartool(2560) ID: 4
0 pinetmgr 27-Oct-05 16:23:25
>> Connection accepted: Process name: piupdmgr(3184) ID: 5
0 piupdmgr 27-Oct-05 16:23:25
>> Starting PI process piupdmgr.
0 pinetmgr 27-Oct-05 16:23:26
>> Connection accepted: Process name: piartool(2588) ID: 6
0 pinetmgr 27-Oct-05 16:23:26
>> Servertablelist received from: piupdmgr(3184). 4 entries: piupdmgr|1
piupdmgr|2 piupdmgr_subsysquery|1 piupdmgr_dbsecurity|1
0 piupdmgr 27-Oct-05 16:23:27
>> PI subsystem piupdmgr is now running, version: PI 3.4.370.52
0 piupdmgr 27-Oct-05 16:23:27
>> WorkingSet Parameters changed, Current settings: 0.195313, 1984MB,
Previous settings: 0.195313, 1.34766MB
0 piupdmgr 27-Oct-05 16:23:27
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:23:29
>> Connection accepted: Process name: pibasess(2732) ID: 7
0 pinetmgr 27-Oct-05 16:23:29
>> Connection accepted: Process name: piartool(3124) ID: 8
0 pibasess 27-Oct-05 16:23:29
>> Starting PI process pibasess.
0 pinetmgr 27-Oct-05 16:23:30
>> Servertablelist received from: pibasess(2732). 6 entries: piptss|1
piusss|1 piptsdk|1 PIModuleDbSDK|1 pibasess_subsysquery|1
pibasess_dbsecurity|1
0 pibasess 27-Oct-05 16:23:31
>> PI subsystem pibasess is now running, version: PI 3.4.370.52
0 pibasess 27-Oct-05 16:23:31
>> WorkingSet Parameters changed, Current settings: 0.195313, 1984MB,
Previous settings: 0.195313, 1.34766MB
0 pibasess 27-Oct-05 16:23:31
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:23:32
>> Connection accepted: Process name: pisnapss(3720) ID: 9
0 pisnapss 27-Oct-05 16:23:32
>> Starting PI process pisnapss.
0 pievqwriter 27-Oct-05 16:23:33
>> Primary Queue successfully initialized (64MB/1024KB)
0 pinetmgr 27-Oct-05 16:23:33
>> Connection accepted: Process name: piartool(2728) ID: 10
0 pinetmgr 27-Oct-05 16:23:34
>> Servertablelist received from: pisnapss(3720). 3 entries: pisnapss|1
pisnapss_subsysquery|1 pisnapss_dbsecurity|1
0 pisnapmgr 27-Oct-05 16:23:34
Page 282
>> Snapshot records loaded, count: 13, found: 13, status: [0] Success
0 pisnapmgr 27-Oct-05 16:23:34
>> PIsnapmgr::loadsnaptables: loaded: C:\PI\dat\piarcmem.dat, status:
[0] Success
0 pisnapss 27-Oct-05 16:23:35
>> PI subsystem pisnapss is now running, version: PI 3.4.370.52
0 pisnapss 27-Oct-05 16:23:35
>> WorkingSet Parameters changed, Current settings: 0.195313, 1984MB,
Previous settings: 0.195313, 1.34766MB
0 pisnapss 27-Oct-05 16:23:35
>> Digital State table synchronized with Base Subsystem
0 pisnapss 27-Oct-05 16:23:35
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:23:35
>> Deleting connection: piartool(2568), Shutdown request received from
piartool(2568) (8), ID: 2
0 Connection Statistics 27-Oct-05 16:23:35
>> ID: 2; Duration: 0.03 min.; kbytes sent: 4.90; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:35
>> Deleting connection: piartool(3772), Shutdown request received from
piartool(3772) (8), ID: 3
0 Connection Statistics 27-Oct-05 16:23:35
>> ID: 3; Duration: 0.03 min.; kbytes sent: 4.90; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:36
>> Connection accepted: Process name: piarchss(356) ID: 11
0 pinetmgr 27-Oct-05 16:23:36
>> Connection accepted: Process name: piartool(2720) ID: 12
0 piarchss 27-Oct-05 16:23:36
>> Starting PI process piarchss.
0 pievqreader 27-Oct-05 16:23:37
>> Primary Queue successfully loaded (0 events)
0 piarcmgr 27-Oct-05 16:23:37
>> Primary archive file C:\PI\dat\piarch.001 loaded.
0 piarcmgr 27-Oct-05 16:23:37
>> Archive file C:\PI\dat\piarch.002 loaded.
0 piarcmgr 27-Oct-05 16:23:37
>> Archive file C:\PI\dat\piarch.003 loaded.
0 piarcmgr 27-Oct-05 16:23:37
>> Cache Manager: cache pool set to 2048 records, maximum unflushed
events per point is 256.
0 pinetmgr 27-Oct-05 16:23:37
>> Servertablelist received from: piarchss(356). 5 entries: piarss|1
piarss2|1 piarbatch|1 piarchss_subsysquery|1 piarchss_dbsecurity|1
0 piarchss 27-Oct-05 16:23:38
>> PI subsystem piarchss is now running, version: PI 3.4.370.52
0 piarchss 27-Oct-05 16:23:38
>> WorkingSet Parameters changed, Current settings: 0.195313, 1984MB,
Previous settings: 0.195313, 1.34766MB
0 piarchss 27-Oct-05 16:23:38
PI Server System Management Guide Page 283
>> Digital State table synchronized with Base Subsystem
0 piarchss 27-Oct-05 16:23:38
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:23:39
>> Connection accepted: Process name: piartool(3544) ID: 13
0 pinetmgr 27-Oct-05 16:23:42
>> Connection accepted: Process name: piartool(3920) ID: 14
0 pinetmgr 27-Oct-05 16:23:44
>> Connection accepted: Process name: piartool(1984) ID: 15
0 pinetmgr 27-Oct-05 16:23:47
>> Deleting connection: piartool(2728), Shutdown request received from
piartool(2728) (8), ID: 10
0 Connection Statistics 27-Oct-05 16:23:47
>> ID: 10; Duration: 0.03 min.; kbytes sent: 23.77; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:47
>> Deleting connection: piartool(2560), Shutdown request received from
piartool(2560) (8), ID: 4
0 Connection Statistics 27-Oct-05 16:23:47
>> ID: 4; Duration: 0.05 min.; kbytes sent: 4.76; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:47
>> Deleting connection: piartool(2588), Shutdown request received from
piartool(2588) (8), ID: 6
0 Connection Statistics 27-Oct-05 16:23:47
>> ID: 6; Duration: 0.03 min.; kbytes sent: 4.76; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:47
>> Deleting connection: piartool(3124), Shutdown request received from
piartool(3124) (8), ID: 8
0 Connection Statistics 27-Oct-05 16:23:47
>> ID: 8; Duration: 0.03 min.; kbytes sent: 8.30; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:47
>> WorkingSet Parameters: 0.195313MB, 1984MB.
0 pinetmgr 27-Oct-05 16:23:47
>> Connection accepted: Process name: piartool(3724) ID: 16
0 pinetmgr 27-Oct-05 16:23:50
>> Connection accepted: Process name: piartool(3052) ID: 17
0 pinetmgr 27-Oct-05 16:23:53
>> Connection accepted: Process name: piartool(3684) ID: 18
0 pinetmgr 27-Oct-05 16:23:56
>> Connection accepted: Process name: piartool(2184) ID: 19
0 pinetmgr 27-Oct-05 16:23:58
>> Deleting connection: piartool(1984), Shutdown request received from
piartool(1984) (8), ID: 15
0 Connection Statistics 27-Oct-05 16:23:58
>> ID: 15; Duration: 0.05 min.; kbytes sent: 35.21; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:58
Page 284
>> Deleting connection: piartool(3920), Shutdown request received from
piartool(3920) (8), ID: 14
0 Connection Statistics 27-Oct-05 16:23:58
>> ID: 14; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv:
0.54; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:58
>> Deleting connection: piartool(3544), Shutdown request received from
piartool(3544) (8), ID: 13
0 Connection Statistics 27-Oct-05 16:23:58
>> ID: 13; Duration: 0.03 min.; kbytes sent: 35.21; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:58
>> Deleting connection: piartool(2720), Shutdown request received from
piartool(2720) (8), ID: 12
0 Connection Statistics 27-Oct-05 16:23:58
>> ID: 12; Duration: 0.03 min.; kbytes sent: 26.59; kbytes recv:
0.54; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:23:58
>> Connection accepted: Process name: pishutev(2540) ID: 20
0 pishutev 27-Oct-05 16:23:58
>> Starting PI process pishutev.
0 pishutev 27-Oct-05 16:24:00
>> PI subsystem pishutev is now running, version: PI 3.4.370.52
0 pishutev 27-Oct-05 16:24:00
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pishutev 27-Oct-05 16:24:00
>> Shutdown input file: C:\PI\dat\shutdown.dat.
0 pishutev 27-Oct-05 16:24:00
>> Shutdown events will be written for tag mask *
Point attributes:
shutdown, 1
0 pinetmgr 27-Oct-05 16:24:01
>> Connection accepted: Process name: piartool(3780) ID: 21
0 pinetmgr 27-Oct-05 16:24:03
>> Connection accepted: Process name: pisqlss(3388) ID: 22
0 pisqlss 27-Oct-05 16:24:03
>> Starting PI process pisqlss.
0 pinetmgr 27-Oct-05 16:24:05
>> Servertablelist received from: pisqlss(3388). 3 entries: pisqlss|1
pisqlss_subsysquery|1 pisqlss_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:05
>> Connection accepted: Process name: piartool(2748) ID: 23
0 pisqlss 27-Oct-05 16:24:06
>> PI subsystem pisqlss is now running, version: PI 3.4.370.52
0 pisqlss 27-Oct-05 16:24:06
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pisqlss 27-Oct-05 16:24:06
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:24:08
PI Server System Management Guide Page 285
>> Connection accepted: Process name: pibackup(3496) ID: 24
0 pibackup 27-Oct-05 16:24:08
>> Starting PI process pibackup.
0 pinetmgr 27-Oct-05 16:24:09
>> Deleting connection: piartool(2184), Shutdown request received from
piartool(2184) (8), ID: 19
0 Connection Statistics 27-Oct-05 16:24:09
>> ID: 19; Duration: 0.05 min.; kbytes sent: 35.21; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:09
>> Deleting connection: piartool(3684), Shutdown request received from
piartool(3684) (8), ID: 18
0 Connection Statistics 27-Oct-05 16:24:09
>> ID: 18; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:09
>> Deleting connection: piartool(3052), Shutdown request received from
piartool(3052) (8), ID: 17
0 Connection Statistics 27-Oct-05 16:24:09
>> ID: 17; Duration: 0.03 min.; kbytes sent: 35.21; kbytes recv:
0.42; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:09
>> Deleting connection: piartool(3724), Shutdown request received from
piartool(3724) (8), ID: 16
0 Connection Statistics 27-Oct-05 16:24:09
>> ID: 16; Duration: 0.03 min.; kbytes sent: 35.06; kbytes recv:
0.55; app: ; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:10
>> Servertablelist received from: pibackup(3496). 3 entries: pibackup|1
pibackup_subsysquery|1 pibackup_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:10
>> Connection accepted: Process name: piartool(3256) ID: 25
0 pibackup 27-Oct-05 16:24:11
>> PI subsystem pibackup is now running, version: PI 3.4.370.52
0 pibackup 27-Oct-05 16:24:11
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pibackup 27-Oct-05 16:24:11
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:24:12
>> TCP/IP (IPV4) connection listener opened on port: 5450
0 pinetmgr 27-Oct-05 16:24:13
>> Connection accepted: Process name: pitotal(1804) ID: 26
0 pitotal 27-Oct-05 16:24:13
>> Starting PI process pitotal.
0 pinetmgr 27-Oct-05 16:24:15
>> Connection accepted: Process name: piartool(1152) ID: 27
0 pinetmgr 27-Oct-05 16:24:18
>> Connection accepted: Process name: pialarm(3300) ID: 28
0 pialarm 27-Oct-05 16:24:18
>> Starting PI process pialarm.
Page 286
0 pinetmgr 27-Oct-05 16:24:20
>> Deleting connection: piartool(2748), Shutdown request received from
piartool(2748) (8), ID: 23
0 Connection Statistics 27-Oct-05 16:24:20
>> ID: 23; Duration: 0.05 min.; kbytes sent: 38.44; kbytes recv:
0.54; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:20
>> Servertablelist received from: pialarm(3300). 3 entries: pialarm|1
pialarm_subsysquery|1 pialarm_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:20
>> Deleting connection: piartool(3780), Shutdown request received from
piartool(3780) (8), ID: 21
0 Connection Statistics 27-Oct-05 16:24:20
>> ID: 21; Duration: 0.05 min.; kbytes sent: 35.06; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:20
>> Connection accepted: Process name: piartool(2592) ID: 29
0 pialarm 27-Oct-05 16:24:21
>> PI subsystem pialarm is now running, version: PI 3.4.370.52
0 pialarm 27-Oct-05 16:24:21
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pialarm 27-Oct-05 16:24:21
>> Initializing alarms.
0 pialarm 27-Oct-05 16:24:21
>> Registered to update manager as a consumer
0 pialarm 27-Oct-05 16:24:21
>> Registered for point updates.
0 pialarm 27-Oct-05 16:24:21
>> Initialize group tags (pointsource G )
0 pialarm 27-Oct-05 16:24:21
>> 0 alarm group tags. 0 alarm groups.
0 pialarm 27-Oct-05 16:24:21
>> Restarting from save file C:\PI\dat\pilastalarm.dat
0 pialarm 27-Oct-05 16:24:21
>> 0 alarm tags.
0 pialarm 27-Oct-05 16:24:21
>> Initialize SQC alarm tags (pointsource Q )
0 pialarm 27-Oct-05 16:24:21
>> 0 sqc alarm tags.
0 pialarm 27-Oct-05 16:24:21
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:24:23
>> PInet accepted TCP/IP connection, cnxn ID 30 Hostname:
samson.osisoft.com, 127.0.0.1:1104
0 pinetmgr 27-Oct-05 16:24:23
>> New Pinet 1 connection: PipeE Protocol: 00010008
0 pinetmgr 27-Oct-05 16:24:23
>> New Pinet 1 connection: PipeE Successful Trust-Relation login:
samson.osisoft.com|127.0.0.1|PipeE piadmin.
0 pinetmgr 27-Oct-05 16:24:23
PI Server System Management Guide Page 287
>> Connection accepted: Process name: PIPESCHD(2076) ID: 31
0 pinetmgr 27-Oct-05 16:24:25
>> Servertablelist received from: pitotal(1804). 3 entries: pitotal|1
pitotal_subsysquery|1 pitotal_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:25
>> Connection accepted: Process name: piartool(2628) ID: 32
0 pitotal 27-Oct-05 16:24:26
>> PI subsystem pitotal is now running, version: PI 3.4.370.52
0 pitotal 27-Oct-05 16:24:26
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pitotal 27-Oct-05 16:24:26
>> Registered to update manager as a consumer
0 pitotal 27-Oct-05 16:24:26
>> Registered for point updates.
0 pitotal 27-Oct-05 16:24:26
>> Restarting from save file C:\PI\dat\pilasttot_T.dat
0 pitotal 27-Oct-05 16:24:26
>> Startup complete - 0 active points.
0 pitotal 27-Oct-05 16:24:26
>> Rpcservertablelist successfully registered to pinetmgr.
0 pinetmgr 27-Oct-05 16:24:27
>> Successful login ID: 30. Address: 127.0.0.1. Host:
samson.osisoft.com. Name: PipeE. User: piadmin. Trust: !Proxy_127!
0 pinetmgr 27-Oct-05 16:24:28
>> Connection accepted: Process name: pibatch(2708) ID: 33
0 pibatch 27-Oct-05 16:24:28
>> Starting PI process pibatch.
0 pinetmgr 27-Oct-05 16:24:30
>> Servertablelist received from: pibatch(2708). 3 entries: pibatch|1
pibatch_subsysquery|1 pibatch_dbsecurity|1
0 pinetmgr 27-Oct-05 16:24:30
>> Connection accepted: Process name: piartool(2504) ID: 34
0 pibatch 27-Oct-05 16:24:31
>> PI subsystem pibatch is now running, version: PI 3.4.370.52
0 pibatch 27-Oct-05 16:24:31
>> WorkingSet Parameters changed, Current settings: 0.195313, 10MB,
Previous settings: 0.195313, 1.34766MB
0 pibatch 27-Oct-05 16:24:31
>> Starting pibatch
0 pibatch 27-Oct-05 16:24:31
>> Registered to update manager as a consumer
0 pibatch 27-Oct-05 16:24:31
>> Registered for point updates.
0 pibatch 27-Oct-05 16:24:31
>> Batch databases loaded
0 pibatch 27-Oct-05 16:24:31
>> Rpcservertablelist successfully registered to pinetmgr.
0 pibackup 27-Oct-05 16:24:31
>> Successfully registered subsystem pibatch, version 3.4.370.52
0 pinetmgr 27-Oct-05 16:24:32
Page 288
>> Deleting connection: piartool(1152), Shutdown request received from
piartool(1152) (8), ID: 27
0 Connection Statistics 27-Oct-05 16:24:32
>> ID: 27; Duration: 0.03 min.; kbytes sent: 39.83; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:32
>> Deleting connection: piartool(3256), Shutdown request received from
piartool(3256) (8), ID: 25
0 Connection Statistics 27-Oct-05 16:24:32
>> ID: 25; Duration: 0.03 min.; kbytes sent: 39.83; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:38
>> Connection accepted: Process name: piartool(3348) ID: 35
0 pinetmgr 27-Oct-05 16:24:40
>> Connection accepted: Process name: piartool(1240) ID: 36
0 piafserver.exe 27-Oct-05 16:24:43
>> Loading SubSystems from 'C:\Program Files\PIPC\PIAF\SubSystems':
0 pinetmgr 27-Oct-05 16:24:43
>> Connection accepted: Process name: piafserver.exe(3140) ID: 37
0 pinetmgr 27-Oct-05 16:24:44
>> Deleting connection: piartool(2504), Shutdown request received from
piartool(2504) (8), ID: 34
0 Connection Statistics 27-Oct-05 16:24:44
>> ID: 34; Duration: 0.03 min.; kbytes sent: 46.71; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:44
>> Deleting connection: piartool(2592), Shutdown request received from
piartool(2592) (8), ID: 29
0 Connection Statistics 27-Oct-05 16:24:44
>> ID: 29; Duration: 0.03 min.; kbytes sent: 41.19; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:44
>> Deleting connection: piartool(2628), Shutdown request received from
piartool(2628) (8), ID: 32
0 Connection Statistics 27-Oct-05 16:24:44
>> ID: 32; Duration: 0.03 min.; kbytes sent: 42.55; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:52
>> PInet accepted TCP/IP connection, cnxn ID 38 Hostname:
samson.osisoft.com, 127.0.0.1:1105
0 pinetmgr 27-Oct-05 16:24:52
>> New Pinet 1 connection: RmpSE Protocol: 00010008
0 pinetmgr 27-Oct-05 16:24:52
>> New Pinet 1 connection: RmpSE Successful Trust-Relation login:
samson.osisoft.com|127.0.0.1|RmpSE piadmin.
0 pinetmgr 27-Oct-05 16:24:52
>> PInet accepted TCP/IP connection, cnxn ID 39 Hostname:
samson.osisoft.com, 127.0.0.1:1106
0 pinetmgr 27-Oct-05 16:24:52
>> New Pinet 1 connection: RandE Protocol: 00010008
0 pinetmgr 27-Oct-05 16:24:52
PI Server System Management Guide Page 289
>> New Pinet 1 connection: RandE Successful Trust-Relation login:
samson.osisoft.com|127.0.0.1|RandE piadmin.
0 pinetmgr 27-Oct-05 16:24:55
>> Deleting connection: piartool(1240), Shutdown request received from
piartool(1240) (8), ID: 36
0 Connection Statistics 27-Oct-05 16:24:55
>> ID: 36; Duration: 0.03 min.; kbytes sent: 46.71; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:55
>> Deleting connection: piartool(3348), Shutdown request received from
piartool(3348) (8), ID: 35
0 Connection Statistics 27-Oct-05 16:24:55
>> ID: 35; Duration: 0.05 min.; kbytes sent: 46.64; kbytes recv:
0.55; app: piartool; user: ; osuser: ; trust: ; ip address: ; ip host:
0 pinetmgr 27-Oct-05 16:24:57
>> Successful login ID: 38. Address: 127.0.0.1. Host:
samson.osisoft.com. Name: RmpSE. User: piadmin. Trust: !Proxy_127!
0 pinetmgr 27-Oct-05 16:24:57
>> Successful login ID: 39. Address: 127.0.0.1. Host:
samson.osisoft.com. Name: RandE. User: piadmin. Trust: !Proxy_127!
0 pishutev 27-Oct-05 16:24:58
>> Shutdown of PI subsystem pishutev in progress.
0 pishutev 27-Oct-05 16:25:00
>> Shutdown Events at 27-Oct-05 16:21:46 sent for 10 Points
0 pishutev 27-Oct-05 16:25:00
>> Shutdown of PI subsystem pishutev complete.
0 pibackup 27-Oct-05 16:25:08
>> Successfully registered subsystem pisnapss, version 3.4.370.52
0 pibackup 27-Oct-05 16:25:08
>> Successfully registered subsystem piarchss, version 3.4.370.52
0 pibackup 27-Oct-05 16:25:08
>> Successfully registered subsystem pimsgss, version 3.4.370.52
0 pibackup 27-Oct-05 16:25:09
>> Successfully registered subsystem pilicmgr, version 3.4.370.52
0 pibackup 27-Oct-05 16:25:09
>> Successfully registered subsystem pibasess, version 3.4.370.52
0 pinetmgr 27-Oct-05 16:25:19
>> Deleting connection: pishutev(2540), Shutdown request received from
pishutev(2540) (8), ID: 20
0 Connection Statistics 27-Oct-05 16:25:19
>> ID: 20; Duration: 1.07 min.; kbytes sent: 38.39; kbytes recv:
15.06; app: pishutev; user: ; osuser: ; trust: ; ip address: ; ip host:
Client Connection Messages
The pinetmgr utility writes messages to the PI System message log that track
communications between PI clients and the PI Server.
The following message from pinetmgr indicates that a client is attempting to connect to PI
Server. Note that a connection ID (cnxn ID) is assigned.
0 pinetmgr 27-Oct-05 17:23:14
Page 290
>> PInet accepted TCP/IP connection, cnxn ID 44 Hostname:
samson.osisoft.int, 127.0.0.1:1209
PI API-based clients will have a message similar to the following. The client publishes its
name and protocol. The name is a five-character string. The first four letters give the
application name or login name; the fifth character is always E. In this example, the client
name is snapE:
0 pinetmgr 27-Oct-05 17:23:14
>> New Pinet 1 connection: snapE Protocol: 00010008
PI Server then attempts to use the credentials of the incoming connection to locate a record in
the PItrust database. If a match is found, the following message is written:
0 pinetmgr 27-Oct-05 17:23:14
>> New Pinet 1 connection: snapE Successful Trust-Relation login:
samson.osisoft.int|127.0.0.1|snapE piadmin.
If a match is not found, the message is:
0 pinetmgr 27-Oct-05 17:28:14
>> New Pinet 1 connection: snapE No Trust established for:
figaro.osisoft.com|24.20.166.163|snapE using default login.
A default login means that the connection is a member of the world as defined by the security
string associated with PI Server internals such as the point database and archived data. See
Chapter 1, System Management, for a description of the PI Server security model.
PI-SDK-based applications have a similar set of connection establishment messages. There
are two differences. First, the published application name is more detailed. It contains the full
executable name plus the process ID. Second, the trust login information is not published.
Here is a set of messages showing the About PI-SDK application connecting:
0 pinetmgr 27-Oct-05 19:04:44
>> PInet accepted TCP/IP connection, cnxn ID 49 Hostname:
caleb.osisoft.com, 192.1.1.114:4508
0 pinetmgr 27-Oct-05 19:04:44
>> Connection accepted: Process name: AboutPI
SDK.exe(5632):remote(5632) ID: 49
0 pibasess 27-Oct-05 19:04:45
>> Trust <pi3build> Granted to:
OSI\ADMINISTRATOR|caleb|192.1.1.114|AboutPI SDK.exe
(108 ms)
0 pinetmgr 27-Oct-05 19:04:46
>> Successful login ID: 49. Address: 192.1.1.114. Host:
caleb.osisoft.com. Name: AboutPI SDK.exe(5632):remote. User: piadmin.
Trust: caleb
Subsystem Connection Messages
The pinetmgr utility writes messages to the PI System message log that track
communications between utilities and the subsystems.
New connections requested by one of the PI subsystems are assigned a connection ID:
0 pinetmgr 27-Oct-05 16:23:25
PI Server System Management Guide Page 291
>> Connection accepted: Process name: piupdmgr(3184) ID: 5
The subsystem begins its own initialization. On Windows, part of this process involves
updating the subsystem’s own working set size limits:
0 piupdmgr 27-Oct-05 16:23:25
>> Starting PI process piupdmgr.
0 piupdmgr 27-Oct-05 16:23:27
>> PI subsystem piupdmgr is now running, version: PI 3.4.370.52
The above messages may be following by subsystem-specific initialization messages. When
initialization is complete, the subsystem tells pinetmgr which Remote Procedure Calls
(RPCs) it supports. This is indicated in the following message:
0 pinetmgr 27-Oct-05 16:23:26
>> Servertablelist received from: piupdmgr(3184). 4 entries: piupdmgr|1
piupdmgr|2 piupdmgr_subsysquery|1 piupdmgr_dbsecurity|1
When pinetmgr receives notification of new RPCs, it updates the master list, and then sends
the updated list to all PI subsystems. When a subsystem receives this updated master RPC
list, it writes the following message. At this point, the subsystem is ready to process remote
procedure calls:
0 piupdmgr 27-Oct-05 16:23:27
>> Rpcservertablelist successfully registered to pinetmgr.
If pinetmgr is unable to send the updated list to the new subsystem, it writes a message as
follows:
0 pinetmgr 27-Oct-05 16:32:22
>> Error sending client table(2) to: piupdmgr
A successfully connected subsystem may write messages indicating its initialization progress.
In general, there is no message written when initialization is complete and the subsystem is
ready to process RPC calls.
Disconnect Messages
The following messages indicate normal disconnects. The error number (in square brackets)
is given along with its translation.
0 pinetmgr 27-Oct-05 16:25:19
>> Deleting connection: pishutev(2540), Shutdown request received from
pishutev(2540) (8), ID: 20
0 pinetmgr 27-Oct-05 16:44:21
>> Deleting connection: RandE, [-10721] PINET: Client Aborted
Connection. (4), ID: 39 samson.osisoft.com 127.0.0.1:1106
The following messages indicate abnormal disconnects. The error number (in square
brackets) is given along with its translation.
0 pinetmgr 27-Oct-05 19:26:31
>> Deleting connection: snapE, GetQueuedCompletionStatus error:
Network name deleted [64] The specified network name is no longer
available. Connection: snapE (14, 64), ID: 51 samson.osisoft.com
127.0.0.1:1835
Page 292
The following message indicates that an RPC was not completed within the timeout
specified. The requestor passes the timeout when it places the call with pinetmgr. This
timeout is not configurable.
0 pinetmgr 19-Feb-97 17:19:26
[-10722] PINET: Timeout on PI RPC or System Call
RPC Resolver Messages
Every few minutes, the pinetmgr sends a healthcheck message to each of the PI subsystems.
If one doesn’t respond within a given amount of time, pinetmgr will report the following
message and the subsystem (RPC resolver) is marked off-line.
>> Deleting connection: pisnapss, Subsystem Healthcheck failed.
If an RPC is made to a subsystem that is marked off-line, the following message is generated.
[-10733] PINET: RPC Resolver is Off-Line
The following message indicates that the first part of a message was retrieved. This contains
the message length. The pinetmgr attempted to retrieve the rest of the message but a timeout
occurred.
>> Deleting connection: pisnapss, Connection lost(1),
[-10731] PINET: incomplete message
Piupdmgr
The pinetmgr utility keeps track of processes that have signed up for updates. It is possible
for a signed-up process to go away without properly unsigning up. If pinetmgr detects this
case, it will remove the dead process from its table and report the following message:
0 piupdmgr 19-Feb-97 17:31:15
>> Consumer <UNKNE|8> timed out! removed...
Error Codes
System error messages usually contain error codes. Error codes are reported in square
brackets. Negative numbers indicate PI System errors. Positive numbers indicate operating
system errors.
Pidiag
Use the pidiag utility to interpret error codes. Do not type the square brackets:
pidiag -e errorcode
This will display the associated error message. For example:
pidiag -e -10722
[-10722] PINET: Timeout on PI RPC or System Call
PIdiag will also translate operating system error codes, which are always positive numbers.
Note that the error code translation takes place on the operating system running pidiag. For
example, on Windows, you could issue the command:
PI Server System Management Guide Page 293
pidiag -e 2
[2] The system cannot find the file specified.
Avoid reading error codes from the PI Server message log on one operating system and
translating them with pidiag -e on another.
PI Error Message Codes
System error messages usually contain error codes. Error codes are reported in square
brackets. Negative numbers indicate PI System errors. Positive numbers indicate operating
system errors.
Table A-1. Error Codes 1-99, With Messages
Code Code Identifier Message
0 PI_NORMAL Success
-1 PI_ERROR Generic Error or PI 2.x Point Out of Range or Not
Defined
-2 PI_ATT_BLANKTAG Blank tag
-3 PI_ATT_PTDBFULL Point data base full
-4 PI_ATT_MEMDBFULL Memory data base full
-5 PI_ATT_TAGNOTFOUND Tag not found
-6 PI_ATT_BADCHARTAG Illegal Characters in Tag
-7 PI_ATT_TAGEXISTS Tag already exists
-8 PI_ATT_BADTIME Time is After Current Time and Date or Time is <0
-9 PI_ATT_BADINTVALUE Illegal Status Value or Integer Value
-10 PI_ATT_OTHERPROC Cannot Create Tag Because Other Procedure is
Creating Tag
-11 PI_ATT_BADDIGCODERANGE Digital Code is Out of Range
-12 PI_ATT_NODSSTRING Digital state string not found
-13 PI_ATT_BADDSCODERANGE Digital State Code Out of Range For This Tag
-15 PI_ATT_NOSOURCETAG Source tag not found
-19 PI_ATT_PTATTZERO Point Attribute Zero Error or Disk Error for Point
Database
-20 PI_ATT_BADZEROSPAN Bad Zero or Span For Integer Point
-21 PI_ATT_NEGSPAN Span not greater than zero
-22 PI_ATT_BADTYPVALUE Typical Value Not Between Zero and Top of Range
Page 294
Code Code Identifier Message
-23 PI_ATT_BADDSCODE Illegal digital state code
-24 PI_ATT_BADNUMDS Bad Number of Digital States
-25 PI_ATT_BADPTTYPE Illegal point type
-26 PI_ATT_BADPTSOURCE Illegal point source
-27 PI_ATT_BADENGUNIT Illegal engineering unit code
-28 PI_ATT_BADLOC1 Bad Location Parameter 1 (Range Depends on
Point Source)
-29 PI_ATT_BADLOC2 Bad Location Parameter 2 (Range Depends on
Point Source)
-30 PI_ATT_BADLOC3 Bad Location Parameter 3 (Range Depends on
Point Source)
-31 PI_ATT_BADLOC4 Bad Location Parameter 4 (Range Depends on
Point Source)
-32 PI_ATT_BADLOC5 Bad Location Parameter 5 (Range Depends on
Point Source)
-33 PI_ATT_BADTOTPTTYPE Point Type of Totalized Point is Not Real
-34 PI_ATT_BADRATEPT Rate Point Type Must Be Real or Integer
-35 PI_ATT_BADRESCODE Illegal resolution code
-36 PI_ATT_BADARCHONOFF Illegal archiving on/off value
-37 PI_ATT_BADCOMPONOFF Illegal compressing on/off value
-38 PI_ATT_BADCOMPDEV Illegal compression deviation specification
-39 PI_ATT_BADCOMPMINTIME Illegal compression minimum time specification
-40 PI_ATT_BADCOMPMAXTIME Illegal compression maximum time specification
-41 PI_ATT_BADEXCDEV Illegal exception deviation specification
-42 PI_ATT_BADEXCMINTIME Illegal exception minimum time specification
-43 PI_ATT_BADEXCMAXTIME Illegal exception maximum time specification
-44 PI_ATT_BADFILTCODE Illegal filter code
-45 PI_ATT_BADTOTCODE Illegal totalization code
-46 PI_ATT_BADTOTCONV Illegal totalization conversion factor
-49 PI_ATT_BADSQRTCODE Illegal square root code
-50 PI_ATT_BADSCANONOFF Illegal scan on/off value
PI Server System Management Guide Page 295
Code Code Identifier Message
-51 PI_ATT_RESCODECONST Cannot change resolution code
-52 PI_ATT_BADTIMEFORMAT Illegal time/date string format
-53 PI_ATT_POINTNOTTOTAL Point is Not a Total
-54 PI_ATT_TOTDBFULL Totalization data base full
-55 PI_ATT_PTNOTINTOTDB Point Not Defined in Totalization Data Base
-56 PI_ATT_SINGLEQUOTE Tagname Should Be in Single Quotes, not Double
Quotes
-57 PI_ATT_MISSINGTAG Filter or Trigger Tag Does Not Exist
-58 PI_ATT_EXTDESCSYNTAX Syntax Error in Extended Descriptor
-59 PI_ATT_BADEXTDESCKEYWD Unrecognized Keyword in Extended Descriptor
-60 PI_ATT_NOPIDAVAIL No more pid slots for retrieving point update lists
-61 PI_ATT_NOTAGCHANGE No More Tags Created, Edited, or Deleted
-62 PI_ATT_NOPTUPDATE Not signed up for point updates
-63 PI_ATT_BADDISPDIG Display Digits <-20 or >10
-64 PI_ATT_BADCLAMPCODE Illegal Clamping Code (<0 or >3)
-65 PI_ATT_BADSCHEDCODE Illegal Scheduling Code (<0 or >2)
-66 PI_ATT_NONATSCHED Natural Scheduling is Not Allowed For Post-
Processed Tags
-67 PI_ATT_BADGROUPPSIZE Illegal group size for moving average (<2)
-68 PI_ATT_BADPERIOD Illegal period
-69 PI_ATT_BADOFFSET Illegal Offset (<0 or >86399)
-70 PI_EVM_BADNUMPOINTS Illegal Number of Points (<1)
-71 PI_EVM_BADPOINTNUM Point Number Out of Range
-72 PI_EVM_NOMOREEXCEPT No more room for programs requesting exceptions
-73 PI_EVM_TOOMANYPTS No room for this many points for this list
-74 PI_EVM_NOMOREPTS No room for more points
-75 PI_EVM_NOPTSESTAB No points established
-76 PI_EVM_PTSNOTDISESTAB Some points not disestablished
-78 PI_EVM_TIMEOUT Timed out
Page 296
Code Code Identifier Message
-79 PI_EVM_BADTIMEOUT Bad timeout value
Table A–2. Error Codes 100-199, With Messages
Code Code Identifier Message
-101 PI_ARCH_DATENOTONLINE Date not on-line
-102 PI_ARCH_RECORDNOTFOUND Record not found (empty)
-103 PI_ARCH_NODATA No Data For This Point at This Time
-105 PI_ARCH_BADSTARTENDTIME End Time Not After Start Time, or Start Time <0
-106 PI_ARCH_NOGOODDATA No Good Data For This Point at This Time
-107 PI_ARCH_NEGSQUAREROOT Cannot Calculate Square Root of Negative Number
-108 PI_ARCH_BADEDITTIME Time is Before the Editing Time Limit
-109 PI_ARCH_VALUEEXISTS Value at This Time Already Exists
-110 PI_ARCH_SLOWARCHIVE Archive program not keeping up with events
-111 PI_ARCH_30SECRULE Event Not Processed by Archive Program Within
30 Seconds
-112 PI_ARCH_ARCH1OFFLINE Point not created because archive one not on-line
-113 PI_ARCH_TOOFEWVALUES “Number of Values” Argument to Archive Retrieval
Routine is Bad
Table A–3. Error Codes 200-299, With Messages
Code Code Identifier Message
-201 PI_PE_CORRUPTFILE Performance Equation file corrupted
-202 PI_PE_CANTDELETEPETAG Cannot delete tag that is used in PE
-203 PI_PE_CANTDELETETOTTAG Cannot delete tag that is used in totalization
-204 PI_PE_CANTDELETESQCTAG Cannot delete tag that is used in SQC calc
-251 PI_SQL_MEMERR SQL: memory allocation error
-252 PI_SQL_SYNERR SQL: syntax error
-253 PI_SQL_INVSTMT SQL: invalid statement
-254 PI_SQL_INTERR SQL: severe internal error
-255 PI_SQL_NOSUPPORT SQL: unsupported statement
-256 PI_SQL_TIMERR SQL: invalid time
PI Server System Management Guide Page 297
Code Code Identifier Message
-257 PI_SQL_TAGERR SQL: tag not found
-258 PI_SQL_TYPERR SQL: invalid data type
-259 PI_SQL_CALCERR SQL: calculation error
-260 PI_SQL_INVWHERE SQL: invalid WHERE clause
-261 PI_SQL_COLERR SQL: column count error
-262 PI_SQL_NOSELECT SQL: statement is not a SELECT
-263 PI_SQL_SYSTEMERR SQL: system error occurred
-264 PI_SQL_TIMESTEPERR SQL: TIMESTEP error
-265 PI_SQL_NOQUERY SQL: no query found in string
-266 PI_SQL_USERABORT SQL: use aborted execution
-267 PI_SQL_INVARG SQL: invalid function argument
-268 PI_SQL_NOTSAFE SQL: execution too expensive
-269 PI_SQL_INVTABLE SQL: invalid table name
-270 PI_SQL_INVALIAS SQL: invalid table alias name
-271 PI_SQL_BADINI SQL: invalid INI file entries
-272 PI_SQL_TRUNC SQL: returned string truncated
-273 PI_SQL_TIMEOUT SQL: query timed out
-274 PI_SQL_NOPARAM SQL: run-time parameter missing
-275 PI_SQL_BUSY SQL: handle is busy with another operation
-280 PI_GRID_MEMERR Pigrid: memory allocation error
-281 PI_GRID_RANGERR Pigrid: column index out of range
-282 PI_GRID_NOCOLTYPE Pigrid: column not defined
-283 PI_GRID_NOCOLSIZE Pigrid: data size not set
-284 PI_GRID_INVDTYPE Pigrid: invalid data type
-285 PI_GRID_INVDSIZE Pigrid: invalid data size
Table A–4. Error Codes 500-599, With Messages
Code Code Identifier Message
-501 PI_SQC_BADCHARTTYPE Sqc: illegal chart type
Page 298
Code Code Identifier Message
-502 PI_SQC_BADALARMGROUP Sqc: illegal alarm group number
-503 PI_SQC_CALCDBFULL Sqc: calculation data base full
-504 PI_SQC_BADSAMPLESIZE Sqc: Illegal Sample Size (<0 or >32767)
-505 PI_SQC_BADSAMPLEPERIOD Sqc: illegal sample period
-506 PI_SQC_BADCALCPERIOD Sqc: calculation period less than sample period
-507 PI_SQC_BADPERIODSTART Sqc: illegal start period time
-508 PI_SQC_BADIGNORESAMP Sqc: Illegal Number of Samples to Ignore After
Trigger
-509 PI_SQC_BADMOVAVGWT Sqc: illegal geometric moving average weight
-510 PI_SQC_CUSUMKNEG Sqc: CUSUM k Less Than Zero
-511 PI_SQC_CUSUMHNEG Sqc: CUSUM h Less Than Zero
-512 PI_SQC_BADINITCUSUM Sqc: Illegal Initial CUSUM (<0 or >h)
-513 PI_SQC_BADTESTGROUP Sqc: Illegal Test Group Number (<1 or >256)
-515 PI_SQC_CALCMISSING Sqc: calculation not found
-516 PI_SQC_RAWTAGMISSING Sqc: raw data tag for SQC calculation not found
-517 PI_SQC_TRIGTAGMISSING Sqc: Trigger Tag for SQC Calculation Not Found
-518 PI_SQC_CHARTTAGDEFD Sqc: Chart Tag Already Defined in SQC Database
-519 PI_SQC_CHARTEQUALSRAW Sqc: Chart Tag is the Same as the Raw Tag
-520 PI_SQC_INPUTFILEMISSING Sqc: input file does not exist
-521 PI_SQC_BADINPUTFILEFMT Sqc: Input File is Not Properly Formatted
-522 PI_SQC_BADRANGEVALUE Sqc: Value is Out of Range
-523 PI_SQC_BADRANGEALARM Sqc: Alarm Number is Out of Range
-524 PI_SQC_CANTWRITEFILE Sqc: cannot open file for writing
-525 PI_SQC_COMMENTMISSING Sqc: Comment Not Found in Comment File
-526 PI_SQC_INVARRAYINDEX Sqc: Array Index is Out of Valid Range
-527 PI_SQC_CTLLIMTAGMISSING Sqc: Control Limit Tag is Not in SQC Structure
-528 PI_SQC_CTLLIMNOTINFILE Sqc: Control Limits Not Found in Control Limit File
PI Server System Management Guide Page 299
Table A–5. Error Codes 800-899, With Messages
Code Code Identifier Message
-801 PI_EP_BADCONST Expression parser: illegal constant
-802 PI_EP_BADNUM Expression parser: illegal number
-803 PI_EP_TOOMANYTAGS Expression parser: too many constants/tags
-804 PI_EP_TOOCOMPLEX Expression parser: expression too complex
-805 PI_EP_BADKEYWORD Expression parser: illegal keyword
-806 PI_EP_BADCHAR Expression parser: illegal character
-807 PI_EP_TOOMANYUNARIES Expression parser: too many unary operators
-808 PI_EP_BADBOOLEANS Expression Parser: Illegal Combination of Boolean
Operators
-809 PI_EP_UNBALPARENS Expression parser: unbalanced parentheses
-810 PI_EP_TOOMANYRTPARENS Expression parser: too many right parentheses
-811 PI_EP_NOPARENS Expression Parser: Nothing in Parentheses
-812 PI_EP_BADIF Expression parser: illegal if-then-else structure
-813 PI_EP_CMDSTACKOVERFLOW Expression parser: command stack overflow
-814 PI_EP_NULLEQUATION Expression Parser: Null Equation for Expression
-815 PI_EP_REDSTACKOVERFLOW Expression Parser: Reduction Stack Overflow for
Expression
-816 PI_EP_BADTOKEN Expression parser: illegal token
-817 PI_EP_SYNTAX Expression parser: syntax error
-818 PI_EP_CALCSTACKOVERFLOW Expression parser: calculation stack overflow
-819 PI_EP_DISKERR Expression parser: disk error reading constant files
-820 PI_EP_CALCOVERFLOW Expression parser: calculation overflow
-821 PI_EP_DIVZERO Expression Parser: Division by Zero
-822 PI_EP_BADARGUMENT Expression parser: illegal function argument
-823 PI_EP_BADEXPONENT Expression Parser: Non-integer exponent
-824 PI_EP_BADCONSTANT Expression parser: undefined constant
Table A–6. Error Codes 900-999, With Messages
Code Code Identifier Message
Page 300
Code Code Identifier Message
-900 PI_EE_BADTAG Expression evaluation: illegal tag
-912 PI_EE_BADIF Expression evaluation: illegal if-then-else structure
-914 PI_EE_NULLEQUATION Expression Evaluation: Null Equation for
Expression
-916 PI_EE_BADTOKEN Expression evaluation: illegal token
-917 PI_EE_SYNTAX Expression evaluation: syntax error
-918 PI_EE_CALCSTACKOVERFLOW Expression evaluation: calculation stack overflow
-920 PI_EE_CALCOVERFLOW Expression evaluation: calculation overflow
-921 PI_EE_DIVZERO Expression Evaluation: Division by Zero
-922 PI_EE_BADARGUMENT Expression evaluation: illegal function argument
-923 PI_EE_BADEXPONENT Expression Evaluation: Non-integer exponent
-925 PI_EE_BADVALUE Expression evaluation: illogical current value
-981 PI_NET2_BADTABLEID Table ID Specified is Not Supported
-982 PI_NET2_BADTABLECODE Specified Table Code is Not Supported
-983 PI_NET2_BADTRANSMODE Requested Transaction Mode is Not Supported
-991 PI_NET2_BADFUNCCODE PINet Function Code is Not Valid
-992 PI_NET2_BADLENGTH Specified Length is Not Consistent
-993 PI_NET2_BADCOUNT Specified Count is Not Valid
-994 PI_NET2_BADPINETVER Incompatible PINet version
-995 PI_NET2_BADMSGSEQ Bad PINet message sequence
-996 PI_NET2_MSGTOOBIG Message Too Big for PINet
-998 PI_NET2_MEMALLOCERR Memory allocation error
-999 PI_NET2_LOGINREQD Request not permitted without login
Table A–7. Error Codes 1000-1099, With Messages
Code Code Identifier Message
-1000 PI_NET2_BADGRID Grid not implemented
-1001 PI_NET2_NODEFHOST Default host not found
-1002 PI_NET2_NOBATSUBSYS No Batch Subsystem on PI2 server
PI Server System Management Guide Page 301
Table A–8. Error Codes 10000-10999, With Messages
Code Code Identifier Message
-10000 PI_ERR_MALLOC Failed memory allocation
-10001 PI_ERR_NEW Failed new operation
-10002 PI_ERR_ACTIVATE Unable to Activate Object
-10003 PI_ERR_PASSIVATE Unable to Passivate Object
-10004 PI_ERR_IMPOSS Internal error (impossible)
-10005 PI_ERR_UNDERRANGE Subscript under range
-10006 PI_ERR_OVERRANGE Subscript over range
-10007 PI_ERR_BADPOINTER Bad or Null Pointer
-10008 PI_ERR_UNSUPPORTED Unsupported or Unimplemented Call
-10009 PI_SHUTDOWN PI system shutting down
-10010 PI_ERR_TIMEOUT PI system timed out
-10011 PI_ERR_ACCESSLOCK Target Object in Use or Locked
-10400 PI_XS_NOREAD No read access – secure object
-10401 PI_XS_NOWRITE No write access – secure object
-10402 PI_XS_BADSTRING Badly formed access string
-10403 PI_XS_BADUGVER Version Mismatch in Usergroup Activate
-10404 PI_XS_BADUSERVER Version Mismatch in User Activate
-10405 PI_XS_CTXIDINUSE User Context ID in Use
-10406 PI_XS_GROUPINUSE Group ID in Use
-10407 PI_XS_NOACCESS No access – secure object
-10408 PI_XS_BADUSERSTR Invalid security user/owner string
-10409 PI_XS_BADGRPSTR Invalid security group string
-10410 PI_XS_BADDBNAME Invalid security database name
-10411 PI_XS_MISMATCH security or trust relation mismatch
-10412 PI_XS_TRUSTUNSUP Trust relation not supported on server
-10413 PI_XS_NOTRUST No trust relation for this request
-10414 PI_XS_SIMILARTRUST Trust records must differ more than name and
Piuser
Page 302
Code Code Identifier Message
-10415 PI_XS_IPANDMASK Must specify both IP address and Net Mask
-10416 PI_XS_NONULLTRUST Trust definition must include more than name
and Piuser.
-10417 PI_XS_NOPIADMIN User must be piadmin for this operation
-10418 PI_XS_DBSECNOTINIT DB Security not initialized
-10419 PI_XS_NULLSECOBJ Unable to retrieve secure object
-10450 PI_FB_BADCREATEFILE Create new file failed
-10451 PI_FB_BADOPENFILE Open existing file failed
-10452 PI_FB_BADFILECLOSE Close file failed
-10453 PI_FB_BADFILEREMOVE Delete file failed
-10454 PI_FB_BADFILETRUNCATE Truncate file failed
-10455 PI_FB_INVALIDFILE Fstat Failed
-10456 PI_FB_BADFILELOCK Fcntl Failed to Get Lock
-10457 PI_FB_BADFILEUNLOCK Fcntl Failed to Free Lock
-10458 PI_FB_BADHEADER Illegal file header parameters
-10459 PI_FB_FILEOPEN File open
-10460 PI_FB_FILECLOSED File closed
-10461 PI_FB_BADFILEREAD Read from file failed
-10462 PI_FB_BADFILEWRITE Write to file failed
-10463 PI_FB_BADRECNOVALUE Recno Greater Than Directory Size
-10464 PI_FB_RECNOINUSE Recno In Use
-10466 PI_FB_RECNONOTFOUND No Record Available for Passed recno
-10467 PI_FB_BADRECLEN Reclen Greater Than Maximum Allowed Size
-10468 PI_FB_TIMETOGROWDIR Getting New recno, Directory is Full
-10469 PI_FB_BADBUFFERSIZE Passed Buffer Too Small to Hold Record
-10470 PI_FB_BADFILESEEK Lseek Failed
-10471 PI_FB_BADFILEHEADER Fatally corrupted file header
-10472 PI_FB_DIRTYHEADER Dirty header
-10473 PI_FB_INVUSERBLOCK Invalid user block size
PI Server System Management Guide Page 303
Code Code Identifier Message
-10474 PI_FB_BADVERSION Version mismatch
-10475 PI_FB_CNTMISMATCH Record count mismatch between header and
index
-10476 PI_FB_LOWDISKSPACE low disk space, file size cannot be increased
-10477 PI_FB_PATHNOTDIRECTORY The path is valid, but the path is not a
directory
-10478 PI_FB_NULLPATHSTRING Cannot extract file and path from null string
-10550 PI_PD_TAGEXISTS Tag Already Exists in Table
-10551 PI_PD_INVTAG Invalid Characters in Tag
-10552 PI_PD_BADCHAIN Broken Context Chain in Table
-10553 PI_PD_INVPTID Ptid is Not a Valid Point
-10554 PI_PD_CTXEXISTS Tag Already Exists for Context
-10555 PI_PD_NOTAG Tag Does Not Exist in Table
-10556 PI_PD_ENDSEARCH End of Table Reached
-10557 PI_PD_BADASVER Bad ptattributeset Version
-10558 PI_PD_BADPTCLVER Bad ptclass Version
-10559 PI_PD_BADPOINTVER Bad point version
-10560 PI_PD_POINTINUSE Point Already Has a ptclass
-10561 PI_PD_PTCLASSINUSE Point class already defined
-10562 PI_PD_CLASSESINUSE Ptclasses Already Defined
-10563 PI_PD_BADPTCLASSREV Point class revision mismatch
-10564 PI_PD_NOPTCLASS Point class not defined
-10565 PI_PD_NOMOREPTS No More Points in Search
-10566 PI_PD_VALIDFAIL Point validation failed
-10567 PI_PD_AMBIGUOUS Point ID does not match Tag or Tag rename
to same name
-10568 PI_PD_NOMATCHINGPOINTS No points found in search
-10569 PI_PD_BADATTRIBUTE Point does not contain specified attribute
-10570 PI_PD_NOEDIT Attempt to edit or set internally set point
attribute
Page 304
Code Code Identifier Message
-10571 PI_PD_INVALIDATT Attempt to create attribute set with invalid
attribute name
-10572 PI_PD_INVALIDNAME Invalid name for point class or attribute set
-10573 PI_PD_NOBASEATT Base attribute set not included in point class
definition
-10574 PI_PD_NODELBASEATT Attribute set delete not allowed.
-10575 PI_PD_ATTSETINUSE Attribute set is in use.
-10576 PI_PD_MISSINGREQATTRIBUTES Required attribute missing in the attribute set
-10577 PI_PD_BASEATTNAME Attribute name being used by base attribute
set
-10578 PI_PD_BUILTINATTNAME Attribute name being used by built-in
-10579 PI_PD_BADPTTYPECHANGE Unsupported point type change
-10580 PI_PD_RESERVEDNAME Name reserved for internal use
-10581 PI_PD_INVALIDBASEATTNAME Invalid attribute name for base attribute set
-10582 PI_PD_NOATTSETRENAME Rename not allowed for this attribute set
-10583 PI_PD_CLASSINUSE Point class is in use
-10584 PI_PD_BADPTCLASSESREV PIptclasses revision mismatch
-10585 PI_PD_NOEDITBASECLASS Base point class edit/delete not allowed
-10586 PI_PD_INVALIDATTTYPE Unsupported attribute type
-10587 PI_PD_NOEDITBASEATT Base attribute set edit not allowed except for
default change
-10588 PI_PD_MISSINGREQATTRIBUTESE Required attribute set missing in the point
TS class
-10589 PI_PD_NODELSET Delete not allowed for this attribute set
-10590 PI_PD_NODELCLASS Delete not allowed for this point class
-10591 PI_PD_NOPTCLSRENAME Rename not allowed for this point class
-10592 PI_PD_ATRTYPECHANGEINPREDE Attribute type change in this attribute set not
FORINUSEATRSET allowed
-10593 PI_PD_ATTRIBDELINPREDEFORIN Attribute delete in this attribute set not allowed
USEATTRIBSET
-10594 PI_PD_ATTRIBSETDELINPREDEFO Attribute set delete in this point class not
RINUSEPTCLASS allowed
PI Server System Management Guide Page 305
Code Code Identifier Message
-10595 PI_PD_STANDALONEMODEREQUI This operation requires StandAlone mode
RED
-10650 PI_UD_INVALIDGRPUSRNM Invalid Group or User Name
-10651 PI_UD_INVGRPSLFREF Invalid Group self reference
-10652 PI_UD_INVGRPLAYER Super Group cannot be member Super Group
-10700 PI_DS_NAMEEXISTS State Already Exists in Table
-10701 PI_DS_SETNOTFOUND Set not found
-10702 PI_DS_STATENOTFOUND State not found
-10703 PI_DS_ILLEGALSETDEFINITION Illegal set definition: no states defined
-10704 PI_DS_CANTDELETESYSSET Cannot delete system state-set
-10705 PI_DS_TOOMANYSETS Maximum number of Sets Exceeded
-10706 PI_DS_TOOMANYSTATES Maximum number of States Exceeded
-10707 PI_DS_SETMISMATCH Digital set number mismatch during type
coercion
-10708 PI_DS_NEGATIVEOFFSET Negative state number in digital type coercion
-10721 PI_NET_ABORT PINet: client aborted connection
-10722 PI_NET_TIMEOUT PINet: Timeout on PI RPC or System Call
-10723 PI_NET_NOCONNECTION PINet: no connection
-10724 PI_NET_QUEOVERFLOW PINet: queue overflow
-10725 PI_NET_SYNCHRONOUS PINet: synchronous
-10726 PI_NET_ASYNCHRONOUS PINet: asynchronous
-10727 PI_NET_RPC_NONEXISTENT PINet: RPC is Non-Existent
-10728 PI_NET_SEND_ERROR PINet: send error
-10729 PI_NET_RECV_ERROR PINet: receive error
-10730 PI_NET_NO_MESSAGE PINet: no message
-10731 PI_NET_INCOMPLETE_MESSAGE PINet: incomplete message
-10732 PI_NET_CORRUPTED_MESSAGE PINet: corrupted message
-10733 PI_NET_RPCRESOLVEROFFLINE PINet: RPC Resolver is Off-Line
-10734 PI_NET_BROKENCONNECTION PINet: broken connection
Page 306
Code Code Identifier Message
-10735 PI_NET_TRANSACTIONLISTFULL PINet: session manager transaction list full
-10736 PI_NET_ILLEGALRPCID PINet: RPC Table ID or Entry ID set to illegal
value of 0.
-10737 PI_NET_PENDING PINet: Asynchronous connection to pinetmgr
is Pending
-10738 PI_NET_DISABLED PINet: connection disabled
-10739 PI_NET_INVALIDRPCSERVERTABL PINet: Invalid or Null RPC Server Table List
ELIST
-10740 PI_NET_INVALIDHOST PINet: invalid host
-10741 PI_NET_RPCRESOLVERNOTAVAIL PINet: RPC Resolver chooses to not service
ABLE request
-10742 PI_NET_CONNECTIONLISTFULL PINet: Connection list full
-10743 PI_NET_RPCRESOLVERTMPOFFLI PINet: RPC Resolver temporarily Off-Line
NE
-10744 PI_NET_TRANSLATORINUSE PINet: PI API client attempted two or more
simultaneous calls.
-10745 PI_NET_MESSAGEVERIFICATIONF PINet: Message verification failure.
AILURE
-10746 PI_NET_MESSAGETOOLARGE PINet: Attempt to send or receive message
larger than maximum allowable
-10747 PI_NET_TRANSLATORVERIFICATI PINet: PIAPI translator verification failure.
ONFAILURE
-10748 PI_NET_NOROUTEENTRY PINet: No routing entry exists for RPC
-10749 PI_NET_NORPCCODE PINet: No RPC entry for table/function code
-10750 PI_NET_NORPCNAME PINet: No RPC entry for table/function name
-10751 PI_NET_NORPCCALLBACK PINet: No callback function for RPC entry
-10752 PI_NET_EXCESSIVEZEROBYTERE PINet: Connection broken by peer
ADS
-10753 PI_NET_INVALIDSESSIONID PINET: Invalid session ID
-10754 PI_NET_RPCTABLEGENMISMATCH PINET: RPC Table Generation mismatch
-10755 PI_NET_COMPLETIONPORTERRO PINET: Completion Port Error
R
-10756 PI_NEWERSERVERVERSIONREQU PINET: Newer server version required
IRED
PI Server System Management Guide Page 307
Code Code Identifier Message
-10757 PI_NOREMOTECONNECTION PINET: No remote connection
-10758 PI_NET_FAILEDREMOTECONNECT PINET: Failed remote connection
ION
-10759 PI_NET_NO_BYTES recv() returned zero bytes
-10760 PI_NET_EXCESSIVEREADRETRIES Read retry limit exceeded.
-10761 PI_NET_FORCEDDISCONNECT Connection deleted by request of
administrator
-10762 PI_NET_MAXCONNIDLETIME Maximum Connection Idle time reached:
Connection Closed
-10763 PI_NET_INVALIDPINETMGRCONTR Invalid PINetMgr Control Mode
OLMODE
-10764 PI_NET_NOTLOCALSESSION Access only allowed by local PI Server
connection
-10765 PI_NET_USERCANCELEDCONNEC ser canceled session login
TION
-10766 PI_NET_TRANSACTIONABORTED PINET: Transaction aborted by local session
thread
-10767 PI_NET_CONCURMSGABOVELIMIT Client exceeded maximum concurrent queries
in RPC thread pool
Table A–9. Error Codes 11000-11999, With Messages
Code Code Identifier Message
-11001 PI_AR_RCHDVMM Record header version mismatch.
-11002 PI_AR_RCHDDMM Record header data mismatch.
-11003 PI_AR_RCHDSMM Record header size mismatch.
-11004 PI_AR_RCHDBADPTRECID Record header bad (0) point record ID.
-11005 PI_AR_RCHDBADRECID Record header bad (0) record ID.
-11006 PI_AR_RCHDBADSIZE Record header bad set size byte count.
-11007 PI_AR_RCHDOVERWRITE Record header stream overwrite.
-11008 PI_AR_RCBADDATATYPE Attempted to Add Event With Invalid Data Type.
-11009 PI_AR_RCOBJTOOBIG Event Contents Are Too Big to Fit in Any Record.
-11010 PI_AR_NOTTYPEDIG Record not type=digital.
-11011 PI_AR_NOTTYPEFLOAT2 Record not type=float2 – zero/span do not apply.
Page 308
Code Code Identifier Message
-11012 PI_AR_INVRECCNT Invalid record count for creating archive.
-11013 PI_AR_INVRECSIZE Invalid record size for creating archive.
-11014 PI_AR_BADSTREAMATT Failed to Attach Archive File to Stream.
-11015 PI_AR_ARCFILEVMM Archive file version mismatch.
-11016 PI_AR_ARCFILERAB Archive File in Unrecognized State.
-11017 PI_AR_CRPTTIME Corrupt Time Values in Archive Header.
-11018 PI_AR_CRPTPTRS Corrupt Overflow or Primary Record Pointers.
-11019 PI_AR_ARCNOTMNTD Archive file not mounted.
-11020 PI_AR_INVPTCNT Point Count Out of Range.
-11021 PI_AR_CRPTCACHEREC Cache record corrupt.
-11022 PI_AR_PTRECIDBND Invalid Value for Requested ptrecid.
-11023 PI_AR_BOUNDS Archive record full.
-11024 PI_AR_BADCACHELOAD Cache->loadrecord Failed.
-11025 PI_AR_BADGETTARREC Arcmgr::gettargetrecord Failed.
-11026 PI_AR_BADOVERFLOW Arcfile::overflowrecord Failed.
-11027 PI_AR_BADARLOADREC Arcfile::loadrecord Failed.
-11028 PI_AR_DUPARCFAIL Requested to Load Archive File Already Loaded.
-11029 PI_AR_BADSETINDEX An Index Record Does Not Have an Index.
-11030 PI_AR_BADINDEXSRC Set Index Did Not Receive an Index Record.
-11031 PI_AR_EMPTYRECORD No Events in Record.
-11032 PI_AR_NOEVENTAFTER No Events After Passed Eventide.
-11033 PI_AR_NOEVENTBEFORE No Events Before Passed Eventid
-11034 PI_AR_BADPTRECID Invalid ptrecid Passed.
-11035 PI_AR_STOREOPEN Underlying Storage is Open.
-11036 PI_AR_BADARCRECORD Invalid archive record pointer passed.
-11037 PI_AR_BADARCFILE Invalid archive file pointer passed.
-11038 PI_AR_NOARCHIVEBEFORE No archive before passed archive.
-11039 PI_AR_NOARCHIVEAFTER No archive after passed archive.
PI Server System Management Guide Page 309
Code Code Identifier Message
-11040 PI_AR_NORECORDBEFORE No record before passed record.
-11041 PI_AR_NORECORDAFTER No record after passed record.
-11042 PI_AR_RECNOTINCACHE Target Record Not in Cache.
-11043 PI_AR_DATENOTONLINE No archive online for target time.
-11044 PI_AR_EVENTOUTOFORDER Attempting to Add an Event Before Last Event.
-11045 PI_AR_INDEXRECMISMATCH Add event index mismatch.
-11046 PI_AR_DATEINFUTURE Target Date in Future.
-11047 PI_AR_INVMAXCOUNT Invalid maximum count.
-11048 PI_AR_INVINTERVAL Invalid intervals for archive call.
-11049 PI_AR_INVTIMES Invalid times for archive call.
-11050 PI_AR_INVRECTYPE Invalid record type.
-11051 PI_AR_COUNTTOOSMALL Count not large enough for interval.
-11052 PI_AR_SNAPMISMATCH Count mismatch loading snapshot.
-11053 PI_AR_ARCHIVEFULL No More Available Records in This Archive.
-11054 PI_AR_INVALIDSTATE Invalid Archive State For Mounting or Dismounting.
-11055 PI_AR_INVSTIME Invalid start time.
-11056 PI_AR_INVETIME Invalid end time.
-11057 PI_AR_NOTENOUGHVALS Not enough good values for calculation.
-11058 PI_AR_INVSUMMARYCODE Invalid code for summary function.
-11059 PI_AR_NOGOODDATA No good data for this time.
-11060 PI_AR_CALCFAILED Calculation Failed (e.g. Division by Zero).
-11061 PI_AR_INVMODEADD Invalid mode for archive add event.
-11062 PI_AR_INVMODEEDIT Invalid mode for archive edit event.
-11063 PI_AR_INVMODEDEL Invalid mode for archive delete event.
-11064 PI_AR_RCHDRMM Mismatch in record header record ID.
-11065 PI_AR_RCHDPMM Mismatch in record header chain pointer.
-11066 PI_AR_EMPTYDRECORD Empty data archive record.
-11067 PI_AR_EMPTYIRECORD Empty index archive record.
Page 310
Code Code Identifier Message
-11068 PI_AR_BADPRIMARY Failed to get primary archive.
-11069 PI_AR_CREATEFLAG Archive creation flag already set.
-11070 PI_AR_NOARCHMOUNT No archives mounted.
-11071 PI_AR_NOSHIFTARC No archive qualified for shift.
-11072 PI_AR_REMNER No events in record for removal.
-11073 PI_AR_REMENF Target event for removal not found in record.
-11074 PI_AR_REPNER No events in record to replace.
-11075 PI_AR_REPENF Target event for replacement not found in record.
-11076 PI_AR_NAVBEFORE Target time before archive start time.
-11077 PI_AR_NAVAFTER Target time after archive end time.
-11078 PI_AR_NOTWRITEABLE Target archive is not writeable.
-11079 PI_AR_NOTSHIFTABLE Target archive is not shiftable.
-11080 PI_AR_DUPPRIMARY Attempted to register two primary archives.
-11081 PI_AR_OVERLAP Attempted to register overlapping archives.
-11082 PI_AR_RECLOCKFAIL Attempted to lock a locked archive record.
-11083 PI_AR_RECUNLOCKFAIL Attempted to unlock an unlocked archive record.
-11090 PI_AR_EMPTYFILE Attempting operation on an empty archive file.
-11091 PI_AR_TOOMANYEVENTS Event collection exceeded maximum allowed.
-11092 PI_AR_NOANNOTATION Annotation not found in archive.
-11093 PI_AR_ANNOTMISMATCH Annotation mismatch (archive).
-11094 PI_AR_ANNOTEXIST Annotation already exist in archive.
-11095 PI_AR_SHIFTINPROG: Archive Shift already in progress.
-11096 PI_AR_BCKUPINPROG: Archive Backup already in progress.
-11097 PI_AR_BCKMODEMISMTCH: Backup End must follow Start and vice versa.
-11098 PI_AR_BADDIGDATA: Cannot convert to a Digital State.
-11099 PI_AR_SAMETIMEREC: Start time equal end time in archive record.
-11100 PI_AR_SAMETIMEARG: Start time equal end time argument in archive call.
-11101 PI_AR_SCALLFILTER: All data events are filtered in summary calculation.
PI Server System Management Guide Page 311
Code Code Identifier Message
-11102 PI_AR_SCNOEVENT: No events found within the time range of summary
calculation.
-11103 PI_AR_SCOOSCALL: Out of sequence calls in summary calculation.
-11104 PI_AR_SCOOSEVENT: Out of sequence data events in summary
calculation.
-11105 PI_AR_NULLLOADREC: Invalid record pointer for loading.
-11106 PI_AR_PTLOCKFAIL: Failed to lock archive-cache point.
-11107 PI_AR_NAVUNEXPECTED: Unexpected error navigating the archive.
-11108 PI_AR_ARCITERINVALID: Archive event iterator not properly initialized.
-11109 PI_AR_INVSAMPMODE: Invalid sample mode.
-11110 PI_AR_INVSAMPTIMES: Error with sample time array specification.
-11111 PI_AR_INVTIMECONST: Error with summary calculation time array.
-11112 PI_AR_INVNUMINTERVALS: Error with the summary calculation numInterval
array.
-11113 PI_AR_SCNINVCB: Invalid CalculationBasis.
-11114 PI_AR_SCNINVTYPE: Invalid Summary CalcType.
-11115 PI_AR_SCNINVTIMES: Error with time constraint array in Sumnav object.
-11116 PI_AR_SCNINVFILTER: Error with the filter constraint array in Sumnav
object.
-11117 PI_AR_SCNOOSRESCALL: Calling getresult before done in sumnav object.
-11118 PI_AR_SCNBADRE Internal error with result in sumnav object.
-11119 PI_AR_SCNINVARG: Invalid parameter in sumnav object.
-11120 PI_AR_SCNINTERPERR: Error interpolating data in sumnav object.
-11121 PI_AR_SCNOOSCALL: Out of sequence call in sumnav object.
-11122 PI_AR_SCNOOSEVENT: Out of sequence data event in sumnav object.
-11123 PI_AR_RCOVERFLOW: Point query exceeded maximum cache record
count.
-11124 PI_AR_NONNUMERICSUM: Non-numeric tag in summary calculation.
-11125 PI_AR_LOWDISKSPACE: Low disk space, file cannot be created.
-11126 PI_AR_ANNGUIDMISMATCH: Annotation file ID is not matching archive file.
-11127 PI_AR_NODOWNGRADE: Archive file downgrade to requested version not
Page 312
Code Code Identifier Message
supported.
-11128 PI_AR_TOOMANYREQEVENT Number of requested events exceeded the
S: maximum allowed.
-11129 PI_AR_NOTARCHIVING: Archive subsystem not in archiving state.
-11130 PI_AR_NEEDARCSIZE: Missing size information for new archive file
creation.
-11131 PI_AR_RCEXCEEDSLIMIT Point has more cache records than maximum
configured
-11132 PI_AR_CACHEUSECOUNT Cache record found with invalid reference count on
clean operation
-11133 PI_AR_RECEIVEDNEWSNAP New snapshot event received while pending delete
-11134 PI_AR_SHIFTIMMINENT Archive Shift predicted withing backup lead time
-11135 PI_AR_FLUSHQLIMIT Reached maximum write cache events in lock
contention
-11136 PI_AR_FLUSHEVTIMEOUT Timeout waiting for point flush operation
-11137 PI_AR_PRIMARYREADONLY Primary archive is Read-only. Archiving and
archive shifts disabled
-11138 PI_AR_INVMODEADDCACHE Invalid mode for adding event to cache
-11200 PI_3PHUNAVAIL PI Server is not installed properly or is not running
-11201 PI_RDR_HISTTIMEDVALUEFAI PI Redirector could not get archived value from
L foreign system
-11202 PI_ RDR PI Redirector could not get archived data from
_HISTTIMEDVALUESFAIL foreign system
-11203 PI_ RDR PI Redirector could not get snapshot value from
_SNAPTIMEDVALUEFAIL foreign system
-11204 PI_ RDR _SNAPISLOCALFAIL PI Redirector could not determine whether to cache
snapshot values from foreign system
-11205 PI_ RDR _SNAPSSIGNUP PI Redirector could not signup for updates with
foreign system.
-11206 PI_ RDR PI Redirector could not get updates from foreign
_SNAPSUPDATESFAIL system.
-11207 PI_ RDR PI Redirector could not write snapshots to foreign
_SNAPPUTTIMEDVALUEFAIL system.
-11208 PI_ RDR PI Redirector could not load connector or set PI
_ADDCONNECTORFAIL Server system name.
PI Server System Management Guide Page 313
Code Code Identifier Message
-11209 PI_ RDR _ARCSUMMARYFAIL PI Redirector could not get arcsummary/summaries
directly from foreign system.
-11300 PI_V_NOANNOTATION Annotation not found in Pivalue.
-11301 PI_V_ANNOTMISMATCH Annotation mismatch.
-11302 PI_V_ANNOTEXIST Annotation already exist.
-11303 PI_V_ANNOTTOOLONG Annotation exceeds size limit.
-11304 PI_V_INVALID_VARIANT_TYP Invalid variant type code.
E
-11305 PI_V_MISMATCH PIvalue mismatch
-11306 PI_V_NOTATIME Variant type is not a time
-11307 PI_V_NOTAUID Variant type is not a UID
-11901 PI_OFFL_BADOPENFILE Error opening offline file
-11902 PI_OFFL_BADRECNO Bad record number for offline input
-11903 PI_OFFL_BADIDCONV Bad Id conversion table
-11904 PI_OFFL_BADFILEREAD Failed to read input file (PI2)
-11905 PI_OFFL_NOTINIDCONV Point ID not found in ID conversion table
-11906 PI_OFFL_PTIDMM Point ID mismatch in offline loading
-11907 PI_OFFL_NOTARGETREC Cannot post events, no target record
-11908 PI_OFFL_INVTIMES Invalid Times For Offline loading
-11909 PI_OFFL_BADARCTYPE Invalid archive type for processing
-11910 PI_OFFL_NOEVENTS No events from input file were added to output
archive
Table A–10. Error Codes 12000-12999, With Messages
Code Code Identifier Message
-12000 PI_TABLEFROZEN Pint is Frozen from Changes
-12001 PI_TABLENONAME Name Not Found in pint
-12002 PI_TABLENOCODE Code Not Found in pint
-12003 PI_TABLEDUPNAME Name Already in Use in pint
-12004 PI_TABLEDUPCODE Code Already in Use in pint
-12005 PI_TABLEINVNAME Invalid Name for Use in pint
Page 314
Code Code Identifier Message
-12006 PI_TABLEINVSLOT Invalid Slot for Use in pint
-12007 PI_TABLEINUSE Table already contains entries
-12008 PI_TABLELOADMIS Count Mismatch on Load
-12009 PI_TABLEFILEUSE Underlying File Store in Use
-12010 PI_TABLEMAXENTRIESEXCEEDED Attempt to activate or create table larger than
allowed
-12011 PI_TABLENOIDENTIFIER Identifier not found in PInttemplate
-12012 PI_TABLEINVIDENTIFIER Identifier in PInttemplate is not valid
-12013 PI_TABLENORECORDDEFINITION Record definition of generic table is empty
-12050 PI_ARG_N OOWNLIST Arglist is Not Owned
-12051 PI_ARG_OWNLIST Arglist is Owned
-12052 PI_ARG_FROZEN Operation is Invalid on a Frozen List
-12053 PI_ARG_BADMERGE Failed merge
-12100 PI_GRID_BADSETCOLINF Pigrid: setcolinfo Failed
-12101 PI_GRID_BADSETNUMROW Pigrid: setnumrows Failed
-12102 PI_GRID_BADVERSION Pigrid: Version Mismatch in Activate
-12103 PI_GRID_BADSETNUMCOL Pigrid: setnumcols Failed
-12150 PI_UPD_NOTREG Not registered in updmgr
-12151 PI_UPD_NOCONS Consumer not registered in updmgr
-12152 PI_UPD_NOPROD Producer not registered in updmgr
-12153 PI_UPD_MISMATCH Id mismatch
-12200 PILIC_NOLICFILE no license file
-12201 PILIC_ERROPENFILE error open license file
-12202 PILIC_BADKEY invalid license key
-12203 PILIC_INVSPECS invalid license specs
-12204 PILIC_NOSUCHLIC no such license
-12205 PILIC_NOTREGISTERED user not registered
-12206 PILIC_LICEXCEDED usage exceeded licensed amount
-12207 PILIC_LICEXPIRED license expired
PI Server System Management Guide Page 315
Code Code Identifier Message
-12208 PILIC_BADUSERKEY user mismatch
-12209 PILIC_MISMATCH amount or another mismatch
-12210 PILIC_NOLICFILE10 license error 10
-12211 PILIC_SERVIDFILEEXISTS Server ID file creation failure; file already
exists.
-12212 PILIC_SDKCONNECTIONS Maximum licensed SDK Application
connections exceeded. Connection refused.
-12213 PILIC_APICONNECTIONS Maximum licensed API Application
connections exceeded. Connection refused.
-12214 PILIC_POINTCOUNT Maximum licensed Point Count exceeded.
-12215 PILIC_MODULECOUNT Maximum licensed Module Count exceeded.
-12216 PILIC_POINTMODULECOUNT Maximum licensed aggregate Point/Module
Count exceeded.
-12217 PILIC_BDB Not licensed to use Batch Database.
-12218 PILIC_MDB Not licensed to use Module Database.
-12219 PILIC_COMCONNECTORS Not licensed to use COM Connector-mapped
points.
-12220 PILIC_SERVERAPP Not licensed to use this server or UDS
application.
-12221 PILIC_CLIENTAPP Not licensed to use this client application.
-12222 PILIC_MAXHISTORY Not licensed to access Archive for passed
dates.
-12223 PILIC_ERRGETMAC Error getting Machine info
-12224 PILIC_NOLICMGR License Manager not accesible
-12225 PILIC_NOKNOWNAPPS Did not receive Known Application data
-12226 PILIC_OLDLICFILE License file too old to parse
-12227 PILIC_INTERFACE Not licensed to use this interface
-12228 PILIC_MIDDLEWARE Not licensed to use this middle-ware
application
-12229 PILIC_NONCCPOINTCOUNT Maximum licensed non-COM Connector Point
Count exceeded
-12250 PI_BA_DUPACTIVETAG Batch active tag is already being used by
another unit
Page 316
Code Code Identifier Message
-12251 PI_BA_BADSIZE Number of arguments in PIarray is incorrect
-12252 PI_BA_BADACTIVETAGTYPE Batch Active Tag Type is not STEP or
PULSE.
-12253 PI_BA_UNITARCHIVETAGMISSING Invalid unit identifier.
-12254 PI_BA_WAIT Wait for in use object.
-12255 PI_BA_BADSYNTAXBATCHID Batch ID expression Syntax Error.
-12256 PI_BA_BADSYNTAXPRODUCTID Product ID expression Syntax Error.
-12257 PI_BA_BADPTBATCHID Invalid tag in Batch ID expression.
-12258 PI_BA_BADPTPRODUCTID Invalid tag in Product ID expression.
-12259 PI_BA_UNSUPPORTEDACTIVETAG Batch active tag is not integer, real, or digital.
TYPE
-12260 PI_BA_NOBATCHINEVENT PIevent does not contain a batch record
(PIblob len 0 ).
-12261 PI_BA_PIBANEXISTS Could not create a unique archive tag name
for unit.
-12262 PI_BA_STARTTIMESTATUSINVALID Status of start time for a batch is invalid.
-12263 PI_BA_STOPTIMESTATUSINVALID Status of stop time for a batch is invalid.
-12264 PI_BA_BATCHEND This is an end of batch event.
-12265 PI_BA_BATCHSTART This is a start of batch event.
-12266 PI_BA_TIMENOTFOUND Time was outside boundaries of PIbaIndex
Directory.
-12267 PI_BA_INVALIDINDEX Index for PIbaIndex Directory is invalid.
-12268 PI_BA_INVALIDTIMESPAN Time span within search contains no indexes.
-12269 PI_BA_NO_UNITS_MATCHED Unit mask matches none of the current units.
-12270 PI_BA_NO_END_EVENT_EXISTS No end event exists for this batch handle.
-12271 PI_BA_BATCHOREVENT_EXISTS Attempt to archive batch over existing batch.
-12272 PI_BA_INVALIDPIBLOB Archived batch record invalid.
-12273 PI_BA_CANTDELETE Attempt to delete an active batch or batch
with null end timestamp
-12274 PI_BA_NOBATCHES No matching batches were found.
-12275 PI_BA_INVALIDHANDLE Invalid or missing batch handle. Batch edit
requires specifying a valid batch handle.
PI Server System Management Guide Page 317
Code Code Identifier Message
-12299 PI_BA_DUPACTIVETAG Batch active tag is already being used by
another unit
-12300 PI_PE_ERROR Performance equation error
-12301 PI_PE_PARSEERROR Performance equation parsing error
-12302 PI_PE_DIVIDEBYZERO Performance equation divide by zero error
-12303 PI_PE_OVERFLOW Performance equation overflow error
-12304 PI_PE_LEX_FILE_NOT_FOUND Performance Equation: File PExxx.llr not
found in DAT directory
-12305 PI_PE_RULE_FILE_NOT_FOUND Performance Equation: File PExxx.dfa not
found in DAT directory
-12306 PI_PE_RESOURCES_NOT_FOUND Performance Equation: File pisystem.res not
found in DAT directory
-12307 PI_PE_INVALID_CONNECTION Performance Equation: Invalid Connection
-12308 PI_PE_BAD_TREE_AT_GENCODE Performance Equation: Bad parse tree during
code generation
-12309 PI_PE_BAD_TREE_AT_TYPECHEC Performance Equation: Bad parse tree during
K type check
-12310 PI_PE_FUNC_WRONG_NUMBER_O Performance Equation: Function has wrong
F_ARGS number of arguments
-12311 PI_PE_FUNC_NEEDS_ONE_ARG Performance Equation: Function needs at
least one argument
-12312 PI_PE_FUNC_TO_MANY_ARGS Performance Equation: Function has too
many arguments
-12313 PI_PE_FUNC_ARG1_NOT_DIGITAL Performance Equation: First argument for
function is not digital
-12314 PI_PE_FUNC_ARG1_NOT_TIME Performance Equation: First argument for
function is not a time
-12315 PI_PE_FUNC_BAD_ARG_TYPES Performance Equation: Function has bad
argument data type
-12316 PI_PE_FUNC_NEEDS_MORE_ARG Performance Equation: Wrong number of
S arguments for function
-12317 PI_PE_FUNC_ARG1_INVALID Performance Equation: Invalid first argument
-12318 PI_PE_FUNC_ARG2_INVALID Performance Equation: Invalid second
argument
-12319 PI_PE_FUNC_ARG3_INVALID Performance Equation: Invalid third argument
Page 318
Code Code Identifier Message
-12320 PI_PE_FUNC_ARG4_INVALID Performance Equation: Invalid fourth
argument
-12321 PI_PE_FUNC_ARGS_NOT_SAME_T Performance Equation: All arguments must
YPE have same data type
-12322 PI_PE_FUNC_ARGS_NOT_NUMBE Performance Equation: All function arguments
RS must be numbers or evaluate to numbers
-12323 PI_PE_TOO_MANY_ARGS Performance Equation: Function has too
many arguments
-12324 PI_PE_ADD_CONNECT_FAILED Performance Equation: Connection failed
-12325 PI_PE_TOO_MANY_CONNECTS Performance Equation: Too many
connections
-12330 PI_PE_PCT_GOOD_TOO_SMALL Performance Equation: Percent good is below
requested threshold
Table A–11. Error Codes 13000-13999, With Messages
Code Code Identifier Message
-13000 PI_MSG_BADQUERY Bad query for messages in GetMessages
-13001 PI_MSG_BADMAXCOUNT The query for messages contains an invalid total
number of messages parameter in GetMessages
-13002 PI_MSG_BADSTARTTIME The query for messages contains an invalid PI
format start time in GetMessages
-13003 PI_MSG_BADENDTIME The query for messages contains an invalid PI
format end time in GetMessages
-13004 PI_MSG_BADMESSAGEID The query for messages contains an invalid
Message ID in GetMessages
-13005 PI_MSG_BADUSER The query for messages contains an invalid
program name in GetMessages
-13006 PI_MSG_BADSEARCHSTRING The query for messages contains an invalid
message search string in GetMessages
-13007 PI_MSG_BADOPTION1 The query for messages must have end time
and/or total message count in GetMessages
-13008 PI_MSG_BADOPTION2 The query for messages must have start time
and/or total message count in GetMessages
-13009 PI_MSG_BADOPTION3 The query for messages must have start time
and/or end time in GetMessages
-13010 PI_MSG_NAMEMISMATCH The query for messages contains an invalid name
in the query name table in GetMessages
PI Server System Management Guide Page 319
Code Code Identifier Message
-13011 PI_MSG_BADFILE The PI Message file can not be read. It may be
corrupt.
-13050 PI_AUD_FNF Cannot find audit file
-13051 PI_AUD_CREFAIL Cannot create audit file
-13052 PI_AUD_BCKUPINPROG Audit disabled during backup
-13053 PI_AUD_WRITEERR Failed to write audit record
-13100 PI_NTLOG_NOHANDLE No Application Event Log Handle
-13101 PI_NTLOG_NOUPDATE Unable to get updates from App Log
-13102 PI_NTLOG_NOSENDTOPI Unable to send event log messages to PI
-13103 PI_NTLOG_BADGETREGVAL Unable to get values for pimsgss service registry
key
-13104 PI_NTLOG_NOREGKEY Unable to get registry key for service pimsgss
-13200 PI_CTR_BADPERFINFO PIPerfInfo struct is bad
-13201 PI_CTR_BADGETPERFREG Unable to get Perflib registration info
-13202 PI_CTR_BADSETPERFREG Unable to set Perflib registration info
-13203 PI_CTR_BADGETPIREG Unable to get PI performance registration info
-13204 PI_CTR_BADSETPIREG Unable to set PI performance registration info
-13205 PI_CTR_BADPERFLIBNUM Perflib Last Counter larger than Last Help
-13206 PI_CTR_ODDPERFLIB Perflib Last Counter is odd number or Last Help is
even number
-13207 PI_CTR_BADPERFLIBSET Perflib Last Help is greater than Last Counter by
more than one
-13208 PI_BADCOUNTERNAMELENG he performance counter name is larger than 32
TH characters, counters will not be installed
-13250 PI_TST_NOTFOUND Test not found in DB
-13251 PI_TST_DBERROR Cannot record results in test DB
-13252 PI_TST_MAILERROR Cannot Email test results
-13253 PI_TST_NOPISYS Test requires running PI system
-13254 PI_TST_INVATR Invalid test attribute
-13255 PI_TST_FAILED Test failed
Page 320
Table A–12. Error Codes15000-15999, With Messages
Code Code Identifier Message
-15000 PI_ISTREAMFAIL Istream::get Failed
-15001 PI_OSTREAMFAIL Ostream:: Failed
-15002 PI_BADOFFSET Generic Out-of-Bounds Error (pistring,
piarray)
-15003 PI_NOTFOUND Element Not Found (piarray)
-15010 PI_OVERFLOW Number Too Big For pivalue
-15011 PI_NOTANUMBER Pivalue Type is Not Numeric
-15012 PI_INFINITY Pivalue Divide by Zero
-15013 PI_NOTAFLOAT Pivalue Type or pistring is Not Float
-15014 PI_NOTANINTEGER Pivalue Type or pistring is Not Integer
-15015 PI_BADFLOATFORMAT Number of Digits or Decimals Out of
Range
-15016 PI_NOTASTRING Pivalue Type is Not a String
-15017 PI_WRONGVALTYPE Pivalue Type is Not Allowed For This Call
-15018 PI_NOTABLOB Pivalue Type is Not a Blob
-15019 PI_NOTAVALUETYPE Value Type is Not a Valid pivalue Type
-15020 PI_INVALIDPATH Invalid path specified
-15021 PI_BADTARGET Context sensitive bad target error
-15022 PI_BADINITIALIZE Context sensitive initialization failure
-15023 PI_BADVERSION Generic bad version failure
-15024 PI_DUPLICATE Generic duplicate name
-15025 PI_BADEVENTMODE Invalid or Unsupported pievent Mode
-15026 PI_MAXLENGTHEXCEEDED Attempt to activate or create a pistring or
piblob larger than max allowable
-15027 PI_LOGMESSAGESTHROTTLED Excessive messages to PImsgss, log
messages temporarily terminated
-15028 PI_INVALIDBOOKMARK Invalid or corrupt book mark
-15029 PI_INVALID Generic invalid call or argument
-15030 PI_MISMATCH Generic mismatch
-15031 PI_NOTADIG PIvalue type is not digital
PI Server System Management Guide Page 321
Code Code Identifier Message
-15032 PI_PATHNOTFOUND Requested path not found
-15033 PI_BCKUPINPROG Cannot perform operation during backup
-15034 PI_INVALIDTZCONFIG TimeZone configuration is invalid
-15035 PI_MAXARRLENGTHEXCEEDED Attempt to activate or create a PIarray
larger than max allowable.
-15036 PI_UNABLETORETRIEVEUNIXERRNO A call on UNIX fails but errno is zero.
-15037 PI_BADARGUMENTCONVERSION No suitable conversion from a variant to
RPC argument.
-15038 PI_INVALIDTIMESTAMP PIvalue cannot represent PIstring as a
valid timestamp.
-15039 PI_ENVVAR_EXISTS System environment variable already
exists
-15040 PI_MAXQUEUELIMIT Non-expandable PIfifo reached maximum
capacity
-15041 PI_EMPTYQUEUE Attempt to extract data from empty PIfifo
Table A–13. Error Codes 16000-16999, With Messages
Code Code Identifier Message
-16000 PI_INVALIDEFFECTIVEDATE Object not found for passed effective date
-16001 PI_MODULENOTFOUND Module does not exist
-16002 PI_INVALIDMODULEVERSION Invalid or missing module version
-16003 PI_DUPLICATEEFFECTIVEDATE Value with passed effective date already
exists
-16004 PI_LASTMODULEVALUE Cannot remove last module value. Use
module remove
-16005 PI_ROOTMODULE Attempt to remove or edit a Built in module
element
-16006 PI_MODULEHIERARCHYBREAK Attempt to delete or remove a module that
breaks existing hierarchy
-16007 PI_UNEXPECTEDMODULEDBERROR Unexpected PI Module Database error
-16008 PI_MODULEVALUEEXISTS Effective date already exists for attempt
add or move of a module value
-16009 PI_INVALIDPARENT Invalid parent specified for the operation
-16010 PI_DUPLICATEHIERARCHY Attempt to create or edit object with
Page 322
Code Code Identifier Message
duplicate hierarchical level
-16011 PI_INVALIDHIERARCHY Attempt to create or edit object with
invalided hierarchical level
-16012 PI_NOPARENTREFERENCE Module does not have parent reference to
specified module
-16013 PI_NOCHILDREFERENCE Module does not have child reference to
specified module
-16014 PI_INVALIDQUERYDATE Invalid or unspecified query date
-16015 PI_INVALIDUID Invalid or unspecified uid
-16016 PI_INVALIDMODE Invalid or unspecified module value access
mode
-16017 PI_MODULEVALUENOTFOUND Module Value for passed effective date not
found
-16018 PI_INVALIDHEADING Specified heading does not exist or is
member of different heading set
-16019 PI_INVALIDTIMERANGE Invalid or unspecified time range for batch
database search
-16020 PI_NOMATCHINGMODULES No matching PIModules for call
-16021 PI_NOMATCHINGBDBRECORDS No Matching Batch Database records
-16022 PI_MDBNOTSUPPORTED Attempted operation not supported by the
specified database
-16023 PI_MDBCIRCULARREFERENCE Attempt to insert a PIModule that would
cause a circular reference
-16024 PI_MDBNOMATCHINGVALUES No module values within the passed time
range
-16025 PI_MDBLASTVALUE Attempt to remove the last module value.
-16026 PI_BDBCROSSREFERENCE Attempt to remove a Batch Database
Record which contains a cross reference to
another record.
-16027 PI_BDBBSSNOTSUPPORTED Batch Database does not support this
action with Batch Subsystem Batch.
-16028 PI_INVALIDBDBTIME Invalid start or end time for Batch Database
Record.
-16029 PI_BDBMAXRECORDSEXCEEDED Batch database search exceeded
maximum allowed records
-16201 PI_THREADPOOLDISABLED Subsystem does not support thread pool or
PI Server System Management Guide Page 323
Code Code Identifier Message
thread pool is disabled.
-16202 PI_THREADSUSPENDED Thread is in suspended state.
-16203 PI_INVALIDTHREADID Passed thread ID is invalid.
-16204 PI_THREADTIMEOUT Time out waiting for semaphore or lock.
-16205 PI_THREADABANDONED Thread or handle has been abandoned.
-16206 PI_THREADUNLOCK Attempt to release exclusive lock from
thread that did not acquire the lock.
-16207 PI_THREADESCALATE Attempt to Escalate lock without prior non-
exclusive lock.
-16208 PI_THREADEXCLUSIVE Thread already has exclusive lock.
-16209 PI_IOCOMPLETED Asynchronous IO has completed.
-16210 PI_THREADNOTSUPPORTED Thread control function not supported.
-16211 PI_UKNOWNLOCKERROR Unknown system error attempting to get
lock.
-16212 PI_SHAREDLOCKTIMEOUT Timeout attempting to get non-excluseive
lock.
-16213 PI_UNBALANCEDLOCKRETURN Lock return count greater than get count.
-16214 PI_EXCLUSIVELOCKTIMEOUT Timeout attempting to get excluseive lock.
-16215 PI_THREADPOOLOVERRANGE Attempt to create too many threads.
-16300 PI_ARCHK_OVFREVCHAIN Invalid backwards chaining of overflow
record
-16301 PI_ARCHK_IDXREVCHAIN Invalid backwards chaining of index record
-16302 PI_ARCHK_RECIDXNOTFOUND Overflow record not found in index records
-16303 PI_ARCHK_MULTIPLEIDXREF Index entry referenced by multiple overflow
records
-16304 PI_ARCHK_OOOIDXREC Out-of-order overflow record in index
record
-16305 PI_ARCHK_OOOEVENT Out-of-order event found in overflow record
-16306 PI_ARCHK_INVANNHANDLE Event marked as annotated with no
annotation handle
-16307 PI_ARCHK_INVANNOTATION Annotation record not found for annotated
event
-16308 PI_ARCHK_DUPANNHANDLE Annotation record referenced by multiple
Page 324
Code Code Identifier Message
events
-16309 PI_ARCHK_IDXTIMEMISMATCH Index not matching overflow record start
time
-16310 PI_ARCHK_EVBEFORESTART Event before archive start time
-16311 PI_ARCHK_EVAFTEREND Event after archive end time
-16312 PI_ARCHK_IDXACTIVATION Unexpected error reading index record
-16313 PI_ARCHK_IDXSTARTERROR Index start time doesn't match archive start
time
-16314 PI_ARCHK_1STRECNOTHEAD First overflow record has a previous record
-16315 PI_ARCHK_PTTYPEMISMATCH Point type not matching primary record
-16316 PI_ARCHK_INVALIDIDXTYPE Unexpected data type for index record
-16317 PI_ARCHK_INVALIDARCNUM Invalid archive file number
-16318 PI_ARCHK_OVFCIRCHAIN Circular chaining of overflow record
-16319 PI_ARCHK_IDXCIRCHAIN Circular chaining of index record
-16320 PI_ARCHK_TOOMANYERRORS Too many errors, filtering non-fatal errors
-16500 PI_MMQ_SYNC_CREATE Creation of Piarchss synchronization object
failed
-16501 PI_MMQ_SYNC_OPEN Opening of Pisnapss synchronization
object failed
-16502 PI_MMQ_SYNC_WRITETIMEOUT Timeout waiting for write access to Event
Queue
-16503 PI_MMQ_SYNC_WRITEFAILED Wait for queue write returned a
WAIT_FAILED status
-16504 PI_MMQ_SYNC_UNEXPECTED Unexpected error waiting for Event Queue
access
-16505 PI_MMQ_SYNC_READTIMEOUT Timeout waiting for read access to Event
Queue
-16506 PI_MMQ_SYNC_READFAILED Wait for queue read returned a
WAIT_FAILED status
-16600 PI_MMQ_INVALID_FILESIZE Invalid queue file size (requires ٛ inimum 2
data pages)
-16601 PI_MMQ_FILEPATH_TOOLONG File path and name exceed 260 characters
(MAX_PATH)
-16602 PI_MMQ_PHYSFILE_CREATE Error while creating queue file
PI Server System Management Guide Page 325
Code Code Identifier Message
(pimapevq.dat)
-16603 PI_MMQ_MAPFILE_CREATE Error while creating mapped file of Event
Queue
-16604 PI_MMQ_MAPFILE_OPEN Error while opening mapped file of Event
Queue
-16605 PI_MMQ_MAPFILE_MAPVIEW Error while mapping a page view of the
queue file
-16606 PI_MMQ_MAPFILE_INIT Event queue not initialized before read or
write access
-16607 PI_MMQ_MAPFILE_UNMAPVIEW Error while unmapping a page view of the
queue file
-16608 PI_MMQ_MAPFILE_FULL Event queue file is entirely full
-16609 PI_MMQ_FILESIZE_MISMATCH Configured file size doesn’t match existing
file
-16610 PI_MMQ_PAGESIZE_MISMATCH Configured page size doesn’t match
existing file
-16611 PI_MMQ_FORWARD_VERSION Existing queue file is from a later version
-16612 PI_MMQ_INVALID_READPAGE Invalid read page index in existing queue
file
-16613 PI_MMQ_INVALID_WRITEPAGE Invalid write page index in existing queue
file
-16614 PI_MMQ_INVALID_FREEPAGES Inconsistent number of available pages in
existing queue file
-16615 PI_MMQ_WRITEPAGE_FULL Write failedtarget write page is full
-16616 PI_MMQ_STREAMINIT_ERROR Error while creating i/o stream object
-16617 PI_MMQ_ACTIVATION_FAILED Read error while activating event from
queue
-16618 PI_MMQ_UNRECOGNIZABLE_FILE File format is not a valid memory-mapped
Event Queue file
-16619 PI_MMQ_MAPFILE_FLUSHVIEW Error while flushing to disk a view of the
queue file
-16620 PI_MMQ_EMPTY_READPAGE Attempt to read data from an empty page
-16621 PI_MMQ_BAD_FILENAME Invalid overflow file name template
-16622 PI_MMQ_BAD_EXTENSION Missing extension in overflow file name
template
Page 326
Code Code Identifier Message
-16623 PI_MMQ_BAD_DATA_OFFSET Invalid data member offset within
PImapfilepage
-16624 PI_MMQ_EVCOUNT_MISMATCH Event count mismatch with empty data
pages
-16700 PI_SUBSYSINFO_INVALID_ARGUMEN Invalid arguments for Sub-system
TS Information RPC
-16701 PI_SUBSYSINFO_INVALID_PROCESSI Invalid process ID Sub-system Information
D RPC
-16821 PI_BCKFILE_FILENAME_NULL Cannot add file to the list of backed up files
because the file name is null
-16823 PI_BCKFILE_REMOVE_ERROR_FILEN Cannot remove file from list of backed up
OTFOUND files because the file name was not found
in the list
-16824 PI_BCKFILE_ADD_ERROR_DUPLICAT Cannot add file to the list of backed up files
EFILENAME because the file is already in the list
-16826 PI_BCKFILE_DUPLICATE_BACKEDUP Only one backup file list object can be
_FILE_LIST created
-16840 PI_BACKUP_BACKUPSUBSYS_NOT_I Backup manager is not initialized
NITIALIZED
-16841 PI_BACKUP_VSS_UNSUPPORTED Unsupported operating system for Volume
Shadow Copy Services
-16842 PI_BACKUP_INVALID_COMPONENT_ Invalid component name
NAME
-16860 PI_VSSEVENT_FREEZE_IN_PROGRE VSS Freeze already in progress
SS
-16861 PI_VSSEVENT_FREEZE_NOT_IN_PR Expected VSS Freeze to be in progress,
OGRESS but freeze was not in progress
-16863 PI_BCKEVENT_FREEZE_TIMEOUT_W VSS Freeze timed out waiting for VSS thaw
AITING_FOR_THAW_EVENT event
-16864 PI_VSSEVENT_FREEZE_TIMEOUT_D VSS Freeze timed out before VSS freeze
URING_FREEZE_EVENT event could complete
-16868 PI_VSSEVENT_IDENTIFY_COMPONE VSS Identify failure. Two VSS components
NT_MISMATCH have the same name but different
component properties
-16893 PI_BCKEVENT_SUBSYSTEM_NOT_P Subsystem does not participate in backups.
ARTICIPATING The backup event was ignored
-16896 PI_BCKEVENT_RPCRESOLVEROFFLI RPC Resolver offline for a subsystem to
NE which the backup subystem is
communicating. Find -10733 error in
PI Server System Management Guide Page 327
Code Code Identifier Message
message log to identify problematic RPC
-16898 PI_BCKEVENT_IN_PROGRESS Backup event in progress
-16914 PI_BCKSTATE_INVALID_STATE_TRA Invalid state transition for backup
NSITION
-16915 PI_BCKSTATE_BACKUP_ABORTED Backup was aborted
-16916 PI_BCKSTATE_BACKUP_SHUTDOWN Backup shutdown without completing
_NOCOMPLETE
-16917 PI_BCKSTATE_BACKUP_IN_PROGRE Backup in progress
SS
-16920 PI_BCKRPC_NO_RESPONSE Expected VSS Async callback function was
not called within timeout period
-16921 PI_BCKRPC_CALLBACK_UNEXPECTE Unexpected VSS Async callback. Callback
D function was called but was not expected
-16923 PI_BCKRPC_INVALID_BACKUP_COM Invalid backup command
MAND
-16940 PI_VSSAPI_ADDCOMPONENT_FAILE VSS API call AddComponent failed
D
-16941 PI_VSSAPI_ADDDATABASEFILE_FAIL VSS API call AddDatabaseFiles failed
ED
-16942 PI_VSSAPI_BACKUPTYPE_UNKNOW Unknown backup type
N
-16943 PI_VSSAPI_BACKUPTYPE_LOG_UNS Backup type of LOG is unsupported
UPPORTED
-16944 PI_VSSAPI_BACKUPTYPE_OTHER_U Backup type of OTHER is unsupported
NSUPPORTED
-16980 PI_BCKLOCK_GETLOCK_TIMEOUT GetLock timeout for master backup lock
-16981 PI_BCKLOCK_GETEXCLUSIVELOCK_ GetExclusiveLock timeout for master
TIMEOUT backup lock
-16983 PI_BCKLOCK_RETURNEXCLUSIVELO ReturnExclusiveLock failed for master
CK backup lock
-16984 PI_BCKLOCK_RETURNEXCLUSIVELO ReturnExclusiveLock for master lock failed
CK_NOTLOCKED because master lock was not locked
-16985 PI_BCKLOCK_GETLOCK_NONVSSBA GetLock failed for master backup lock
CKUP because a non-VSS backup is in progress
Page 328
Table A–14. Error Codes 17000-17999, With Messages
Code Code Identifier Message
-17000 PI_UNX_SEMRANGE Semaphore count out-of-range
-17001 PI_UNX_ARRSEM Semaphore belongs to array
-17002 PI_UNX_EVNONAME No name for shared event
-17003 PI_UNX_EVNOINIT Event not initialized
-17004 PI_UNX_BADEVSEM Named semaphore init failed
Table A–15. Error Codes 30000-30999, With Messages
Code Code Identifier Message
-30000 PI_WARNING Generic warning
-30100 PI_PD_IGNORE Attribute ignored
-30101 PI_PD_OPERATIONFAILED One or more point SDK operations failed
-30150 PI_BCKSTATE_NOTREADY_FORFRE Warning - not ready for freeze yet
EZE
-30200 PI_NODATA Generic Nothing Found warning
-30201 PI_TMPUNAVAIL Generic temporary unavailable - try later
-30202 PI_RELOADED Generic reload warning
-30250 PI_UPD_OVERFLOW Update queue overflow, some events
missing
-30260 PI_ALREADYLOCKED Request locking an already locked
-30300 PI_CTR_NOINSTALL Perflib registry is bad, will not install
counters
-30301 PI_CTR_DONOTINSTALLCOUNTERS Performance counters chosen not to be
installed
-30350 PILIC_GRACELICEXP License expired or exceeded grace period
-30400 PI_AR_DUPTIMESTAMPS Last event in collection has same
timestamp as next event
-30401 PI_AR_REMGENEVENT Attempt to remove or replace a generated
event
-30402 PI_AR_ANNFILERENAMED Annotation file not matching archive ID,
successfully renamed
-30403 PI_AR_INVCOMPEVENT Event for removal not found in snapshot
record, passed to archive
PI Server System Management Guide Page 329
Code Code Identifier Message
-30404 PI_AR_NOTINBACKUPSTATE No archive file in backup state
-30500 PI_RDR_PARTIALSUCCESS One or more Redirector operations failed
-30501 PI_RDR_SUMMARYNOTSUPPORTED PI COM Connector does not support this
summary. Summary will be performed on
host.
Page 330
APPENDIX B: PI PERFORMANCE COUNTERS
PI Server has a number of performance counter statistics that can to be viewed using
Microsoft’s Performance Monitor utility (System Monitor in Windows 2000).
The following tables list the statistics that may be viewed.
PI Base Subsystem Statistics
Attribute Description
Point Count Total number of defined points. This number includes the Connector
Point Count.
Connector Point Count Count of defined points that are mapped points. These are points
that interact with points on a foreign data historian using a COM
Connector.
Point Create or Edit/sec Rate at which points are created or edited.
Digital State Rate at which digital state strings are translated to offsets.
Translations/sec
Wild Card Searches/sec Rate of wild card point searches. This counter represents the rate at
which new searches are started, not the number of points found.
Point Accesses/sec Rate at which point information is accessed, not including point
edits. This will include translations of tag to point id.
Module Count The total number of modules in the module database.
Heading Set Count The total number of heading sets in the module database.
Heading Count The total number of headings in the module database.
Module Database Record The total number of records in the module database.
Count
Module Create or Edit/sec Rate at which modules are created or edited.
Heading Set Create or Rate at which heading sets are created or edited.
Edit/sec
Heading Create or Edit/sec Rate at which headings are created or edited.
Module Database Create or Rate at which MDB records are created or edited.
Edit/sec
PI Server System Management Guide Page 331
Attribute Description
Module Accesses/sec Rate at which module information is accessed, not including module
edits.
Heading Set Accesses/sec Rate at which heading set information is accessed, not including
module edits.
Heading Accesses/sec Rate at which heading information is accessed, not including module
edits.
Module Database Rate at which module database information is accessed, not
Accesses/sec including module edits.
PI Archive Subsystem Statistics
Attribute Description
Archived Events/sec Rate of successful event addition to the archive.
Out of Order Events/sec Out of order events posted in the archive.
Events Cascade/sec Rate of Out-of-Order events causing record shifts.
Events Read/sec Rate of archive events read.
Read Operations/sec Rate of archive read calls. Each call can return multiple events. The
rate of event retrieval is Events Read/sec.
Primary Archive Number Internal index number of archive current assigned to primary position.
Cache Record Count Archive cache records in memory.
Cache Records Rate at which archive cache records are created.
Created/sec
Cache Records Rate at which archive cache records are deleted.
Deleted/sec
Record Disk Reads/sec Rate of archive disk reads (includes Cache Record Disk Reads/sec).
Record Disk Writes/sec Rate of archive disk writes.
Cache Record Disk Rate of archive cache disk reads.
Reads/sec
Cache Record Memory Rate of archive cache memory hits.
Reads/sec
Overflow Index Record/sec Rate at which index archive records are created.
Overflow Data Record/sec Rate at which data archive records are created.
Cache Clean Rate at which archive cache records are removed from memory.
Operations/sec
Cache Flush Rate at which points are flushed to disk.
Page 332
Attribute Description
Operations/sec
Time to Archive Shift Number of seconds until the archive is projected to shift. This time is
not calculated if the archive is less than 20% full.
Connector Read Rate of calls to read events for mapped points through COM
Operations/sec Connectors. This rate is NOT included in the Read Operations/sec
counter.
Connector Events Rate of events read for mapped points through COM Connectors.
Read/sec This rate is NOT included in the Events Read/sec counter.
Connector Summaries/sec Rate of summaries for mapped points through COM Connectors. This
rate is NOT included in the Events Read/sec counter.
Connector Events Read Time elapsed in milliseconds for one Events Read for a COM
Exec Time Connector point.
Connector Event Read Time elapsed in milliseconds for one Event Read for a COM
Exec Time Connector point.
Connector Summaries Time elapsed in milliseconds for one summaries call for a COM
Exec Time Connector point.
Point Flushes Last Cycle Number of points flushed to disk during last cycle. Busy points might
get flushed several times per cycle.
Unflushed Points Number of points that have at least one unflushed event.
Archive Cycles/Sec Number of Subsystem cycles per second.
Total Unflushed Events Total number of unflushed events.
Configured Cache Record Maximum number of cache records in the read-only pool.
Pool
Current Cache Record Current maximum number of cache records, this may be lower that
Pool the configured value due to low memory resources.
Config. Max Unflushed Maximum number of unflushed events per point.
Events/pt
Current Max Unflushed Current maximum number of unflushed events per point, this may be
Events/pt lower that the configured value due to low memory resources.
Primary Archive % Used Percent of used records in Primary Archive File.
Event Queue Chunk Size Number of events read per Event Queue read operation.
Flush Queue Size Number of pending flush operations in memory queue.
Write Contentions/sec Rate of write lock contentions (EVQ threads).
Write Contention Points Number of points in write contention last cycle.
GetSnapshot Calls/sec Rate of internal calls to the Snapshot Subsystem.
PI Server System Management Guide Page 333
Attribute Description
ArcEvent Calls/sec Rate of single archive event calls.
CompEvents Calls/sec Rate of compressed events calls.
InterpEvents Calls/sec Rate of interpolated events calls.
PlotEvents Calls/sec Rate of plotted (trended) event calls
Summary Calls/sec Rate of summary/filter expression calls.
PICampaigns Created/sec Rate of PI Campaign creation.
PIBatches Created/sec Rate of PI Batch creation.
PIUnitBatches Created/sec Rate of PI Unit Batch creation.
PITransferRecords Rate of PI Transfer Record creation.
Created/sec
PICampaigns Edited/sec Rate of PI Campaign edits
PIBatches Edited/sec Rate of PI Batch edits
PIUnitBatches Edited/sec Rate of PI Unit Batch edits
PITransferRecords Rate of PI Transfer Record edits.
Edited/sec
PICampaigns Read /sec Rate of PI Campaign access.
PIBatches Read /sec Rate of PI Batch access.
PIUnitBatches Read /sec Rate of PI Unit Batch access.
PITransferRecords Rate of PI Transfer Record access.
Read/sec
PICampaigns Deleted /sec Rate of PI Campaign deletion.
PIBatches Deleted /sec Rate of PI Batch deletion.
PIUnitBatches Deleted /sec Rate of PI Unit Batch deletion.
PITransferRecords Deleted Rate of PI Transfer Record deletion.
/sec
PI Snapshot Subsystem Statistics
Attribute Description
Snapshots/sec Rate at which events are sent to the snapshot.
Out Of Order Rate at which out-of-order events are sent to the snapshot.
Snapshots/sec
Page 334
Attribute Description
Queued Events/sec Rate at which events are sent to the Event Queue.
GetSnapshots/sec Rate at which events are read from the snapshot.
GetSnapshot Calls/sec Rate of individual snapshot value calls.
GetSnapshots Calls/sec Rate of multiple snapshot values calls.
Remove Snapshots/sec Rate of snapshot values being deleted.
Digital State Rate of digital strings translated into offsets.
Translations/sec
Connector Snapshots/sec Rate at which events are sent to mapped points through COM
Connectors. This rate is NOT included in the Snapshots/sec counter.
Connector Rate at which events are read from mapped points through COM
GetSnapshots/sec Connectors. This rate is NOT included in the GetSnapshots/sec
counter.
Connector Updates/sec Update events received from COM Connectors. This rate is NOT
included in the Connector GetSnapshots/sec counter.
Connector Snapshot Put Time elapsed in milliseconds for Snapshot Put for COM Connector a
Elapsed Time point.
Connector Snapshot Read Time elapsed in milliseconds for Snapshot Read for a COM
Elapsed Time Connector point.
Connector Updates Time elapsed in milliseconds for Updates for COM Connector points.
Elapsed Time
Events in Primary Queue Number of events in the primary queue file.
Number of Overflow Number of overflow queue files (0 if only the primary queue is active).
Queues
Events in Overflow Queues Total of events in the overflow queue files.
Estimated Remaining Estimated maximum number of events with current queue file.
Capacity
Event Queue Total Pages Number of data pages in primary queue file.
Event Queue Used Pages Number of full data pages in primary queue file.
Event Queue Page Rate of data page shifts in primary queue file.
Shifts/sec
Primary Event Queue Id Identification number of primary queue (0 to 65,535).
PI Server System Management Guide Page 335
PI Message Subsystem Statistics
Attribute Description
Sent Messages/sec The number of messages sent to PI Message Subsystem per
second.
Retrieved Messages/sec The number of messages retrieved by the PI Message Subsystem
per second.
Inserted Messages/sec The number of messages that were inserted into the PI Message
Subsystem from the Application Event Log per second.
PI SQL Subsystem Statistics
Attribute Description
Callbacks/sec Rate of calls to PI-SQL execution callback routine.
ArcValueCompCalls/sec Rate of RPC calls made to the PI Archive Subsystem for compressed
events.
ArcValueCompEvents/sec Rate at which compressed data events are returned by the PI Archive
Subsystem.
WildcardSearches/sec Rate at which new wildcard searches are initiated in the PI Point
Database.
WildcardPoints/sec Rate at which points are returned when performing wildcard searches
of the PI Point Database.
ArcValueCalls/sec Rate of RPC calls made to the PI Archive Subsystem to obtain a
single archived value.
SnapshotCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to obtain a
single snapshot value.
WHERE Clause Rate of full evaluations of the WHERE clause of a SELECT
Evaluations/sec statement.
ArcValueTimedCalls/sec Rate of RPC calls made to the PI Archive Subsystem for interpolated
or timed events.
ArcValueTimedEvents/sec Rate at which interpolated or timed data events are returned by the PI
Archive Subsystem.
SummaryArcValueCalls/se Rate of RPC calls made to the PI Archive Subsystem for summarized
c values (i.e. average, total, standard deviation, etc.).
Dot Variable Rate of "dot" variable evaluations made within the PI SQL Library. A
Evaluations/sec dot variable in SQL is a table alias and column name, such as
"picomp.tag.” This rate is a measure of PI SQL Subsystem
processing not related to obtaining data from other subsystems.
Next Point With Source Rate at which points are returned by the PI Base Subsystem in
Calls/sec searches for points with a specific PointSource attribute.
Page 336
Attribute Description
PostCalls/sec Rate of RPC calls made to the PI Snapshot Subsystem to post
events from execution of SQL INSERT or UPDATE statements.
PostEvents/sec Rate at which data events are posted to the PI Snapshot Subsystem
from execution of SQL INSERT or UPDATE statements.
Handles Number of PI SQL handles currently allocated in the PI SQL
Subsystem. This is an indication of how many clients are actively
processing SQL statements.
PI Totalizer Subsystem Statistics
Attribute Description
Total Point Count The total number of active PI Totalizer Subsystem points.
Source Tag Values/sec Rate of Totalizer input events.
EventExpr/sec Rate of EventExpr evaluations.
FilterExpr/sec Rate of FilterExpr evaluations
Filter Changes/sec Rate of Filter state changes
Period End/sec Rate of Totalization period completions
Updates/sec Rate of snapshot values to Totalizer points
Update status The status of the PI Update Manager as perceived by the PI
Totalizer. If non-zero, this is the absolute value of the most recently
received error code. If zero, all is well.
PI Network Manager Statistics
Attribute Description
Connections The number of connections to the PI Network Manager. Applies to _Total
only.
Messages Sent/sec The number of messages sent to the PI Network Manager.
Messages The number of messages received by the PI Network Manager.
Received/sec
Bytes Sent/sec The number of bytes sent to the PI Network Manager.
Bytes Received/sec The number of bytes received by the PI Network Manager.
Overflow/sec The number of times an overflow message is required by the PI Network
Manager.
Receive Errors The number of times an error occurs during a receive of a message to the
PI Network Manager.
PI Server System Management Guide Page 337
Attribute Description
Send Errors The number of times an error occurs during a send of a message to the PI
Network Manager.
PI API Connections The number of PI API applications connected.
PI SDK Connections The number of PI SDK applications connected.
Licensing Failures The number of times an application was rejected due to licensing
concerns
Licensing Warnings The number of times an application was warned of licensing concerns
PI Performance Equations Statistics
Attribute Description
AlarmFuncCalls/sec Rate of calls made to alarm functions.
ArcFindCalls/sec Rate of calls made to the PI Archive Subsystem for finding values.
ArcSummaryCalls/sec Rate of calls made to the PI Archive Subsystem for summarized values.
ArcValueCalls/sec Rate of calls made to the PI Archive Subsystem for compressed events.
FailedEvaluations/sec Rate of PE evaluations that return the digital state Calc Failed.
NumberOfPEs Number of Performance Equations.
SnapshotCalls/sec Rate of calls made to the PI Snapshot Subsystem to obtain snapshot
event(s).
SnapshotEvents/sec Rate of snapshot event retrieval.
SteamFuncCalls/sec Rate of calls made to steam functions.
TotalEvaluations/sec Rate of PE evaluations.
PI Session Statistics
Attribute Description
Messages Sent/sec The number of messages sent by the PI session.
Messages Received/sec The number of messages received by the PI session.
Bytes Sent/sec The number of bytes sent by the PI session.
Bytes Received/sec The number of bytes received by the PI session.
Receive Errors The number of times an error occurs during a receive a message by the
PI session.
Send Errors The number of times an error occurs during a send of a message by the
PI session.
Page 338
PI Subsystem Statistics
Attribute Description
Message Queue Length Number of incoming messages in queue.
Pending Transactions Number of pending transactions.
Actual Pending Only for internal debugging purpose. You should use it only under the
Transactions suggestion of OSI Technical Support.
Message Pickup Time Latency of incoming messages (time in message queue).
Message Execution Execution time of incoming message (RPC).
Time
Message Complete Time Total message handling time (including results sending).
Callback Execution Time Execution time of transaction callback.
Transaction Number of transactions completed per second.
Completed/sec
Transaction Number of transactions cancelled per second.
Cancelled/sec
Transaction Avg Time Average execution time of outgoing transactions.
Transaction Max Time Maximum execution time of outgoing transactions.
Lock Acquisitions/sec Number of successful lock acquisitions per second
Lock Timeouts/sec Number of lock timeouts (failed locks) per second.
Lock Contentions/sec Number of lock conflicts (threads waiting for the same lock).
RPC Threads Total Total number of RPC worker threads (query processing).
RPC Threads Active Number of RPC worker threads processing a query.
File Open Number of time File base Open called.
File Close Number of time File base Close called.
File Read/Sec Rate of File base Read.
File Write/Sec Rate of File base Write.
File Delete/Sec Rate of File base Delete.
File Create Number of time File base Create called.
File Compress Number of time File base Compress operations.
File Grow Number of time File Directory grow operations.
PI Server System Management Guide Page 339
PI Update Manager Statistics
Attribute Description
Pending events Total Events pending in the PI Update Manager database.
New events/sec Events sent to the PI Update Manager.
Lost events/sec Events lost due to the PI Update Manager database being full.
Update signups Queued signups in the PI Update Manager.
New registration/sec Consumer and Producer registration rate.
Consumer count Total number of registered consumers.
Max pending events Maximum pending events reached in the PI Update Manager database.
Get Events calls/sec Total consumers Getevent calls rate.
PI Update Consumer Statistics
Attribute Description
Pending events Total Events pending for this consumer.
New events/sec Event rate for this consumer.
Lost events/sec Events lost due to the PI Update Manager database being full.
Update sign-ups Queued sign-ups for this consumer.
Get Events calls/sec Getevent calls rate.
PI Update Producer Statistics
Attribute Description
Pending events Total Events pending for this producer.
New events/sec Event rate for this producer.
Update calls/sec Rate of incoming update calls
Update sign-ups Queued sign-ups for this producer.
PI Server LocalHost Statistics
The piperfmon.dif file contains examples of some basic performance counters useful in
monitoring PI Server. These points contain performance information about the PI Server as
well as the machine that runs it. The performance counters for the machine are useful in
determining resource problems of the machine that runs PI Server. The performance counters
for the PI Server are useful in determining how well the PI Server is performing.
Page 340
Table B–16. PI Performance Counters
Tag Explain Text
PERF.LOCALHOST.Logical Free Megabytes displays the unallocated space on the disk drive in
Disk(_Total).Free Megabytes megabytes. One megabyte = 1,048,576 bytes.
PERF.LOCALHOST.Memory % Committed Bytes In Use is the ratio of Memory: Committed
.% Committed Bytes In Use Bytes to Memory: Commit Limit. (Committed memory is physical
memory in use for which space has been reserved in the paging
file should it need to be written to disk. The commit limit is
determined by the size of the paging file. If the paging file is
enlarged, the commit limit increases, and the ratio is reduced). This
counter displays the current percentage value only; it is not an
average.
PERF.LOCALHOST.Memory Page Faults/sec is the overall rate that faulted pages are handled
.Page Faults/sec by the processor. It is measured in numbers of pages faulted per
second. A page fault occurs when a process requires code or data
that is not in its working set (its space in physical memory). This
counter includes both hard faults (those that require disk access)
and soft faults (where the faulted page is found elsewhere in
physical memory). Most processors can handle large numbers of
soft faults without consequence. However, hard faults can cause
significant delays. This counter displays the difference between the
values observed in the last two samples, divided by the duration of
the sample interval.
PERF.LOCALHOST.Process % Processor Time is the percentage of time that the processor is
or(0).% Processor Time executing a non-Idle thread. This counter was designed as a
primary indicator of processor activity. It is calculated by measuring
the time that the processor spends executing the thread of the Idle
process in each sample interval, and subtracting that value from
100%. (Each processor has an Idle thread, which consumes cycles
when no other threads are ready to run). It can be viewed as the
percentage of the sample interval spent doing useful work. This
counter displays the average percentage of busy time observed
during the sample interval. It is calculated by monitoring the time
the service was inactive, and then subtracting that value from
100%.
PERF.LOCALHOST.TCP.Se Segments Retransmitted/sec is the rate at which segments are
gments Retransmitted/sec retransmitted, that is, segments transmitted containing one or more
previously transmitted bytes.
PERF.LOCALHOST.TCP.Se Segments Sent/sec is the rate at which segments are sent,
gments Sent/sec including those on current connections, but excluding those
containing only retransmitted bytes.
PERF.LOCALHOST.Process % Processor Time is the percentage of elapsed time that all of the
(piarchss).% Processor Time threads of this process used the processor to execute instructions.
PERF.LOCALHOST.Process An instruction is the basic unit of execution in a computer, a thread
(pibasess).% Processor Time is the object that executes instructions, and a process is the object
created when a program is run. Code executed to handle some
PERF.LOCALHOST.Process hardware interrupts and trap conditions are included in this count.
(pinetmgr).% Processor Time On Multi-processor machines the maximum value of the counter is
PERF.LOCALHOST.Process 100 % times the number of processors.
(pisnapss).% Processor Time
PI Server System Management Guide Page 341
Tag Explain Text
PERF.LOCALHOST.PI Rate of archive events read.
Archive.Read Events
operations/sec
PERF.LOCALHOST.PI Archive cache disk reads.
Archive.Cache Record Disk
Reads/sec
PERF.LOCALHOST.PI Archive cache memory hits.
Archive.Cache Record
Memory Reads/sec
PERF.LOCALHOST.PI Base Total number of defined points. This number includes the
Subsystem.Point Count Connector Point Count.
PERF.LOCALHOST.PI The number of connections to the PI Network Manager. This
Network counter only applies to instance _Total.
Manager(_Total).Connection
s
PERF.LOCALHOST.PI The number of messages sent to the PI Network Manager.
Network
Manager(_Total).Messages
Sent/sec
PERF.LOCALHOST.PI
Network
Manager(piarchss).Message
s Sent/sec
PERF.LOCALHOST.PI
Network
Manager(pibasess).Message
s Sent/sec
PERF.LOCALHOST.PI
Network
Manager(pisnapss).Message
s Sent/sec
PERF.LOCALHOST.PI Out of order events sent to the snapshot.
Snapshot.OutOfOrderSnapsh
ots/sec
PERF.LOCALHOST.PI Events sent to Event Queue.
Snapshot.Queued
Events/sec
PERF.LOCALHOST.PI Events sent to the snapshot.
Snapshot.Snapshots/sec
PERF.LOCALHOST.PI Total Events pending in the PI Update Manager database.
Update-Manager.Pending
events
PERF.LOCALHOST.CALCU PI Compression Ratio is a performance equation that calculates
LATED.PI Compression amount of data that is compressed.
Ratio
Page 342
Tag Explain Text
PERF.LOCALHOST.CALCU PI Archive.Cache Hit Rate is a performance equation that
LATED.PI Archive.Cache Hit measures the rate at which data is accessed from memory as
Rate opposed to disk.
PI Server System Management Guide Page 343
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
PI Server System Management Guide Page 345
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion -v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option -v (for example, piarchss.exe -v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname -a
Page 346
INDEX OF TOPICS
? command, 186 combining files, 59
?atr command, 186 contents of, 27
?tbl command, 186 Corrupted, 243
piconfig, 173 dividing, 60
Abbreviations, 220 dynamic, 36
Access Permissions file recovery, 270
algorithm, 122 Files, 34
Changing, 123 Fixed, 36
read-write, 122 full, 36
Active Directory initializing, 57
Slow access to, 255 Listing values, 203
Activity grid, 253 Management, 33
Adding a digital state Set, 196 data file, 270
Alias Table Memory Cache, 28
Batch, 208 Performance
Annot, 201 daily monitoring, 27
Annotations, 207 Primary Archive, 46
API Number, 29
about, 96 Registering, 46
on VMS, 95 Reorganizing files, 59
API buffering. See buffering Repairing the Registry, 246
API Nodes, 96 Restore, 244
application programming interface, Sequence Number, 47
96 Shift
AppName field, 131 Enable Flag, 58
APS utility, 113 Prediction, 29
architecture Archive Manager Data File
distributed data collection, 94 recovery, 270
Archive archive record
Archived Events counter, 28 size, 34
Archiving Flag, 29 archive registry, 56
Cache, 28 Archive Subsystem
PI Server System Management Guide Page 347
performance counters, 332 registering, 33
Archive Subsystem shift p rediction, 57
Troubleshooting, 231 size considerations, 53
archive walk, 49 sizing, 53
archives slow access, 35
archive registry, 56 space needs, 51
annotation files, 52 specifying maximum size, 54
anticipating overflow, 51 specifying number of points,
archive shift, 33 53
archive shifts, 57 time limit on modifying, 52
archive walk, 49 unregistering, 56
backfilling without Archives
compression, 54, 55 About, 33
command-line tools, 37 ArchiveX, 202
creating, 52 ASCII file
creating new primary, 55 using in piconfig, 183
deleting, 56 Attribute Point
editing data in, 51 Location4, 104
failing to register, 55 PointSource, 103
fixed and dynamic, 33, 35 Attribute Set Table, 191
for previously collected data, Attributes
54 Access Permissions
forcing archive shifts, 58 changing, 123
gaps, 34 Displaying, 174
ID conversion file, 43 For subsystems, 210
index records, 35 Istructure, 190
list record details, 49 Llisting for table, 186
maximum size, 53 Modifying
minimum and maximum size, in Point Database, 189
52
Wrong Class, 189
moving, 56
Set
moving to another server, 43
Point Database, 188
naming, 52
Time, 207
offline utility, 41
Timenum, 207
piarchss parameters, 41
Automatic Point Synchronization,
piarchss utility, 41 113
piartool utility, 37 Automatic Startup
precentage records used, 47 Compaq Tru64 UNIX
predicting shifts, 47 Systems, 11
processing, 41 HP-UX 10 Systems, 9
records, 34 HP-UX 9 Systems, 15
registering, 56 IBM AIX Systems, 13
Page 348
PI Server, 6 Case-preserving, 220
Solaris UNIX Systems, 7 Case-sensitive, 220
Windows Services, 6 Digital State Set, 198
backfilling archives flag, 186
creating new primary archive, UNIX operating system, 172
55 Cd command, 186
without compression, 54, 55 Character
backfilling data, 54 special, Changing, 223
Backups t for true, 178, 179
Automating, 66 Classic Point
PI Server, 63 Attributes, 189
Recommendations, 66 Classicctr, 258
Base Subsystem, 230 Clear command, 186
performance counters, 331 Client Applications
Batch Alias Table, 208 Connection Messages, 290
Batch method Security, 125
piconfig, 172 clock
Batch mode, 183 setting on interface nodes, 101
Batch Subsystem clock, system, 23
Batch Unit Table, 207 codes, error
Batch Tables, 209 operating system, 21
BATCHEXPR, 208 COM component
BID register, 279
Batch Subsystem, 209, 214, COM Connector
215
in-process, 262
BIDsearch
out-of-process, 262
Batch Subsystem, 209
troubleshooting, 257, 261
Boolean values, 222
Web site, 257
buffer, 95
Combining Archives, 59
buffering
ComChar, 186, 223
about, 95
Comma Separated Format, 179,
maximum size of buffer, 95 190
recommendations, 95 Command
Buffering ?tbl, 173
PI API, 96 All in piconfig, 186
bufserv Bye, 183
file buffer size, 95 Case, 220
Bye command, 183 character, 186, 223
BytesRecv, 211, 212 piconfig, 172
BytesSent, 211, 212 Comm, 180
C language, API, 96 Endsection, 182
Case command, 220 Error, 184
PI Server System Management Guide Page 349
help, 176 firewall, 135
Iistructure, 196 Connections
input, 220 connection credentials, 128
Llisting all, 186 Display info on, 212
Ostructure, 180 ID, 291
Output, 184 Messages
piconfig commands, 176 Clients, 290
Quit, 183 Subsystems, 291
Select, 176, 181 slow, 254
Status ConStatus, 212
piconfig, 173 Consumer
Table, 173 pilistupd utility, 238
Command Line Arguments, 223 ConTime, 212
Command Specification ConType, 212
Persistence, 223 conversion files, ID, 43
Comment, 186 Convert mode, 178, 224
Character, 186, 190, 223 Corrupted
Changing, 180 Archives, 243
Command, 180 non-primary, 241
Lines, 180 Primary, 242
Communication Count
layer, 251 Batch Subsystem, 209
Routing function of PINet PIARC Table, 203
Manager, 229
piartool -al, 47
COMP
counter
mode, Piarc Table, 203
events, 23
Compaq Tru64
events in queue, 24
process count, 234
events in queue counter, 24
Compare mode, 178
events sent to queue counter,
compression 24
backfilling archives without, number of overflow queues, 25
54, 55
out of order events, 23
for backfilling archives, 54
out-of-order events, 23
out of order events, 23
remaining queue capacity, 25
ratio, 24
snapshot events read, 24
Compression
total overflow events, 25
Specifications, 24
Counter
compression tuning, 24
Archive Memory Cache
Computer platform counters, 28
Information, 346 Archived Events, 28
Connection Credentials, 128 Events Read, 28
evaluating matches for, 134
Page 350
number of archive read Dates
requests, 28 overlapping, 245
out-of-order event Daylight Savings Time
archive, 28 and interface nodes, 101
Overflow Data Record, 30 customizing changes, 267
Overflow Index Record, 30 list of changes, 267
PI Server Performance, 340 Dbsecurity, 173
counter, point, 23 DbsecurityTable, 216
counters Dcomcnfg, 257, 262
performance, 331 Default
CPU Digital State Set, 195
Excessive usage of, 253 default values
CPU usage pigetmsg parameters, 19
by utilities, 252 Delete
Create Mode, 178
Mode, 178 deleting archives, 56
creating archives for old data, 54 deleting connection error message,
creating new primary archives, 55 22
CSV format, 190 Delimited
ctr_lmap, 258 Structure type, 179
ctr_progid, 258 Delimiter, 186
ctr_strmap, 258 Character, 180, 187, 223
data Command, 180
time limit on modifying, 52 Format, 179, 223
Data Digital State, 5, 172
File repairs, 241 Table, 195
Recovering from corrupted Digital State Set
archives, 241 adding, 196
Data Archive capitalization, 198
Adding values, 201 Changing the Name, 198
data buffering default, 195
about, 95 limits, 195
data flow modifying, 197
buffering, 95 Digital State Table
snapshot, 22 merging systems, 153
Database Digital State Value
Firewall, 219 Sending to the Snapshot
Point, 57, 189 database, 200
Timeout, 219 Digital tag
Trust, 218 Creating, 199
Database Security, 173 DigitalSet, 199
Database Security Table, 216 Directory
PI Server System Management Guide Page 351
PIHOME directory on NT, 101 error messages
Disconnect Messages, 292 about, 21
distributed data collection, 94 deleting connection, 22
Documentation interpreting, 21
conventions, v operating system, 21
for interfaces, vi rpc resolver, 22
Domain subsystem health check failed,
Name Server, 129 22
trust logins, 132 EVEN
Domain Controller interpolated events, Piarc, 203
Slow access to, 255 event
Dr. Watson, 278 definition of, 23
DST in the event queue, 24
and interface nodes, 101 out of order, 23
Dump capability overflow events, 25
crash pidiag, 278 remaining primary queue
capacity, 25
dxWindows, 234
sent to the Event Queue, 24
Dynamic archive, 36
Event Log
dynamic archives, 33, 35
configuring, 260
Echo, 186
event queue
Edit Mode, 178
events in, 24
Edit Mode Attribute, 204
events sent to, 24
editing archives, 51
monitoring, 25
Ellipsis construct, 182
number of overflow queues, 25
End of file, 183
remaining capacity, 25
EndRecord, 186
total overflow events, 25
End-Repeat, 186
Event Queue
Endsection, 186
recovery, 61
Command, 182
Troubleshooting, 230
Endtime, 203
Event Timestamps
error
correcting, 245
messages
events
interpreting, 21
time limit on modifying, 52
Error
events counter, 23
code number
events in queue counter, 24
translating to message
text, 265 events read counter, 24
Command, 184 events sent to queue counter, 24
messages, 281 Excel
interpreting, 281 Adding tags to Point Database,
190
Negative or Positive, 293,
294 Exit, 183, 187
Page 352
Failed to unregister input archive Command, 176
message, 242 lists all commands, 187
file buffer, 95, See also buffering Hexadecimal notation, 224
maximum size, 95 Hostmask, 173, 219
File corruption, 241 Modify, 120
File handles, 233 HP-UX
File-base Utility, 269 process count, 235
compact, 269 I/O
index, 269 Redirection, 184, 185
Firewall, 219 IBM AIX
Database, 219 process count, 234
Modifying, 118 ID
Security, 117 PINetMgr, 212
troubleshooting, 228 ID Conversion File, piarchss, 43
Fixed index record, 35
Format, 180 Initialization
structure Structure type, 179 archive, 57
Fixed Archive, 36 Input
fixed archives, 33, 35 Command, 183, 220
Flag redirect, 187
Shift-enable, 57 to piconfig, batch files, 183
Flags, 201 Installation
Flatline in a trend Redirector, 257
troubleshooting, 255 Integer Format to String, 266
Force processing, 196 Interactive session
Format piconfig, 172
Delimiter, 179, 182, 223 interface nodes
Fixed, 180 setting clock, 101
Keyword, 180, 186 Interface Nodes
full, archive, 33 definition of, 94
gaps Interface Status Utility, 113
archives, 34 interfaces
General Table Interface and PI API, 96
Timeout, Firewall, Proxy, 219 APS utility, 113
Group definition of, 94
assigning users to, 126 Interface Status Utility, 113
Database, 125 setting system clock, 101
table for, 215 Interfaces
Handle downloading documentation
Batch Subsystem, 209, 214, for, vi
215, 219 internal counters
Help piartool-qs, 25
PI Server System Management Guide Page 353
Inter-process communication maxpoints, 53
TCP/IP, 252 maxsize, 54
UNIX Sockets, 251 MaxUpdateQueue, 31
IP Address, 117 Maxuprc, 235
IPAddr Maxusers, 235
trust logins, 132 message log, 18
IPHost Message Log, 2, 3, 229
trust logins, 132 message logs
Istat message subsystem offline, 20
Attributes, 202 pigetmsg, 18
Istructure, 180, 187, 190 remote login, 20
Command, 196 rpc resolver error, 22
Istype, 179 searching messages, 19
Key viewing on other servers, 20
primary, 176 viewing with pigetmsg, 18
Keyword, 180 Message Subsystem
Delimiter, changing, 180 performance counters, 336
Structure type, 179 message subsystem offline
Limit viewing messages, 20
digital state sets, 195 Messages
limits, time, 52 Client Connection, 290
List, 187 Disconnects, 292
Mode, 178 Interpreting, 281
primary key default, 181 Normal Startup, 281
LocalHost RPC Resolver, 293
Statistics, 340 Subsystem, 229
Location4, 104 Subsystem Connection, 291
Performance point, 112 Method
Login, 187 batch or interactive, piconfig,
explicit over trust, 135 172
Trust, 128 Millisecond timestamps, 207
login, remote minimum archive size, 52
pigetmsg, 20 Mode, 187
Manager. See PI Server System Edit, 178
Manager Piarc Table, 203
Mapped points, 258 piconfig, 176, 178
Max_nprocs, 235 Specifications, persistence,
Maxerr, 187 223
Maximum t option, 178
data segment, 233 Modify, 187
file handles/descriptors, 233 Command, 189
maximum archive size, 52, 53 Specifications, 189
Page 354
Module Database Security, 116
Repairing, 250 Operators
moving archives, 56 Modify Point Attributes, 189
XE "conversion files, ID" to piconfig, 181
another server, 43 OSBuild, 210
Moving PI Servers, 147 OSIsoft Universal Interface. See
MsgRecv, 211 UNIINT
MsgSent, 211, 212 OSSysName, 210
Name Ostructure, 187
Connection name, 212 Command, 180
naming archives, 52 Ostype, 179, 187
Netmask OSUser
trust logins, 132 trust logins, 133
NetType, 212 OSVersion, 210
Network Out of order event
definitions, display the, 278 counter
Router, 116 archive, 28
Security, 116 out of order events
Network Manager compression, 23
performance counters, 337 out of order events counter, 23
NEWhostmask, 119 Output, 187
Newset keyword, 176 Command, 184
Newtag keyword, 176 overflow events, 25
NEWUnitName, 207 Overflow Offsets
nodes, 94 piartool -al, 47
NT overflow queues, 25
Interface installation overflow XE "primary record"
PIHOME directory, 101 record, 34
Octal notation, 224 Overlapping dates, 245
offline archive utility, 37, 40, 41 Owner
list of parameters, 41 point attribute, 123
Offline Archive Utility Parameter
ID Conversion File, 43 Passing an input file, 184
time conversion file, 44 Passing as Output, 184
Time Filtering, 43 Timing, 219
offline mode Password, 126
pimsgss, 20 blank, 127
offline, message subsystem, 20 changing, 127
OpenVMS default, 127
and PI API, 95 reset piadmin, 278
Operating System Path
Error Codes, 293, 294 piartool -al, 47
PI Server System Management Guide Page 355
PeerAddress, 212 Subsystem, 229
PeerName, 212 PI ProcessBook
Pending Number Data access, 125
pilistupd utility, 239 PI Processes, 229
Performance Counter Running independently, 232
PI Server, 340 Sign up for updates, 293
performance counters Status, 228
Archive Subsystem, 332 Stopping interactively, 4
Base Subsystem, 331 PI Proxy Database, 220
Message Subsystem, 336 PI Server
Network Manager, 337, 338 Automatic Startup, 6
PEs, 338 Backups, 63
Snapshot Subsystem, 334 data files, 235
SQL Subsystem, 336 Error Codes, 293, 294
TotalizerSubsystem, 337 Message Log, 290, 291
performance equations moving PI Systems, 147
performance counters, 338 performance counters, 340
Performance Equations Subsystem performance monitoring, 27
performance counters, 338 restore from backup, 243
performance problems Security, 116
out of order events, 23 Starting, 1, 281
Permissions Windows, 2
Attributes, changing, 123 Winpdows, 2
PEs Stopping, 1, 3
performance counters, 338 System Manager, 116
PI API Security responsibilities,
about, 96 116
Buffering, 96 Timing parameters, 219
impact on system set number, tuning, 251
201 PI Server System
on VMS, 95 Manager, 116
PI API buffering. See buffering PI session
PI Attribute Set Table, 191 performance counters, 338
PI Base Subsystem PI Session
Troubleshooting, 230 Statistics, 338, 339
PI Batch Alias Table, 208 PI Subsystem, 211
PI Batch Table, 209 Table, 211
PI Connections, 213 PI Subsystem Table, 210
PI DataLink PI System
Data access, 125 merging two systems, 153
PI Message PI tables
Log, 229 how to select, 172
Page 356
PI TagConfigurator, 171 number of overflow queues, 25
PI Thread Table, 215 out of order events counter, 23
PI_GEN, 173, 219 point counter, 23
Piadmin, 117, 124, 125 remaining capacity, 25
reset password, 278 total overflow events, 25
Piarc, 173 piartool -ss, 22
Edit mode attribute, 204 PIATRSET, 173
Piarc Table, 202 Pibaalias, 173, 208
piarchss, 37, 40 Pibasess, 230
offline archive utility, 41 Pibatch, 209
Piarchss, 231 PIBatch
piarchss -id, 43 considerations when merging
piarchss offline utility systems, 154
list of parameters, 41 Pibaunit, 173, 207
Piarcmem.dat, 236 Piconfig, 127, 203
piarcreate, 37, 52 Abbreviations, 220
Piarcreate, 52 Commands, 176, 186, 223
piarstat.dat, 56 Configuration.Persistence, 223
Piarstat.dat, 236 Echo command, 184
piartool, 37 Modes, 178
-aw, 49 Overview, 171
creating archives with, 52 Remote sessions, 185
deleting archives, 56 Starting, 172
moving archives, 56 Stopping, 172
-qs, 25 using quotes, 221
registering archives, 56 values sent as strings, 222
unregistering archives, 56 pidemo user account, 125
Piartool, 52 pidiag, 263
-al, 46 about, 21
results from, 47 -ad, 270
-as, 27 -ahd, 271
piartool -ac, 52 -ar, 271
piartool -acd, 52 -ara, 270
piartool -ar, 56 -e errorcode, 265
piartool -au, 56 -fb, 269
piartool -ooo, 23 -fb utility, 236
piartool -ss -fbc <path>, 269
events counter, 23 -fbf <path>, 270
events in queue counter, 24 -h or -?, 265
events read counter, 24 -host, 278
events sent to queue counter, interpreting error messages, 21
24 operating system errors, 21
PI Server System Management Guide Page 357
Recovery utility, 247 PINet/OpenVMS, 115
-rgs, 279 Manager Subsystem, 229
-t time <U>, 265 Pinetmgr, 229
-tz, 266 Messages from, 290, 291
-udf <path>, 278 Pinetmgrstats, 212
-v, 265 PINetMgrStats, 173
Pidiag piperfmon.dif, 340
-crash, 278 Pipes
Interpreting Error Messages, WIN32, 212
293 PIPoint, 188
Utility, 293 Pipoints.dat, 237
-w msec, 278 Piptalia.dat, 237
Pidiff Piptattr.dat, 237
Keyword PIPTCLS, 173, 193, 194
mappings, 224 Piptclss.dat, 237
Pidignam.dat, 236 Piptunit.dat, 238
Pidigst.dat, 236 Pisetpass utility, 126, 127
Pids Pishutev, 5, 228, 231
Table, 195 Pisnap, 200, See also Snapshot
Pifilebase, 236 Pisnap.dif
pigetmsg list Snapshot values, 201
about, 18 Pisnap2, 201, 202, See also
default values, 19 Snapshot
parameters, 18 Pisnapss, 230
remote login, 20 PIStartupTime, 210
searching messages, 19 pistop.sh script, 4
Utility, 229 Pisubsys, 210
Pigetmsg PISubsys, 173
Utility, 281 PISubsysName, 211
pigrp, 126, 215 Pisubsysstats, 211
Pilastsnap.dat, 237 PISubsysStats, 173
Pilistupd utility, 238 PIThread, 173
Troubleshooting, 230 Pitimeout, 173, 219
pimaNNNN.dat, 237 PITimeout Table, 31
Pimapevq.dat, 237 PItrust, 218
pimsgss Piudsrdr.exe, 259
offline, viewing messages, Piupdmgr, 230
20 Messages from, 293
offline mode, 20 PIUser, 214
Pimsgss, 229 field for trust logins, 134
Pimsgtxt.dat, 237 Piusr.dat, 238
PINet Nodes, 95 Piusrctx.dat, 238
Page 358
Piusrgrp.dat, 238 piartool -al, 47
Piverify.sh script, 228 primary record, 34
PIVersion, 210 Priority
Point Trust Records, 135
access to, 124 PRODEXPR, 208
data access, 122 ProdIDsearch
Database, 189 Batch Subsystem, 209
Datagroup, 124 Producer
Dataowner, 124 pilistupd utility, 238
object for security, 122 Prompt, 187
Ownership, Changing, 123 ProtocolVersion, 212
Point class, 188 PtClass, 187
Point Attributes Ptclass command, 188
access to, 122 queue
Changing Owner, 123 number of overflow events, 25
Modifying, 189 number of overflow queues, 25
With Operators, 189 remaining capacity, 25
Point Class queue, event
Base, 188 monitoring, 25
Point Class Database, 192, 194 Quit command, 183
point counter, snapshot, 23 Quote, 187
Point Database, 57, 188 character, 223
migration from PI2, 224 Quote marks
Repairing, 250 used in piconfig, 221
table name, 188 RampSoak, 232, 240
PointID, 200 Random, 240
PointSource attribute, 103 Random Simulator, 232
Command line parameters, 102 record
PoolName, 215 archive, 34
predicting archive shifts, 47 Record, 188
primary archive, 33 attributes, 175
Primary Archive, 35, 46 Record Size
Recovering, 242 piartool -al, 47
primary archives records
creating new, 55 determining percentage used,
failing to register, 55 47
Primary index listing details, 49
Connection, 212 Records
Primary key, 172 Trust, Weighting, 135
Default, 181 Recovery tool, 247
Primary Offsets Recsep, 187
RecvErrors, 211, 212
PI Server System Management Guide Page 359
Redirection Troubleshooting, 254
Output to files, 185 Root, 3, 116
Redirector Router, 116
confirming installation, 257 rpc resolver error message, 22
dump script, 261 RPCs, 251, 292, 293
starting, 258 Rval attributeAttributes, 202
troubleshooting, 257 Sam utility, 235
registering archives, 56 Scan classes, 104
Registry Score
archive, 56 Trust Records, 135
regsvr32, 262 SearchStart
Remote Batch Subsystem, 209
piconfig sessions, 185 Security, 115
Procedure Calls, 251, 292 Attributes
remote logins Changing, 123
pigetmsg, 20 Client, 125
Remove consumer from update Default points, 125
table, 293 Firewall, 117
removing archives, 56 Network, 116
Repairs Operating System, 116
Archive Registry, 246 Physical, 115
Data file, 241 Scenario for Users and Groups,
Excessive CPU Usage by 122
Utilities, 252 Table Edits, 216
Module Database, 250 Tag, 122
Point Database, 250 Troubleshooting, 230
Snapshot, 247 Trust Login, 128
System Time, 249 User Name and Password, 125
Tuning the Server, 251 Select, 188
Repeating attributes command, 176, 181
Ellipsis construct, 182 PI table, 172
Replacesp mode, 206 SendErrors, 211, 212
resolver error message, 22 server messages, 18
Resolver Messages, 293 Services
Restore Troubleshooting, 228
Archive, 244 trust login OSUser Names, 133
PI Server from backup, 243 SET, 191, 193, 194, 195
Subsystem Databases, 245 SETNO, 191, 193, 195
Reusing an Output File as an Input Shift
File
Archives, 57
piconfig, 185
shift flag
Reverse Name Lookup, 129
piartool -al, 47
Page 360
shift predicting, 47 Modify, 189
shift, archive, 33 Special Characters, Changing, 223
Shift-enable flag, 57 Specifications
Shutdown Events, 4 Compression, 122
Shutdown.dat, 4, 5, 238 Spreadsheet, 190
Sigd, 188 SQL Subsystem
Sign up for updates, 293 performance counters, 336
Significant decimal digits, 188 Start
sinusoid, 232 Messages, 281
Site-specific files, 2 PI, 1
size of file buffer, 95 UNIX, 3
size, archive records, 34 Windows, 2
Smit utility, 234 piconfig, 172
SMT Redirector, 258
about, vi Starting
snapshot PI, 2
event count, 22 Starttime, 203
events counter, 23 State
events in queue counter, 24 piartool -al, 47
events read counter, 24 STATE, 195
events sent to queue counter, State Sets
24 listing, 195
listing current information, 22 statistics
monitoring data flow, 22 performance counters, 331
number of overflow queues Status, 188
counter, 25
command, 173
out of order events counter, 23
PI processes, 228
point counter, 23
Stdout, 2
remaining queue capacity, 25
Stop
total overflow events counter,
PI, 1
25
on UNIX, 4
Snapshot, 5
on Windows, 3
list values, 201
piconfig, 172
repairing, 247
String to Integer Format, 266
Subsystem
Structure, 187, 188
Adding digital state
values, 200 Specifications, 181
recovering, 248 Type, 179
Troubleshooting, 230 STYP, 188
Snapshot Subsystem Stype, 179
performance counters, 334 Subnet, 118
Span specifying for trust login, 132,
143
PI Server System Management Guide Page 361
Subsystem how to list, 173
Attributes, 210 PI_GEN, 219
Connection Messages, 291 Piarc, 202
PI Message, 229 Pibaalias, 208
Restore from Backup, 245 Pibatch, 209
Update Manager, 230 Pibaunit, 207
subsystem health check failed, 22 Pids, 195
Sun PIFIREWALL, 219
Solaris Pigroup, 215
process count, 235 Pinetmgrstats, 212
Superuser Pipoint, 188
Privileges, 122 Pisnap, 200
Sysdef utility, 235 Pisnap2, 201
SYST, 188 Pisubsys, 210
System Pisubsysstats, 211
Clock Pitimeout, 219
resetting, 249 PItrust, 218
digital state set name, 195 PIUser, 214
set number, 201 Selecting, 172, 173
Statistics, 211 Snapshot, 200, 201
system aggregate compression Specifications,persistence, 223
ratio, 24 Tag
system clock, 23 Adding Values to the Snapshot
on interface nodes, 101 Table, 201
system error codes, 21 creating, 199
System Management Tools, vi Datagroup, 124
system message logs Dataowner, 124
pigetmsg, 18 Listing information, 178
System State Set Mask, for shutdown, 6
modifying, 197 Removing point security, 124
Table Security, 122
Attributes TagConfigurator, 171
Displaying, 174 TCP/IP, 212
With Ellipsis, 182 Default port, 229
Batch Alias, 208 Technical Support, 345
Batch Unit, 207 Thread Table, 215
Command, 188 actions, 216
piconfig, 173 Threading, 253
Database Security, 216 Threads, 173
For accessing the PI Archive, time
202 setting on interface nodes, 101
Names, 172 Time
Page 362
Attributes, 207 shutdowns, 135
conversion file, 44 Trust Records
Filtering, 43 Weighting, Score, 135
future times in Snapshot Tuning
removing, 248 Utilities timeout value, 252
piconfig millisecond, 206 Tuning the PI System, 251
piconfig TimeFormat, 206 Type
Time Zone, 266, 268 Files, 236
utilities, 265 piartool -al, 47
time limits on modifying data, 52 UniInt
Time Transformation Processing, downloading documentation
245 for, vi
conversion file, 246 UnitName, Batch Subsystem, 207,
time zones 209
and interface nodes, 101 Universal Interface
TimeFormat, 206 downloading documentation
for, vi
TimeNum, 200
UNIX, 212
Timenum Attributes, 207
Case-sensitive, 220
Timeout Database, 219
Sockets protocol, 251
Timestamp
UNIX Process
Corrections, 44
Stopping, 232
Millisecond, 207
UNIX Process Quotas, 233
Timformat, 188
Unregister Archive
Timing Parameters, 219, 251
list unregistered files, 271
Totalizer Subsystem
unregistering archives, 56
performance counters, 337
Update Manager, 30
totalUpdateQueue, 31
MaxUpdateQueue, 31
TotalUpdateQueue, 31
Pending Update Limit, 31
Troubleshooting
Statistics, 340
Checklist, 225
TotalUpdateQueue, 31
PI Update Manager, 230
Troubleshooting, 230
Redirector, 257
Upgrade
Strategy, 225
Post Upgrade Tasks on UNIX,
Trust Database, 128, 218
147
defining a record, 130
User
fields, 131
Adding, 127
how to configure, 131
Database, 126
Trust Login, 128
Name and Password Security,
evaluating, 134 125
examples, 137 Passwords
installation, 136 changing, 127
network definitions, 278
PI Server System Management Guide Page 363
Table for, 214 piartool -al, 47
User Group. See Group pidiag, 265
Utility Visual Basic, API, 96
File-base, 269 VMS
piconfig, 126, 127, 171 and PI API, 95
pidiag, 263 Wait for passed milliseconds
pidiag -fb, 236 command
pidiag recovery, 247 pidiag, 278
pidiff, 171 Weighting
pisetpass, 126, 127 Trust Records, 135
sam, 235 Wildcards, 182
smit, 234 WIN32 named pipes, 212
sysdef, 235 Windows
time, 265 performance counters, 331
Values Stopping Processes, 232
Attributes, Modifying, 189 Write Flag
Verifying PI Processes, 228 piartool -al, 47
Version
Page 364
Auditing the PI Server
PI3 Server
Version 3.4.370
© 1998-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
Auditing the PI Server is part of the OSIsoft PI Server Documentation Set. It explains your
options for maintaining an audit trail of your process data in the PI Server. Consult the
Introduction to PI System Management or PI Server System Management Guide for more
information regarding PI Server administration tools discussed in this guide.
The PI Server Documentation Set
You can download the most recent version of the PI Server Documentation Set from the
OSIsoft Technical Support Web site (http://techsupport.osisoft.com).
The PI Server Documentation Set includes the following user guides.
Title Subject
Introduction to PI System A simple guide explaining everything you need to do to manage a
Management PI Server. This book walks you through all the basic system
management tasks using point-and-click administration tools.
PI Server Installation and A guide to installing and upgrading PI Servers.
Upgrade Guide
PI Server System An in-depth guide to PI Server system management, including the
Management Guide many command-line tools provided with the PI Server, such as
PIConfig, PIDiag, and PIArtool.
PI Server Reference Guide A comprehensive reference guide for the PI Server, including
details on databases and data flow, including exception and
compression.
Auditing the PI Server A guide to maintaining a good audit trail of your process data in the
PI Server.
PI Server Applications User A guide to the PI Server applications: Performance Equations,
Guide Totalizer, Recalculator, Batch, Alarm, and Real Time SQC. These
applications are typically licensed separately from the PI Server.
PINet and PIonPINet User A guide to PINet/OpenVMS and PIonPINet packages (PI PN)
Guide which allow parts of a PI for OpenVMS display system to run
transparently on a PINet node.
Auditing the PI Server Page iii
Preface – Using this Guide
Related Documentation
OSIsoft provides a variety of documentation to help you use and understand the PI Server,
interfaces and client tools. Each interface has its own manual, and each client tool has its own
online help and/or user manual.
PI Server System Managers should read the UniInt End User Manual, which describes the
OSIsoft Universal Interface (UniInt). Many PI interfaces are based upon UniInt, and this
guide can provide a deeper understanding of interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
the System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
Note: Auditing consumes computing resources. If the PI audit database is enabled,
a management strategy is required to ensure that the audit files do not grow too
large. The PI Server System Management Guide discusses how to monitor and
manage database file sizes and backups. Section 2.1.7, Audit Database File Archive
and Size Management, provides additional information.
Page iv
Preface – Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI CLIENT TOOLS Use the client tool, PI ProcessBook, to verify that all
PI SYSTEM ELEMENTS data has been recovered.
PI SERVER SUBSYSTEMS All incoming data is queued in the Event Queue by
the Snapshot subsystem.
Italic text FILES, DIRECTORIES, PATHS The backup script is in the \PI\adm directory.
EMPHASIS See Auditing the PI Server for Message Log
NEW TERMS information.
PLACEHOLDERS Archive files can be either fixed or dynamic. The
archive receiving current data is called the Primary
FIELDS Archive.
Bold Italic text REFERENCES to a publication See the PI Server Reference Guide …
Bold text SYSTEM and APPLICATION The Archive Subsystem, PIArchss, manages data
components: archives. PIArchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, the site-specific startup script is
pisitestart.sh and on Windows it is
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
PROCEDURES and KEY On the Tools menu, select Advanced Options.
COMMANDS Press CTRL+ALT+DELETE to reboot
INTERFACE components Select Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: CODE examples use the piartool -ss command. For example:
"Consolas" COMMANDS to be typed on the
font command line (optionally with
arguments or switches)
System INPUT or OUTPUT such
as excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
Auditing the PI Server Page v
QUICK TABLE OF CONTENTS
Chapter 1. PI Server Auditing .......................................................................................................1
Chapter 2. The PI Audit Database ................................................................................................5
Chapter 3. The PI Audit Trail Message Log...............................................................................25
Auditing the PI Server Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Chapter 1. PI Server Auditing .......................................................................................................1
1.1 Overview of the PI Audit Database ..................................................................................1
1.2 Overview of PI Audit Trail Message Log .........................................................................2
1.3 The PI AuditViewer ............................................................................................................3
Chapter 2. The PI Audit Database ................................................................................................5
2.1 Audit Database Design and Administration ...................................................................5
2.1.1 Audit Database Design...........................................................................................5
2.1.2 Audit Database Recording Mechanism ..................................................................6
2.1.3 Database Integrity ..................................................................................................6
2.1.4 Enable Subsystem Auditing and Set Online/Offline Mode .....................................6
2.1.5 Startup of Audit-enabled Subsystems ....................................................................7
2.1.6 Audit Database File Locking and Unlocking...........................................................7
2.1.7 Audit Database File Archive and Size Management..............................................7
2.1.8 Audit Offline Mode Timeout ....................................................................................8
2.2 PI Snapshot Subsystem Considerations ........................................................................9
2.2.1 Data Buffering and the Audit Database..................................................................9
2.2.2 Audit Database File Open Failure ..........................................................................9
2.2.3 PI Snapshot Audit Database Exceptions..............................................................10
2.3 Audit Database Procedures............................................................................................10
2.3.1 Enable Auditing ....................................................................................................10
2.3.2 Set Subsystem Auditing Mode .............................................................................12
2.3.3 Archive and Create New Audit Database Files ....................................................12
2.3.4 Export Audit Records to XML ...............................................................................13
2.4 Audit Database File Contents.........................................................................................15
2.4.1 Audit Record Definition.........................................................................................16
2.4.2 Change Record Definition ....................................................................................16
2.5 Example Audit Records ..................................................................................................16
2.5.1 PI Points ...............................................................................................................16
Auditing the PI Server Page ix
Table of Contents
2.5.2 PI Digital State Sets..............................................................................................17
2.5.3 PI Point Attribute Sets ..........................................................................................18
2.5.4 PI Point Classes ...................................................................................................18
2.5.5 PIUsers .................................................................................................................19
2.5.6 PIGroups...............................................................................................................19
2.5.7 PITrusts ................................................................................................................19
2.5.8 PI Snapshot ..........................................................................................................20
2.5.9 PI Archive .............................................................................................................20
2.5.10 PI DBSecurity .......................................................................................................22
2.5.11 MDB (Module Database) and BDB (Batch Database) .........................................23
Chapter 3. The PI Audit Trail Message Log...............................................................................25
3.1 How the Audit Trail Message Log Works......................................................................25
3.2 Manage the Message Log ...............................................................................................25
3.3 Log Archive and Snapshot Edits or Deletes.................................................................25
3.3.1 Structure of Audit Trail Messages for Archive and Snapshot Changes ...............25
3.3.2 Enable Logging for Archive and Snapshot Changes ...........................................26
3.4 Log PI Batch Database/SDK Object Changes ..............................................................27
3.4.1 Structure of Audit Trail Messages for PI Batch Database/SDK Object Changes 27
3.4.2 Enable Logging for PI Batch Database/SDK Object Changes.............................28
Technical Support and Resources.................................................................................................29
Index of Topics.................................................................................................................................31
Page x
Chapter 1. PI SERVER AUDITING
PI Server Auditing Resources
The PI Server includes two independent mechanisms that record extensive audit records.
These mechanisms record the data that are added, edited, or removed from specific PI Server
database files, as well as other events or changes to configuration that occur in the PI Server.
The PI Audit Database provides enhanced auditing capabilities that meets stringent
auditing requirements. It logs changes to 14 key PI system database tables, including
changes made to Archive Data, to PI System configuration, and to system security
settings. The PI Audit Database stores audit records in three separate, protected Audit
Database files. Audit Database security measures ensure the integrity of audit
records, and therefore the validity of the audit trail.
The PI Audit Trail Message Log provides basic auditing capabilities that meet
many less-regulated auditing needs. The PI Audit Trail Message Log logs changes to
incoming data only. Audit messages are added to the PI System Message Log, which
is automatically managed by the PI System.
You may use either or both audit methods, depending on your requirements.
Note: Some changes made to Audit Database settings, such as changes to the
Timeout Table, are captured in the Audit Trail Message Log, not in the Audit
Database itself.
The PI System AuditViewer Utility
In addition to the methods described in this guide that you can use to store, export, and
review audit records, OSIsoft provides the PI System AuditViewer utility, which enables you
to view and manage Audit Database records. The AuditViewer is available as a separate
package with its own documentation. It is introduced in section 1.3, The PI AuditViewer.
1.1 Overview of the PI Audit Database
The PI Audit Database records changes to the data stored in key databases in the PI system.
In addition to recording direct changes to PI Server databases, the Audit Database keeps
detailed records of changes made to the configuration of the PI System that affect the way in
Auditing the PI Server Page 1
Chapter 1 – PI Server Auditing
which applicable data is recorded, accessed or changed. Audit Database records include PI
Server system changes that affect:
Data collection
Data access
Metadata (Module data and Batch data)
Editing of existing data in the Snapshot or Data Archive
Schema (Point Class and Attribute Sets)
For example, the exception and compression specifications for a point affect what is written
to the Data Archive. Similarly, the digital set definition for a point affects the interpretation
of events written to and read from the Archive. To effect a stringent audit of the data that the
PI Server stores in the Data Archive requires an auditable trail of changes made to both the
Point Database and the Digital State Set Database.
Security settings affect the security and integrity of data and data collection. To track security
changes that may affect data integrity, changes to the User, Group, and Trust Databases
(which determine who can access the PI System) are also recorded to the Audit Database.
In This Guide
Audit Database Design and Administration is explained on page 5
PI Snapshot Subsystem Considerations are discussed on page 9.
Audit Database Procedures are provided on page 10.
Procedures to Enable Auditing on PI Server databases is described on page 10.
Procedures to Set Subsystem Auditing Mode are provided on page 12 .
Procedures to Archive and Create New Audit Database Files are provided on page
12.
Procedures to Export Audit Records to XML are provided on page 13.
Audit Database File Contents are explained on page 15.
Example Audit Records are provided on page 16.
1.2 Overview of PI Audit Trail Message Log
When the PI Audit Trail Message Log is enabled, specified PI system data updates and
activities are logged to the Audit Trail Message Log. The Audit Trail Message Log records
changes made to the Snapshot and Data Archive, including the Batch Database.
Instructions for managing and monitoring the PI System Message Log is provided in
Monitoring PI System Health in the PI Server System Management Guide.
Page 2
1.3 – The PI AuditViewer
In This Guide
The PI Audit Trail Message Log is described on page 25.
Procedures to Enable Logging of Archive and Snapshot Changes are on page 26.
Procedures to Enable Logging of PI Batch Database / SDK Object Changes are on
page 28.
1.3 The PI AuditViewer
PI AuditViewer is a Microsoft Windows-based application that controls aspects of the
auditing function. It allows you to view records from the Audit Database, and manages Audit
Database files. PI AuditViewer (Figure 1.1 - PI AuditViewer ) allows you to select records
from the Audit Database, examine them, print them, or export them to a new file.
Figure 1.1 - PI AuditViewer Application
Important: PI AuditViewer satisfies the U.S.C. 21 CFR, Part 11 FDA regulation
requirements for generating accurate and complete copies of Audit Records in both
human-readable and electronic form suitable for inspection, review, and copy.
PI AuditViewer allows you to search for and display audit records in the PI Audit Database.
It allows you to sort, filter, and organize audit records in a grid format. It is an essential tool
for analyzing and validating a PI system for compliance with a company's implementation of
cGMP. It facilitates the generation of selected reports in Windows file formats, to comply
with FDA audit requests.
Because AuditViewer can change auditing status and control the execution of PI system
processes, certain restrictions are in place:
Auditing the PI Server Page 3
Chapter 1 – PI Server Auditing
AuditViewer must run on the same computer as the PI Server
The user must be a member of the Windows Administrator User Group
The user must log on to the PI system as the PIAdmin user
The PI AuditViewer application is available for download from the OSI Web site.
Documentation is provided in online Help format.
Note: Earlier versions of PI AuditViewer are not compatible with the current release
of PI (3.4.370).
Page 4
Chapter 2. THE PI AUDIT DATABASE
2.1 Audit Database Design and Administration
This section describes how Audit Database records are collected, protected, and managed.
You must understand basic mechanisms to be able to configure the Audit Database for
desired behavior and for essential housekeeping tasks.
System administration tasks include:
Enable auditing of PI subsystem databases.
Set auditing offline to enable viewing or export of database records, or for the
management of Audit Database files.
Archive Audit Database files and create new files, to maintain manageable file sizes
and validated audit trails.
Understand the mechanism for Audit Database file creation failure, and the creation
of alternate Audit Database files.
2.1.1 Audit Database Design
The Audit Database is comprised of records of changes made to fourteen PI Server database
tables. The database tables belong to three subsystems: PI Archive, PI Base, and PI
Snapshot.
The Audit Database is stored in three files (one for each subsystem) with a proprietary binary
format, as listed in the following table. Details about the format of records stored in the Audit
Database is provided in section 2.4, Audit Database File Contents.
Table 2.1. Audit Database Files; PI Subsystem and Database Tables
Audit DB Filename Subsystem Database Table
piarchssAudit.dat PIArchss PI Archive
pisnapssAudit.dat PISnapss PI Snapshot
pibasessAudit.dat PIBasess PI Point
PI Digital State Set
PI User
PI Group
Auditing the PI Server Page 5
Chapter 2 – The PI Audit Database
Audit DB Filename Subsystem Database Table
PI Trust
PI Modules
PI Headings
PI Batches
PI Unit Batches
PI Transfer Records
PI DB Security
Point Class
Attribute Set
2.1.2 Audit Database Recording Mechanism
When activity that is monitored occurs, the PI Archive, PI Base, or PI Snapshot subsystem
add records to the corresponding file of the Audit Database.
The PI Base subsystem creates and writes an audit record in the Audit Database for any
change that occurs in the tables that PIBasess maintains. The PI Snapshot and PI Archive
subsystems create and write an audit record in the Audit Database for all edit and delete
actions performed on the data in their respective databases.
Note: Each of the three audited subsystems can add audit records to the Audit
Database. However, audited subsystems cannot modify or delete existing audit
records.
2.1.3 Database Integrity
The Audit Database cannot be changed except for when an audited subsystem is running and
writes a change to the Audit Database. There are no PI Server tools or interfaces designed to
change audit records.
Each audit record is assigned a unique identifier and contains all pertinent change
information. It is not possible to modify an audit record without creating an additional audit
record. In addition, all changes to the Audit Database and to data collection configuration
specifications are recorded in new audit records.
To ensure the integrity of the Audit Database, the PI Base subsystem blocks any edit
activities that are attempted to Audit Database files when the Audit Database is offline.
2.1.4 Enable Subsystem Auditing and Set Online/Offline Mode
You must enable auditing for each subsystem database (and tables) that can be audited. You
can enable auditing on an individual basis, to allow auditing only for the subsystem(s) for
which you want to collect audit records.
Page 6
2.1 – Audit Database Design and Administration
For each audit-enabled subsystem, you must set auditing “online” to enable the collection of
audit records, and “offline” to enable system administration on the Audit Database or audit
records. See section 2.3.1, Enable Auditing for procedures.
2.1.5 Startup of Audit-enabled Subsystems
When an audit-enabled subsystem starts, auditing automatically enters online mode and the
corresponding Audit Database file is opened and locked. If the Audit Database file does not
exist, it is created. If the Audit Database file cannot be opened or created, the subsystem will
stop.
Note: Open or creation failures and successes are reported to the PI Server
Message Log.
When a new Audit Database file is created, a record is added to the file to indicate the
creation date and time.
When an existing Audit Database file is opened, it is read entirely to determine the number of
records in the file. The current EnableAudit bit mask value and the audit record count is
written to the Message Log. For example, a successful open message is:
0 pibasess 20-Oct-05 19:40:33
>> Audit Enable Mask: -1
Audit file contains 310 Records
2.1.6 Audit Database File Locking and Unlocking
When auditing is enabled and online for a subsystem, the corresponding Audit Database
file(s) are opened and locked, and can be accessed only by the corresponding subsystem.
When auditing is offline or an audit-enabled subsystem is stopped, the PI Base subsystem
blocks any independent attempt to edit the Audit Database.
To view Audit Database records, you must either:
• Place the corresponding subsystem auditing offline, or
• Stop the subsystem.
An audit record is kept every time auditing is placed offline, or when a subsystem is stopped.
In addition, you must place auditing offline or stop a subsystem to copy or move an Audit
Database file (for system optimization and management).
2.1.7 Audit Database File Archive and Size Management
The PI Server auditing function does not include a mechanism to automatically manage
(monitor size, remove, store, and replace) Audit Database files. (Note that the Backup system
does copy Audit Database files if the Audit Database is enabled.) Audit records are simply
appended indefinitely to Audit Database files. Over time, Audit Database files can grow
large, which will cause several potential problems if left unchecked.
Auditing the PI Server Page 7
Chapter 2 – The PI Audit Database
The first concern is that large Audit Database files may compete for hard drive space
with other data files (including the event queue file, pieventq.dat.)
The second concern is that upon startup and/or entering auditing online mode, each
subsystem reads the entire corresponding Audit Database file. A large file can
considerably slow down subsystem startup – or the return to auditing online mode.
The third concern is that audit files that are very large will invariably cause greater PI
system problems.
The solution is to adhere to the following Audit Database file size recommendations.
Eventually, you must remove, safely store, and create new Audit Database files. See section
2.3.3, Archive and Create New Audit Database Files, for instructions.
Each Audit Database file should not exceed 100 MB. Files this large may be very slow to
process, or impossible for PI Audit Viewer to index. Furthermore, if any file grows larger
than 2 GB (2**31 bytes), it will cause problems for the associated subsystem.
Replacement requirements vary by site. Some interfaces and applications make periodic
changes to the Archive database. These changes can cause the PI Base subsystem audit file to
grow quite fast. For example, PI-APS modifies a property of a module to indicate the latest
scan, which results in two audit records. If PI-APS scans every 5 minutes, 576 audit records
will be generated every day.
2.1.8 Audit Offline Mode Timeout
To copy, delete, export, move, or back up an Audit Database file, you must first change
subsystem auditing to offline mode (or you must stop the audited subsystem) to unlock the
database file(s).
Audited subsystems can remain in auditing offline mode for limited periods, after which they
automatically switch to auditing online mode:
The PI Snapshot subsystem, because of critical data-loss prevention duties, switches
to auditing online mode after 5 minutes.
The PI Archive subsystem and PI Base subsystem switch to auditing online mode
after 30 minutes.
If an Audit Database file cannot be opened or created when a subsystem is switched from
offline to online mode, the subsystem automatically re-enters auditing offline mode. If the
problem persists, this cycle continues until the audit file is successfully opened. In addition,
this activity is written to the Message Log.
Note: Several PI System features are unavailable when subsystem auditing is
offline. For example, you cannot create or edit points. Consequently, to back up,
copy, delete, export, or move an Audit Database file, you should place subsystem
auditing offline, perform the required activity, and then promptly place subsystem
auditing back online.
Page 8
2.2 – PI Snapshot Subsystem Considerations
2.2 PI Snapshot Subsystem Considerations
2.2.1 Data Buffering and the Audit Database
If the PI Snapshot subsystem is not running – perhaps because it is shut down to perform
administration on the pisnapssAudit.dat Audit Database file – data from non-buffered API
and PINet nodes would be lost. However, because it plays a key role in data loss prevention,
PISnapss buffers all events until they can be successfully written to the PI Archive
subsystem.
Likewise, when Snapshot subsystem auditing is offline, PISnapss continues to accept new
audit record values in an internal buffer. These are cached until Snapshot subsystem auditing
returns to online mode and the cached records are transferred to the Audit Database.
Note: Since auditing is enabled only at startup, the audit record cache process will
work only if the subsystem is placed in audit mode at startup.
Regardless of auditing mode, the PI Snapshot subsystem always accepts new, edited, and
snapshot deletion requests. While auditing mode is offline, requests that generate an audit
record are cached for the Audit Database. When auditing returns to online mode,
pisnapssAudit.dat is opened if it exists, or is created if it does not, the cache is processed and
audit records are written to the Audit Database. This process occurs if auditing online mode is
initiated automatically (through audit offline mode timeout) or by system administrator
command.
2.2.2 Audit Database File Open Failure
If the PI Snapshot Audit Database file, pisnapssAudit.dat fails to open or cannot be created
when Snapshot subsystem auditing returns to online mode, PISnapss creates an alternate
Audit Database file named pisnapssAudit~<UTCSeconds>.dat, where <UTCSeconds> is the
current time expressed in UTC seconds. For example, pisnapssAudit~1003043789.dat.
On the next return to auditing online mode or subsystem re-start, the PI Snapshot subsystem
once again attempts to open or create pisnapssAudit.dat. If this fails again, a new file, using
the same format above, is created and used for auditing.
Note: PiasnapssAudit~<UTCSeconds>.dat files in the PI\log directory contain valid
audit records that are not included in the primary defined Audit Database file. There
is no merge function available. You should store and back up these alternate files to
maintain a complete audit trail.
To avoid the creation of alternate Audit Database files during Audit Database maintenance:
1. Invoke auditing offline mode (vs. stopping the subsystem)
2. Immediately copy or move the audit file to a different directory
3. Restore auditing online mode
Auditing the PI Server Page 9
Chapter 2 – The PI Audit Database
2.2.3 PI Snapshot Audit Database Exceptions
Normally, when interfaces send data to the Snapshot, the data is not audited. Otherwise, the
audit file would contain a duplicate of everything in the archive, but in a less accessible form.
However, some interfaces, applications, and PI-ACE calculations can send data in a way that
causes auditing to occur. This can result from:
• Batch file interface operations
• Filling in history by sending data prior to the current Snapshot
• An interface or application making certain API calls (for example, see
piar_putarcvaluex or piar_putarcvaluesx with mode=ARCREPLACEX in the
PI-API User Guide)
• An interface, application, or PI ACE calculation invoking certain SDK methods
(for example, see the object PIData methods UpdateValue or UpdateValues
with the default mergetype=dmReplaceDuplicates in the PI-SDK User Guide)
2.3 Audit Database Procedures
This section provides instructions for the following administrative procedures.
Enable Auditing – You must enable auditing for each of the three subsystems.
Auditing is not enabled by default in the PI Server installation because the Audit
Database uses disk, CPU, and memory resources.
Set Subsystem Auditing Mode – Subsystem auditing must be set offline to copy,
delete, view, export, move, or back up Audit Database files or records, as applicable.
Store and Create New Audit Database Files – From time to time, you must archive
Audit Database files and refresh the Audit Database with new files. This might be
required due to file size, or for required site auditing policies and procedures.
Export Records to XML for Viewing – You can export the Audit Database to XML
format for easy viewing and analysis with applications such as Microsoft Access,
Microsoft Excel, or a Web browser.
2.3.1 Enable Auditing
You can enable auditing on individual database tables. Auditing is controlled through the
EnableAudit parameter in the PITimeOut Table. The value is a bit mask where each bit
controls auditing to a specific database. A bit value of 1 enables auditing for the
corresponding database. Table 2.2 lists the PI Server databases, the corresponding bit, and the
controlling bit mask value in hexadecimal and decimal format.
Table 2.2. – Database Bit mask for the EnableAudit Parameter
Value to Enable
Database Table Subsystem Bit Hexadecimal Decimal
Point PI Base 0 1h 1
Digital State 1 2h 2
Page 10
2.3 – Audit Database Procedures
Value to Enable
Database Table Subsystem Bit Hexadecimal Decimal
Attribute Set (Point 2 4h 4
database schema)
Point Class (Point 4 10h 16
database schema)
User 5 20h 32
Group 6 40h 64
Trust 7 80h 128
Modules 8 100h 256
Headings and 9 200h 512
HeadingSets
Transfer Records PI Arch 10 400h 1024
Campaign 11 800h 2048
Batches 12 1000h 4096
Unit Batches 13 2000h 8192
Snapshot PI Snap 28 10000000h 268435456
Archive PI Snap and 29 20000000h 536870912
PI Arch
DB Security PI Base 30 40000000h 1073741824
All Databases 0-31 FFFFFFFFh -1
Set the EnableAudit parameter value to -1 to enable auditing on all database tables that
support auditing. Set the EnableAudit parameter to 0 or remove the parameter altogether to
disable auditing on all corresponding databases. Note that you must restart the affected
subsystems for changes to take effect.
To enable auditing for the Point Database (which has a bit mask value of 1) and Digital State
Database (which has a bit mask value of 2) set the EnableAudit parameter to 3 (= 1 + 2.)
Similarly, set the EnableAudit parameter to 131 (= 1 + 2 + 128) to enable Point, Digital
State, and Trust Database auditing.
Numeric values must be entered into the timeout table as decimal numbers. Hexadecimal
(base 16) notation is more convenient for creating or examining the bit mask value entered
into the EnableAudit parameter. It is easier to use hexadecimal notation to create the desired
bit mask and convert to decimal for entry into the timeout table. Conversely, it is easier to
read a decimal entry from the timeout table and convert to hexadecimal in order to interpret
the value as a bit mask.
Auditing the PI Server Page 11
Chapter 2 – The PI Audit Database
Example Commands to Enable Auditing on all Databases
The following commands (used in the PI\adm directory) enable auditing on all databases:
piconfig
(Ls - ) Piconfig> @table pi_gen,pitimeout
* (Ls – PI_GEN) Piconfig> @mode create,t
* (Cr – PI_GEN) Piconfig> @istr name,value
* (Cr – PI_GEN) Piconfig> EnableAudit,-1
*> EnableAudit,-1
* (Cr – PI_GEN) Piconfig>
2.3.2 Set Subsystem Auditing Mode
Subsystem auditing must be set offline to copy, delete, export, move, or back up Audit
Database files. In addition you can perform administrative activities on Audit Database files
when the corresponding subsystem is stopped.
Place Subsystem Auditing Offline
To place subsystem auditing offline, use the command:
piartool –systembackup start –subsystem <subsystem>
Note: As of version 3.4.370, the PI Server supports online backups as described in
the PI Server System Management Guide. To maintain backward compatibility, the
command piartool –systembackup is still used to control subsystem auditing.
Place Subsystem Auditing Online
To place subsystem auditing online, use the command:
piartool –systembackup end –subsystem <subsystem>
2.3.3 Archive and Create New Audit Database Files
To safely archive Audit Database files and create new empty files, follow these steps:
Replace an Audit Database File
1. Place the subsystem into auditing offline mode, as described in Place Subsystem
Auditing Offline, or stop the subsystem.
2. Copy/move the Audit Database file from the PI\log directory to a safe location. Since
storage of the file may be part of site validation, take care to ensure safe and
accountable storage.
3. Delete the file from the PI\log directory.
4. Return the subsystem to auditing online mode as described in Place Subsystem
Auditing Online below, or restart the subsystem.
When a subsystem enters auditing online mode, it creates a new data file. If file creation fails,
the piartool –backup command will return an error, and the subsystem will remain in
auditing offline mode.
Page 12
2.3 – Audit Database Procedures
Replace Audit Database Files for Each Subsystem
The following commands for each subsystem can be run from the PI\adm directory:
PI Archive
piartool –systembackup start –subsystem piarchss
copy ..\log\piarchssaudit.dat ..\pi\temp
del ..\log\piarchssaudit.dat
piartool –systembackup end –subsystem piarchss
PI Base
piartool –systembackup start –subsystem pibasess
copy ..\log\pibasessAudit.dat ..\temp
del ..\log\pibasessAudit.dat
piartool –systembackup end –subsystem pibasess
PI Snapshot
piartool –systembackup start –subsystem pisnapss
copy ..\log\pisnapssAudit.dat ..\temp
del ..\log\pisnapssAudit.dat
piartool –systembackup end –subsystem pisnapss
2.3.4 Export Audit Records to XML
You can use PIDiag to export Audit Database records to XML format text. The exported
XML format text allows you to easily view and analyze records with applications such as
Microsoft Access, Microsoft Excel, or a Web browser.
The pidiag –xa export command allows export filtering on Time Range, Unique Audit
Record ID, and Audit Database Mask.
Export Procedure
Subsystem auditing must be offline or the subsystem must be stopped to export records
directly from the Audit Database files.
Note: Once subsystem auditing is offline, several subsystem operations are blocked.
Therefore, it is best to copy the file promptly to a different directory for access, and to
re-start the affected subsystem or place auditing online, as soon as possible.
To export audit records to XML:
1. Place the subsystem into auditing offline mode, as described in Place Subsystem
Auditing Offline. Alternatively, stop the subsystem.
2. Copy or move the Audit File from the PI\log directory to another directory.
3. Place the subsystem into auditing online mode, as described in Place Subsystem
Auditing Online, or re-start the subsystem.
4. Export the Audit Database file.
Auditing the PI Server Page 13
Chapter 2 – The PI Audit Database
The following is the minimum syntax, which exports all records in the specified file:
pidiag –xa "audit file path"
For example:
pidiag –xa ..\temp\pibasessAudit.dat
Optional Arguments
Optionally, use the following arguments to control output.
Time Range
You can specify the start time and end time to constrain output to audit records during a time
range. Use the –st and –et arguments to specify the range of time, in PI Time Format. (For a
discussion of PI Time Format, see Appendix A, PI Time Format in the PI Server Reference
Guide.)
The first audit record on or before the start time through the last record on or after the end
time is displayed. For example:
Pidiag –xa ..\temp\pibasessAudit.dat –st "21-Feb-99 13:00:00" –et "*"
This displays the first audit record on or before 1:00 PM, February 21, 1999, through the
current time.
Note: Space ( ) characters and asterisk (*) characters in command line arguments
confuse command line interpretation. Avoid confusion by enclosing the time
arguments in double quote " " characters as shown in the above example.
Unique Audit Record ID
You can specify an audit record to export by specifying an audit record ID. Start time and end
time options are ignored when you use this option. For example:
Pidiag –xa ..\temp\pibasessAudit.dat –uid "1A027C7F-3B82-4992-8BBF-B20C2EA66FD1"
Audit Database Mask
You can specify one or more Audit Databases to export to XML with the pidiag –xa
dbmask <mask> option. The database mask values are listed in Table 2.2. The mask supplied
to PIDiag is a decimal integer sum of the values corresponding to the databases to export. For
example the mask for the User database is 32, and the mask for the Group database is 64.
You can export Audit records for these two databases by specifying a –dbmask value of 96:
Pidiag –xa ..\temp\pibasessAudit.dat –dbmask 96
Schema
The exported XML includes a reference to URLs for XSD (XML Schema Definition) files.
The XSD files are a formal declaration of the schema. The schema describes and constrains
the content of the Audit Database output.
Page 14
2.4 – Audit Database File Contents
OSIsoft specifies the URL of a default PI Audit Database schema that is W3C-compliant. The
default OSIsoft schema reference included in the exported XML is:
<PIAudit xmlns="xml.osisoft.com-schemas-piaudit"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="xml.osisoft.com-schemas-piaudit
http://xml.osisoft.com/Schemas/PIAudit">
In certain cases it may be advantageous to specify a different reference for a schema. For
example, an application running on a computer behind a firewall may not have access to XSD
files on the Internet.
The schema may be specified on the command line by the –xh export header option. The
schema specified replaces everything inside the PIAudit tag in the default PIAudit schema
reference. Specifying this argument has no other effect.
For example, use the following command to refer to the schema located at
http://xml.yourcompany.com/Schemas/PIAudit:
Pidiag –xa ..\temp\pibasessAudit.dat –xh "xmlns=\"xml.osisoft.com-
schemas-piaudit\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-
instance\" xsi:schemaLocation=\"xml.osisoft.com-schemas-piaudit
http://xml.somecompany.com/Schemas/PIAudit\""
Note: Double quote (") characters embedded in command line parameters must be
escaped with a backslash (/) character.
A useful case is when you wish to bypass a corporate firewall by placing the XML XSD file
in the same directory as the XML file. You can obtain a copy of the default PIAudit.xsd file at
http://xml.osisoft.com/Schemas/PIAudit. You should save the displayed page as a local file
named PIAudit.xsd, and then move the file into the same directory where exported XML files
are stored.
The following command will export the XML with a reference to the PIAudit schema
PIAudit.xsd in the same directory as the exported XML:
Pidiag –xa ..\temp\pibasessAudit.dat –xh "xmlns=\"xml.osisoft.com-
schemas-piaudit\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-
instance\" xsi:schemaLocation=\"xml.osisoft.com-schemas-piaudit
PIAudit.xsd\""
Even though this still refers to the XML namespace definitions at
http://www.w3.org/2001/XMLSchema-instance, most readers such as Microsoft Internet
Explorer or Microsoft Excel use cached or built-in definitions so they will not need to
connect to the Internet.
2.4 Audit Database File Contents
Each Audit Database file is comprised of a header followed by the audit records. The header
states file path and name used during creation, the creation date, and EnableAudit mask
value. An audit record is created for each of the three action types: Add, Edit, and Remove.
Auditing the PI Server Page 15
Chapter 2 – The PI Audit Database
On Add or Remove, the record contains the entire object definition. On Edit, just the changes
are shown.
Each database that supports auditing utilizes a general audit record format. The following are
table views of the generalized audit record.
2.4.1 Audit Record Definition
Field Description
PIUser User who made change (Exception: In audit records from the PI Archive
subsystem, ID=0. See examples on page 21.)
PITime Time and date of change
Database Affected database
Action Change action: Add, Remove, Edit
AuditRecordID Unique ID assigned to audit record
Name Affected Record Name
ID Affected Record ID
Changes Table of specific changes. On Add and Remove, the change indicates each
attribute setting. On Edit, the change shows the before and after value of
changed attributes
2.4.2 Change Record Definition
Field Description
Property Property that was edited
Before Value prior to edit
After Value after edit
On Adds, the current property setting is shown in the After field. The Before field is empty.
On Removes, each property is shown in the Before field. The After field is empty.
2.5 Example Audit Records
The following sections show example audit records for each of the supported databases.
2.5.1 PI Points
The table below shows the audit record that results from a PI user called PIAdmin modifying
the compression specifications of the point with an id=9.
Page 16
2.5 – Example Audit Records
Date AuditRecordID Database Record Name User Action
13:00:00 36D1787A-5D06- PIPoints 9 Ba:temp.1 PIAdmin Edit
11-Oct-01 4cd5-90D8-
FF4BE3EAD9B6
Changes
Property Before After
Compmin 10 0
Compdev 2.0 1.25
Compmax 5000 6000
2.5.2 PI Digital State Sets
Adding a third state to a digital state set looks like this:
Date AuditRecordID Database Record Name User Action
13:01:00 49ae70f7-79e6- StateSets 23 Phases PIAdmin Edit
11-Oct-01 4f9e-b4d4-
5aa7715ae333
Changes
Property Before After
DigitalState Code null 3
DigitalSet Name null Cool
Renaming the third state changes the record, as follows:
Date AuditRecordID Database Record Name User Action
13:02:00 fb36d2f2-5ad4- StateSets 23 Phases PIAdmin Edit
11-Oct-01 47f3-810a-
f8ca16bff338
Changes
Property Before After
DigitalState Code 3 3
DigitalSet Name Cool Freeze
Auditing the PI Server Page 17
Chapter 2 – The PI Audit Database
2.5.3 PI Point Attribute Sets
The table below shows an audit record for renaming the set Atrset1.
Date AuditRecordID Database Record Name User Action
13:03:00 0dca1316- PIPointAttributeSets 11 Atrset1 PIAdmin Edit
11-Oct- b297-4e46-
05 83a9-
7fd79f80b692
Changes
Property Before After
Name Atrset1 Atrset1_newName
Attribute set edits and point class edits involve four steps:
1. The original set is renamed to a temporary name.
2. The new set with desired attributes is added.
3. Implicit point class and point edits are performed.
4. If the first three steps are successful, the original set with temporary name is removed
from the database.
Each of these steps is audited. For additional information, see the PI Server Reference
Guide.
2.5.4 PI Point Classes
The table below shows an audit record for deleting the class MyPtClass.
Date AuditRecordID Database Record Name User Action
13:04:00 64098c84- PIPointClasses 8 MyPtClass PIAdmin Remove
11-Oct- a9e8-4833-
05 982f-
24531ba19d10
Changes
Property Before After
Name MyPtClass
Attribute1 Attribute1value
AttributeN AttributeNvalue
Page 18
2.5 – Example Audit Records
2.5.5 PIUsers
The table below shows an audit record for the description change for user Pidemo.
Date AuditRecordID Database Record Name User Action
13:03:00 4c9b4295- PIUsers 2 Pidemo PIAdmin Edit
11-Oct-01 0c49-4058-
9f17-
2ac3125ed4da
Changes
Property Before After
Description Demo user Demonstration User
2.5.6 PIGroups
The table below shows an audit record for the removal of group Tests.
Date AuditRecordID Database Record Name User Action
13:04:00 d25dfa82-7b4e- PIGroups 5 Tests PIAdmin Remove
11-Oct-01 4a90-b497-
e5071a1335ef
Changes
Property Before After
Description Test group Null
2.5.7 PITrusts
The table below shows an audit record for the creation of a PITrust:
Date AuditRecordID Database Record Name User Action
13:05:00 e65bf817-14e1- PITrusts 6 Trust1 PIAdmin Add
11-Oct-01 480e-a89e-
0215cc8eb9d3
Changes
Property Before After
AppName Null Test
Domain Null OSI
IPAddr Null 113.13.14.0
Auditing the PI Server Page 19
Chapter 2 – The PI Audit Database
Changes
IPHost Null Null
Netmask Null 255.255.255.0
OSUser Null Beta
Piuser Null piadmin
2.5.8 PI Snapshot
Snapshot and Archive audit records are slightly different than the other databases. First, for
efficiency, only the Point ID for the affected point is shown. The Tag Name is not shown
because including it would hinder performance by requiring a query to the PI Base subsystem
to translate the Point ID to Tag Name. Second, the Event Timestamp as well as the Point ID
are included because they are needed to describe the record being modified.
The table below shows an audit record for Point ID 1852, showing the snapshot value being
changed from 99.99 to 14:
Date AuditRecordID Database Record Timestamp User Action
13:06:00 d25dfa82-7b4e- PISnapshot 1852 12:05:01 PIAdmin Edit
11-Oct-01 4a90-b497- 11-Oct-01
e5071a1335ef
Changes
Property Before After
Value 99.99 14
Flags Null S
Notice that “Flags” has changed from empty to “S”. This is the substituted flag that PI Server
sets when an event is edited.
2.5.9 PI Archive
Archive modification attempts are posted via the Snapshot subsystem. The Snapshot
subsystem performs some validation. On successful validation, it creates an audit record
indicating it is a removal attempt or an edit attempt.
The attempt is then forwarded to the Archive subsystem for completion. If the modification is
successful, the Archive subsystem creates a corresponding audit record.
Removal
For Archive event removal, passing the value is optional. If it is passed, it is displayed in the
Snapshot audit record.
Page 20
2.5 – Example Audit Records
The user is identified through the Snapshot audit record but is shown as 0 in the Archive audit
record.
The following are the audit records generated by PISnapss and PIArchivess when an event
is deleted from the Archive:
Removal – PISnapss
Date AuditRecordID Database Record Timestamp User Action
13:10:00 e7fd45f0-6337- PIArchive 1852 03:05:01 PIAdmin Remove
11-Oct-01 4c4e-bcd1- 11-Oct-01 Attempt
c90d0ac72d33
Changes
Property Before After
Value Null or value (3) Null
Removal – PIArchivess
Date AuditRecordID Database Record Timestamp User Action
13:10:00 6deb33eb-958d- PIArchive 1852 03:05:01 0 Remove
11-Oct-01 4a43-977c- 11-Oct-01
98e8e4b35a1e
Changes
Property Before After
Value 3 Null
Edit
For an Edit call, the Before value is not displayed in the PISnapss audit record. The
corresponding archive record does pass and displays the old value. The user name is
displayed only in the Snapshot record. User ID is shown as 0 in the Archive audit record.
The following are the audit records generated by PISnapss and PIArchivess when an event
is edited in the Archive:
Edit – PISnapss
Date AuditRecordID Database Record Timestamp User Action
13:10:00 e7fd45f0-6337- PIArchive 1852 03:05:01 PIAdmin Edit
11-Oct-01 4c4e-bcd1- 11-Oct-01 Attempt
c90d0ac72d33
Auditing the PI Server Page 21
Chapter 2 – The PI Audit Database
Changes
Property Before After
Value Null 3.14159
Edit – PIArchivess
Date AuditRecordID Database Record Timestamp User Action
13:10:00 6deb33eb-958d- PIArchive 1852 03:05:01 0 Edit
11-Oct-01 4a43-977c- 11-Oct-01
98e8e4b35a1e
Changes
Property Before After
Value 3 3.14159
2.5.10 PI DBSecurity
The table below shows an audit record for the edit of the DBSecurity entry for the PIPoint
table corresponding to group owner change and access change:
Date AuditRecordID Database ID Name User Action
2005-12- 11cefbc1-ecef- PISecurityDB 0 PIPOINT PIAdmin Edit
14 45cf-80b4-
12:10:31 bce262451b2a
Changes
Property Before After
Access o:rw g:r w:r o:rw g:rw w:r
Group Piadmin MyGroup
The table below shows an audit record for the creation of a DBSecurity entry for the
PIUpdmgr subsystem:
Date AuditRecordID Database ID Name User Action
2005-12- 8fe5e042-79bb- PISecurityDB 0 piupdmgr PIAdmin Add
14 40c4-8d72-
15:14:12 804af4900720
Page 22
2.5 – Example Audit Records
Changes
Property Before After
Access Null o:rw g:rw w:r
Group Null MyGroup
Owner Null piadmin
Note that new entries in the DBSecurity table can only be created by PIConfig. Once entered,
any DBSecurity table entry can be edited by the SMT, subject to security access limitations.
2.5.11 MDB (Module Database) and BDB (Batch Database)
The Module Database and Batch Database objects pose a more difficult auditing issue. For
the most part, audit records are similar to the examples for the other databases. Rather than
attempting to display these audit records here, use the PI AuditViewer or PIDiag export
XML function to view the record structure.
Modules
Modules are actually an array of module values. Modules support change over time. Each
module value represents the module that was in effect for a given time period. Therefore, a
module audit record is actually a module value change record.
A module value is uniquely identified by the module unique ID and the module effective
date. This is different from most audit records that just need the record ID for unique
identification. For example, the Point Database only needs the Point ID to identify the record.
The following is an example of a module record identification. It consists of the unique ID,
effective date, and name:
UniqueID=541061d0-748b-4dfb-99c5-c37b12a44fda, 31-Dec-69 16:00:01"
Name="Flatten"
Module Hierarchy
Modules are hierarchical. A module may have parent modules and child modules. Although,
inserting a module into a parent module is effectively an edit of both parent and child module,
the Audit database only shows this modification as a change to the parent.
Child modules are inserted into a specific value of the parent. This is an explicit edit of a
module value. The parent references of a child are not assigned to specific value. All module
values that represent this child implicitly acquire the link to the parent. Since it is implied a
child module was edited and to avoid clutter and confusion in the Audit database, only the
change to the parent is shown. The inserting of a child into a module is shown as a change to
the module’s Children attribute.
The following represents the change to that attribute when adding a child. Notice the after
value has the additional unique ID of the child that was inserted.
PIModuleAttribute="Children"
Before=f127f0e5-1237-48c7-beae-42bcc5a8d99c
Auditing the PI Server Page 23
Chapter 2 – The PI Audit Database
After=f127f0e5-1237-48c7-beae-42bcc5a8d99c, 0c260103-8909-4007-9d14-
60f169feb3b4
PI Properties
PI Properties are hierarchical. Properties can have properties, which can have properties, etc.
Since properties do not have unique identifiers, a rename is indistinguishable from a deletion
followed by an addition.
Adding a PI Property is shown as an edit to the module by showing the parent property the
property was added to. All modules have an implicit root property called \\PIProperties.
The following are details of adding a root property with a value of 106.
PIProperty Name="Prop-106" ParentUNC_Name="\\PIProperties"
Value=106
Here are details of adding a sub-property to the above property.
PIProperty Name="Sub-Prop" ParentUNC_Name="\\PIProperties\Prop-106"
Value=99
The above examples focus only on the attribute that changed. The audit record contains
information that complete identifies the modified module. Also, renaming a property is
shown as a deletion followed by an addition in a single audit record.
PI Batches
PI Batch subsystem audit records are much like Module audit records. PIProperties are
handled identically as Module properties. Inserting a PIUnitBatch is similar to inserting a
child module: the PIUnitBatches property shows the list of Unique IDs that represent the
PIUnitBatches. The reference to the PIUnitBatch gains to the PIBatch is also shown as an
edit to the PIUnitBatch.
PI Unit Batches
PIUnitBatches only have one unique issue, which is showing changes to the PISubbatches
collection. This is handled similarly to PIProperties. Since sub-batches are uniquely
identified, renames can be represented as a rename.
Audit Records Suppressed when End Time is Not Set
PIBatches, PIUnitBatches, and PITransferRecords are often created and modified by
automated processes such as Batch Event File Monitor (EVTintf) and the PI Batch
Generator (PIBaGen). Creating an audit record for each modification would quickly
overwhelm the Audit Database. To avoid this issue, audit records are only generated for
batches if the End Time is set. The one exception is deletions of batches. When auditing is
enabled, all deletions create an audit record.
Page 24
Chapter 3. THE PI AUDIT TRAIL MESSAGE LOG
3.1 How the Audit Trail Message Log Works
You can configure the PI Server to create an audit trail on certain edits to the Data Archive or
to the PI Batch Database/SDK objects.
Audit Trail messages do not conflict with the Audit Database described in the previous
chapter. You may use either technique, or both.
3.2 Manage the Message Log
Audit trail messages are logged to the PI Message Log database. These messages are
accessible through PI SMT, PI SDK, or the pigetmsg command. Consult the PI Server
System Management Guide for more information on file sizes and file management of the
Message Log.
3.3 Log Archive and Snapshot Edits or Deletes
When this feature is enabled, all deletions or edits to Data Archive events are logged.
Note: Blob points do not support this feature.
Logging of archive value edits is a two part process involving both the Snapshot subsystem
and the Archive subsystem. The Snapshot subsystem is aware of the name of the PI user
requesting the change and, if the change is an edit, the new value. It does not know the old
value, since this value is known only by the Archive subsystem. The Archive subsystem, on
the other hand, does not know the PI user, but does know the original value being replaced.
To generate a complete record of the change, both subsystems write a message to the
Message Log. The message source name is Archive Edit for both, so that the messages can be
conveniently filtered.
3.3.1 Structure of Audit Trail Messages for Archive and Snapshot Changes
Archive Audit Trail messages always contain the following information:
Field Description
Message source The message source is Archive Edit.
Auditing the PI Server Page 25
Chapter 3 – The PI Audit Trail Message Log
Field Description
Edit date Edit date
Edit type Delete or Replace
Point ID Point ID
User Only in message from Pisnapss
Event time Edit time
New value Only in message from Pisnapss
Old value Only in message from PI Archive.
The following are some example Audit Trail messages:
For an edit, the two messages generated are:
0 Archive Edit 20-Feb-02 14:52:30
>> Replace request> Point ID: 951, User: piadmin
Event time: 20-Feb-02 14:44:09, New value: 2.1
Old value in following message
0 Archive Edit 20-Feb-02 14:52:31
>> Replace completed> Point ID: 951
Event time: 20-Feb-02 14:44:09, Old value: 31.123
For a value deletion, the two messages generated are:
0 Archive Edit 20-Feb-02 14:56:34
>> Delete request> Point ID: 951, User: piadmin
Event time: 20-Feb-02 14:44:09
Old value in following message
0 Archive Edit 20-Feb-02 14:56:34
>> Delete completed> Point ID: 951
Event time: 20-Feb-02 14:44:09, Old value: 2.1
3.3.2 Enable Logging for Archive and Snapshot Changes
Enable logging by creating an entry in the PITimeout Table named ArchiveEditLogging. Set
the value to 1 to enable and 0 to disable. The PI Archive subsystem must be restarted for the
changes to take effect.
The following PIConfig commands enable the Archive Edit Audit Trail. The session must be
run on the PI Server:
d:\pi\adm>piconfig
* (Ls© - ) Piconfig> @table pi_gen,pitimeout
* (Ls© - PI_GEN) Piconfig> @mode create,t
* (Cr – PI_GEN) Piconfig> @Istr name,value
* (Cr – PI_GEN) Piconfig> ArchiveEditLogging,1
*> ArchiveEditLogging,1
* (Cr – PI_GEN) Piconfig>
Page 26
3.4 – Log PI Batch Database/SDK Object Changes
3.4 Log PI Batch Database/SDK Object Changes
PIBatch and PIUnitBatch object changes and deletions are recorded after logging is
enabled.
Both of these objects are automatically created and modified by Batch-aware interfaces.
These interfaces create and modify PIBatch or PIUnitBatches many times during normal
operation. Excessive log messages are avoided by logging only significant changes to
PIBatch and PIUnitBatch objects. Object creation is never logged. Object deletion is always
logged.
3.4.1 Structure of Audit Trail Messages for PI Batch Database/SDK Object Changes
When logging is enabled, the following changes are logged for each of these objects:
Field Description
Source PIBatchDb Edit Always included
Edit Time Always included
Edit type Edit or Delete
Batch ID Pre-edit Batch ID Always included
Unique ID Always included
Start time New and old, if changed
End time Initial setting of the end time is not recorded;
subsequent changes are recorded
Product New and old, if changed
Recipe This attribute only applies to PIBatch objects
ProcedureName This attribute only applies to PIUnitBatch objects
All messages are recorded under the message source of PIBatchDb Edit along with the edit
time. The messages always record the pre-edit Start Time, pre-edit Batch ID, and Unique
ID. The other attributes are only reported if they are changed.
Here are some typical Audit Trail messages:
0 PIBatchDb Edit 1-Feb-01 13:34:02
>> Edit completed> PIBatch BID2 (9ce16c30-7bda-41ca-9010-bc57becf08e3)
1-Feb-01 13:33:49
New Start 1-Feb-01 13:33:50. Old Start 1-Feb-01 13:33:49
0 PIBatchDb Edit 1-Feb-01 13:37:46
>> Delete completed> PIBatch BID1 (0c286bfa-c445-447c-b698-9f5f39c8ce2a)
1-Feb-01 13:37:46
0 PIBatchDb Edit 1-Feb-01 13:37:47
Auditing the PI Server Page 27
Chapter 3 – The PI Audit Trail Message Log
>> Edit completed> PIBatch BID1 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New BatchID BID2. Old BatchID BID1
0 PIBatchDb Edit 1-Feb-01 13:37:47
>> Edit completed> PIBatch BID2 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New Product Prod2. Old Product Prod1
0 PIBatchDb Edit 1-Feb-01 13:37:47
>> Edit completed> PIBatch BID2 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New Recipe Recipe2. Old Recipe Recipe1
0 PIBatchDb Edit 1-Feb-01 13:37:47
>> Edit completed> PIBatch BID2 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New End 1-Feb-01 13:37:57. Old End 1-Feb-01 13:37:47
0 PIBatchDb Edit 1-Feb-01 13:37:47
>> Edit completed> PIBatch BID2 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New End Not set. Old End 1-Feb-01 13:37:57
0 PIBatchDb Edit 1-Feb-01 13:37:47
>> Edit completed> PIBatch BID2 (73989768-e2b6-4fd4-8399-838dbd8d7198)
1-Feb-01 13:37:46
New Start 1-Feb-01 13:37:47. Old Start 1-Feb-01 13:37:46
3.4.2 Enable Logging for PI Batch Database/SDK Object Changes
To enable logging, add an entry in the PITimeout table, named BatchDbEditLogging.
Set the value to 1 to enable logging. Set the value to 0 or delete the entry to disable logging.
You must re-start the PI Archive subsystem for changes to take effect.
Page 28
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls.
Select My Support > My Calls (Online Support). The My Support menu allows you to
review My Products, My Download History, and SRP Terms, which covers Service
Reliance Program (SRP) service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
Auditing the PI Server Page 29
Technical Support and Resources
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-select My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a
Page 30
INDEX OF TOPICS
'21 CFR, Part 11', 3 open failure, 9
API nodes, 9 records, 6
Archive size management, 7
event modification, 20 starting, 7
event removal, 20 unique ID, 14
Subsystem, 25 viewing, 10
Archive Database, 5, 6 Audit records
example audit record, 20 Batch database, 23
Audit data files creation, 6, 7
contents, 15 Definition of, 16
Audit Database, 1 examples, 16
alternate database file(s), 9 ID, 14
archive, 12 Module database, 23
bit mask, 7 PI Batch, 24
contents, 15 Audit Trail
create new files, 12 Message Log, 2
-dbmask, 14 Message Log, 25
description, 1 message structure,Archive, 25
design, 5 message structure,Batch, 27
enabling, 10 PIBatch and PIUnitBatch
exceptions, 10 changes, 27
exporting Audit Trail Message Log
records to XML, 13 description, 1, 2
specific record by ID, 14 Audit Viewer
time range, 14 description, 3
file archive, 7 Auditing
files, 5 enable, 6
integrity, 6 set online/offline mode, 6
managing files, 7 AuditRecordID, 16
mask, 14 AuditViewer, 1
offline mode Backup
timeout, 8 Audit Database data files, 12
automatic termination of, 8
Auditing the PI Server Page 31
Index of Topics
best practice recommendation, PI SMT, 25
9 PI Snapshot Subsystem, 6
caching, 9 PIArchss, 6, 11, 26, 28
PISnapss, 9 automatic termination of
Batch Database, 23, 25 backup, 8
Batches, 6 PIBasess, 6, 10
Blob points, 25 automatic termination of
Change Record backup, 8
Definition of, 16 PIBatch, 27, 28
Computer platform Audit records, 24
Information, 30 Piconfig, 26
Digital State Set Database, 5 Pigetmsg, 25
example audit record, 17 PINet nodes, 9
Documentation PISnapss, 6, 11
conventions, v automatic termination of
backup, 8
for interfaces, iv
backup mode caching, 9
PI Server, iii
PisnapssAudit.dat, 9
Enable logging
PISubbatches, 24
Archive Audit Trail, 26
PITime, 16
FDA
PITimeout Table, 28
Regulatory requirements, 3
PITransferRecords, 24
Group Database, 5
PIUnitBatch, 24, 27
example audit record, 19
PIUser, 16
Interfaces
Point Database, 5
downloading documentation
for, iv example audit record, 16
Logging edits to Schema, 2
Archive events, 25 XML, 14
PI Batch Database/SDK SDK objects, 25
objects, 28 SMT
Message Log, 2 about, iv
Mechanism, 25 Snapshot Database, 5, 6
Metadata, 2 example audit record, 20
Module Database, 23 Snapshot Subsystem, 25
Modules, 6 System Management Tools, iv
Online/offline mode, 12 Technical Support, 29
PI Archive Subsystem, 6 Time Range
PI Base Subsystem, 6 option for exporting Audit
PI Headings, 6 Database, 14
PI Properties, 24 Transfer Records, 6
PI Server Trust Database
documentation, iii example audit record, 19
Page 32
Index of Topics
Trust Table, 6 example audit record, 18, 19
UniInt example Audit record, 22
downloading documentation Utilities
for, iv AuditViewer, 1
Unit Batches, 6 W3C compliance, 15
Universal Interface XML
downloading documentation export, 10
for, iv
export records to, 13
User Database, 5
export schema, 14
Auditing the PI Server Page 33
PI Server Reference Guide
PI3 Server
Version 3.4.370
© 1998-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PI Server Reference Guide provides comprehensive information and instructions that
System Administrators need to understand, plan, administer and troubleshoot the PI Server,
PI subsystems, and PI System interfaces.
This guide includes the following topics:
Overview of all PI Databases
Data flow in the PI System
PI Point Classes and Attributes
Class Edit and Type Edit
Exception Reporting
Compression Testing
Security
SQL Subsystem
PI Time Format and Conversions
Overview of the PI Application Programming Interface (PI API)
This guide assumes that the System Administrator has a working understanding of PI Server
tools and utilities such as PIConfig, PIDiag and PIArtool. For additional information about
these command-line tools and other PI System setup and configuration procedures, see the PI
Server System Management Guide.
For a broader overview of the PI System architecture and system administration, see
Introduction to PI System Management.
PI Server Reference Guide Page iii
Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set provides complete PI Server information and system
management procedures. It includes seven user guides, described below.
Tip: Updated user guides with the most up-to-date information may be available for
download from the OSIsoft Technical Support Web site:
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security and
trusts, and performance. It includes a glossary and resource guide.
PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data Archive,
monitoring system health, managing backups, interfaces, security, and
moving and merging servers. Includes comprehensive instructions for using
command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth
troubleshooting and repair information.
PI Server Reference A comprehensive reference guide for the system administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).
Auditing the PI An administration guide that explains the Audit Database, which provides a
Server secure audit trail of changes to PI System configuration, security settings,
and Archive Data. It includes administration procedures to enable auditing, to
set subsystem auditing mode, to create and archive database files, and to
export audit records.
PI Server A guide to key add-on PI Server Applications: Performance Equations (PE),
Applications User Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality
Guide Control). Includes a reference guide for Performance Equations, and Steam
calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
Page iv
Preface - Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI Client Tools Use the client tool, PI ProcessBook, to verify that all
PI System Elements data has been recovered.
PI Server Subsystems All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text Files, Directories, Paths The backup script is located in the \PI\adm directory.
Emphasis Archive files can be either fixed or dynamic. The
New Terms archive receiving current data is called the Primary
Archive.
Fields
See Section 4.2, Create a New Primary Archive.
References to a chapter or section
Bold Italic text References to a publication See the PI Server Reference Guide.
Bold text System and Application The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
Procedures and Key Commands On the Tools menu, click Advanced Options.
Press CTRL+ALT+DELETE to reboot
Interface components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: Code examples use the piartool -ss command. For example:
"Consolas" Commands to be typed on the
font command line (optionally with
arguments or switches)
System input or output such as
excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
PI Server Reference Guide Page v
Preface - Using this Guide
Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. The PI Server ...............................................................................................................1
Chapter 2. PI Data Flow.................................................................................................................9
Chapter 3. PI Server Databases .................................................................................................19
Chapter 4. PI Point Classes and Attributes...............................................................................41
Chapter 5. PI Point Class Edit ....................................................................................................57
Chapter 6. PI Point Type Edit......................................................................................................81
Chapter 7. Exception Reporting and Compression Testing ...................................................87
Chapter 8. Security ......................................................................................................................95
Chapter 9. PI SQL Subsystem ....................................................................................................97
Appendix A: PI Time Format.........................................................................................................111
Appendix B: PI Time Conversions ...............................................................................................115
Appendix C: PI API and Toolkit Usage ........................................................................................121
Appendix D: Predefined Attribute Sets and Point Classes .......................................................129
PI Server Reference Guide Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Table of Tables.................................................................................................................................xv
Table of Figures .............................................................................................................................xvii
Chapter 1. The PI Server ...............................................................................................................1
1.1 PI Server Subsystems.......................................................................................................1
1.2 Configuration and Administrative Utilities .....................................................................3
1.2.1 Using Command-Line Tools Remotely...................................................................4
1.2.2 Displaying the PI Version Number .........................................................................4
1.2.3 Checking Snapshot Values (apisnap and pisnap) .................................................5
1.3 Interfaces Installed with the PI Server.............................................................................5
1.3.1 Interfaces to Other Data Sources...........................................................................5
1.4 PI Application Programming Interface (API)...................................................................5
1.5 PI Directory Structure .......................................................................................................6
1.5.1 Windows Directory Structure ..................................................................................6
1.5.2 Windows File System Concerns.............................................................................7
1.5.3 UNIX Directory Structure ........................................................................................8
Chapter 2. PI Data Flow.................................................................................................................9
2.1 Data Flow from Data Sources into the PI Archive..........................................................9
2.1.1 The Snapshot .......................................................................................................11
2.1.2 The Archive Subsystem........................................................................................11
2.2 Data Retrieval from the Archive .....................................................................................13
2.2.1 The Archive Read Cache .....................................................................................13
2.3 PI Data Retrieval with Foreign Data Sources................................................................14
2.3.1 Point Configuration ...............................................................................................15
2.3.2 Retrieval of Snapshot Data...................................................................................16
2.3.3 Retrieval of Archive Data......................................................................................16
2.3.4 Archive Files .........................................................................................................17
PI Server Reference Guide Page ix
Table of Contents
2.3.5 Exception Reporting .............................................................................................17
2.3.6 Compression ........................................................................................................18
2.3.7 Point Security .......................................................................................................18
Chapter 3. PI Server Databases .................................................................................................19
3.1 Point Database.................................................................................................................19
3.2 Data Archive.....................................................................................................................19
3.2.1 Archive Size Considerations ................................................................................20
3.3 Snapshot ..........................................................................................................................20
3.4 Annotations......................................................................................................................20
3.4.1 Annotation Files....................................................................................................21
3.5 Digital State Table ...........................................................................................................23
3.5.1 System State Set for All Points ............................................................................23
3.5.2 Defining a Custom Digital State Set .....................................................................24
3.6 Timeout Database............................................................................................................25
3.6.1 Table of Configurable Timeout Database Parameters.........................................25
3.7 Firewall Database ............................................................................................................37
3.8 Proxy Database................................................................................................................37
3.9 Trust Database.................................................................................................................37
3.10 User Database..................................................................................................................38
3.11 Group Database...............................................................................................................38
3.12 Module Database .............................................................................................................38
3.13 Batch Database................................................................................................................38
3.14 List of Database Files......................................................................................................38
Chapter 4. PI Point Classes and Attributes...............................................................................41
4.1 About Point Classes........................................................................................................41
4.2 Base Class Point Attributes ...........................................................................................41
4.2.1 Tag........................................................................................................................42
4.2.2 PtClassName........................................................................................................42
4.2.3 PointType..............................................................................................................43
4.2.4 NewTag ................................................................................................................44
4.2.5 Descriptor .............................................................................................................44
4.2.6 ExDesc .................................................................................................................44
4.2.7 TypicalValue .........................................................................................................45
4.2.8 DigitalSet ..............................................................................................................45
4.2.9 Zero ......................................................................................................................45
4.2.10 Span .....................................................................................................................45
Page x
Table of Contents
4.2.11 Impact of Changing Zero and Span .....................................................................45
4.2.12 EngUnits ...............................................................................................................46
4.2.13 PointSource ..........................................................................................................46
4.2.14 SourceTag ............................................................................................................46
4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent....................................................47
4.2.16 Scan Flag..............................................................................................................47
4.2.17 Compressing Flag ................................................................................................47
4.2.18 CompDev, CompMin, CompMax and CompDevPercent .....................................47
4.2.19 Archiving ...............................................................................................................48
4.2.20 Step ......................................................................................................................48
4.3 Classic Point Class Attributes .......................................................................................50
4.3.1 Instrument Tag .....................................................................................................50
4.3.2 Location1, Location2, Location3, Location4, and Location5 ................................50
4.3.3 SquareRoot ..........................................................................................................50
4.3.4 UserInt1, UserInt2, UserReal1 and UserReal2 ....................................................51
4.3.5 Filtercode ..............................................................................................................51
4.3.6 Totalcode ..............................................................................................................51
4.3.7 Srcptid...................................................................................................................51
4.3.8 Convers ................................................................................................................51
4.3.9 Ranges of ExcMax and CompMax.......................................................................51
4.4 COM Connector Point Attributes ...................................................................................52
4.5 Default Values for Point Attributes................................................................................52
4.6 System-Assigned Attributes ..........................................................................................55
4.6.1 Creator..................................................................................................................55
4.6.2 CreationDate ........................................................................................................55
4.6.3 Changer ................................................................................................................55
4.6.4 ChangeDate .........................................................................................................55
4.6.5 PointID ..................................................................................................................55
4.6.6 RecNo...................................................................................................................55
Chapter 5. PI Point Class Edit ....................................................................................................57
5.1 Introduction......................................................................................................................57
5.2 Overview...........................................................................................................................58
5.3 Attribute Sets Database Edit ..........................................................................................60
5.3.1 Attribute Set Creation ...........................................................................................60
5.3.2 Attribute Set Deletion............................................................................................63
5.3.3 Attribute Set Edit...................................................................................................64
PI Server Reference Guide Page xi
Table of Contents
5.4 Point Classes Database Edit ..........................................................................................70
5.4.1 Point Class Creation.............................................................................................70
5.4.2 Point Class Deletion .............................................................................................70
5.4.3 Point Class Edit ....................................................................................................71
5.5 Editing a Point’s Point Class Attribute..........................................................................76
5.5.1 Conversion of CC Class to and from a Native PI Class .......................................77
5.6 Point Database Audit ......................................................................................................77
5.6.1 Audit Records .......................................................................................................78
5.7 Thread-safety ...................................................................................................................80
Chapter 6. PI Point Type Edit......................................................................................................81
6.1 Introduction......................................................................................................................81
6.2 Error handling ..................................................................................................................85
Chapter 7. Exception Reporting and Compression Testing ...................................................87
7.1 Exception Reporting .......................................................................................................87
7.1.1 ExcDev and ExcDevPercent ................................................................................89
7.1.2 ExcMin ..................................................................................................................89
7.1.3 ExcMax .................................................................................................................89
7.1.4 Turning Off Exception Reporting ..........................................................................90
7.2 Compression Testing......................................................................................................90
7.2.1 Step Flag ..............................................................................................................93
Chapter 8. Security ......................................................................................................................95
8.1 User Name and Password ..............................................................................................95
8.2 Point Security...................................................................................................................95
8.3 Database Security ...........................................................................................................95
8.4 Trust Access ....................................................................................................................96
Chapter 9. PI SQL Subsystem ....................................................................................................97
9.1 Architecture......................................................................................................................97
9.1.1 Statement Handles ...............................................................................................97
9.1.2 Concurrency .........................................................................................................98
9.2 Differences between PI 2.x and PI 3.x ...........................................................................98
9.2.1 The PIPoint Table.................................................................................................98
9.2.2 Using Performance Equation Subsystem Built-In Functions................................99
9.3 Configuration ...................................................................................................................99
9.3.1 Hierarchy of PI SQL Subsystem Settings...........................................................100
9.3.2 Initialization File Settings ....................................................................................100
Page xii
Table of Contents
9.3.3 Command Line Arguments.................................................................................100
9.4 Troubleshooting ............................................................................................................103
9.4.1 Using the ipisql Utility .........................................................................................103
9.4.2 Generating a Trace File......................................................................................106
9.4.3 Output from the TRACE Option..........................................................................106
9.4.4 Clearing Expensive Query Problems .................................................................107
9.4.5 Performance Counters .......................................................................................108
9.4.6 Technical Support and Problem Reports ...........................................................109
Appendix A: PI Time Format.........................................................................................................111
A.1 Relative Time .................................................................................................................111
A.2 Absolute Time ................................................................................................................111
A.2.1 Specifying Standard or Daylight Savings Time ..................................................112
A.2.2 Examples ............................................................................................................113
A.3 Combined Formats........................................................................................................114
A.3.1 Examples ............................................................................................................114
Appendix B: PI Time Conversions ...............................................................................................115
B.1 Timestamps on PI 2 Systems .......................................................................................115
B.2 Daylight Savings Time Changes on PI 2 Systems .....................................................115
B.3 Timestamps across Time Zones on PI 2 Servers.......................................................116
B.4 Timestamps on PI Server Systems..............................................................................117
B.5 Translating PI 2 Timestamps to PI Server Systems...................................................117
B.6 Translating PI Server Timestamps to PI 2 Based Timestamps.................................118
B.7 How PI Client Applications Handle DST Changes .....................................................119
B.8 PI in the 21st Century....................................................................................................120
Appendix C: PI API and Toolkit Usage ........................................................................................121
C.1 Overview.........................................................................................................................121
B.1.1 PI API..................................................................................................................121
C.2 PI API Usage on PI Server ............................................................................................121
C.3 PI Toolkit Usage on PI Server.......................................................................................127
Appendix D: Predefined Attribute Sets and Point Classes .......................................................129
D.1 Predefined Attribute Sets .............................................................................................129
D.1.1 alarmparam ........................................................................................................129
D.1.2 base ....................................................................................................................130
D.1.3 classic .................................................................................................................130
D.1.4 sqcalm_parameters ............................................................................................131
PI Server Reference Guide Page xiii
Table of Contents
D.1.5 totals ...................................................................................................................132
D.2 Predefined Point Classes .............................................................................................132
Technical Support and Resources...............................................................................................133
Index of Topics...............................................................................................................................135
Page xiv
TABLE OF TABLES
Table 2–1. COM Connector Point Attributes............................................................................15
Table 3–1. Typical Digital States..............................................................................................23
Table 3–2. ConfigurableTimeout Parameters ..........................................................................25
Table 4–1. Point Types ............................................................................................................43
Table 4–2. Point Database Default Table ................................................................................53
Table 9–1. Default Attributes in BASE Point Class..................................................................98
Table 9–2. Command Line Arguments ..................................................................................101
Table 9–3. Command Line Option Tokens ............................................................................101
Table 9–4. Command Line Arguments Supported by ipisql ..................................................105
Table B-1 PI 2 Standard Time to Daylight Savings Time ...................................................115
Table B-2 PI 2 Daylight Savings Time to Standard Time ...................................................116
Table B-3 PI2 Timestamps across Time Zones .................................................................116
Table B-4 PI Server Standard Time to Daylight Savings Time ..........................................117
Table B-5 PI Server Daylight Savings Time to Standard Time ..........................................118
Table B-6 PI Examples of Timestamp conversions for California-based systems .............119
PI Server Reference Guide Page xv
TABLE OF FIGURES
Figure 2-1. Processing of New Events.....................................................................................12
Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector ........16
Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector ............17
Figure 5-1. Formation of a point class......................................................................................57
Figure 7-1. Swinging Door Compression .................................................................................92
Figure 9-1. Windows Control Panel Services Applet .............................................................103
PI Server Reference Guide Page xvii
Chapter 1. THE PI SERVER
The PI System is a set of software modules for plant-wide monitoring and analysis. It acts as
a data server for Microsoft Windows-based client applications. Operators, engineers,
managers, and other plant personnel use a variety of client applications to connect to the PI
Server to view plant data stored in the PI Archive or in external data storage systems.
The PI Server typically runs on one computer, while PI interfaces and client applications run
on a variety of other computers on the network. Such a distributed data collection architecture
offers several advantages over a monolithic architecture, including scalability, robustness,
and flexibility.
A PI Server includes:
PI Server Subsystems: The processes, called subsystems, that comprise the PI Server.
Configuration and administrative utilities.
Interfaces, including Random and Ramp Soak for simulated data, and PerfMon,
SNMP and Ping for monitoring purposes.
PI API and PI-SDK. This software is included with the PI Server for internal use by
the applications on the PI Server.
This chapter provides an introduction to these elements of the PI Server, and explains the
structure of the PI Server File system.
1.1 PI Server Subsystems
The PI Server consists of several interlocking processes, which this book refers to as
subsystems. The executable for each of the PI subsystems is installed in the PI\bin directory.
Six PI subsystems make up the core PI Server. Generally, the system cannot function to a
minimum level without these subsystems. Some subsystems depend on other subsystems for
proper behavior. All subsystems will wait for any dependent subsystems. The core PI
subsystems are listed in the following table.
PI Server Reference Guide Page 1
Chapter 1 - The PI Server
Subsystem Executable What It Does Dependency Issues
Archive piarchss.exe Stores and serves the data after it Requires the PI
comes out of the Snapshot Snapshot Subsystem.
subsystem. Data consists of multiple
timestamped measurements for each
data point. This includes values such
as on/offs, pressures, flows,
temperatures, setpoints, etc.
Base pibasess.exe Maintains the Point Database, Digital Requires the PI Update
State Table and configuration Manager
databases for user and group
security. It also hosts the PI Module
Database.
License pilicmgr.exe Maintains licensing information for
Manager the PI Server and all connected
applications
Message pimsgss.exe Records status and error messages Messages are routed to
for the PI Server in a control log file. the Windows Event log
or UNIX standard
output if this subsystem
is not available.
Network pinetmgr.exe Manages communication between PI
Manager Server subsystems, client
applications and interfaces. Also
validates clients at time of
connection. Clients may be standard
products such as PI ProcessBook, or
they may be user-written PI API or PI
SDK programs.
Snapshot pisnapss.exe Stores the most recent event for each Requires the PI Update
point. Applies compression, sends Manager.
data to the Event Queue, and serves
Snapshot events to the client
applications.
Update piupdmgr.exe Sends notifications of changes in These services are
Manager values or point attributes to any essential for proper
interface or client application that is operation of a PI
signed up for notification. Server; it is required by
most of the PI
Subsystems and most
client applications.
In addition to the core PI Subsystems, the PI Server includes additional subsystems such as
Batch and Performance Equation Scheduler. These subsystems do not need to be running in
order for PI to be running. Some of these subsystems are licensed separately and might not be
installed on your PI Server.
Page 2
1.2 - Configuration and Administrative Utilities
Other Subsystems
Subsystem Executable What It Does
Alarm* pialarm.exe Provides alarm capabilities for PI points.
Backup pibackup.exe Manages backups of PI.
Batch* pibatch.exe Detects and records batch activity.
Performance pipeschd.exe Performs PI Performance Equation calculations for PI calculated
Equations* points.
Recalculator pirecalc.exe Automatically adjusts values of Performance Equation (PE)
points.
Redirector piudsrdr.exe The Base, Archive, and Snapshot Subsystems use the
Redirector to obtain data from the external systems.
Shutdown pishutev.exe Determines when the PI system was stopped and writes
shutdown events to points configured to receive these events
(runs only at startup and then stops)
SQL pisqlss.exe 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.
Totalizer* pitotal.exe Performs postprocessing calculations on a point in the
snapshot, storing the results in a PI “Totalizer” point.
* indicates a separately licensed subsystem
1.2 Configuration and Administrative Utilities
The PI Server for Windows and UNIX includes several utilities that are used to configure
points, monitor the data flow, manage the archives, and configure the security settings.
The PI Server comes with a wide variety of configuration and administrative utilities:
Utility Location Description
apisnap PI\adm A tool for checking snapshot values.
piarchss PI\bin PI Offline Archive Utility. This is actually the archive subsystem
executable—which you can run with command-line options, as a utility.
piarcreate PI\adm Archive creation utility. Once created, Archive files can be mounted
using piartool.
piartool PI\adm PI Archive Tool. This utility includes many commands to monitor,
inspect or modify the state of a running PI Server.
piconfig PI\adm A tool for configuring PI Server databases, such as the Point database
and the Digital State table.
PI Server Reference Guide Page 3
Chapter 1 - The PI Server
Utility Location Description
pidiag PI\adm A tool for PI diagnostics and repair.
pigetmsg PI\adm A tool for viewing PI Server messages.
pilistupd PI\adm A tool for monitoring the Update Manager, specifically for looking at
Event Queues.
pipetest PI\adm Performance equation test utility.
pisetpass PI\adm A tool for changing user passwords
pisnap PI\adm Starts apisnap against the local PI Server
pisqlss PI\bin Pisqlss is actually the SQL Subsystem—which you can run with
command-line options, as a utility.
piversion PI\adm Use piversion –v to get the version and build numbers of the PI Server.
To view usage information for any of these utilities, use the -? argument. For example:
pilistupd -?
1.2.1 Using Command-Line Tools Remotely
It is useful to be able to run the PI administration tools remotely. A piconfig session may be
run remotely by issuing the Login command.
The piartool, pigetmsg and pilistupd utilities can be run remotely by specifying four
parameters:
PI Server home node host name or IP address
PI user account name
PI user account password
Port ID (defaults to 5450)
For example:
pilistupd -remote
This requires PI-SDK installation on the client.
1.2.2 Displaying the PI Version Number
Get PI Server version and build numbers by typing:
piversion –v
From the PI\adm directory.
If you have applied a patch to your PI Server, the version numbers of the executable modules
affected will be different from that shown by piversion -v.
When a module is executed using the -v option, the module is not actually started; only the
version number is displayed.
Page 4
1.3 - Interfaces Installed with the PI Server
1.2.3 Checking Snapshot Values (apisnap and pisnap)
On both Windows and UNIX platforms, there is a utility in the PI\adm directory called
apisnap that shows the current value (Snapshot) for a specified point.
When you run the apisnap utility on the PI Server, it prompts you for a point name. (To quit
the utility, press <Enter> instead of entering a point name).
The apisnap utility accepts as a parameter the network name (and optionally, a TCP/IP port
number) of a computer running a PI Server. For example, to connect to a PI Server running
on the same computer, you would enter:
apisnap localhost:5450
There is also a script in the PI\adm directory called pisnap.bat on Windows and pisnap.sh on
UNIX. This script runs the apisnap utility and connects to PI on the same computer.
1.3 Interfaces Installed with the PI Server
Each PI Server includes several interfaces. Two of these, Random and Ramp Soak, are
simulator interfaces. They can be configured to simulate random, sinusoidal, and batch data.
These are installed on the PI Home Node, but may be run remotely.
Three additional interfaces are useful for monitoring the health of your system and network.
Each is limited to a maximum of 512 performance points in the Point Database and can only
be run on the PI Home node.
PerfMon reads Performance Counters on Windows systems and stores the values in
PI points,
SNMP collects performance data from computer systems and network routers using
the Simple Network Management Protocol, and stores the values in PI points.
Ping monitors the network availability of computer systems by pinging them and
stores the response times in PI points.
A version of the interface without the 512-point limit may be purchased separately.
1.3.1 Interfaces to Other Data Sources
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), lab systems, and process models. Most
interfaces can also send data in the reverse direction, from PI to the foreign system.
1.4 PI Application Programming Interface (API)
The PI Application Programming Interface (PI API) is a library of functions that allow
programmatic access to the PI System, both for data archiving and for retrieval. OSIsoft uses
the API internally to create interfaces that run on a variety of platforms. Users may also use
the API for their own applications.
PI Server Reference Guide Page 5
Chapter 1 - The PI Server
The PI API is a library of functions that may be called from C, Visual Basic, or other
languages. These functions let you read and write values from the PI Server. They also let
you retrieve point configuration information.
The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to
be taken offline for software or hardware upgrades without compromising data collection.
When PI becomes available again, the buffered data are then forwarded to PI.
API nodes are UNIX or Windows workstations that run programs such as interfaces that are
based on the PI API.
1.5 PI Directory Structure
The PI Server file organization is a little different for Windows and UNIX platforms. Refer to
the section for the appropriate operating system.
1.5.1 Windows Directory Structure
By default, PI installs its files in a folder called PI on the disk with the most available space,
but you can choose a different location for PI during installation. Within the PI directory, PI
installs a few subdirectories.
Directory Contents
PI\adm Contains administrative tools.
PI\bin Contains subsystem or PI service executables.
PI\dat Contains databases such as points and digital states. This is also the
default directory for Archive files and the Event Queue.
PI\interfaces Contains interfaces that were installed with previous versions of PI. Is
not present on new PI Server installations, but might be present on
Servers that are running upgrades.
PI\log Contains log files.
PI\setup Contains files for install and uninstall.
The PI directory structure for Windows systems differs depending on whether the system is a
new installation or an upgrade.
PI Interfaces Directory on Windows
PI installs interfaces in a directory called PIPC. The PIPC directory tree, if it does not exist,
is created during the installation of the PI-SDK. Refer to the PI-SDK documentation for more
information about the PI-SDK installation.
Previous versions of PI installed interfaces in a directory called interfaces under the main PI
directory. If your PI Server is based on an upgrade, rather than a new install, then older
interfaces might be located in the PI/interfaces directory. For upgrades, interfaces that have
been installed in the PI directory tree will remain in the PI directory tree. All other interfaces
are installed in the PIPC directory tree.
Page 6
1.5 - PI Directory Structure
1.5.2 Windows File System Concerns
When running PI on Windows, OSIsoft recommends the following:
Disable virus scanning on the archive and database folder. Virus scanning may
corrupt active files (e.g. the primary archive). The problem with virus scanning is
that, because the data is random, it might have a bit pattern that matches a known
virus signature. The virus scanning software then locks and quarantines the PI Server
file.
Don't use the Windows File System Compression feature on the PI Server. When
you use compressed files, you slow down PI's access to Archive files. The
compression might save disk space, but it requires more CPU resources.
The following sections explain these recommendations in more detail.
Windows File Compression
Using compressed files can slow down the access to the Archive files, and thus degrade the
performance of the whole system. This is especially true on files that are constantly changing,
such as the primary archive, the Event Queue or the current message log file.
OSIsoft recommends that you do not use the File System Compression feature of Windows.
If you use this compression, while it may save disk space, it will require more CPU resources
each time data arrives at the Archive or database files or is accessed by clients.
Using Anti-Virus Software
OSI Software recommends against using anti-virus software to scan the directories containing
PI Server database and Archive files on systems collecting production data.
To be effective, anti-virus software must be configured to immediately scan files whose
contents 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,
which means that 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. This corruption of the Archive file system
has happened at several sites, resulting in the unrecoverable loss of production data. The
same situation can occur for other PI Server database files, although these files change less
often.
Anti-virus software should be configured to exclude scanning the PI\dat directory and any
directory containing Archive files. The PI\dat directory does not contain any executable
programs or scripts.
Another effective technique for protecting a production PI Server from Internet hackers is to
install a firewall between the Internet and the server. For maximum protection, the firewall
can be configured so that it stops all incoming Internet traffic except for those packets which
(1) originate from safe, user-specified IP addresses, and (2) are destined for TCP/IP port 5450
on the PI Server computer. Downloaded files, or files from an unverifiable source could be
scanned for viruses on a separate "quarantine" computer before moving them to the PI Serve
PI Server Reference Guide Page 7
Chapter 1 - The PI Server
Other Files on Windows Systems
On Windows systems, the PI System may use the file, WINNT\system32\pdh.dll – this is the
Microsoft Performance Data Helper library, which is used by the PI Performance Monitor
interface. This file is loaded or upgraded on your system during the normal installation
procedure.
Additionally, the PI-SDK places some Windows files during installation. The files placed by
the PI-SDK are listed in the PI-SDK Release Notes, which are installed in the SDK
subdirectory of the directory indicated by the pihome entry of the pipc.ini file.
1.5.3 UNIX Directory Structure
The PI directory structure for UNIX systems:
Directory Contents
PI/adm Contains administrative tools.
PI/bin Contains the PI System executables.
PI/dat Contains data files such as the Point Database
PI/interfaces Contains subdirectories with executables for each of the interfaces.
PI/lib Contains libraries used by PI.
PI/log Contains all PI log files. Log files for the interfaces may also be found in the
PI\interfaces subdirectories.
PI/patches Contains miscellaneous files that may be needed for some installations.
Other Files on UNIX Systems
There are a few files used by the PI System that are not located under the PI directory. On
UNIX systems, the following files may be used by the PI System:
/etc/piparams.default - This file is created during PI installation.
/etc/passwd - This file is modified to create the piadmin and OSI login accounts.
/etc/group - This file is modified to create the pigrp group.
/usr/lib/libC.ansi.sl - This file is needed only on some platforms. The file name may vary.
/usr/piadmin/.profile - This file is modified by the System Administrator to define the
shared library path environment variable if using the Korn shell. It is needed only on
some platforms. The path may vary, depending on the installation The environment
variable varies depending on the platform.
/usr/piadmin/.chsrc - This file is modified by the System Administrator to define the
shared library path environment variable if using the Korn shell. It is needed only on
some platforms. The path may vary, depending on the installation. The environment
variable varies depending on the platform.
Page 8
Chapter 2. PI DATA FLOW
This chapter describes the flow of data through a PI Server and interfaces. PI typically stores
data in the PI Data Archive, which is managed by the PI Archive Subsystem. However,
Windows-based PI Servers can also retrieve data from foreign data-storage systems. Foreign
data-storage systems are, for the purposes of this book, any data systems other than the PI
Data Archive.
This chapter begins by explaining the flow of data from data sources to the PI Data Archive.
Later sections discuss data retrieval, both from the PI Data Archive and from foreign data
storage systems. This chapter contains the following sections:
Data Flow from Data Sources into the PI Archive begins on page 9
Data Retrieval from the Archive begins on page 13
PI Data Retrieval with Foreign Data Sources begins on page 14
Note: In the PI Server for UNIX, there is no COM Connector capability. All data must
be stored in the PI Data Archive.
2.1 Data Flow from Data Sources into the PI Archive
The fundamental unit of data storage in the PI System is called an event. An event consists of
a timestamp, a value, and a status. In the simplest terms, interfaces collect data from data
sources, then send these data to the PI Server in the form of events. The PI Server then stores
these events in the PI Archive. This simple view of PI data flow is shown in the following
illustration.
PI Server Reference Guide Page 9
Chapter 2 - PI Data Flow
In reality, the data flow is more complex than the preceding illustration indicates. The most
important thing to understand about PI data flow is that PI does not save every single event
that an interface collects. Instead, PI stores only significant events. A significant event is one
that is essential for recreating the original data. PI discards events that are not significant.
This section provides a more detailed description of the data path that an event follows from
the data source to the PI Data Archive and describes the places in the data path where PI
evaluates a point to see whether it is significant. The basic steps along the path are as follows:
1. The interface collects the data from the data source. The data sources can be almost
anything, including Distributed Control Systems (DCSs), Programmable Logic
Controllers (PLCs), lab systems, Supervisory Control and Data Acquisition systems
(SCADA), process models, and other business information systems. PI Performance
Equations, ACE, and Totalizer are also all data sources.
2. Each different data source needs a PI interface that can interpret it. Most PI interfaces
run on a separate computer, called an Interface Node. (The Interface Node is
sometimes also called the API Node.)
3. The PI interface uses exception reporting to determine which events to pass on the PI
Server and which are not needed. Exception reporting is a simple linear test that
determines whether the incoming value is significantly different from the existing
value. You set the specifications for exception reporting in the tag attributes for each
point. By tuning these exception specifications, you can ensure that the interface
passes on only values that are of interest to you.
4. The interface sends significant events to the buffering service, if the buffering service
is configured for that interface.
5. The buffering service sends the events on to the PI Server or, if the Interface Node
cannot connect to the PI Server, the buffering service holds the data until the Server
connection is restored. This is an important mechanism for safeguarding your data, so
it’s important to configure buffering for your interfaces, where possible.
Page 10
2.1 - Data Flow from Data Sources into the PI Archive
6. When an interface sends an event to the PI Server, it goes first into the Snapshot
Subsystem. The Snapshot Subsystem holds a “snapshot” of each point in the point
configuration database. This snapshot includes: the current value of the point, the last
archived value, compression specifications, and security attributes.
7. The Snapshot uses the information about each point to decide what to do with
incoming events for that point. If an event is out of order, the Snapshot sends it
straight to the archive. If the event is not out of order, the Snapshot Subsystem
applies the compression test.
8. PI uses the compression test to decide whether an event is significant. As in
exception reporting, you set the specifications for compression in the tag attributes
for each point. Unlike exception reporting though, compression testing is not linear.
PI uses a very sophisticated compression algorithm to determine whether it needs a
particular value in order to accurately reconstruct the data curve for a particular point.
9. If the event passes the compression test, the Snapshot sends it to the PI Event Queue.
10. The Archive Subsystem retrieves events from the Event Queue. Since the Event
Queue is a memory-mapped file, the events in it are persistent. This means that they
are recoverable in cases of unexpected crashes or delays.
2.1.1 The Snapshot
A new event entering the PI System from an interface or manual input program is sent to the
Snapshot Subsystem. The Snapshot is the most recent event for a point. It can be viewed as a
buffer that is only one element deep. When a new event comes in, it becomes the new
Snapshot. The previous Snapshot is evaluated according to the compression specifications
and is either sent to the Event Queue or discarded.
Any event that has a timestamp older than the Snapshot will not become the Snapshot.
Instead, it is sent to the Archive Subsystem through the Event Queue.
Event values are always stored in full precision in the Snapshot. Scaling, if applicable, is
applied when the event is stored into the Archive. For more information on scaling, see the
section on point types in Chapter 3, PI System Databases.
When the archive events for a point are listed or trended by PI ProcessBook and other tools,
the Snapshot is automatically included in the list.
The Snapshot Table resides in memory. It is flushed to disk (piarcmem.dat) by the Snapshot
Subsystem at least every 15 minutes.
2.1.2 The Archive Subsystem
The PI Snapshot sends events that pass compression to the Archive Subsystem. When events
enter the Archive Subsystem, they do not go directly to Archive files for storage. Instead,
they go first to the Archive Event Queue, which sends them to the Archive Write Cache.
Finally the Archive Write Cache sends the events to the Archive Files themselves for storage.
PI Server Reference Guide Page 11
Chapter 2 - PI Data Flow
SnapShot
1
2 Queue(s)
3
4 Compress
5
New Event
file(s)
Cache
0 m
RecNo 0
Other
On-Line
Archives
n Primary
Archive
Figure 2-1. Processing of New Events
The Event Queue
Events that have passed the compression filter are placed in the Event Queue. This includes
events that are out of order, events for points whose status has changed, and events for points
with the Compression attribute set to OFF.
The Event Queue has the job of buffering the incoming process data on the way to the
Archive. The operation of the queue protects the data against loss should any of the following
system upsets occur:
Loss or failure of the Archive Subsystem
Surge of process data from process or other upset
Temporary CPU loading of the computer running PI
The memory-resident Event Queue is always backed up on disk (pimapevq.dat). If the queue
becomes full due to long delays in the Archive Subsystem, up to 65,535 additional queues
may be created. When the Archive is able to recover from the cause of the upset, all the
queues are processed in the order created.
The default size of the Event Queue is 64 megabytes but it may be configured from 8
megabytes to 128 gigabytes. The amount of free space on the disk is generally the only
limitation on the size and number of queues.
The Event Queue is located in the PI\dat directory, but can be on a different volume. The
System Manager should ensure that adequate free disk is maintained on that volume. When
the Archive Subsystem is unavailable, you may need an average of 5 kilobytes of free space
per point per day. This assumes 250 events per point per day for a floating-point tag.
The Write Cache
When the Event Queue sends an event to the Archive Subsystem, the Archive keeps it first in
the Write Cache, which is a memory array that stores events for each point. The Write Cache
Page 12
2.2 - Data Retrieval from the Archive
stores events for a point in memory until the data reaches certain configurable limits on size
and/or time since the last write to disk. Then the Write Cache data for that point is written to
the Archive files. By holding events for each point up to the specified limits, PI reduces the
frequency of disk access, improving overall performance.
Specifically, write cache events are flushed to disk at the following times:
When the Write Cache for a particular point reaches the maximum size, the data for
that point (and just for that point) is flushed to disk. The maximum number of events
in the Write Cache for each point is 256, but this is configurable by the
Archive_MaxWriteCachePerPoint setting in the timeout table.
Every record in the Write Cache is flushed at least once every Flush Cycle. The
default cycle is 900 Seconds (15 minutes) and can be configured using the timeout
parameter Archive_SecondsBetweenFlush.
2.2 Data Retrieval from the Archive
Many applications request data from the PI Server system, for example, trends or PI
DataLink. Every such request translates into a low level call to the archive that retrieves the
raw data, values and timestamps. This raw data is always exactly what was put into the
archive by the interface. However, there are two exceptions where the data-retrieval functions
generate an extra event.
When the request spans a time period with no mounted Archive files, a digital state of Arc
OffLine is inserted one second after the end of the last scanned Archive file. This prevents
the interpolation of data over an unknown period, for example when an archive is offline for
maintenance.
This option is active by default but can be disabled by setting the timeout parameter:
MarkArchiveGaps, 0
Similarly, when requests for data go into the future, a NoData digital state is inserted one
second after the current time. If the Snapshot is in the future, then the NoData digital state is
inserted one second after the Snapshot, in order to prevent data extrapolation into the future.
The PI server rejects Snapshots more than 10 minutes into the future.
Requests for data before the oldest registered archive also return NoData.
Since these two digital states are used within the PI Server, we recommend not inserting them
into the archive as this can lead to misinterpretation of data-retrieval results.
2.2.1 The Archive Read Cache
The read cache is a piece of memory that contains a linked list or records for each point. The
read cache has a one-to-one relationship with records in the Archive. When a client asks for
data from the Archive, the Archive translates that data to Record Number, and then figures
out if the data being requested is in the Read Cache already. If not, it determines in which
Archive to go look for the data.
PI Server Reference Guide Page 13
Chapter 2 - PI Data Flow
The size of the Read Cache is configurable and, by default, a single point can use as many as
512 records from the pool. This number is configurable with the
Archive_CacheRecordsPerPoint parameter (the maximum value is half the cache pool).
Assuming enough memory resources, the limit on the total number of records in the Read
Cache is set to 4 times the point count, but can be manually overwritten by the
Archive_CacheRecordPool parameter.
You can use piartool -cas (cache statistics) to view cache information for a point, and
piartool -cad (cache diagnostics) to dump the information in both the read and write caches.
2.3 PI Data Retrieval with Foreign Data Sources
Data are sometimes not stored in the Archive or Snapshot Subsystem. They 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.
Each COM Connector is coded to interact with a specific foreign data system. 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 system
can access any number of foreign data systems. It is not necessary to dedicate an installation
of PI Server strictly to communication with external 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.
Note: The Redirector is a module in PI Server for Windows only. PI Server for UNIX
does not support the use of COM Connectors or the Redirector.
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-process COM objects are .exe files. OSIsoft has developed some
COM Connectors to specific data systems. Others may be available from vendors or
integrators. In general, the decision to build an in-process vs. an out-of-process COM object
is made by the COM Connector developer.
The PI Server Redirector is an out-of-process COM object. It does not run as a service, which
means it will not be found in the Services control panel applet. When the Redirector is
running, system managers will be able to see a process called piudsrdr.exe in the Processes
tab of the Windows Task Manager.
Page 14
2.3 - PI Data Retrieval with Foreign Data Sources
Client applications are not aware of the difference between data retrieval from the PI Data
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 from which data are
retrieved is identified by a tag, and has attributes stored in the PI Point Database, regardless
of the source of the data. The differences in data flow are implemented by the Snapshot and
Archive Subsystems. Details are in the sections Retrieval of Snapshot Data and Retrieval of
Archive Data, below.
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.
The PI Server can put new data into a foreign data system if it is supported by the COM
Connector for the foreign data system.
2.3.1 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 Server Point Database.
A mapped point in the Point Database is simply one that links to data in a foreign-system.
To build a mapped point, you must select a point class that includes three specific attributes,
as well as the normal attributes of a point class. These three point attributes are shown in the
following table:
Table 2–1. COM Connector Point Attributes
Attribute Name Description
ctr_progid COM program ID, as stored in the Windows registry. This name is used to
invoke the COM Connector object when needed.
ctr_lmap Longword mapping parameter. ctr_lmap and ctr_strmap are passed to the
COM Connector so that it can locate the appropriate foreign system point.
ctr_strmap String mapping parameter. ctr_lmap and ctr_strmap are passed to the
COM Connector so that it can locate the appropriate foreign system point.
PI Server ships with a point class called classicctr that contains these three point attributes as
well as the base and classic attribute sets. You can create this point class by executing the
script PI\adm\classicctr.dif using the piconfig utility. You may also use the contents of this
script as a basis for your own point class definition.
You construct points according to the specifications of the point class. A complete list of
point attributes is listed in PI Server Databases on page 19 in the Point Database section.
Point creation and maintenance are done 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 will obtain data values from the corresponding foreign system point.
PI Server Reference Guide Page 15
Chapter 2 - PI Data Flow
2.3.2 Retrieval of Snapshot Data
When the PI Server Snapshot Subsystem starts, it is notified of the presence of mapped points
by the Base Subsystem. When a client application requests a Snapshot value, the Network
Manager routes the request to the Snapshot Subsystem.
If the point’s data are normally stored in the PI Data Archive, the Snapshot value would be
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. Then it is routed to the Network Manager for transmission to the client.
Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector
2.3.3 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, it is notified of the presence of mapped points by the Base Subsystem.
When a client application requests archive values, the request is routed to the Archive
Subsystem by the Network Manager as before. The archive values are retrieved from the
subsystem and returned to the Network Manager for transmission to the client.
Page 16
2.3 - PI Data Retrieval with Foreign Data Sources
If archive values for a mapped point are requested, the data path is different. In this case, the
Archive Subsystem requests the value from the Redirector, which in turn obtains the value
from the appropriate COM Connector
Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector
2.3.4 Archive Files
Even though Archive files are not used if data are retrieved using COM Connectors, the files
must exist and must be sized as if all points on the PI Server were PI Data Archive points.
Normal maintenance and backup procedures apply to the Archive files, with one exception: if
a PI Server installation consists entirely of mapped points, it will not be necessary to back up
the Archive files.
2.3.5 Exception Reporting
The COM Connection mechanism includes support for exception reporting. There is a ‘sign
up’ method that the PI Server Snapshot Subsystem will call in the COM Connector if a client
signs up for exceptions on a mapped point. The Snapshot Subsystem will obtain 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.
PI Server Reference Guide Page 17
Chapter 2 - PI Data Flow
2.3.6 Compression
PI Server does apply the PI Data 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.
2.3.7 Point Security
Data retrieved from foreign data system is subject to the same security as data values
retrieved from storage within the PI Data Archive. Every PI point, whether mapped or not,
carries a security descriptor that defines the access PI users may have to data.
Page 18
Chapter 3. PI SERVER DATABASES
The PI Server includes several databases that store PI configuration information and process
data. The two main databases are the Point Database and the Data Archive. Other parts of the
system, including the Snapshot Subsystem, the Digital State Table, and Module Database,
support the main databases.
System Management Tools as well as a set of command line utilities are used to configure
and manage the PI Server.
See also PI Server System Management, and documentation about free System Management
tools posted on the OSIsoft Web site.
3.1 Point Database
The most important configuration database is the Point Database. This contains the list of
points that are either recorded in the PI Data Archive or mapped to points in foreign data
systems when COM Connectors are used. The points whose data are stored in PI Data
Archive are sometimes called native PI points. The points whose data are stored in foreign
data systems are interchangeably referred to mapped points or COM Connector points. The
Point Database stores configuration information for each point as a list of point attributes.
Attributes are grouped into attribute sets, which in turn are grouped into point classes. The
Base class, Totalizer class and Classic class are some of the point classes commonly used in
PI. When a point is created, it is assigned a point class, which restricts the point to a specific
set of attributes.
For a complete explanation of the PI point classes and point attributes, refer to PI Point
Classes and Attributes on page 41.
3.2 Data Archive
The most important process information database is the Data archive. The archive is a
historical record of values for each point in the Point Database.
The Data Archive contains the time-stamped values for all the points in the Point Database.
The time-stamped values are stored in a set of disk files. Each file covers a different,
non-overlapping time period. Three archive files are created during installation. Additional
archives can be created when needed, using the utilities provided. The archive files may vary
in size.
PI Server Reference Guide Page 19
Chapter 3 - PI Server Databases
3.2.1 Archive Size Considerations
When an archive value is replaced, the new value is flagged in the archive as modified. This
results in additional storage being allocated for the replaced value. For numeric values the
size approximately doubles.
Caution: When you delete a point, the records for that point in the current archive
are made available for reuse. A consequence of this is that all history is irrecoverably
lost for the deleted point. Records in old Archive files that contain data for the
deleted point are not directly accessible. However, the data can be recovered using
the Offline Archive Utility using an ID-conversion table.
3.3 Snapshot
The Snapshot Database contains the most recent value, status, and time stamp for each point
in the Point Database.
The Snapshot database piarcmem.dat contains mostly frequently updated data. If this file is
damaged it can be rebuild using pibasess –snapfix. Snap fix rebuilds this file based on the
point database and sets all values to a Shutdown status; normal data collection quickly
replaces Shutdown statuses with new values. Many PI Systems have a few points that update
very infrequently; in this case these values will remain at Shutdown until a new Snapshot
value is received.
The PI Snapshot Subsystem actually maintains several databases. The pimapevq.dat
maintains the Event Queue. If pimapevq.dat (or pimq####.dat, where #### is a hexadecimal
number between 0000h and FFFFh) is corrupted, pisnapss may not be able to start. In this
case the file can be renamed and pisnapss will create a new one. Offline archive recovery
tools can be used to recover data from this file. The file pilastsnap.dat maintains the Snapshot
time of the newest event. This is used to determine the PI Server shutdown time. This file is
overwritten every 10 minutes and during PI Server shutdown.
File name Description
piarcmem.dat Snapshot database
pimapevq.dat Event queue (could also be pimq0000.dat, pimq0001.dat…)
pilastsnap.dat Time of newest event
Two utilities provide access to the Snapshot Database. The pisnap.sh (UNIX) or pisnap.bat
(NT) utility can be used to view the contents of the Snapshot. The piconfig utility can be used
to both view and modify the contents of the Snapshot.
3.4 Annotations
Every value in the Snapshot or the Archive may be annotated. An annotation can be of any
data type.
Page 20
3.4 - Annotations
Annotations can be accessed via the PI-SDK. Text annotations can be added and edited using
piconfig. This option should only be used for testing and verification.
Applications using the PI-SDK can add/edit annotations for a specified Archive event.
The Batch Database uses annotations to store the following object types:
PIBatches
PIUnitBatches
PITransferRecords
3.4.1 Annotation Files
Annotations are store in an Annotation file. Each Archive file has a single associated
Annotation file. An annotation is a variant associated with a PI Event.
Note: The PI SDK supplies a programmatic interface for creating, accessing and
editing annotations. The PI SDK User Guide and online help are the best source for
details on valid variants for annotations.
Annotations are best understood with a simplified description of creating and accessing them.
For example:
1. A PI-SDK based application creates a variant. Variants can be of many types, such as
strings, an array of strings, various numeric types, etc. For this example, the variant is
an array of strings. The first string may be a lab technician’s name, the second string
may be a comment.
2. This same application creates a timed value, for example, a value and timestamp that
represent a manual measurement made on a piece of lab equipment. The variant
created above is associated with the timed value—the value is now annotated. The
PI-SDK is used to make this association. In this example, the annotation contains the
technician making the measurement and an associated comment.
3. The annotated value is then sent to the PI Snapshot. This is sent just as any other
event. The difference is that the event also contains the annotation.
4. Annotated events will always bypass compression. Upon reaching the Snapshot, the
annotated event is sent to the Archive via the Event Queue.
5. From the queue, the annotated event is written to the cache. Then, a few special steps
are taken writing the annotated event to the Archive.
First the target Archive and the Archive’s Annotation file is found. The variant that
represents the annotation is written to the Annotation file. On writing to the file, the
annotation is assigned a handle. The handle represents where in the Annotation file
the annotation was written.
Finally, the annotation handle is written to the event and the event is written to the
Archive. The event contains the timestamp, value and handle to the associated
annotation.
PI Server Reference Guide Page 21
Chapter 3 - PI Server Databases
6. Annotation retrieval starts by accessing the event. The event is accessed by normal
PI-SDK data access, such as get plot values or get archive value. Annotations may be
quite large, so annotations are never returned by normal Archive access. The PI-SDK
represents events as timed values.
7. The PI-SDK timed value, if annotated, supports retrieving the annotation. Annotation
retrieval requires a call the PI Server, where the annotation handle is used to read the
annotation from the Annotation file and return it to the caller.
8. Annotations may be edited and posted back to the PI Server to replace an existing
annotation. This works like any Archive event edit, except the event is annotated.
Filling an archive will cause a shift of both the Archive and Annotation file; filling an
Annotation file will cause a shift of both the Archive and Annotation file.
Annotation files grow as annotations are added; they generally use significantly less
space than the Archive. On most systems the Archive fills before the Annotation file.
The annotation size is limited by the Event Queue page size, which has a default size of 1MB
and a maximum size of 8MB. You set Event Queue page size using the timeout parameter,
Snapshot_EventqueuePageSize.
Annotation file statistics are shown with the archive listing utility piartool –al. The following
is output from an archive listing:
Archive[0]: D:\PI\dat\piarch.033 (Used: 1.8%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: $]::
Version: 7 Path: D:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 1.7
Offsets: Primary: 20/65536 Overflow: 128673/131072
Annotations: 10826/65535 Annotation File Size: 434144
Start Time: 19-Oct-05 12:39:10
End Time: Current Time
Backup Time: Never
Last Modified: 19-Dec-05 13:10:32
In the above listing, the Archive file is d:PI\arc\piarch.033. The corresponding Annotation
file is d:PI\arc\piarch.033.ann. There are 10,826 annotations; with room for a total of 65,535.
This number is configurable with the parameter Archive_MaxAnnotations, which only
controls the number of annotations in the primary archive. Note however that Annotation
files are limited to 2GB in size. In the above example, the Annotation file is 434,144 bytes (or
424KB).
The Annotation file always is identical path and name to the archive with the .ann suffix. As
archives are loaded, Annotation files are loaded, using this naming convention. The
Annotation file is created if it does not exist. It is important the Archive and Annotation files
remain together—most importantly when a backed up archive is restored.
System management needs for Annotation files are simple—keep the Archive file
and corresponding Annotation file together:
• Archive backups should copy the Annotation file to the same backup location.
Page 22
3.5 - Digital State Table
• When an Archive is moved to a new location, move the corresponding
Annotation file to the same location.
• When an Archive file is deleted, delete the corresponding Annotation file to
avoid future name collisions.
3.5 Digital State Table
The Digital State Table contains the 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.
When retrieving digital state strings using the PI API, note that the state strings will be
truncated to 79 characters.
3.5.1 System State Set for All Points
The default set is called the System Digital State Set and contains over 300 digital states that
may apply to any tag. The following table describes some of these pre-defined digital states:
Table 3–1. Typical Digital States
State Use
I/O Timeout Interfaces use this state to indicate that communication with a remote device has
failed.
No Data Data-retrieval functions use this state for time periods where no archive values
for a tag can exist. 10 minutes into the future or before the oldest mounted
archive.
Under Range For float16 point types, this state indicates a value that is less than the zero for
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 A tag is given this state when it is created. This is the value of a tag before any
values have been put into the system for that tag.
Shutdown All tags that are configured to receive shutdown events get set to this state on
system shutdown.
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.
The System Digital State Set also contains all of the digital state strings found in the PI 2.x
Digital State Table. See the PI Server System Management Guide for details on how to get a
list of these.
PI Server Reference Guide Page 23
Chapter 3 - PI Server Databases
Note: The last possible state in the System Digital State Set (number 16383) is
reserved for the PI System’s internal usage. OSIsoft recommends minimizing
changes to the System Digital State Set. 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.
3.5.2 Defining a Custom Digital State Set
For a digital tag, there are typically only a small number of valid states. Before defining the
tag, a custom digital state set containing just those valid states is defined. When the tag is
defined, it is assigned the custom digital state set.
There is no need to include System states in custom sets because the System states contained
in the System state set will be used where needed by the PI Server. You may define up to
16383 state sets with up to 16383 states in each set.
For example, suppose a valve position is reported by an instrument system as having a digital
code value of 0 or 1. The value 0 means that the valve is closed, while the value 1 means the
valve is open.
Before configuring this tag, it is necessary to establish a digital state set with two strings,
CLOSED and OPEN. You might name it Valve Position. Other tags that also have states of
CLOSED and OPEN could be defined to use the same digital state set, Valve Position. Tags
that have states of ON and OFF would use a different digital state set, which you might have
called Switch Position.
The digital code value (0 or 1) is determined by the PI Server according to the position of the
state (digital state string) in the Digital State Table. The first value is 0 (zero), the second one
is 1, the third is 2, etc. This is termed digcode in PI API.
When retrieving state strings, PI API returns a maximum of 79 characters.
Editing the Digital State Table
The Digital State Table may be viewed and edited using the piconfig utility or the PI System
Management Tools (SMT), which are discussed in PI Server System Management Guide.
Changing a state string affects the retrieval of values already in the archive. If you change the
first state string in the example above from CLOSED to SHUT, all values in the archive are
reported with the new state string instead of the old one.
If you wish to affect only new values being received by the archive, you can define a new
state set and change the point attribute to use this new state set. In this example, values of 0
recorded before you change the DigitalSet point attribute have a value of CLOSED. Values
of 0 recorded after the point attribute edit will have a value of SHUT.
Deleting a Digital State Set
Once a set has been defined, it cannot be deleted. Attempting to delete a complete set will
result in a set named DIGSET_nn, where nn is the set number. This is to ensure that old
archive events can always refer to a valid set.
Page 24
3.6 - Timeout Database
Capitalization of Digital State Names
Like tags, digital state names are not case-sensitive. If you define a state with all capital
letters (for example OFF) then any later references to that state are not case sensitive (so off
or Off are valid references to your state set called OFF). for display purposes. Leading and
trailing blanks are removed from state names. Blank states are not allowed.
3.6 Timeout Database
The PI Timeout database, also called the Timeout Table contains a variety of PI Server
configuration parameters. Originally the PI Timeout database contained only timing
parameters, but other PI Server settings are now included in the Timeout database. In most
cases, the default values for these parameters are best, however in some situations you might
want to adjust one or more parameters to tune the PI Server performance.
3.6.1 Table of Configurable Timeout Database Parameters
The following table lists the Timeout Table Parameters that are configurable. To edit Timeout
database parameters, use piconfig or the Timeout Table editor in the PI System Management
Tools (SMT). Modifications to the Timeout Database will only be recognized upon restarting
PI.
Table 3–2. ConfigurableTimeout Parameters
Subsystem Name Min – Max Read Description
(Default)
All <subsysname>_Bac 30 – 86400 Periodically This is the maximum number of seconds
kupTimeout (1800) when in to remain in system backup mode. This
system timeout parameter only pertains to the
backup piartool –systembackup command,
mode which is used to take the audit databases
offline. The parameter has no effect for
VSS backups or non-VSS backups that
are started with the piartool –backup
command.
All <subsysname>_Thr 1–- startup only Size of the subsystem message thread
eadCount (4 threads) pool. Message threads are 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.
PI Server Reference Guide Page 25
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
All <subsysname>_Ma depend on startup only Limits the number of concurrent, identical
xThreadsPerClientQ value of queries from a client. The possible value
uery <subsysnam range depends on the number of RPC
e>_ThreadC threads for a subsystem. For example, if
ount the number of threads is 8, then the
(0) possible values range from -7 to 7.
A negative value means that the same
request from the same client can
consume all but that number of threads
concurrently.
A positive value means that the same
request from the same client can
consume a maximum of that number of
threads concurrently.
A value of 0 implies no limits.
When exceeding the number of
concurrent threads allowed, the client gets
the following error message:
“[-10767] Client exceeded maximum
concurrent queries in RPC thread pool.”
All SBHThreshold 0 – 1920 startup only Threshold for CRT library small block
(128 bytes) heap memory allocation
All <subsysname>_Writ 10 – 900 Startup only PI internally keeps track of the last
eModTimesToFileP (60 sec) modified date of most of the files that it
eriod needs to back up. The last modified times
for each subsystem are updated every
WriteModTimesToFilePeriod. The
smaller the period, the more accurate the
last modified time will be.
A complete list of backed up files along
with their last modified dates can be listed
with the piartool –backup –identify -
verbose command. For archives, the last
modified date can also be viewed with
piartool –al.
Note for Archive files:
When a value is written to a PI point, the
value is not actually written to the archive
until the archive cache is flushed. The
maximum period between archive flushes
is set with the
Archive_SecondsBetweenFlush timeout
parameter. After the cache is flushed, the
last modified time will be updated within
WriteModTimesToFilePeriod seconds.
Archive Archive_AutoArchiv - before every Automatic Archive file creation on shifts. If
eFileRoot (path + shift present, this parameter defines the path
name prefix) and file name prefix to be used for new
archives. Example: "C:\PI\arc\auto_"
Page 26
3.6 - Timeout Database
Subsystem Name Min – Max Read Description
(Default)
Archive Archive_BackupCut 01-Jan-70 – Before every Archives that contain data more recent
offDate NA backup than the Archive_BackupCutoffDate will
(01-Jan-70) be backed up. For example, if “*-30d” is
specified, then at least 30 days of data will
be backed up.
Archive Archive_BackupLea 5 – 86400 On backup Number of seconds before the predicted
dtime (1800 sec) startup archive shift that a non-VSS archive
backup may start. The PI Backup
Subsystem will wait up to 30 minutes for
the archive shift to complete. This timeout
parameter has no effect on VSS backups.
Archive Archive_BSTimeout 1 – 86400 Once a This timeout parameter is now obsolete.
(1800 sec) minute
Archive Archive_CacheClea 1 – Flush startup only Frequency at which read-only cache
nCycle Cycle cleanup operations are performed. Setting
(10 sec) this limit too low may affect the
performance of the Archive Subsystem.
Archive Archive_CacheHigh 100 – 200 startup only High cache cleanup threshold, in
PctLimit (110 percentage of the
percent) Archive_CacheRecordPool value.
Oldest cache records are deleted when
the read-only cache pool is above this
limit, regardless of
Archive_MaxIdleCleanCycles.
Archive Archive_CacheLow 20 – 100 startup only Low cache cleanup threshold, in
PctLimit (80%) percentage of the
Archive_CacheRecordPool value.
Oldest cache records stop being deleted
when the read-only cache pool is below
this limit.
Archive Archive_CacheReco 2048 – startup + Maximum number of archive cache
rdPool 1048576 end of each records for read access queries. The
(4 x ptcount flush cycle actual size of the read-only cache pool
records) may lower due to low physical memory
resources.
Archive Archive_CacheReco 4 – cache startup + Maximum number of archive cache
rdsPerPoint epool / 2 end of each records per point. In the default
(512 flush cycle configuration, up to 512 records may be
records) allocated to a single point.
Archive Archive_CacheTrim 1 – 75 startup only Percentage to trim the read and write
Percent (40 %) cache when low physical memory
resources are detected.
PI Server Reference Guide Page 27
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
Archive Archive_DataCoerci 0–3 startup only Error handling policy of archive event
onPolicy (0) coercion after point type changes. Archive
events are preserved (i.e. not modified)
when the type of a point is modified after
its creation. When clients request these
events, automatic data coercion is
performed. This parameter decides what
the Archive Subsystem should do when
this coercion fails. For more details,
please refer to the chapter “PI Point Type
Edit” on page 81.
Archive Archive_EventQueu 1 – 255 startup only This parameter is now obsolete in version
eThreadCount (5 threads) 3.4.370, a single Event Queue thread now
exists (see Archive_FlushThreadCount
below).
Archive Archive_FlushThrea 1 – 255 startup only Number of Flush threads responsible for
dCount (4 threads) saving write cache events to disk. These
threads communicate with the Event
Queue thread via a Flush Queue (see
also Archive_FlushQueueSize).
Archive Archive_FlushQueu 16 – 8192 startup only Size of the Flush Queue between the
eSize (256 flush EVQ (Event Queue) thread and the Flush
tasks) threads. A flush task is created when a
point’s write cache events must be saved
to disk. Increasing this parameter may
improve the archive write throughput in
some cases.
Archive Archive_LowDiskSp - once a Minimum amount of free disk space to
aceMB (256 MB) minute with leave on Archive file volumes. A dynamic
a dynamic primary archive will stop growing if this
primary limit is reached and a shift will be
archive + on triggered.
shifts when
Archive_Au
toArchiveFi
leRoot is set
Archive Archive_MaxAnnota 128 – startup only Maximum number of event annotations
tions 134217728 per Archive file (annotations are stored in
(65,535 the parallel file with the .ann extension).
annotations)
Archive Archive_MaxIdleCle 1 – 60 startup only Maximum idle time of archive cache
anCycles (2 flush records before being discarded. This
cycles) number is expressed in number of flush
cycles
(Archive_SecondsBetweenFlush).
Archive Archive_MaxWriteC 0 – 2,048 startup + Maximum number of write cache events
achePerPoint (256 events) end of each per point. Events of a given point will be
flush cycle flushed to disk when this limit is reached.
Page 28
3.6 - Timeout Database
Subsystem Name Min – Max Read Description
(Default)
Archive Archive_MinCacheR 1,024 – startup only Minimum size of the record pool when
ecordPool 102,400 doing cache trimming due to low-memory
(2,048 conditions.
records)
Archive Archive_MinMemAv 0 – 1,024 startup only Minimum amount of free physical memory
ail (10 MB) to leave for OS and other subsystems.
The Archive Subsystem will start trimming
its cache when physical memory
resources go below this or the
Archive_MinPercentMemAvail
percentage.
Archive Archive_MinPercent 0 – 50 startup only Minimum percentage of free physical
MemAvail (0%) memory to leave for OS and other
subsystems. The Archive Subsystem will
start trimming its cache when physical
memory resources go below this or the
Archive_MinMemAvail value.
Archive Archive_MinWriteCa 1 – 1,024 startup only Minimum number of write cache events
chePerPoint (8 events) per points when doing cache trimming due
to low-memory conditions.
Archive Archive_PointLockL 0 – timeout startup only Archive lock delay reporting option. By
ogging (5,000 ms) default, threads taking longer than 5
seconds to acquire a lock will report in the
message log. A value of 0 disables lock
time reporting.
Archive Archive_PointLockTi 1000 – startup only Maximum time RPC (query) threads can
meout 270,000 wait accessing archive points. Default is 2
(120,000 minutes (120 seconds).
ms)
Archive Archive_SecondsBe 1 – 86,400 startup only Archive cache flush cycle or maximum
tweenFlush (900 sec) time between consecutive disk flushes for
a given point.
Archive Archive_ShiftFreeTi 0 – 86,400 startup only Number of seconds to substract from the
me (1,800 sec) predicted time to determine the actual
shift time. Setting this parameter to
something greater than zero will leave the
corresponding free archive space (default
is 30 minutes). This parameter and/or the
Archive_ShiftRatio are useful on
systems where backfilling or out-of-order
events are expected.
PI Server Reference Guide Page 29
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
Archive Archive_ShiftRatio 4 – 2048 startup only Ratio of total records to free records at
(512 ratio) which archive shifts are triggered. The
inverse of this parameter defines the
percentage of free records to leave in
Archive files (default is 1/512 = 0.2%).
This parameter and/or the
Archive_ShiftFreeTime are useful on
systems where backfilling or out-of-order
events are expected.
Archive Archive_ShiftRecord 256 – 16384 before every Number of records to process in one
Count (2048 shift chuck during Archive file initializations.
records) When shifting or initializing new archives,
this parameter partly defines the speed of
archive initializations. However, setting
this parameter higher than the default may
impact system performance as more
memory will be consumed.
Archive Archive_WriteLockT 5000 – startup only Maximum time Flush (writer) threads can
imeout 900,000 wait accessing archive points. Default is
(270,000 4.5 minutes (270 seconds).
ms)
Archive ArcInsertRecOnOO 0–1 startup only Break the chain and insert new records
O (1 boolean) when out-of-order events need to be
inserted into full overflow records. When
set to 0 (false), this parameter makes the
Archive Subsystem to revert back to the
event cascading algorithm of PI 3.3 and
earlier versions.
Archive ArcMaxCollect - startup only Maximum number of compressed events
(15000 that can be retrieved by a single query.
events) This number does not affect interpolated
event retrieval or archive summary calls.
Archive BreakCrossRefOnD 0–1 startup only Break reference between UnitBatch and
elete (1 boolean) PIBatch on deletion of UnitBatch.
Archive Cache_FreelistSize 1000 – startup only Size of the list of reusable cache records
100000 that were discarded from the read-only
(10000 record pool. This parameter should only
records) be changed upon recommendation from a
technical support engineer.
Archive MarkArchiveGaps 0–1 startup only Return special "Arc Off-line" events when
(1 boolean) Archive files are taken offline or when time
gaps are detected in mounted archives.
The archive offline markers are primarily
useful to prevent any mis-interpolation of
data across missing archives.
Page 30
3.6 - Timeout Database
Subsystem Name Min – Max Read Description
(Default)
Archive piarchss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(100000
sec)
Archive BatchDb_MaxSearc -1 – startup only Maximum size (number of records) of
hRecords 1,000,000 batch queries returned by the Archive
(-1) Subsystem. Very large batch searches
can lead to performances problems with
the PI Archive Subsystem. This applies to
PIUnitBatches, PIBatches and
PICampaigns.
If set, exceeding the limit causes the
search to be terminated, no records
returned and the following error:
[-16029] Batch database search exceeded
maximum allowed records.
Archive BatchDb_SearchLo 1 – 365 startup only Controls the batch search look back
okBackDays (31 days) period. Batch searches are performed
internally this many days in the past from
the start time provided. This can be set
from 1 to 365 (days). The default value is
31 days (one month).
Backup Backup_ArchiveCut 01-Jan-70 – Before every If the cutoff date is not explicitly specified
offDate NA backup in arguments to the pibackup.bat backup
(01-Jan-70) script, then this timeout parameter defines
the default cutoff date. Archives that
contain any data between
Backup_ArchiveCutoffDate and current
time will be backed up. For example, if “*-
30d” is specified, then at least 30 days of
data will be backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict the
number of archives for backup. Whichever
timeout parameter is most restrictive takes
precedence.
Backup Backup_NumArchiv 1 – 1000000 Before every If the number of archives to be backed up
es (3) backup is not explicitly specified in arguments to
the pibackup.bat backup script, then this
timeout parameter defines the default
number of archives to be backed up.
Backup Backup_TraceLevel 0 – 1000 Startup only This is the default backup trace level.
(0) Non-zero backup trace levels cause
debug messages to be written to the PI
Message Log. The default trace level can
be overridden while the PI Backup
Subsystem is running with the piartool –
backup –trace <level> command.
PI Server Reference Guide Page 31
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
Base BatchDbEditLogging 0–1 startup only Logging of Batch Database edits and
(0 boolean) deletions to the message log. This
parameter does not apply to PIBatch
Subsystem and is superceded by the
Audit feature (EnableAudit) of the PI
Server.
Base ModuleDb_CleanPe 30 – 3600 startup only Frequency at which checks for idle
riodSec (300 sec) modules are performed. Setting this limit
too low may affect the performance of the
Base Subsystem.
Base ModuleDb_MaxIdle 0 – 604800 startup only Maximum idle time of MDb modules
CleanSec (3600 sec) before being unloaded from memory.
Checks are performed every
ModuleDb_CleanPeriodSec seconds.
Base pibasess 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(10000
µsec)
Base PointDb_CleanPerio 30 – 3600 startup only Frequency at which checks for idle points
dSec (300 sec) are performed. Setting this limit too low
may affect the performance of the Base
Subsystem.
Base PointDb_MaxIdleCle 0 – 604800 startup only Maximum idle time of PI Points before
anSec (3600 sec) being unloaded from memory. Checks are
performed every
PointDb_CleanPeriodSec seconds.
Base PointEditLogging 0–1 startup only Logging of point edits and deletions to the
(0 boolean) message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Base RecreateServerTrus 0–1 startup only Recreate missing trust entries for local
t (1 boolean) machine access. These trust settings are
used by SDK or API applications or
interfaces running on the server node.
Base WindowsAuthenticat 0–1 startup only Perform windows user authentication
ion (1 boolean) against a domain controller. This feature
should only be disabled upon
recommendation from a technical support
engineer.
Base, EnableAudit 0- startup only Auditing mask, -1 (or 0xFFFFFFFF)
Snapshot, 0xFFFFFFF enable the audit of all databases. See
Archive F Auditing the PI Server for details on
(0 bitmask) acceptable values.
Page 32
3.6 - Timeout Database
Subsystem Name Min – Max Read Description
(Default)
Batch pibatch 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000
µsec)
Message pimsgss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000
µsec)
NetManager backlog 5 – 1000 startup only Maximum number of pending TCP/IP
(5) connections.
NetManager connectionlocktimeo 1 – 1000 startup only Amount of time to wait for a connection
ut (90 sec) locked by another thread.
NetManager connectionwait 1000 – startup only Amount of time for a new TCP/IP
1000000 connection to become writable.
(30000
msec)
NetManager DefaultUserAccess 0–1 startup only Enable guest (or "world") access to the PI
(1 boolean) Server.
NetManager HealthCheckInterval 60 – 1000 startup only Frequency at which health checks are
(1800 sec) performed between NetManager and the
PI Subsystems. NetManager will close
connections if subsystems don't respond
to health checks.
NetManager keepalive -1 – 1 startup only TCP/IP keepalive option. A value of -1 is
(-1 sec) the system default, 0 indicates disabled.
NetManager linger_on 0–1 startup only Socket closure behavior (see
(0 boolean) linger_time).
NetManager linger_time 0 – NA startup only Time in seconds to linger on socket
(0 sec) closure, if linger_on is set
NetManager MaxMessageLength 10 – 512 startup only Maximum size of messages handled by
(256 MB) NetManager, PI3 Subsystems and PI SDK
applications.
NetManager maxzerobytereads 0 – 1000 startup only Assume a connection close when
(100 bytes) receiving a series of zero-byte messages.
NetManager minbufsize 1 – 1000 startup only TCP/IP send and receive buffers
(8 KB)
NetManager pinetmgr 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(10000
µsec)
PI Server Reference Guide Page 33
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
NetManager ReadCompletionTim 120 - startup only Amount of time to block for read
eout 0xFFFFFFF completion.
F
(300 sec)
NetManager readretry 1– startup only Maximum retry attempts on read stream
10000000 errors
(250)
NetManager readtimeout 1– startup only Read timeout on network I/Os
50000000
(50000
µsec)
NetManager reversenamelookupf 0–1 startup only Translate IP addresses to IP host names
lag (1) on new connections.
NetManager ThreadStackSize 0 – 10 startup only Stack of Net Manager worker thread. A
(0 MB) value of 0 means the same as
NetManager's main thread.
NetManager writeretry 1– startup only Maximum retry attempts on write stream
10000000 errors
(250)
NetManager writetimeout 1 – 5000000 startup only Write timeout on network I/Os
(50000µsec)
PESchedule pipeschd 1– startup only Subsystem wait time after every main loop
r 10000000 iteration.
(50000µsec)
Snapshot EditDays 0- startup only Number of past days where events can be
(0) modified in the Snapshot or Archive
databases. A value of zero means no time
check is done.
Snapshot pisnapss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(1000µsec)
Snapshot SnapFlushCycle 60 – 3600 startup only Snapshot table flush cycle or maximum
(900) time between consecutive flushes for a
given point.
Snapshot Snapshot_EventQu 64 – 8192 startup only Size of the memory pages from the
euePageSize (1024 KB) memory mapped Event Queue. This
number must be a multiple of 64.
Snapshot Snapshot_EventQu - startup only Path where the memory-mapped queues
euePath (path) are created (default is PI\dat). The primary
queue name is always pimapevq.dat and
overflow queues are pimq0000.dat,
pimq0001.dat ... pimqFFFF.dat.
Page 34
3.6 - Timeout Database
Subsystem Name Min – Max Read Description
(Default)
Snapshot Snapshot_EventQu 8 – 131072 startup only Size of the primary and overflow Event
eueSize (64 MB) Queues on disk. This parameter should
be adjusted according to archive event
rate to avoid the creation of overflow
queues.
Snapshot Snapshot_LowDisk - when Minimum amount of free disk space to
SpaceMB (256 MB) overflow leave when creating overflow Event
Event Queues (pimqXXXX.dat).
Queues are
created
Snapshot, ArchiveEditLogging 0–1 startup only Logging of event edits and deletions to the
Archive (0) message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Snapshot, Snapshot_EventQu 1 – 3600000 startup only Frequency at which the memory-mapped
Archive eueFlushPeriod (30000 queue is flushed to disk by the Snapshot
msec) and Archive Subsystems.
SQL pisqlss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000µsec)
Totalizer pitotal 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000µsec)
UpdateMan MaxUpdateQueue - startup only Maximum number of events per consumer
ager (4095) held in the Update Manager.
UpdateMan PIUPD_MaxConsTi 0 – 7200 startup only Maximum value of client-supplied cleanup
ager meout (0 sec) time for inactive consumer signups.
UpdateMan PIUPD_MinConsTi 0 – 7200 startup only Minimum value of client-supplied cleanup
ager meout (600 sec) time for inactive consumer signups.
UpdateMan PIUPD_TimeoutKill 0–1 startup only Remove timed out consumers in addition
ager Cons (0) to removing all pending events.
UpdateMan piupdmgr 1– startup only Subsystem wait time after every main loop
ager 10000000 iteration.
(12000
µsec)
UpdateMan TotalUpdateQueue - startup only Maximum number of events in Update
ager (100000 Manager for all consumers.
events)
Utilities CheckUtilityLogin 0–1 startup only Force an interactive login from console
(0) utilities (piconfig, pisetpass).
PI Server Reference Guide Page 35
Chapter 3 - PI Server Databases
Subsystem Name Min – Max Read Description
(Default)
Utilities piartool 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(1000µsec)
Utilities piconfig 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.
Utilities pigetmsg 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.
Utilities pilistupd 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.
Timeout Database Parameters for UNIX-based Systems
On UNIX-based PI Systems, the low-level I/O routines use several PI Timeout table
parameters. You might change the values of some of these parameters to get better
performance for the specific version of UNIX you are running, the size of the PI System and
so on.
The Timeout table parameters are stored in PI/dat/pitimeout.tbl. You can use piconfig to edit
the values of Timeout Table parameters. Modifications to the PITimeout Table do not go into
effect until PI is restarted.
The timeout table contains the entries shown below, where the time values are specified in
microseconds:
$ piconfig
* (Ls - ) piconfig> @table pi_gen, pitimeout
* (Ls - PI_GEN) piconfig> @ostructure name, value
* (Ls - PI_GEN) piconfig> @select name=*
(Ls - PI_GEN) piconfig> @endsection
piarchss,10000
piartool,1
pibasess,10000
pimsgss,12000
pinetmgr,3000
pipeschd,50000
pisnapss,1000
piupdmgr,12000
readtimeout,50000
readretry,250
writetimeout,50000
writeretry,250
piconfig,1
pigetmsg,1
pilistupd,1
Most of the entries define a messaging timeout for the PI subsystems and utilities.
The other entries in the PItimeout Table are used as follows.
Page 36
3.7 - Firewall Database
Readtimeout Time in microseconds to block in select call while reading and assembling a
message
Readretry Number of retries to attempt while reading and assembling a message. Retries
are attempted only on fatal errors, which are: EAGAIN, EWOULDBLOCK,
ENOBUFS, and EIO.
Writetimeout Same as readtimeout, except acts on send call
Writeretry Same as readretry but acts on send call
The following message in pinetmgr.log (PI 3.1 build 2.74 and later) indicates that the
READTIMEOUT or WRITETIMEOUT timing parameter reached the set limit.
PIstream::recv(SOCK_Stream *, int): select failed1 0
The following message in the application standard out indicates that the READRETRY or
WRITERETRY timing parameter reached the set limit.
PIstream::recv(SOCK_Stream *, int): max retries exceeded
3.7 Firewall Database
The PI Firewall is a security feature that allows the PI Server Manager to control access to the
PI Data Archive at the IP network address level. System administrators can allow or deny
access by specific computers this way. More information is available in PI Server System
Management Guide, Chapter 1, PI System Management.
3.8 Proxy Database
As of release 3.3, the Proxy Database is no longer in use. The Trust Database replaces it.
During upgrade, existing proxy entries are converted to trust entries.
3.9 Trust Database
The Trust Database is used to grant PI client application access to the PI Server
automatically. This is necessary for PI API and PI-SDK applications that run unattended,
such as interfaces. It also allows for PI-SDK applications to support single user logons. The
process authorizes the use of the access rights of a specific PI Server user.
The PI System Administrator creates records in the Trust Database, mapping credential
attributes such as Domain name, IP host name, IP address, Application name, and Operating
System Username to a PI user.
Trusts can be specified exactly or by allowing entry, for example, to a group of users from a
given domain.
The connecting application and PI Server obtain information about the client’s credentials.
During client connection, the Trust Database is scanned for a match with the client’s
PI Server Reference Guide Page 37
Chapter 3 - PI Server Databases
credentials. If a match is found, the application is granted the access rights of the specified PI
user.
It is possible that more than one trust record matches the incoming entry specifications. In
such cases, the entry that matches the entry most closely will be granted access.
See PI Server System Management Guide, Chapter 1, PI System Management, for more
details on configuring trust database records.
The Trust Database includes all the previously defined PIproxy records.
3.10 User Database
The PI User Database is where all PI users are defined. They may be assigned to groups.
Groups must already be defined in the PI Group Database. Passwords are also stored here.
Users maintain their passwords using the pisetpass utility.
3.11 Group Database
The PI Group Database is where all PI groups are defined. Members of each group may be
viewed here. Membership is assigned only in the PI User Database.
3.12 Module Database
The PI Module Database stores and maintains all the data objects associated with the Module
Database. This includes PIModules, PIHeadingSets, and PIHeadings. PIBasess maintains
this database. All access to the PI Module Database is provided by the PI-SDK.
3.13 Batch Database
The PI Batch Database is the database for the PI Batch objects supported by the PI-SDK. This
database is independent of the PI Batch Subsystem and the databases it maintains. The PI
Batch Database is actually part of the PI Archive and is therefore, maintained by the PI
Archive Subsystem. All access to the PI Batch Database is provided by the PI-SDK.
3.14 List of Database Files
The following table provides a list of database files for your reference. The files are
organized by the subsystem to which they belong.
PIbasess Databases
File name Description
pipoints.dat Point Database
Page 38
3.14 - List of Database Files
PIbasess Databases
piptattr.dat Attribute Set Database
piptclss.dat Point Class Database
pidigst.dat Digital Set Database
pidignam.dat Digital State Name Database
piusr.dat User Database
piusrgrp.dat Group Database
PIModuleDb.dat Pi Module Database
piusrctx.dat User Context Database
pitrstrl.dat Trust Database
piptunit.dat Database reserved for future use.
piptalia.dat Database reserved for future use.
piptsrcind.dat Point Source index file. This is an index that allows for quick lookup by
pointsource. This file is rebuilt automatically if it does not exist.
PIModuleUnitDb.dat Batch process unit index--an index of all modules with the IsPIUnit flag set
to true. Automatically rebuilt if it does not exist.
piptcomind.dat Index of com connector points. Automatically rebuilt if it does not exist.
PIMsgss Databases
pimsgtxt.dat Message text resource
pimsg_yymmdd.dat Message logs where “yymmdd” represents date covered by file
PINetmgr Databases
pifirewall.tbl Firewall database
pitimeout.tbl Timeout database
pisubsys.cfg Inter-process communication info file
pisysid.dat Identifier data file
PIShutev Databases
shutdown.dat Shutdown event configuration file
Pisnapss Databases
piarcmem.dat Snapshot database
pimapevq.dat Event queue
PI Server Reference Guide Page 39
Chapter 3 - PI Server Databases
PIbasess Databases
pilastsnap.dat Time of newest event
PISqlss Databases
pisql.ini Site specific initialization file
Pisql.res Parsing resource
Page 40
Chapter 4. PI POINT CLASSES AND ATTRIBUTES
A point is any measurement or calculation that is stored in the data archive. Points can
represent transmitter readings, manual inputs, status control limits, and so on.
Note: The terms point and tag are sometimes used interchangeably, but the tag is
actually the name of the point.
The configuration information for each point is stored as a list of attributes in the Point
Database.
4.1 About Point Classes
The Point Database has several different point classes, such as Base and Classic.
Point class is assigned when the point is created. Each point class has a different set of
attributes which define the parameters that describe a point. Default is Base point class.
The Base point class contains 39 attributes. Other point classes, such as Totalizer and Classic,
include more attributes, in addition to the 39 attributes from the Base point class. The
Totalizer Point Class is discussed in the PI Server Applications Guide.
Use the piconfig ptclass command to access the attributes belonging to a particular point
class. For example, to display the attributes of the Classic point class, you would type:
@table pipoint
@ptclass classic
@?atr
As a shortcut, you can specify the point class name while setting the pipoint table with a
single piconfig command:
@table pipoint,classic
The piconfig command ptclass is not to be confused with the attribute ptclassname.
4.2 Base Class Point Attributes
The Base class is a common set of attributes that all other point classes include. This section
describes the user-assigned base class point attributes. The Base class also includes a set of
system-assigned attributes that users cannot edit. See System-Assigned Attributes on page 55.
PI Server Reference Guide Page 41
Chapter 4 - PI Point Classes and Attributes
4.2.1 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, it’s a good idea to 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 6 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:
The first character must be alphanumeric, ‘_’, or ‘%’
No control characters are allowed; such as linefeeds or tabs
The following characters are not allowed:
* ’ ? ; { } [ ] | \ ` ‘ “
(However, these characters are allowed in other tag attributes, such as the descriptor.)
Any tags that follow the above rules are, technically, allowed. However, be aware some legal
characters, such as the ‘_’, are used by other applications in special ways. For example, SQL
uses ‘_’ as a wild card. Using these in tags, may cause problems with these applications.
Note: The PI API functions pipt_tag and pipt_updates truncate the tag to 12
characters. Routines pipt_findpoint, pipt_wildcardsearch, pipt_taglong, and
pipt_tagpreferred will 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.
4.2.2 PtClassName
The PtClassName attribute needs to be defined at point creation time. PtClassName defines
what attributes a point is to have. Prior to PI 3.4.370 the point class of a point could not be
changed once the point was created. In versions 3.4.370.x or greater it can be edited. See
Point Class Edit.
Page 42
4.2 - Base Class Point Attributes
4.2.3 PointType
There are many point types in the PI Server. PointType is assigned when the point is created.
Prior to PI 3.4.370.x this attribute could not be changed, but in versions 3.4.370 or later it can
be edited. See Point Type Edit.
Table 4–1. Point Types
Point Type How It Is Used
Digital Used for points whose value can only be one of several discrete states, such as
ON/OFF or Red/Green/Yellow. Nearest equivalent to the PI 2.x Digital type.
Int16 Used for points whose values are 15-bit unsigned integers (0 to 32767). Nearest
equivalent to the PI 2.x Integer type.
Int32 Used for points whose values are 32-bit signed integers (-2147450880 to
2147483647). PI reserves the lowest 32K values of the 32bit range for digital states.
Float16 Used for floating point values, scaled. The accuracy is one part in 32767. Nearest
equivalent to the PI 2.x Real type.
Float32 Used for single-precision floating-point values, not scaled.
Float64 Used for double-precision floating-point values, not scaled.
String Used to store string data of up to 976 characters.
Blob Binary large object – Used to store any type of binary data up to 976 bytes.
Timestamp Used to store values of type Timestamp. Any Time/Date in the Range 1-jan-1970 to
1-Jan-2038
Choosing Point Type
For points collected automatically, 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.
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 are coming from an analog-to-digital
converter (ADC); float16 is sufficient.
PI Server Reference Guide Page 43
Chapter 4 - PI Point Classes and Attributes
Use int16 or int32 for type I or integer values.
Use digital for type D or discrete values.
Float16 vs. Float32
OSIsoft recommends using float32 as the default type for floating point data. Only tags with
very large amounts of data (more than 1000 values per day) that is frequently retrieved should
be configured as float16, and their configuration should match the input device.
The space saving of float16 can reduce the amount of I/O. This is significant only on very
large data retrievals, for example yearly average calculations or long term trends. There is no
impact on the initial storage of incoming data.
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 zero.
For Digital, string and Blob type tags, the Span and Zero attributes are not
applicable. For digital tags, Zero and Span will be automatically set to the digital set
number and the number of states minus 1 in the set, respectively.
4.2.4 NewTag
The NewTag attribute is used for renaming tags.
4.2.5 Descriptor
The Descriptor is a text field that appears on various client application displays and may be
used in reports. It may be of any length up to 65,535 characters. When this value is read
through the PI API it is truncated to 26 characters.
Be aware that 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.
4.2.6 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 this attribute to encode
additional configuration information.
Page 44
4.2 - Base Class Point Attributes
4.2.7 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, and less than or equal to the
zero plus the span.
4.2.8 DigitalSet
Only Digital type tags use the DigitalSet attribute. It is irrelevant for other type tags and can
be ignored.
A collection of digital states is called a digital state set. For example, a digital state set can
consist of two states {OPEN, CLOSED}. You might also define a digital state set that
consists of {RED, GREEN, BLUE, YELLOW, and ORANGE}. Typically there will be 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. The DigitalSet attribute has no meaning for non-digital tags. However 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, I/O Timeout, etc.
4.2.9 Zero
A zero 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, it is recorded in the archive as
Under Range. The digital state is substituted for the under range value 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.
This attribute is not used for non numeric points.
4.2.10 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 attribute is not used for non numeric points.
4.2.11 Impact of Changing Zero and Span
The Zero and Span for a tag can be changed without affecting data already in the archive.
For points of type Float16, the old zero and span are used for retrieving the archive data
PI Server Reference Guide Page 45
Chapter 4 - PI Point Classes and Attributes
collected before the edit. The new zero and span are 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 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 Zero/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 Zero/Span configuration in other ways.
The PI Server itself does not change out of range data except for tags of type
Float16.
4.2.12 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 will retrieve only the first
12 characters. The PI-SDK does not truncate the string.
Examples include:
DEGF
Degrees Centigrade
Gal/Min
Gallons Per Minute
‘“Hg
Engineering unit strings are case preserving and case-insensitive. The system trims leading
and trailing blanks are trimmed during input.
A single quote (‘) in a string must be preceded by a double quote (“). Similarly, a double
quote in a string must be preceded by a single quote. Long strings can be used for more
readable engineering units.
4.2.13 PointSource
The PointSource attribute is a string that associates a tag with an interface or PI module. In
order for an interface to read or write to a point, the PointSource attribute must match the
point source setting for that interface.
The default point source is “Lab.” Use this for points that are not associated with any
interface to specify lab-input points.
The ‘%’ (percent) character has also special meaning for SQL and other applications. Using it
as a point source can lead to confusion. Similarly, it is advisable to avoid using ‘?’ or ‘*’ as
point source character.
4.2.14 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, then define another tag DEF
Page 46
4.2 - Base Class Point Attributes
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. If you try
to edit SourceTag for points of point-classes that do not have the attribute, you get an error.
4.2.15 ExcDev, ExcMin, ExcMax 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 (ExcMin), and a maximum time (ExcMax). 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 are changed at once ExcDevPercent takes precedence.
For digital, string and Blob tags, ExcDev and ExcDevPercent are ignored. They are
displayed by applications as zero.
4.2.16 Scan Flag
Some interface programs use a Scan flag. Interfaces that honor this attribute will not update
points whose scan flag is set to OFF. Refer to the documentation to see if your interface
program uses it.
4.2.17 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.
4.2.18 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 are written to the archive. This process is
called compression.
The compression specifications consist of a deviation (CompDev), a minimum time
(CompMin), and a maximum time (CompMax):
CompMin: An event is archived if the elapsed time since the previous event is
greater than or equal to the minimum time and the value has changed by more than
PI Server Reference Guide Page 47
Chapter 4 - PI Point Classes and Attributes
the deviation. For points associated with interfaces that send exception reports, the
CompMin should be 0.
CompMax: Events are also archived if the elapsed time is greater than the maximum
time. The recommended maximum time specification is one work shift (e.g., 8
hours). Duplicate values will be 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 at once
CompDevPercent takes precedence.
For non numeric tags, CompDev and CompDevPercent are ignored. They will be displayed
by applications as zero.
Out of Order Events
Events that are sent to the PI Server out of time order bypass the compression calculation and
are sent to the archive.
Turning off Compression
To turn off compression (that is, to archive every event), set the Compressing attribute to
OFF (0).
4.2.19 Archiving
The Archiving flag must 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.
4.2.20 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,
Page 48
4.2 - Base Class Point Attributes
A request for the value at 12:00:30 would return 101.0.
In general, data coming from continuous signals should be archived in points with the step
flag OFF. Examples might include signals from thermocouples, flow meters, etc. 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.
PtOwner , PtGroup, PtAccess, DataOwner, DataGroup, DataAccess
The access permission specifications allow restricted access to be configured independently
for both point attributes and point data. Users are defined in the PI User Database. Groups are
defined in the PI Group Database.
A PtOwner is assigned to own the point attributes. A DataOwner is assigned to own the data.
PtOwner and DataOwner can be the same. The default for both attributes is the creator of the
point.
A group is assigned to be the group for the point and for the data (PtGroup and DataGroup).
Read/write access permissions for owner, group, and world (default) are set using the
PtAccess and DataAccess attributes. Some examples of access permissions are:
o:rw g:rw w:rw (everyone can read and write)
o:rw g:r w:r (owner write; everyone read)
o:rw g:r w: (owner write; owner and group read)
See the Security section in PI Server System Management Guide for a full discussion on
security.
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 Format
3 23.450
2 23.45
1 23.5
0 23.
PI Server Reference Guide Page 49
Chapter 4 - PI Point Classes and Attributes
DisplayDigits Format
-1 2E+001
-2 23.
-4 23.45
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
will automatically add a shutdown event with the timestamp of the PI Server shutdown.
These events are called shutdown events.
The shutdown flag for a point is set to TRUE (1) to indicate that shutdown events should be
recorded for this tag. The default is TRUE.
For points collected from interfaces on distributed collection nodes, set this flag to FALSE
(0) because data buffering in PINet or PI API will retain 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 will 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.
4.3 Classic Point Class Attributes
Standard OSI interfaces rely on classic attributes. Use the Classic point class for all points
using a PI interface that uses the InstrumentTag or location code attributes.
4.3.1 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.
4.3.2 Location1, Location2, Location3, Location4, and Location5
There are five integer location codes. Their meaning depends 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. Refer to the
interface documentation to set these point attributes.
4.3.3 SquareRoot
Some interface programs use the square root code. Check the manual for your interface.
Page 50
4.3 - Classic Point Class Attributes
4.3.4 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.
4.3.5 Filtercode
The Filtercode indicates the time constant of a first-order filter used to smooth incoming
data. OSIsoft recommends not altering incoming data by leaving this code at its default value
of 0. The other options are:
Code Time Constant (Sec.)
1 10
2 60
3 120
4 600
4.3.6 Totalcode
The Totalcode was used by the PI System for OpenVMS to control Totalizer processing. PI
for Windows and UNIX do not use Totalcode. See Totalizer Subsystem in the PI Server
Applications Guide for instructions on configuring the Totalizer for PI for Windows and
UNIX.
4.3.7 Srcptid
This is the PI point number corresponding to the tag specified in the SourceTag attribute. If
this attribute is edited, PI will change SourceTag to the corresponding tag. This attribute
should not be altered directly; change SourceTag instead.
4.3.8 Convers
The Convers attribute was used by the PI System for OpenVMS to control Totalizer
processing. PI for Windows and UNIX does not use Convers. See Totalizer Subsystem in the
PI Server Applications Guide for instructions on configuring the Totalizer for PI for
Windows and UNIX.
4.3.9 Ranges of ExcMax and CompMax
In early releases of PI 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 will
continue to be true for existing systems upgraded to PI 3.3 or greater, but from PI 3.4.370.x
or greater these attributes can be edited to uint32 type. See Attribute Sets Database Edit.
In new installations of PI 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.
PI Server Reference Guide Page 51
Chapter 4 - PI Point Classes and Attributes
The PI API protocol defines the ExcMax 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 will
be 32,767.
PI-SDK applications will obtain from the PI Server a signed 32-bit integer values for
ExcMax and CompMax.
4.4 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 will then obtain data
from the foreign system point to which the PI Server point is mapped.
The PI Server does not use a specific value of the PointSource attribute to identify mapped
points. A specific point class name is not needed either. Instead, you must define a point class
that includes the following attributes:
Attribute Name Description
ctr_progid COM Program ID, as stored in the Windows registry. This
name is used to instantiate the COM Connector object.
ctr_lmap Longword mapping parameter.
ctr_strmap 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.
4.5 Default Values for Point Attributes
When you create a point, at a minimum you must specify the tag attribute. For all other
attributes, if you don’t assign a value to that attribute, then PI uses the default value. The
default values for PI point attributes are listed in the following table.
Page 52
4.5 - Default Values for Point Attributes
Table 4–2. Point Database Default Table
Point Default
Class Field Name Value Limits
Base Archiving On On, Off, 1, or 0
Base ChangeDate System-assigned
Base Changer System-assigned
Base CompDev 2 (eng units)
Base CompDevPercent Comes from CompDev 0 ≤ x ≤ 100
Base CompMax 28800 (sec) see next subsection
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
Base DataAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)
Base DataGroup Piadmin In PI Group Database
Base DataOwner Piadmin In PI User Database
Base Descriptor blank
Base DigitalSet no default Used only for digital tags This must
be specified when the point is
created.
Base DisplayDigits -5 -20 ≤ x ≤ 10
Base EngUnits blank
Base ExcDev 1 (eng units)
Base ExcDevPercent Comes from ExcDev 0 ≤ x ≤ 100
Base ExcMax 600 (sec) see next subsection
Base ExcMin 0 (sec) 0 ≤ x ≤ 65535
Base ExDesc blank
Classic Filtercode 0
Classic InstrumentTag blank
PI Server Reference Guide Page 53
Chapter 4 - PI Point Classes and Attributes
Point Default
Class Field Name Value Limits
Classic Location1 0
Classic Location2 0
Classic Location3 0
Classic Location4 0
Classic Location5 0
Base NEWTag
Base PointID System-assigned
Base PointSource Lab
Base PointType Float32
Base PtAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)
Base PtClassName Base Base, classic, Totalizer, alarm
Base PtGroup Piadmin In PI Group Database
Base ptOwner Piadmin In PI User Database
Base RecNo System-assigned
Base Scan On On, Off, 1, or 0
Base Shutdown True
Classic SourceTag blank
Base Span 100 x≥0
Classic SquareRoot 0 On, Off, or 0 <= x <= 10
Classic Srcptid 0
Base Step Off
Base Tag no default This must be specified when the
point is created.
Classic Totalcode 0
Base TypicalValue 50 Zero ≤ x ≤ (zero + span)
Classic UserInt1 0
Classic UserInt2 0
Page 54
4.6 - System-Assigned Attributes
Point Default
Class Field Name Value Limits
Classic UserReal1 0
Classic UserReal2 0
Base Zero 0
Other The Totalizer Point class includes
other attributes, which are discussed
in the PI Server Applications Guide,
Chapter 6, "Totalizer Subsystem."
Note: Programmatic access to some of the attributes may be limited or unavailable
from the PI API.
4.6 System-Assigned Attributes
When you create a point, several attributes are assigned by the system. You cannot change
the values of these attributes.
4.6.1 Creator
The user who created the point.
4.6.2 CreationDate
The date and time when the point was created.
4.6.3 Changer
The last user to edit the attributes for this point.
4.6.4 ChangeDate
The date and time when the attributes for this point were last edited.
4.6.5 PointID
The PointIdentifier is a unique number that identifies the point internally. PointID is never
reused, even when a point is deleted. This is the PI PointIDentifier 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.
4.6.6 RecNo
The record number is a read-only point attribute that 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 attribute.
PI Server Reference Guide Page 55
Chapter 5. PI POINT CLASS EDIT
5.1 Introduction
A PI point consists of a set of attributes. What attributes a point has is uniquely determined
by its point class. A PI point class consists of a group of PI point attribute sets, each of which
consists of some attributes. The attributes of a point is therefore built by grouping attributes
into attribute sets, and then grouping the attribute sets into a point class and assigning the
point to this point class. A PI point class cannot consist of attribute sets that have overlapping
attributes.
Figure 5-1. Formation of a point class
Point class is assigned to a point when it is created. Prior to PI 3.4.370 it was not possible to
change the attributes of a point once it is created and assigned to a point class. In PI 3.4.370.x
or greater users can edit and delete attribute sets and point classes.
PI Server Reference Guide Page 57
Chapter 5 - PI Point Class Edit
1. Attributes ExcMax and CompMax in base attribute set may now be edited from
uint16 to uint32.
2. It is now also possible to switch a point from one class to another, new or existing, so
that the same point can continue to collect data seamlessly even though its collection
mechanism has changed. For example, one can convert a Totalizer point to a PE
point, which belongs to classic point class, or vice versa, while keeping the same tag.
3. The user can also change the attributes of a point by adding or removing or changing
the types of attributes in the point class of the point. This affects all points that belong
to that point class.
4. By allowing addition, removal and edit of the attributes of point classes, we can
allow the same points to retain their history and continue to collect new data even
when the attribute requirements of the data collecting applications change.
5.2 Overview
Changing the attributes of a point can be accomplished as follows:
1. Edit the PtClassName attribute of the point to the point class that contains the
desired attributes.
2. Edit the point class directly so that it contains the desired attributes. A point class can
be edited by changing the attribute sets that make up the point class. That is, attribute
sets can be added to or deleted from it.
3. Edit the point class implicitly by editing one or more attribute sets that form the point
class. Editing an attribute set triggers edits of all point classes that use the set.
4. Editing a point class, implicitly or directly, triggers edits of all points in that point
class. Therefore a point’s attributes can be modified by editing one or more attribute
sets via implicit edits of point classes and points.
This chapter discusses in detail each of theses processes:
Editing an Attribute Set
Editing a Point Class
Editing the PtClassName Attribute of the Point
Only piadmin is allowed to delete and/or edit attribute sets and point classes. This restriction
was imposed to prevent cases where implicit point class and point edits might fail due to
varying ownerships and permissions.
Attribute sets and point classes may be edited or deleted only in stand alone mode in which
PINetmgr will close the TCP/IP listener and disallow any client connections. Existing PI-
SDK, PI API and PI Server Application connections will be closed, and reconnection
attempts refused for the duration of the stand alone mode. Subsystems and locally run utilities
such as piconfig and piartool can connect. Default-only attribute edits are supported in
Normal mode.
Page 58
5.2 - Overview
The command PIartool –standalone 1 puts the system in stand alone mode (no clients
can connect), and PIartool –standalone 0 sets it in normal operating mode. PIartool –
standalone 2 queries what mode the system is in.
There are some restrictions on which attribute sets and point classes may be edited or deleted.
Below is a summary of the restrictions:
Allow adding attribute(s) to any set except for the Base attribute set.
Note: Any attribute added to a predefined set cannot be removed due to rules
2b, 7a and 9a below: the predefined attribute sets are required by predefined
point classes and predefined point classes may not be deleted. So, they are
always in-use. It is recommended that the user create a new attribute set with
new attributes when expanding a point class rather than adding new attributes to
a predefined set. For the list of predefined attribute sets and point classes see
Appendix.
Allow deleting attributes from a set except from predefined sets (those created by
OSI) if they are required attributes
In-use attribute sets
Disallow renaming attributes
Allow renaming attribute sets except
• Predefined attribute sets
Allow deleting attribute sets except
• Predefined attribute sets
• In-use attribute sets
Allow adding attribute sets to any point class
Allow deleting attribute sets from a point class except from
• Predefined classes (created by OSI) if they are required attribute sets1
• In-use point classes
Allow renaming point classes except
• Predefined point classes
Allow deleting point classes except
• Predefined point classes
In-use point classes
These restrictions were imposed to protect the attribute sets and point classes that PI system
itself uses as building blocks. These restrictions can limit the user’s ability to easily undo
1 Predefined point classes and their required attribute sets are listed in the Appendix.
PI Server Reference Guide Page 59
Chapter 5 - PI Point Class Edit
some actions. To demonstrate how involved undoing some actions can be, suppose that a user
added an attribute set to a point class by mistake. In order to restore the original point class,
all the tags in this class need to be edited to belong to another class so that the class is no
longer in-use. Then the undesired attribute set can be removed from the point class. Finally,
the points can be edited back to the original point class.
It is CRUCIAL to make a backup of the point database before attempting to edit attribute sets
or point classes. One can delete attribute sets from predefined point class as long as the class
is not in use and the set to be deleted is not a required set for that point class. Remember that
any attribute added to a predefined attribute set cannot EVER be removed.
piconfig utility can be used to perform these edits and deletes after placing PI server in stand
alone mode using PIartool utility as discussed above. Examples are shown in the following
sections as appropriate.
5.3 Attribute Sets Database Edit
The following sub-sections discuss three operations that modify the PI Attribute Set database:
Attribute Set Create
Attribute Set Delete
Attribute Set Edit
5.3.1 Attribute Set Creation
An attribute set can be created by specifying the set name and the attribute names, types and
default values. If the type is not specified float32 is assigned. If default value is not specified,
it is set by PI. Allowed types and defaults (in parentheses) are listed below. Types not listed
below are not supported, and will either be rejected outright at attribute set creation time or
have unexpected 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”)
Page 60
5.3 - Attribute Sets Database Edit
Float32 (0)
Bool (0)2
Disallowed Attribute Names
The following attribute names are not allowed in any user-defined attribute set:
Built-in attribute names:
PointID
PtClassName
Recno
PtOwner
PtGroup
PtAccess
DataOwner
DataGroup
DataAccess
DigitalSet
Excdevpercent
Compdevpercent
SourceTag
NEWtag
Reserved names:
NEWCLASS
NEWSET
Set
Class
Base attribute names
Tag
Descriptor
exdesc
2 Note that Boolean values will show as either 1 or 0 instead of true or false. All non-zeros are interpreted as true,
and 0 is interpreted as false.
PI Server Reference Guide Page 61
Chapter 5 - PI Point Class Edit
typicalvalue
engunits
zero
span
pointtype
pointsource
scan
excmin
excmax
excdev
shutdown
archiving
compressing
step
compmin
compmax
compdev
creationdate
creator
changedate
changer
displaydigits
The built-in attributes are added to all points. Their types and defaults cannot be modified by
user. However, the values of non system-assigned attributes such as PtOwner, PtGroup,
PtAccess, DataOwner, DataGroup, DataAccess, DigitalSet, ExcDevPercent,
CompDevPercent, SourceTag and NEWTag can be modified by user.
Base attribute set is created by OSI and its edit is severely restricted. See Attribute Set Edit
for further details. Attribute name checks are case-insensitive.
Example of Creating an Attribute Set
Below is an example of how to create an attribute set in piconfig utility. Stand alone mode is
not required for creating an attribute set.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
Page 62
5.3 - Attribute Sets Database Edit
@istru ...
MyAttributeSet
MyAttribute1,BYTE,
MyAttribute2,int32,2
MyAttribute3,string,”Default string”
MyAttribute4,,
@ends
MyAttribute4 will be assigned the type float32, and default of 0.0. The
following lists the attribute set just created.
@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...
*----------
5.3.2 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 of Deleting an Attribute Set
An example of how to remove an attribute set is given below.
First place the system in standalone mode using PIartool in command window.
PIartool –standalone 1
Then launch piconfig in command window, and type the following.
PI Server Reference Guide Page 63
Chapter 5 - PI Point Class Edit
@table piatrset
@mode delete
@istru set
MyAttributeSet
@ends
When finished place the system back in normal mode.
PIartool –standalone 0
5.3.3 Attribute Set Edit
An attribute set can be edited by adding, removing attributes and/or changing attribute types
and default values.
Edits other than default-only edits require that the system be put in Stand Alone mode by
running piartool utility as follows.
PIartool –StandAlone 1
PIartool –StandAlone 0 puts the system back in Normal mode. Default-only edits do not
require stand alone mode.
Internally, an attribute set edit (except for default-only edits) is actually done in 4 steps:
Rename the original set to a temporary name, “OriginalName~someGUID”.
Create a new set with desired attributes under the original name.
Trigger implicit point class edits, which in turn will trigger implicit point edits.
Remove the original set from the database after successful implicit edits.
These steps are transparent to the user, but each of these steps is audited if auditing is enabled
for the base subsystem.
Default-only edits modify the existing sets directly instead of following the above steps.
Default edit triggers implicit point class edits but point edits. This is because the new defaults
will only be applied to new points. In the rest of this document an edit implies non default-
only edits unless explicitly 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 referred to as implicit edits.
Implicit point edits keep the existing attribute values if they are still in the edited attribute set
that triggered the implicit point edit and are compatible with the new types. If the new
attribute type is not compatible with the old one, the new default takes precedence over the
existing attribute’s value. This situation can arise if the old attribute’s type changed, for
example, from string to int32. If the original string value of the attribute cannot be converted
to an int32, the new default for this attribute type will prevail. Another example is the case
the existing value no longer fits in the new type. For example, if the type changed from
float32 to BYTE, and the existing value was 128.0, then the value will be set to 0.
Page 64
5.3 - Attribute Sets Database Edit
Note that implicit point edit does not validate the point configuration. That is, if a point with
improper configuration (e.g. a Totalizer point with no sourcetag) is implicitly edited, the
implicit edit will succeed although direct edit of the point would have failed validation.
In implicit point edits, additional, if any, attributes are assigned default values until the user
explicitly edits them later. That is, consider a point belonging to a class with base attribute set
and another attribute set called MyAttributeSet. Suppose that MyAttributeSet originally
contained MyAttribute1, MyAttribute2, and MyAttribute3, but was edited to include another
attribute called MyAttribute4. The point will be implicitly edited and will now have the
additional attribute MyAttribute4. This attribute will be set to the default by the implicit edit
process.
Base Attributes and Allowed Types
Base attribute set edit is disallowed except to convert the types of CompMax and ExcMax
attributes from uint163 to uint32 and to change the default values of any attributes in this set.
Name Allowed type
Descriptor String
Exdesc String
Typicalvalue float32
Engunits string
Zero float32
Span float32
Pointtype ubyte
Pointsource string
Scan uint16
Excmax uint16 or uint32
Excdev float32
shutdown byte
Archiving byte
Compressing byte
Step byte
Compmin uint16
3 PI versions earlier than 3.3 were shipped with uint16 type for excmax and compmax.
PI Server Reference Guide Page 65
Chapter 5 - PI Point Class Edit
Name Allowed type
Compmax uint16 or uint32
Compdev float32
Creationdate timestamp
Creator uint16
Changedate timestamp
Changer uint16
Displaydigits byte
Built-in Attributes
Built-in attributes are part of every PI point, but do not belong to any particular attribute set.
The types and defaults of built-in attributes, which are frequently mistaken as belonging to
the base attribute set, do not belong to any attribute set explicitly and cannot be edited. This is
not to say that individual point’s built-in attribute values cannot be edited. Non system-
assigned attribute values may be edited.
Example of Editing an Attribute Set
If an attribute set is edited, its dependent point classes and, subsequently, dependent points
are edited internally by the PI Base Subsystem. No explicit editing of the PI point classes
database by a user is necessary. Such indirect edits are henceforth referred to as implicit edits.
To illustrate, suppose a user wishes to change a set called MyAttributeSet. First place the
system in stand alone mode using piartool utility.
PIartool –standalone 1
List the existing attributes in 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 show as follows.
MyAttribSet
MyAttrib1,Int32,22
MyAttrib2,BYTE,0
MyAttrib3,Float32,5.
To change the attribute MyAttrib2 to type String and add another attribute, MyAttrib4 of type
uint16 in PIConfig:
@table piatrset
Page 66
5.3 - Attribute Sets Database Edit
@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:
@table piatrset
@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
Editing an attribute set works just like PI digital set edit. Attribute name, type and default
should all be explicitly redefined. If a pre-existing attribute is not specified in the new
definition, it will be permanently removed from the set. If the user had not wanted to edit the
existing attributes, but only wanted to add a new attribute MyAttrib4, he still would have had
to specify all attributes in his definition. That is, doing the following
@table piatrset
@mode edit
@istru set
@istru attrib,type,default
@istru …
MyAttribSet
MyAttrib4,uint16,1
@ends
would have produced MyAttribSet containing only one attribute, namely MyAttrib4.
If an attribute set is edited, and its pre-existing attribute name is specified, but not the type
and default, float32 and value 0.0 will be assigned overwriting the original type and default.
If only the type is specified by the user, a new default will be assigned even if the type is
identical to the previous one. The default of MyAttrib3 attribute was changed to 0.0 from the
original 5.0 because it was not explicitly specified in the edit.
When done with the edit, place the system back in normal mode so that applications can
connect.
PIartool –standalone 0
PI Server Reference Guide Page 67
Chapter 5 - PI Point Class Edit
Renaming an attribute set does not trigger any implicit edits of point classes or points and
does not require standalone mode either.
Restrictions on Attribute Set Edit
All restrictions are delineated in the beginning of this chapter. To repeat a few, attributes may
be added to any attribute set, including the predefined sets, except for the base attribute set;
Removing attributes in an attribute set that is in use is not allowed; Removing attributes in a
predefined attribute set is not allowed; Renaming a predefined attribute set is not allowed.
Informational Messages
Messages such as will not be directly returned to the edit initiating application (e.g. piconfig)
are sent to the PI Message subsystem. Examples of these messages are information regarding
the status (success or failure) of 4 steps involved in edit (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, etc. These messages are useful in verifying that the steps are
carried out correctly during the edit.
Rollback
Attribute set edit triggered point class edits, and their dependent point edits are all committed
to disk as they occur. If an error occurs during implicit edits the remaining edits are aborted.
Those edits that already succeeded are rolled back, and the original set is restored. Then the
user can resolve the cause of the edit failure and re-edit.
Note: In rollback all implicitly edited point classes and points are reconstructed from
the original attribute set which is still in the database under a temporary name. Since
no attribute may be removed from its set if the set is in use, the original attributes
should have remained in the set and retained their values in implicit point edits
unless the new type and original type were incompatible and the values had to be
set to the new defaults. In such a case, the original attribute values of the affected
points cannot be recovered.
Successful rollbacks are audited if the base subsystem is enabled for auditing4. Like any other
types of edits, unsuccessful rollbacks are not audited.
Regardless of success of the rollback the error for the failed edit will be returned to the user.
Additional messages may be found in PI message log.
If the rollback fails an error is logged in PI Message log, and the rollback is aborted. PI points
database may end up with some points belonging to the original point class (under a
temporary name) and others to the new point class (under the original class name) containing
the new attribute set. The cause of the rollback failure needs to be resolved and then the
4 Any action that changes an attribute set, a point class or a point in the database will be audited if auditing is
enabled and the edit was successfully completed.
Page 68
5.3 - Attribute Sets Database Edit
system needs to be restored manually. This can be done by using a good system backup or by
following the procedure outlined in the next section. Once the system is restored, the user can
resolve the cause of the actual edit failure and then re-edit.
System Restore Procedure after Rollback Failure
In general, these steps can be taken to restore the system to the original state. Note that
whether it is implicit edit or direct edit, the original set or class would have the temporary
name (original name~GUID) and the new set or class the original name and the edited
attributes.
1. Fix the cause of the rollback failure first (e.g. PI Snap Subsystem down, global lock
re-acquisition failure, etc.). More on lock re-acquisition failure later in thread-safety
section.
2. If some implicit edits (of point classes and points) already completed successfully,
start with points. Then fix the point classes, and lastly the attribute set.
3. Edit the ptclassname attribute of the implicitly edited points to the original point
class with the temporary name. When done with this step, there should be no points
belonging to the new point class.
4. Remove the new point class.
5. Rename the original class from the temporary name to the original name.
6. Remove the new attribute set.
7. Rename the original set from the temporary name to the original name.
8. Internally the points refer to their point classes by their unique IDs, and the point
classes refer to the attribute sets by their IDs. After renaming point classes their
dependent points should correctly refer to the new names.
9. Once the system is in its original state, determine the cause of the edit failure and fix
it. Then re-edit the attribute set. This procedure should cover most failure cases. If
this procedure doesn’t seem to cover your particular situation please call OSI
Technical Support.
As mentioned earlier if a predefined set gets stuck with undesirable attributes they can not be
deleted. This is because each predefined set is one of the required attribute sets in at least one
predefined point class which cannot be removed. Since the set is required, it cannot be
removed from the point class, and therefore is always in use. Attributes may not be removed
from in-use attribute set. In order to add more attributes to a point class, it is better to create a
new attribute set and add that attribute set to the target point class rather than adding the
attributes to one of the existing member attribute sets of the point class, especially if that set
is predefined.
To remove undesired attributes from a non-predefined attribute set:
1. Create a new set with the desired attributes.
2. Create new point classes that include this attribute set, and edit the dependent points
to belong to these new classes so that the set and classes to be fixed are not in use.
PI Server Reference Guide Page 69
Chapter 5 - PI Point Class Edit
If keeping the original attribute set name or point classes is not important user can stop here
and just delete the original point classes and the attribute set. If it is necessary to keep the
original set and the point classes, continue.
1. Edit the original dependent point classes to exclude the set that contains undesired
attributes.
2. Edit the original attribute set removing the undesirable attributes.
3. Add this set back to the original point classes.
4. Edit the points back to the original classes.
Once the dependent points are all converted back to the original classes in the previous step,
the interim point classes and the set created in step 1 and 2 can now be deleted.
5.4 Point Classes Database Edit
Indirect (i.e. implicit) edit of PI point class database was discussed in the Attribute Set Edit
section. Point class database can also be directly modified by a user via one of the following
three operations: creation, deletion and edit.
5.4.1 Point Class Creation
Once a new point class is created, the user can start assigning points to this class.
A point class is created using piconfig by specifying which attribute sets to include. This
does not require standalone mode.
All point classes must include the base attribute set.
Example of Creating a Point Class
In piconfig
@table piptcls
@mode create
@istru class
@istru set,...
MyPtClass
Base,MyAttribSet
@ends
5.4.2 Point Class Deletion
Predefined point classes (see Appendix) may not be deleted.
In-use point classes may not be deleted.
Example of Creating a Point Class
In command window
PIartool –standalone 1
Page 70
5.4 - Point Classes Database Edit
In piconfig
@table piptcls
@mode delete
@istru class
MyPtClass
@ends
Back to normal mode.
PIartool –standalone 0
5.4.3 Point Class Edit
A point class can be explicitly edited by adding/removing attribute sets that form the point
class.
piconfig version 3.4.370.x or higher 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 currently being used to form the
point class.
If there are problems with getting the set names, this operation will return an error but it will
also return as many set names as it can get with the failing set’s name replaced with “???”
(without the quotes). This allows for editing the class to remove the problematic set as a
means to fix a corrupted database.
Internally a point class edit is carried out in four steps:
1. Rename the original point class to a temporary name. It is constructed by
concatenating the original name with a GUID e.g. OriginalName~GUID.
2. Create a new point class with desired attribute sets under the original name.
3. Edit the points that belong to the point class to belong to the new class.
4. Remove the original point class from the database after successful implicit point
edits.
These steps should be transparent to the user if all steps complete successfully.
Example of Editing a Point Class
If 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
PI Server Reference Guide Page 71
Chapter 5 - PI Point Class Edit
MyPtClass
base,classic
*----------
Let’s add attributes MyAttribute1 (string) and MyAttribute2 (int32) to this point class. In
order to do this, create an attribute set, say MyAttributeSet, as follows.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
@istru ...
MyAttributeSet
MyAttribute1,string,my default string
MyAttribute2,int32,22
Then check it 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...
*----------
Edit MyPtClass to include this attribute set. The system needs to be in standalone mode. Type
the following in command window.
PIartool –standalone 1
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
Check that these attributes now form MyPtClass. You should see
* (Ed - 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
Page 72
5.4 - Point Classes Database Edit
base,classic,MyAttributeSet
*----------
To see all attributes that are in this point class type the following.
@table pipoint
@ptclass MyPtClass
@?atr
The following list will appear
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 - descriptor String D: C:
18 - DigitalSet String D: system C:
19 - displaydigits BYTE D: -5 C:
20 - engunits String D: C:
21 - excdev Float32 D: 1. C:
22 - Excdevpercent Float32 D: 1 C:
23 - excmax Uint32 D: 600 C:
24 - excmin Uint16 D: 0 C:
25 - exdesc String D: C:
26 - filtercode Int16 D: 0 C:
27 - instrumenttag String D: C:
28 - location1 Int32 D: 0 C:
29 - location2 Int32 D: 0 C:
30 - location3 Int32 D: 0 C:
31 - location4 Int32 D: 0 C:
32 - location5 Int32 D: 0 C:
33 - myattribute1 String D: my default string C:
34 - myattribute2 Int32 D: 22 C:
35 - PointID Int32 D: 0 C:
36 - pointsource String D: Lab C:
37 - pointtype String D: Float32 C:
38 - PtAccess String D: o:rw g:r w:r C:
39 - PtClassName String D: MyPtClass C:
40 - PtGroup String D: piadmin C:
41 - PtOwner String D: piadmin C:
42 - Recno Int32 D: 1 C:
PI Server Reference Guide Page 73
Chapter 5 - PI Point Class Edit
43 - scan BYTE D: 1 C:
44 - shutdown BYTE D: 1 C:
45 - SourceTag String D: C:
46 - span Float32 D: 100. C:
47 - squareroot Int16 D: 0 C:
48 - srcptid Int32 D: 0 C:
49 - step BYTE D: 0 C:
50 - totalcode Int16 D: 0 C:
51 - typicalvalue Float32 D: 50. C:
52 - userint1 Int32 D: 0 C:
53 - userint2 Int32 D: 0 C:
54 - userreal1 Float32 D: 0. C:
55 - userreal2 Float32 D: 0. C:
56 - zero Float32 D: 0. C:
Place the system back in normal mode.
PIartool –standalone 0
Restrictions on Attribute Set Edit
Some restrictions on point class edits are:
Edited point class should still contain the base attribute set.
Any attribute set may be added to a point class.
Attribute sets may not be deleted from in-use point classes.
Required attribute sets may not be deleted from predefined point classes even if they
are not in use.
Predefined classes may not be renamed.
If the sets in the point class edit definition are not different from the existing ones,
then no further action is taken and success status is returned. If the attributes of one
or more attribute sets have changed, the attribute set edit itself should have taken care
of implicit point class - and point edits.
Renaming a point class does not trigger any implicit edits of points.
Informational Messages
Messages such as will not be directly returned to the user are sent to the PI Message
subsystem. Examples of these messages are information regarding the status of four steps
involved in point class edit (rename the original class, add a new class, implicitly edit
dependent points, remove the original class) and the number of dependent points found, etc.
Rollback
As in the case of an attribute set edits point class edit triggers implicit point edits. If an
implicit point edit fails, all previously successful implicit point edits are rolled back. New
class is deleted, and the original class’s name is restored.
Page 74
5.4 - Point Classes Database Edit
System Restore Procedure after Rollback Failure
If an implicit point edit fails the rest of the edits are aborted. The old class is left in the
database under the temporary name, and the new class will remain also. The edit will return
failure status. Where possible, the failing point name and error description will be returned as
well.
Restoring the system to its original state requires similar procedure as outlined in Attribute
Edit rollback section.
1. First, fix the cause of the rollback failure. For example, if it failed because of
Snapshot Subsystem being off-line, the following repair procedure cannot be carried
out anyway.
2. It may be possible after this step to just edit the remaining points manually to the new
point class. If that is not possible, all dependent points should then be edited to
belong to the original class under the temporary name. Remove the new point class.
3. Rename the original class from the temporary name to the original name. If this is
impossible, restore from backup.
4. Identify the cause of the edit failure and fix it. Then re-edit the point class.
In PI 3.4.370 or greater PIConfig can display the attribute sets that form a point class.
Previously, it had only been possible to display the individual attributes in a point class. The
sets are listed by name. Note that the operation edit in piconfig actually makes two calls, one
for a listing the current set IDs and a second call to do the edit. As long as there are no errors
returned for edit itself, messages like below just means this point class’ original set IDs
contained a set ID (110 in this case) that refers to a set that does not exist anymore5, but the
edit succeeded.
* (Ls - PIPTCLS) PIconfig> @mode edit
* (Ed - PIPTCLS) piconfig> @istru class
* (Ed - PIPTCLS) piconfig> @istru set,...
* (Ed - PIPTCLS) piconfig> Totalizer2
*> Totalizer2
* (Ed - PIPTCLS) piconfig> testatrset,base,totals
*> testatrset,base,totals
Warning: error getting point class' set name list:
*** Start of PIvariant dump ***
setid 110 [-12002] Code Not Found in PInt
*** End of PIvariant dump ***
5 This scenario is unlikely, but if it ever happens, it can be rectified by editing the class.
PI Server Reference Guide Page 75
Chapter 5 - PI Point Class Edit
5.5 Editing a Point’s Point Class Attribute
In some cases, it is more desirable to modify the value of point’s ptclassname attribute (of
type string) to another point class rather then editing the point class it belongs to. A PI point’s
ptclassname attribute edit is supported just as any other point edit.
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 get removed.
The reason is that a point class edit disallows removing any attributes if there are any
dependent points. This effectively prevents points losing existing attributes inadvertently.
However, if the 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 a point’s ptclassname attribute is changed, the new point class’ attributes will be
compared against the existing ones. New attributes will be added and set to default values.
Existing ones will be copied if they are in the new point class. Compatible types retain their
values and incompatible types are set to new defaults value. Attributes that do not belong to
the new point class are removed.
When editing a point via piconfig new attributes can be modified simultaneously. That is, it
is ok 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
needs to 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 follows.
@table pinpoint
@ptclass Totalizer
@mode edit
@istru tag,ptclassname,location4,pointsource
The following error will be 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 location4 attribute. Set the environment to the target point class, Classic,
by using @ptclass Classic first if you want to edit the ptclassname attribute and new
attributes unique to the target point class at the same time.
@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
@ptclass classic
is not necessary since ptclassname is a built-in attribute and every point has this attribute.
Page 76
5.6 - Point Database Audit
Point class of a point can be edited using piconfig in PI 3.4.370 or higher.
5.5.1 Conversion of CC Class to and from a Native PI Class
A 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, PI needs to be aware of the cutoff times and go to the correct source. The
possibility that the conversion may occur multiple times adds to the complexity.
As of PI3.4.370.xx, history of the conversions is ignored and data request will be directed to
the current data source.
5.6 Point Database Audit
Both Attribute Sets and Point Classes have been added to the Audit database. EnableAudit
parameter in PITimeout Table bit6 will be used for Attribute Sets audit database and bit 4 for
Point Classes audit database. Note that audit records will cascade if dependent point classes
and points are implicitly edited.
Database Bit Value to Enable
(decimal)
Point DB 0 1
Attribute Sets DB 2 4
Point Classes DB 4 16
See Auditing chapter for more details.
A new attribute set create generates an audit record.
An attribute set delete generates an audit record.
Each step involved in editing an attribute set will be audited. That is, renaming the
original set to a temporary name, adding a new one under the original name, implicit
point class and point edits, removing the original set will all be audited. In default-
only audit, however, only the set edit, and implicit point class edits are audited as the
original set and classes are not renamed and no implicit point edits are triggered.
A failed operation does not produce an audit record since the DB is not changed. This
means that if there is an error at any stage in the 4 steps involved in an edit, the audit
trail will stop at the audit of the previous successful step. Any changes to the
database during the rollback, however, will be audited.
A new point class create generates an audit record.
6 Starts from 0.
PI Server Reference Guide Page 77
Chapter 5 - PI Point Class Edit
A point class delete generates an audit record.
Each step involved in editing a point class (renaming the original to a temporary
name, adding new one with the desired attribute sets, implicitly editing dependent
point, and then removing the old one) will be audited.
Just as in the attribute set edit a failed operation does not produce an audit record
since the DB is not changed.
5.6.1 Audit Records
The following are Audit Record and Change Record Definitions for attribute sets database
edit.
PI Point Attribute Sets DB
Audit Record Definition
Field Description
PI UserName User who made change
Action Time Time and Date of change
PI Database PIPointAttributeSets
Audit Action Add, Remove, Edit
AuditRecordID Unique ID assigned to audit record
DB RecordName Name of affected attribute set
DB RecordID Affected record ID in database (set ID)
Changes Table of specific changes
Change Record Definition
Property Before After
New_attribute NULL New default
Deleted_attribute Old default NULL
Modified_attrib Old default New default
The name of the attribute set is treated as if it was an attribute and is shown as Name item.
The audit DB exported in XML format also indicates what type the attribute’s value is.
The following are Audit Record and Change Record Definitions for point classes database
edit.
Page 78
5.6 - Point Database Audit
PI Point Classes DB
Audit Record Definition
Field Description
PI UserName User who made change
Action Time Time and Date of change
PI Database PIPointClasses
Audit Action Add, Remove, Edit
AuditRecordID Unique ID assigned to audit record
DB RecordName Name of affected point class
DB RecordID Affected record ID in database (point class ID)
Changes Table of specific changes
Change Record Definition
Property Before After
New_attribute NULL New default
Deleted_attribute Old default NULL
Modified_attrib Old default New default
The name of the point class is treated as if it was an attribute and is shown as Name item.
PI Points DB
Audit Record Definition
Field Description
PI UserName User who made change
Action Time Time and Date of change
PI Database PIPoint database
Audit Action Change action: Add, Remove, Edit
AuditRecordID Unique ID assigned to audit record
DB RecordName Name of affected point
DB RecordID Affected record ID in database (PI point ID)
Changes Table of specific changes
PI Server Reference Guide Page 79
Chapter 5 - PI Point Class Edit
Change Record Definition
Property Before After
New_attrib_name NULL Default
Deleted_attrib_name Old value NULL
Edited_attrib_name Old value New value
5.7 Thread-safety
Attribute set and point class edits rely on the locking mechanism at the global level for thread
safety. Both of these edits lock the entire points database, and it will not be accessible to the
user. That is, two users cannot simultaneously initiate attribute sets and or point classes.
Point edits, however, get the lock (same global lock as attribute set edits and point class edits)
per point basis. To be more specific, a point edit thread releases the global lock while it
updates the Snapshot, and re-acquires it when the snap update is completed. While the thread
is waiting for the synchronous RPC to PI Snap subsystem to return, the point’s edit status flag
is set, and no other thread can edit the point. If another thread has acquired the lock in that
time, the point edit thread cannot re-acquire the lock and the point edit fails.
This temporary lock release mechanism during point edit was implemented to optimize PI
Base Subsystem’s performance and ensure other requests can still be serviced should the
synchronous RPC to update PI Snap take a long time.
Because of this mechanism, it is possible that while an implicit point edit is in progress it
releases the lock, another (but explicit) point edit acquires the lock, and the implicit point edit
as well as all remaining implicit edits fail or vice versa. The scenario described above is
rarely anticipated, but the users should be aware of it, and should NOT attempt to initiate
both attribute set or point class edits and explicit edits simultaneously. Since client
applications ore remote piconfig sessions cannot connect while the system is in stand alone
mode, this situation can be easily avoided if the administrator does not simultaneously launch
multiple point edits and point class edits simultaneously in parallel (local) piconfig sessions.
Page 80
Chapter 6. PI POINT TYPE EDIT
6.1 Introduction
In PI 3.4.370.x or greater a point’s type can be edited just like other attributes. That is, if
listing the point's type as shown below shows the point type as int32,
@mode list
@ostru tag,pointtype
@istru tag
MyTag
only the following operation is needed in piconfig to change its point type to float32.
@mode edit
@istru tag,pointtype
MyTag,float32
@ends
Under the hood, changing a point’s point type causes the Archive Subsystem to close the
current archive record and start a new one with the new type info in the header.
When a point’s pointtype attribute is changed, already archived history of the point will not
change unless the archive is processed off-line. Off-line archive processing will actually
convert the old type events to events of the new type. This allows the user a choice between
keeping the old data type events and converting them all to the new type.
Upon archive record activation, the old type event will be coerced to the new point type if
possible.
If the value does not fit in the new point type, Coercion Failed digital state will be returned
by default. If Archive_DataCoercionPolicy parameter (see below) is defined in PI timeout
table, an appropriately translated digital state will be returned. PI Server does not log a
warning in PI Message subsystem upon point type edit.
Also if the current Snapshot value cannot be coerced to the new type at the time of the point
type edit, the edit will fail even though the value will actually be archived in the record of the
old type. The point will remain the previous type, and the archived data will look as before.
However, piartool –aw will show two new records since the last archived event’s record.
One will be for the attempted new type, and another for the previous (i.e. current type). The
first of these (the record created for the attempted new type) will remain un-filled thereafter.
PI Server Reference Guide Page 81
Chapter 6 - PI Point Type Edit
To illustrate, suppose a point named int16_typedit had the following archived values and was
of type int16.
6-Oct-2005 13:51:53,27
6-Oct-2005 14:21:54,32767
6-Oct-2005 14:44:56,4
6-Oct-2005 14:51:51,Pt Created
Then it was edited to type int32, and three new values were added.
6-Oct-2005 14:52:01,-10
6-Oct-2005 14:52:03,2147483647
6-Oct-2005 14:52:05,-16
The last value -16 is still in the Snapshot. Try editing the point back to int16 type again by
typing the following in piconfig.
@table pinpoint
@ptclass classic
@mode edit
@istru tag,pointtype
int16_typedit,int16
@ends
The edit will fail and the following error will be returned to piconfig since int16 type doesn’t
allow negative values.
[-10005] Subscript Under Range
Note that this is an error status. An error status like this returned by a point type edit
operation should be distinguished from Coercion Failed which is a System Digital State
which acts as a place holder for an event that failed to coerce.
To see what happens to the archive records when a user tries to edit a point’s type and the
operation fails, launch archive walk by typing
piartool –aw
Something like the following will be shown:
Enter Archive Number: 0
Enter Record Number: 130
Point ID: 1219 Record Number: 130
Chain Record Number - Next: 0 Prev: 0 Index: 0
Record Version: 3 Data type: 8
Flags - Index:1 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 29
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
7 There are events in this example before Pt Created event because data were back-filled to create the example.
Page 82
6.1 - Introduction
Type “e” (without the quotes) and press Enter to view the events for the point.
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 130
Chain Record Number - Next: 0 Prev: 0 Index: 0
Record Version: 3 Data type: 8
Flags - Index:1 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 29
4 Event(s):
0: 29-Sep-05 14:00:03, S,O,A,S,Q [0,0,0,0,0]: 96688
1: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: 96730
2: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96687
3: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96686
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Then type 96688 and press Enter to open this Index record:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96688
Chain Record Number - Next: 96730 Prev: 0 Index: 130
Record Version: 3 Data type: 6
Flags - Index:0 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 22
4 Event(s):
0: 6-Oct-05 13:51:53, S,O,A,S,Q [0,0,0,0,0]: 2
1: 6-Oct-05 14:21:54, S,O,A,S,Q [0,0,0,0,0]: 32767
2: 6-Oct-05 14:44:56, S,O,A,S,Q [0,0,0,0,0]: 4
3: 6-Oct-05 14:51:51, S,O,A,S,Q [0,253,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter to see the next record. Notice the Data type for the following record is “8”, which
is Int328:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96730
Chain Record Number - Next: 96687 Prev: 96688 Index: 130
Record Version: 3 Data type: 8
PI Server 3.4.370
Installation and New Feature Guide Page 89
Flags - Index:0 Step:0 Del:0 Dirty:0
8 Point type enumeration:
int16 = 6, int32 = 8, float16 = 11, float32 =12, float64 = 13, digital = 101, Blob = 102, timestamp = 104, string =
105
PI Server Reference Guide Page 83
Chapter 6 - PI Point Type Edit
Flags - Index:0 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 2
Storage (bytes) - Available: 998 Used: 14
2 Event(s):
0: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: -10
1: 6-Oct-05 14:52:03, S,O,A,S,Q [0,0,0,0,0]: 2147483647
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Then press Enter to see the next record. Notice the Data type is now “6”, which is Int16:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96687
Chain Record Number - Next: 96686 Prev: 96730 Index: 130
Record Version: 3 Data type: 6
Flags - Index:0 Step:0 Del:1 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 1
Storage (bytes) - Available: 998 Used: 8
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter again to see the next record. The Data type is now “8” again:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96686
Chain Record Number - Next: 0 Prev: 96687 Index: 130
Record Version: 3 Data type: 8
Flags - Index:0 Step:0 Del:1 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 1
Storage (bytes) - Available: 998 Used: 10
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
At this time, the point is of type int32. The offset 16382 is a special marker that acts as a
placeholder in the new overflow record created when a point’s type is edited. The first valid
new data for the new type should replace this marker but in record 96687 this marker will
remain there and the record will never be filled since the edit failed.
A tricky situation arises if a value stays in a Snapshot for a long time before a new Snapshot
arrives and the point undergoes several point type conversions meanwhile. This is very
important: the Snapshot undergoes a coercion process every time the tag’s type is
successfully edited. When a new value finally arrives at the Snapshot, the old Snapshot is
coerced back to the type it was originally sent as before being sent to the appropriate record
in the archive. Therefore if the Snapshot event went through several point type conversions
and it cannot be coerced from its latest type to the original type, the value will be rejected by
the archive and lost.
Page 84
6.2 - Error handling
An example of the situation mentioned in the preceding paragraph would be a point going
from an integer type to a digital type and then to a string and then back to integer. If the last
Snapshot for this tag was of type int16 and value 1, the integer would have been coerced to a
digital and the appropriate digital state during the subsequent type edit. This digital state
would have been coerced to a string after that. By the time the point is edited back to integer
type, we have a string (whatever the digital state representation was, say, “Closed”) that
needs to be coerced to int16 and can’t. It would only be coercible if it were a digital because
the coercion process would use the offset.
Out of order events that are sent to the archive after the point type change will go into the
archive as the point type that was in effect at the time of the event’s timestamp.
Below is the matrix of allowed type coercions.
int16 int32 float16 float32 float64 digital string blob timestamp
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 (lower than number of digital states)
4. Assuming exact match (case insensitive) with a state string
5. Assuming the range of the source is compatible with the range of the target
6.2 Error handling
If coercion is impossible from the stored type to the current point type, what is returned or
whether a value will be returned, is determined by Archive_DataCoercionPolicy. This PI
timeout parameter can have one of the following values:
0 DTC_MarkBad Failed 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)
PI Server Reference Guide Page 85
Chapter 6 - PI Point Type Edit
If coercion fails during off-line archive processing, values will be replaced as dictated by the
above policy.
Page 86
Chapter 7. EXCEPTION REPORTING AND COMPRESSION
TESTING
Exception reporting and compression testing offer you the opportunity to tune your PI points
for maximum efficiency. Each PI point has attributes that you can set to specify compression
and exception reporting specifications for that point. How you set those specifications will
impact 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). Exception reporting and compression testing are sometimes confused, but it’s
important to understand the distinctions:
Exception Reporting: Exception reporting takes place on the Interface Node. The
point of Exception reporting is to reduce the communication (I/O) burden between
the PI Server and the Interface Node by filtering out “noise”. As networks have
improved and I/O capacity has become less of an issue, some PI System Managers
have essentially turned exception reporting off, by setting the exception deviation to
zero. OSIsoft recommends that you set the exception deviation to slightly smaller
than the precision of the instrument.
Compression Testing: Compression testing takes place on the Server. The Snapshot
Subsystem performs the compression test. The point of compression testing is to
store data efficiently in the PI Data Archive. More efficient data storage allows for
longer periods of on-line data on the same disk-space. The idea here is not to store an
event that PI can essentially “recreate” by extrapolating from surrounding events.
Unlike exception reporting, which is a simple linear test, the compression test uses a
sophisticated algorithm, called the swinging door compression algorithm, to
determine whether an event is significant.
7.1 Exception Reporting
The exception reporting process is the process that interfaces use to evaluate new events to
determine whether they are significant. The interface sends the significant events to the PI
Server and discards the events that are not significant. The purpose of exception reporting is
to avoid sending random changes—changes that are smaller than the instrument can actually
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.
PI Server Reference Guide Page 87
Chapter 7 - Exception Reporting and Compression Testing
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, ExcMin and
ExcMax 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 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 that 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.
Some interfaces do not support exception reporting. See the documentation for your interface
to determine whether it supports this capability. Manually entered data are 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 "ExcMax".
Exception Minimum: Minimum time span between exceptions, expressed in
seconds. This value is configured for each point in the attribute "ExcMin".
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.
Page 88
7.1 - Exception Reporting
If the time new event timestamp and old event timestamp is greater than or equal the
excmax, 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 excmin 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.
7.1.1 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
typical value is 1% 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.
7.1.2 ExcMin
The ExcMin attribute (Exception Minimum) 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 ExcMin interval will be discarded.
7.1.3 ExcMax
The ExcMax attribute (Exception Maximum) 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 ExcMax 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 will be passed to the PI Server.
PI Server Reference Guide Page 89
Chapter 7 - Exception Reporting and Compression Testing
7.1.4 Turning Off Exception Reporting
To turn off exception reporting (that is, to generate an exception for every event), set
ExcMax = 0 and Excmin = 0.
7.2 Compression Testing
The Snapshot Subsystem uses compression testing to determine which events it should pass
to the Archive for storage. The point of compression testing is to store just enough data to
accurately reproduce the original signal.
For example, in the following illustration, all the events fall on the same straight line. In a
simple case like this, you don’t actually need to store all the points on the line. If you store
just two points, you can exactly recreate the point value for any other time.
This line can be reconstructed from any two of these events. So the most efficient storage
would be to store only the first and last events (A and B) rather than storing all the events.
Further, no accuracy is sacrificed. If a user wants to retrieve the value at any point along the
line, it can be interpolated from the values that have been stored.
This simple example illustrates how PI applies data compression. In practice, the curves are
more complex than straight lines, and the compression specifications for each tag must be
tuned properly to achieve a balance between storage efficiency and accuracy.
The same principle applies to compressing real-world data. PI uses a sophisticated
compression algorithm to determine which events it needs to keep in order to provide an
accurate data history. The CompDev, CompMin and CompMax attributes allow you to
control the “granularity” of the compression algorithm.
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.
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.
Page 90
7.2 - Compression Testing
If the Status attribute of the Point has changed.
The compression method used by PI allows PI to keep orders of magnitude more data online
than conventional scanned systems. The data are 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, the previous 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.
Each point has three attributes that comprise the compression specifications: CompDev
(compression deviation), CompMin (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.
The compression specifications work in a similar way to the exception specifications. Just
like exception reporting, compression is a filter. The difference is that the exception
specifications determine which events should be sent to PI, whereas the compression
specifications determine which of the events sent to PI should go into the Archive.
CompMin 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. A new event is always recorded if the time since the last
recorded 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.
PI Server Reference Guide Page 91
Chapter 7 - Exception Reporting and Compression Testing
This value will be archived.
Eng
Unit
A compression deviation blanket
Value drawn to this point would not
include all points since the most
recently archived value, so the
Most recently previous value would be
archived value archived.
Compression
Deviation
Specification
Compression Deviation Blanket
Time
Figure 7-1. Swinging Door Compression
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 (CompMin) to prevent an extremely noisy point from
using a large amount of archive space. This parameter should be set to zero 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.
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.
Page 92
7.2 - Compression Testing
7.2.1 Step Flag
The step attribute setting affects both display and compression.
Data for points with this attribute 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.
PI Server Reference Guide Page 93
Chapter 8. SECURITY
The PI Server is typically used in production systems in which correct and reliable operation
is important. For this reason, a number of security mechanisms are available to protect
against both willful and accidental tampering with the system. These include operating
system security, physical security, network security, and several levels of PI System security.
See the PI Server System Management Guide for details on managing the PI Server security.
8.1 User Name and Password
The PI Firewall provides a first level of access control, based on the network address of the
client. If a connection request successfully passes the PI Firewall, the user ID and password
provide another level of PI access security.
The PI Server has its own user identification and password security.
Client applications are responsible for prompting the user for the login name and password,
and passing this information to the PI Server for authentication.
Users control their own passwords. Use the pisetpass utility to change user passwords. A null
password is allowed but is not generally recommended.
8.2 Point Security
Security applies to point data and point attributes. The archive data for a point is assigned an
owner and a group. The attributes of the point (such as zero, span, compression
specifications, etc.) may be assigned to a different owner and different group, with
independently assigned access permissions.
Users may be assigned to multiple groups, but they don’t have to be assigned to any groups.
There is not necessarily any relationship between the owner and the group.
8.3 Database Security
Security applies to databases owned by the PI Server. Access can be controlled to the Batch,
Campaign, Digital State, Heading Sets, Modules, Point, Transfer Records, User, and
Individual Subsystem Thread and Auditing Table. Each table can be assigned to a different
owner and different group. Access permissions can be different for the owner and the group.
PI Server Reference Guide Page 95
Chapter 8 - Security
8.4 Trust Access
A mechanism for proxy access is provided, primarily to allow interfaces to access the PI
Server for Windows without modifications such as adding login code. The mechanism is
called PI Trust Logins.
Page 96
Chapter 9. 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.
This chapter begins with a discussion of the architecture of the PI SQL Subsystem. It then
outlines the available configuration methods for the PI SQL Subsystem and discusses testing
and troubleshooting techniques. Supporting information, such as details of OSIsoft’s
implementation of SQL, can be found in 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.
9.1 Architecture
This subsection 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.
9.1.1 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
wishes to start processing 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.
PI Server Reference Guide Page 97
Chapter 9 - PI SQL Subsystem
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 will be de-allocated when the PI SQL Subsystem shuts down.
During shutdown, pisqlss will report the total number of handles allocated during its run, and
how many orphaned handles were aborted.
9.1.2 Concurrency
The PI SQL Subsystem handles SQL processing for all client connections to the PI Server for
Windows and UNIX.
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.
9.2 Differences between PI 2.x and PI 3.x
There are some differences in SQL processing between the PI Server for Windows and UNIX
and the PI System for OpenVMS. This section outlines these differences.
9.2.1 The PIPoint Table
This subsection outlines the differences between the implementation of the PIPoint Table
between the two styles of PI System.
Classic vs. Base Point Attributes
The columns of the PIPoint Table are exactly the same as the point attributes of a Classic
point. In the PI System for OpenVMS, all points have a design that closely resembles the
Classic point. The PI Server for Windows and UNIX has a few extra attributes relating to
point ownership and access permissions.
In the PI Server for Windows and UNIX, the lowest common set of point attributes is called
the Base point class. When querying attributes of base class points, the PIPoint columns that
represent attributes of classic points will appear to have default values.
This table lists the point attributes that will have default values when querying base class
points:
Table 9–1. Default Attributes in BASE Point Class
PIPoint Column Default value
Convers 0.0
Filtercode 0
location1, location2, 0
location3, location4,
location5
PointID Same as base class attribute recno
Page 98
9.3 - Configuration
PIPoint Column Default value
See next subsection.
Recordtype If base class attribute step is 1, then 0,
otherwise 1.
Res If base class attribute step is 1, then 4,
otherwise 1.
Squareroot 0
Totalcode 0
The keyword pointnumber originally came from the pidiff utility in PI for OpenVMS. This
name is also used in the PI API User Guide. Most PI API calls require a 32-bit integer
PointIdentifier (pt or ptnum - referenced in the PI API User Guide as PI point number).
PI SQL query Returns PIPoint “base” class attribute…
Select pointid from PIPoint… Recno
Select pointnumber from PIPoint… Pointid
9.2.2 Using Performance Equation Subsystem Built-In Functions
Built-in functions in the Performance Equations Subsystem can be called in the SQL select
list, or in the WHERE clause. In most cases, the function syntax is the same as in
Performance Equations.
The exception is calling functions that take a tag argument according to PI Server
Applications Guide, Chapter 2, Performance Equations Subsystem. In performance
equations, the syntax for a tag argument is:
'tag'
When calling these functions in PI SQL, the syntax must be:
TagNum("tag")
The TagNum function explicitly converts a character string argument to a PI PE tag type,
just as the Date function explicitly converts a character string to a time type.
For example, to call PrevEvent in PI SQL in order to obtain the value of point sinusoid
before noon, you must write:
PrevEvent(TagNum("sinusoid"), Date("12:00"))
9.3 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.
PI Server Reference Guide Page 99
Chapter 9 - PI SQL Subsystem
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 will be
migrated.
This section outlines configuration using the initialization file and command line arguments.
Refer to client product documentation for instructions on changing SQL processing settings
from the client application.
9.3.1 Hierarchy of PI SQL Subsystem 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 will be 60 seconds.
9.3.2 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.
The initialization file settings are read when a new statement is allocated. Any change to this
file will be 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.
Details of the settings can be found in Appendix B of the PI ODBC Driver Manual.
9.3.3 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 subsection 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,
Page 100
9.3 - Configuration
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:
Table 9–2. Command Line Arguments
Command Line
Argument 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
following table for the list of supported options.
-t SQL query timeout, in seconds. If this time expires, pisqlss will 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 SELECT
statement.
The -o argument is followed by a comma-separated list of option tokens with no space
between the tokens. The supported options are as follows:
Table 9–3. Command Line Option Tokens
Option Token Description
AGGRTIMESTART Causes all queries of the aggregate tables to use the time at which 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 will not execute if the PI SQL determines that a query is
too unspecific and would take too long to execute.
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
below. (See Note 1, below.)
QEP Causes the gateway to dump a query execution plan to a file called
pisql_n.qep in the \pi\log\ directory on the PI Server. “n” in the file name
represents the handle number.
SUBSET If a query times out while this option is in effect, pisqlss will return a subset
of the actual results with no error. (See Note 2, below.)
TRACE Writes a summary of every Prepare (that is, query parsing) and Execute
operation by pisqlss to the file sqltrace.log in your \pi\log\ directory. See
also the “LOG” option above.
PI Server Reference Guide Page 101
Chapter 9 - PI SQL Subsystem
Note 1: This file is generated in all PI Server configurations, except while not running
as a service on Windows. In this case, output is directed to standard output, which is
the command window.
Note 2: If this option is in effect, it is important to note that the results returned do not
represent the actual final results of the query. When query development is complete,
this option should be removed.
Refer to the Troubleshooting section in this chapter for details of the information generated in
the sqltrace.log file by the LOG and TRACE options.
Specifying Command Line Arguments on UNIX
Command line arguments can be added to the pisqlss startup by editing the PI Server startup
file pistart.sh. Add any desired arguments to the end of the line that starts pisqlss.
Note: pistart.sh is overwritten at every PI Server upgrade.
Specifying Command Line Arguments on Windows
There are two different methods for providing command line arguments on Windows,
depending on how the PI Server is started.
Starting pisqlss 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 using the Services applet in the Control Panel, or by using the
pisrvstart.bat file in your PI\adm directory.
The only way to pass command line arguments to pisqlss running as a Windows service is to
use the Services applet in the Control Panel. Open the Services applet, 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 pisqlss.
Page 102
9.4 - Troubleshooting
Figure 9-1. Windows Control Panel Services Applet
This examples 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 applet, 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.
9.4 Troubleshooting
Unexpected errors may be generated when using an ODBC application to communicate with
the PI Server for Windows and UNIX.
This section outlines techniques to help you validate the operation of the PI SQL Subsystem
and to log its processing steps.
9.4.1 Using the ipisql Utility
This utility is an interactive program that executes SQL statements directed at the PI Server.
It uses the PI API to connect to the PI Server.
The ipisql utility can be found in the PI\adm\ directory. Start the utility by typing its name at
a command prompt. The utility will connect to the default PI Server, write version
information to the screen, and then prompt for input:
D:\pi\adm\ipisql
PI Server Reference Guide Page 103
Chapter 9 - PI SQL Subsystem
Connecting to default PI System...Done
iPISQL Copyright (c) 1993-2000, OSI Software, Inc. All rights reserved.
PI API Version 1.3.4 PINet Protocol Version 00011101
Connected to PI 3.3 Build 361.43 on node "figaro"
PISQL>
To exit ipisql, type the command exit followed by a semi-colon. The error code from the
processing of the last SQL statement is the return code of the ipisql utility. This allows error
detection if ipisql is used in a script.
Submitting Queries
SQL statements can be typed at the prompt and terminated with a semi-colon ( ; ). This
causes the query to be sent to PI. The query can span multiple lines. The prompt for
subsequent lines looks like:
_PISQL>
You can use as many lines as you like.
You can also process queries stored in a text file using the FILE command:
PISQL>file myquery.txt;
A query in a file need not be terminated with a semi-colon; the query will be processed when
the end of the file is reached.
A query file may contain more than one query. If this is the case, a semi-colon must be used
to separate the queries.
Query files may contain the FILE command.
ipisql Options
The ipisql utility supports several options that can be specified on the command line.
Most of the options are exactly the same as the command line options for the PI SQL
Subsystem itself, specifically timeout (-t), timestep (-ts) and options (-o). For more
information, see Command Line Arguments on page 100.
The options argument supports the same option tokens as pisqlss, except LOG and TRACE.
In addition, ipisql supports the option token ANSISQLVAL, which is not supported as a
command-line option for pisqlss.
The full list of command line arguments are supported by ipisql is as follows:
Page 104
9.4 - Troubleshooting
Table 9–4. Command Line Arguments Supported by ipisql
Command Line
Argument Description
-csv Write results to standard output in comma-separated variable format
suitable for importing into a spreadsheet. The query text, column headings,
row count and error information are written to standard error, also in comma-
separated variable format. No command prompts are displayed.
-f Identifies a query file. If this argument is used, ipisql executes the query in
the specified file and exits. A command prompt will not be displayed.
-node Identifies the PI Server node to which to connect. The name to use is the PI
Server computer’s network name. When connecting to a PI Server for
Windows and UNIX, you must either suffix “:5450” to this name, or specify “-
port 5450”.
-o Options. The options are specified in a comma-separated list of tokens with
no space between tokens. The interpretation of the tokens is not case-
sensitive. For a list of supported options, see the table in the "Configuration"
section on page 99.
-p0...-pn SQL parameter values. The first parameter is –p0 (i.e. zero), the second is –
p1, and so on. You may specify as many SQL parameters as you like, and
need not specify all of them; ipisql will prompt for any additional parameter
values needed. The SQL parameter values are in effect throughout the entire
ipisql session.
- password Password. This argument is interpreted only if the “-username” argument is
supplied. If “-username” is provided, but “-password” is not, ipisql will prompt
you for a password.
-port TCP\IP port number. Default value is 545. You may choose to add “:portnum”
to the end of the node name when providing the “node” argument.
-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the
query to return either a timeout error, or a subset of the actual results,
depending on the “SUBSET” option in effect for pisqlss.
-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 SELECT
statement.
-username Username. If this argument is not present, ipisql will not attempt to validate
your identity; default access rights will apply.
For example, to execute query in the file myquery.txt against the PI 3.2 System larry using a
default timestep of 2 minutes, issue the command:
ipisql –ts 120 –f myquery.txt –node larry:5450
If the file myquery.txt contains the statement:
select * from picomp where tag = ? and time >= ?
you might avoid the prompt for SQL parameter values by issuing the command:
ipisql –f myquery.txt –p0 sinusoid –p1 "today"
PI Server Reference Guide Page 105
Chapter 9 - PI SQL Subsystem
9.4.2 Generating a Trace File
A trace file can be generated by starting the PI SQL Subsystem with the LOG or TRACE
options. Instructions on how to do this are in the Configuration section.
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.
9.4.3 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 will
be 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.
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
Page 106
9.4 - Troubleshooting
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,¶ms) begins...
callback(21): Calls: 1 PctDone: 0 Etime: 1 Limit: 0
fetch(21,*results) [0]
clear(21,1) [0]
9.4.4 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.
If this occurs, the client application’s connection to PI will probably time out. The user is
then free to reconnect to PI to continue query development.
In some cases, however, execution of this query continues on the PI Server. If the subsystem
is left to process an unreasonably large query when the client has timed out and disconnected,
it tends to consume large amounts of virtual memory and can consume a large amount of
CPU time.
This sub-section outlines techniques for clearing runaway queries on the PI Server. The
technique to use varies with the PI Server platform.
PI Server Reference Guide Page 107
Chapter 9 - PI SQL Subsystem
Windows
When running as a service on Windows, the PI SQL Subsystem can be directed to abort
processing the current statement and to release the virtual memory it has acquired without
shutting down.
To do this, you must send a pause command to the pisqlss. Three techniques are available for
doing this:
Start the Services control panel applet. Select the PI SQL Subsystem from the list and
click the “Pause” button.
From a command line prompt, issue the command:
net pause pisqlss
From a command line prompt, issue the command:
\pi\bin\pisqlss –pause
A message will be written to the message log indicating that the pisqlss has been paused. The
query in progress when this command is issued will return immediately with an error –10743
(i.e., RPC resolver temporarily off-line). Attempting execution of any new query when the
subsystem is in this state will also return this error.
To resume normal operation, you must send a continue command to the pisqlss. There are
three techniques available for doing this:
Start the Services control panel applet. Select the PI SQL Subsystem from the list and
click the Continue button.
From a command line prompt, issue the command:
net continue pisqlss
From a command line prompt, issue the command:
\pi\bin\pisqlss –continue
A message will be written to the message log indicating that the pisqlss 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.
UNIX
Shutting down and restarting the PI SQL Subsystem is the only technique currently available
for aborting expensive queries on UNIX. Use the kill –2 command to stop the pisqlss.
9.4.5 Performance Counters
In PI Server for Windows, several aspects of PI SQL Subsystem processing can be monitored
continuously using the Performance Monitor application. A summary of these counters
appears in the PI Performance Counters section of PI Server System Management Guide,
Chapter 1, PI System Management.
Page 108
9.4 - Troubleshooting
9.4.6 Technical Support and Problem Reports
If the PI SQL Subsystem consistently returns an error when processing SQL statements, or
appears to generate incorrect results, you should stop pisqlss and then restart with the
TRACE and LOG options enabled. Send the resulting sqltrace.log to OSIsoft Technical
Support.
PI Server Reference Guide Page 109
APPENDIX A: PI TIME FORMAT
Many PI System utilities prompt for a date and time. The PI time formats are:
Relative
Absolute
Combined
A.1 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
A.2 Absolute Time
Absolute times have one of the following formats:
DD-MMM-YY hh:mm:ss.ssss - day-month-year hour:minute:second
* - current time.
T - 00:00:00 on the current day (TODAY)
Y - 00:00:00on the previous day (YESTERDAY)
Monday - 00:00:00 on the most recent Monday
Sun,Mon,Tue,Wed,Thu,Fri,Sat - 00:00:00 on the most recent Sunday, Monday, ...,
Saturday
For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out,
they default to the current date. Time fields default to 00.
PI Server Reference Guide Page 111
Appendix A: PI Time Format
A.2.1 Specifying Standard or Daylight Savings Time
In almost all cases, PI can accurately determine whether or not 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.
You can find the names of your time zones by using pidiag –tz. This sample output was
generated on Windows NT:
c:\pi\adm>pidiag -tz
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
The PI System on Windows 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
UNIX platforms support only the short names. PIdiag –tz shows you the names to use.
For time zones that observe daylight savings time, there is one hour per year in which an
unqualified absolute time string is ambiguous. 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 will be considered daylight savings if the translation takes place
before 25-Oct-98 02:00:00 Pacific Daylight Time, and will be considered standard time
otherwise. If this is not your intent, suffix your time string with the appropriate time zone
name.
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"
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
Passed Time: 25-Oct-98 01:30:00* PST Local: 909279000 UTC: 909307800
Page 112
A.2 - Absolute Time
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.
Other features of the pidiag –tz command are outlined in PI Server System Management
Guide, Chapter 12, Finding and Fixing Problems: the pidiag Utility.
For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out, they
default to the current date. Time fields default to 00.
A.2.2 Examples
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
Caution should be used 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
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 will be disregarded.
2 :::8 00:00:00 on the 2nd of the current month
PI Server Reference Guide Page 113
Appendix A: PI Time Format
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 caution should also be
used 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
Here 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
A.3 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.
A.3.1 Examples
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
Page 114
APPENDIX B: PI TIME CONVERSIONS
This section describes how timestamps are converted between Windows and UNIX PI
Servers (PI Servers) and OpenVMS (PI 2.x). The PI API is based on PI 2.x timestamps; all
references to PI 2 System time also apply to PI API time.9
B.1 Timestamps on PI 2 Systems
PI 2 Systems timestamp is based on number of seconds since January 1, 1970 00:00:00 local
time. It is important to emphasize local time. There are at least two limitations to this
convention: daylight savings time changes and PI data access from time zones outside of the
PI System Server time zone.
B.2 Daylight Savings Time Changes on PI 2 Systems
Daylight Savings Time transitions on PI 2 Systems cause one hour of duplicate timestamps
during the transition from daylight saving time (DT) to standard time (ST) and a one-hour
discontinuity during the ST-DT transition. The ST-DT transition only causes data display
problems. The DT-ST transition, unless special procedures are followed, overwrites one hour
of data, resulting in data loss. The following two tables show actual timestamps during these
two transitions for an PI 2 Server in California, USA.
Table B-1 PI 2 Standard Time to Daylight Savings Time
Universal Coordinated PI 2 System
Time Local Time Time
7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000
7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800
7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600
7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400
7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000
9 The extended PI API introduces a time object consisting of time zone information. The discussion applies to
non-extended PI API. See the PI Application Programming Interface manual for detail.
PI Server Reference Guide Page 115
Appendix B: PI Time Conversions
Universal Coordinated PI 2 System
Time Local Time Time
7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400
7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000
7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800
7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600
7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400
Table B-2 PI 2 Daylight Savings Time to Standard Time
Universal Coordinated PI 2 System
Time Local Time Time
27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200
27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000
27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800
27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600
27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000
27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800
27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600
27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400
The first table shows two identical moments in time represented by two different times in the
PI 2 Server. The second table shows two unique one-hour spans sharing the same times in the
PI 2 Server.
B.3 Timestamps across Time Zones on PI 2 Servers
The following table compares a timestamp generated on a PINet/VMS node to a timestamp
on a PI 2 Server in a different time zone.
Table B-3 PI2 Timestamps across Time Zones
Time zone Universal Coordinated Time Local Time PI 2 System Time
EST (PINet/VMS 17-Nov-96 10:00:00 17-Nov-96 848206800
node) 05:00:00
PST (PI 2 Server) 17-Nov-96 10:00:00 17-Nov-96 848196000
02:00:00
Page 116
B.4 - Timestamps on PI Server Systems
Both timestamps represent the same moment in time, but have different values. An interface
running on the PINet/VMS node would write values that the Server treats as three hours in
the future.
B.4 Timestamps on PI Server Systems
The PI Servers solve this problem by internally storing time based on Coordinated Universal
Time (or UTC:Universal Time, Coordinated). A given moment in time is represented by the
same timestamp regardless of PI Server location. Feeding data from multiple PI Server
satellite nodes scattered around the world into one PI Server poses no time problems.
B.5 Translating PI 2 Timestamps to PI Server Systems
Data sources based on the PI API or data from PI 2 Net nodes pose a conversion problem.
The timestamps arrive at the Server in PI 2 Server format and must be converted to PI Server
format.
PI 2 Server timestamps are converted to PI Server format on the PI Server. Therefore all
conversions assume the local time and ST/DT state of the PI Server. Conversions are applied
to incoming data (such as data arriving from an interface) and outgoing data (such as archive
values for a PI Process Book trend). Data from a PINet/VMS node in a time zone different
from the PI Server will have conversion errors. Likewise, data from a PI Server destined to a
PI API-based application in a different time zone will also have conversion errors.
PI Servers contain a translation layer that identifies connections from PINet/VMS nodes and
PI API applications. The layer translates calls to appropriate PI Server calls and translates
values and timestamps to PI Server values and timestamps.
The timestamp conversion algorithm is quite simple. The offset between local time and
Universal Coordinated Time is calculated and used as shown in the following two equations:
OpenVMS PI Server based time = PI Server based time – offset
PI Server based time = OpenVMS PI Server based time + offset
The offset calculation requires the PI Server’s operating system to be correctly configured to
the correct time zone and ST/DT status. The offset value will vary by one hour during the
year on systems that honor ST/DT. For example a computer in California will have an offset
of 8 hours during standard time and 7 hours during daylight time. The offset is updated within
5 minutes of actual DT/ST transitions.
The following two tables show time conversions from a PI API-based interface flowing into a
PI Server in California during daylight savings time transitions.
Table B-4 PI Server Standard Time to Daylight Savings Time
Universal Local Time PI 2 System Offset PI Server
Coordinated Time Time Time
7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000 28800 828865800
PI Server Reference Guide Page 117
Appendix B: PI Time Conversions
Universal Local Time PI 2 System Offset PI Server
Coordinated Time Time Time
7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800 28800 828867600
7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600 28800 828869400
7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400 28800 828871200
7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000 25200 828871200
7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800 25200 828873000
7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600 25200 828874800
7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400 25200 828876600
Table B-5 PI Server Daylight Savings Time to Standard Time
Universal Local Time PI 2 System Offset PI Server
Coordinated Time Time Time
27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200 25200 846401000
27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000 25200 846403200
27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800 25200 846405000
27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600 25200 846406800
27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000 28800 846406800
27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800 28800 846408600
27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600 28800 846410400
27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400 28800 846412200
These two tables demonstrate how the PI Server solves the data overlap problem of the DT to
ST transition and the continuity problem of the ST to DT transition. However, there is a
limitation to this conversion algorithm. It is assumed that arriving timestamps are from the
current DT/ST state, that is, a timestamp from ST written to the PI Server during DT will be
converted using the DT offset.
B.6 Translating PI Server Timestamps to PI 2 Based Timestamps
Data flowing from a PI Server to a PI API based application uses a slightly different
timestamp conversion algorithm. If the timestamp conversion algorithm from PI 2 to PI
Server were reversible, the PI Server’s ability to solve the data overlap and discontinuity
problems of DT/ST transitions would not be viewable from a PI API application. Conversion
from PI Server timestamps to PI 2 Server based timestamps uses a constant offset value, that
is, the offset value is not a function of the timestamp being converted. The current offset
value in effect is used to convert any archive value regardless of whether the archive value
Page 118
B.7 - How PI Client Applications Handle DST Changes
represents a value during daylight time or standard time. Here’s a table of examples, again
representing systems in California, USA:
Table B-6 PI Examples of Timestamp conversions for California-based systems
PI Server Time Universal DT/ Returned PI 2 Local Time Offset
of Archive Value Coordinated ST System Time
Time
824851800 20-Feb 21:30:00 ST 824823000 20-Feb 13:30:00 PST 28800
840538800 20-Aug 12:00:00 ST 840510000 20-Aug 04:00:00 PDT 28800
824851800 20-Feb 21:30:00 DT 824826600 20-Feb 13:30:00 PST 25200
840538800 20-Aug 12:00:00 DT 840513600 20-Aug 04:00:00 PDT 25200
This table shows conversion of identical PI Server timestamps when called during ST and
during DT; the resulting PI 2 System Time is different in each case. Although this appears to
be ambiguous behavior, it allows preservation of correct DT/ST transitions.
The PI API time parsing/formatting routines have been modified to handle this behavior. The
PI API detects the server type and invokes parsing/formatting routines that account for this
behavior. Applications that make no assumption of PI timestamps and use PI parsing and
formatting routines will behave correctly. Applications that invoke non-PI time formatting
techniques may report invalid times.
B.7 How PI Client Applications Handle DST Changes
Archive timestamps in PI Server are stored as universal times; thus the PI Server is not
impacted by daylight savings time. This is in contrast to PI 2.x, where there is a one-hour
hole in the data during the springtime change, and one hour of data is discarded during the
fall time change.
The client applications reflect the daylight savings time changes as follows: it is up to the
displayer to apply an interpretation. OSIsoft does not choose the day that the changes take
place; our software responds to the system time of the local machine.
The PI API will interpret the time according to the local client machine's settings. The time
zone setup information is part of the PC configuration. The PI API queries the operating
system to find out if a time is in daylight savings time or not. Operating systems other than
OpenVMS have the dates of the daylight savings transition times built in. A table of
transition dates is maintained which spans decades.
It is interesting to examine a PI ProcessBook trend that spans a daylight savings time change.
On the day of the springtime change, against a PI Server System, a trend would show
continuous and complete data for 23 hours (midnight to midnight). If the time changes on 3
April at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly
01:59:59.99999999999... the clock would change to 3:00:00. The x-axis will be missing the
60 minutes between 2 a.m. and 3 a.m. There will not be a 2:00:00 marker.
PI Server Reference Guide Page 119
Appendix B: PI Time Conversions
On the day of the fall time change, against a PI Server System, a trend would show
continuous and complete data for 25 hours (midnight to midnight) on the day of the fall time
change. If the time changes on 31 October at 2:00 am, one could watch a theoretical clock
during this transition and at exactly 01:59:59.99999999999... the clock would change to
1:00:00. The x-axis will have the 120 minutes between 1a.m. and 2 a.m. There will be two
consecutive 2:00:00 markers.
On the day of the springtime change, against a PI 2.x system, a trend would show continuous
data for 24 hours (midnight to midnight). If the time changes on 3 April at 2:00 am, one could
watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the
clock would change to 3:00:00. The PI 2.x Server must adjust its time, and will interpolate
(adding records to the archive as necessary) in order to span the 1-hour gap. The x-axis will
show the 60 minutes between 2 a.m. and 3 a.m., and the values displayed are the interpolated
data.
On the day of the fall time change, against a PI 2.x system, a trend would show discontinuous
and incomplete data for 24 hours (midnight to midnight). If the time changes on 31 October
at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly
01:59:59.99999999999... the clock would change to 1:00:00.
The PI 2.x Server must adjust its time, and the System Administrator gets to choose which
hour of data to discard. This data is lost forever, and will never be displayed by any
application. The x-axis will show only 60 minutes between 1 a.m. and 2 a.m., with no
indication that data was discarded.
B.8 PI in the 21st Century
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.
Page 120
APPENDIX C: PI API AND TOOLKIT USAGE
C.1 Overview
C.1.1 PI API
The PI API is a library of routines originally written to access a PI 2.x System
programmatically. Before the PI-SDK, all of the Microsoft Windows-based PI client
applications (such as PI ProcessBook) were based on the PI API. Today most PI interfaces
continue to use the PI API, and the library is the only programming method supported on
both Windows and UNIX.
The PI API routines reflect the PI 2.x architecture. For example, in PI 2.x, tag descriptors are
limited to 26 characters, while in PI Server the limit is 65535. The PI API routine
pipt_descriptor ( ) returns a maximum of 26 characters even when the PI Server is running
on Windows or UNIX.
PI API version 1.2 first introduced features to take advantage of the PI 3.x architecture. This
included:
Sub-second timestamps
Access to string data types
Beginning with PI API 1.4, new functions were added to take further advantage of the PI 3.x
architecture. This includes support for long tag names, multi-character point sources, and
reading UTC time from the server. These features are only supported when accessing PI
3.4.370 and later.
The PI Server contains a translation layer to provide backward compatibility with most PI
API routines. The translation layer translates calls to appropriate PI Server calls and translates
values and timestamps to PI Server values and timestamps. However, limitations do exist.
These limitations are documented in this appendix.
C.2 PI API Usage on PI Server
This section assumes knowledge of the PI API. Refer to the PI Application Programming
Interface Manual for details.
Error codes of piar_ routines
All archive interface routines interact with the Snapshot Subsystem. Some routines such as
piar_deletevalue() or piar_putarcvaluex() require an existing event at the passed time. The
PI Server Reference Guide Page 121
Appendix C: PI API and Toolkit Usage
Snapshot Subsystem does not have information about archive events unless the passed time is
the Snapshot itself or the latest archive event. In all other cases, these routines return 0
(success) and pass the request to the archive subsystem via the Event Queue. If the required
event does not exist the archive subsystem sends an error to the PI event log.
piar_replacevalue ( )
This routine replaces a single value for the passed time. Replaced archived values require
approximately twice the archive space to accommodate “edited” flags. Therefore, replacing
large amounts of archived values requires significant free archive space.
piar_panvalues ( )
This routine, if passed a count of 0 will always return error -1. PI 2 behavior is to return the
timestamp if an event exists at the passed timestamp or -103 if now events exist at the passed
timestamp.
piel_addevnt ( )
A call to piel_addevent will create an entry in the PI System message log as follows:
0 Eventlogger 19-Sep-96 11:31:02
>> [Group,3,Type,4,timestamp,19-Sep-96 11:31:02]
This is where the message text goes.
The user name will always be Eventlogger. The timestamp is the time the message arrived in
the Message Subsystem. The second line contains group, type, and passed timestamp in
square brackets, followed by the passed message text.
piel_evntactn ( )
This is not supported in the current version of PI Server.
pipt_compspecs and pipt_compspecseng
Compmin and compmax are passed internally as short integers. This limits the values to +/-
32767. If the compmax value for a point is larger than 32767, it will be returned as 32767.
pipt_dates ( )
Rather than returning a PI user name, the creator and changer arguments return a string
containing a number. The number is associated with the PI user name internally on the
Server.
pipt_descriptor ( )
Although the length of a point descriptor has no practical limit, this PI API function returns a
maximum of 26 characters, for compatibility with PI 2.x.
pipt_digcode ( )
Although the length of a digital state string has no practical limit, this PI API function uses
only the first 12 characters, for compatibility with PI 2.x.
Page 122
C.2 - PI API Usage on PI Server
PI Server is designed to support multiple digital state sets, whereas PI 2.x supports a single
state set. The System Digital State Set is provided for backward compatibility with PI 2.x.
The same digital state string may appear multiple times in the System Digital State Set; it
may appear a single time in a custom state set. In PI Server, the state number and the digital
state code both refer to the same number.
Pipt_digcode ( ) returns the first instance it finds, using the following algorithm:
Search through the digital state sets, from lowest set number to highest. This means
that the System Digital State Set (number 0) will always be searched first.
Search through the given digital state set, from lowest state number to highest.
If found, the digital state is returned as a 32-bit value. The high bit is set; this makes it a
negative number. The next 15 bits indicate the state set number. The low 16 bits indicate the
state number. There is no way to request a subsequent instance of the string.
pipt_digcodefortag ( )
Although the length of a digital state string has no practical limit, this PI API function uses
only the first 12 characters, for compatibility with PI 2.x.
pipt_engunitstring ( )
Although the length of an engineering unit string has no practical limit, this PI API function
returns at most the first 12 characters.
pipt_engunstring( )
This function is called with the point number substituted for the engineering unit code
parameter.
pipt_excspecseng
Excmin and excmax are passed internally as short integers. This limits the values to +/-
32767. If the excmax value for a point is larger than 32767, it will be returned as 32767.
pipt_exdesc ( )
Although the length of an extended descriptor has no practical limit, this PI API function
returns a maximum of 80 characters.
pipt_findpoint ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters.
pipt_nextptwsource ( )
Although the length of a point source string has no practical limit, this PI API function
requires that the point source be a single character only. It will not recognize point source
strings longer than a single character. The passed point number is not used. The first call to
this function begins searching for the matching point source at point number 1. Subsequent
PI Server Reference Guide Page 123
Appendix C: PI API and Toolkit Usage
calls return the next point in the PI Server point database that matches the passed point
source.
pipt_pointid ( )
This function should not be used; use pipt_findpoint ( ) instead.
pipt_pointsource ( )
Although the length of a point source string has no practical limit, this PI API function
returns the first character only.
pipt_recordtype ( ) and pipt_rescode ( )
On PI 2, tags with rescode 1, 2 and 3 store their times as steps. If you display a trend of these
tags, the values are interpolated between events, resulting in a smooth curve.
Tags with rescode 4, however, store their times as full timestamps. If you display a trend of
these tags, the values are not interpolated between events, resulting in a step curve.
On a PI 2 system, pipt_recordtype will return a 1 for tags with rescodes 1, 2, or 3. It will
return a 0 for tags with rescode 4.
On PI Server, there are no rescodes. However, there is the step attribute. In PI Server, if you
display a trend of tags with a step attribute = 0, the values are interpolated between events,
resulting in a smooth curve. If you display a trend of tags with a step attribute = 1, the values
are not interpolated between events, resulting in a step curve.
For compatibility, on a PI Server system, pipt_rescode returns a 1 if the step attribute = 0,
and it returns 4 if the step attribute = 1. It will never return 2 or 3.
For compatibility, on a PI Server system, pipt_recordtype returns 1 if the step attribute = 0,
and it returns 0 if the step attribute = 1.
Keep in mind that pipt_rescode and pipt_recordtype are not very useful on a PI Server
system. They are implemented only to provide compatibility for API programs that were
already written.
pipt_tag ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 12 characters. Delimiters are not included, as this was a PI 2.x concept.
pipt_taglong ( ) and pipt_tagpreferred
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters for compatibility with PI 2.x. Delimiters are not included, as this
was a PI 2.x concept.
pipt_totalspecs ( )
This is not supported in the current version of PI Server.
Page 124
C.2 - PI API Usage on PI Server
pipt_updates ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 12 characters for compatibility with PI 2.x.
pipt_wildcardsearch ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters for compatibility with PI 2.x. Subfields are not used, as this is a
PI 2.x concept.
pisn_“X” ( ) {etc.}
The following discussion is for pisn_getsnapshot ( ), pisn_getsnapshots, pisn_putsnapshot
( ), pisn_putsnapshotq ( ), pisn_putsnapshots ( ), pisn_sendexceptionq ( ) and
pisn_sendexceptions ( ).
Sending Digital States to PI2
In PI2, there is one digital state table with 1024 entries, with entries 193-320 reserved for
OSIsoft error codes.
The interface should send the negative of the table offset if it is an error code.
For example, if the error is IO Timeout then the interface should send -246.
The interface should send the positive relative offset from the digstartcode if it is a valid
digital state.
For example, if the tag has digstartcode defined to be 20, and the two valid states are put in
offsets 20 and 21 in the Digital State Table, then the interfaces should send 0 and 1 in order to
get states 20 and 21, respectively. Note that the interface could send -20 and -21 and this
would work, but this is not the recommended algorithm.
Sending Digital States to PI Server
In PI Server, the System Digital State Set is provided, primarily for compatibility with PI2.
This contains 10240 entries, with entries 193-320 reserved for OSIsoft error codes.
The interface should send the negative of the table offset if it is an error code.
For example, if the error is "IO Timeout" then the interface should send -246.
The interface should send the positive offset in the custom digital set if it is a valid digital
state.
For example, if the tag has a custom digital set defined with two states, then the interfaces
should send 0 and 1. Note that the customer could opt to put the two states in the System
Digital State Set, at offsets 20 and 21 for example. Then the interface could send -20 and -21
and this would work, but this is not the recommended algorithm.
If you retrieve a digital state (istat) from PI, it will be a negative number. You do NOT have
to change this into a positive number in order to send it back to PI.
PI Server Reference Guide Page 125
Appendix C: PI API and Toolkit Usage
Retrieving Digital States from PI2
In PI 2, a negative istat is interpreted as a digital state (rather than an integer). The absolute
value of the istat gives the offset into the digital state table that corresponds to the state
string.
Retrieving Digital States from PI Server
In PI Server, a negative istat is interpreted as a digital state (rather than an integer). To
decode the state, first take the absolute value of the istat. The upper 16 bits now indicate the
digital set number. The lower 16 bits now indicates the digital state number for the given
digital set. The System Digital State Set has a number of 0.
pitm_formtime ( ) or pitm_systime ( )
Sometimes the PI API appears to be off by several hours when translating the time. This is
usually a configuration problem.
You must set the time zone and daylight savings time correctly on both server and client
machines. In WinNT and Win95, set this using Control Panel, Date/Time.
For 16-bit applications, you can set the TZ environment variable. Thirty-two-bit applications
should not use this, especially if the site is not in the United States.
The TZ environment variable will overwrite the settings of the Time zone settings of the
Operating System in the Control Panel. If you use the TZ variable, the Daylight Saving Time
change will be calculated with a fixed algorithm, which is only valid for the United States.
The result is that if you are anywhere else in the world, DST will start and end at the wrong
time. For 16-bit software there is no solution to get this working properly for non-U.S. sites at
the moment.
If you use pitm_systime to retrieve number of seconds past Jan 1, 1970, you should also use
pitm_formtime to translate this to a string. If you mix PI API time functions with
Microsoft C++ time functions (time and localtime) you may get results that are off by several
hours.
Here is an excerpt from Microsoft's MSDN Run-time Library Reference:
The _tzset function uses the current setting of the global environment variable TZ to
assign values to three global variables:
_daylight, _timezone, and _tzname.
TZ is a Microsoft extension and not part of the ANSI standard definition of localtime.
These variables are used by the _ftime and localtime functions to make corrections from
coordinated universal time (UTC) to local time, and by the time function to compute
UTC from system time.
Use the following syntax to set the TZ environment variable:
set TZ=tzn[+ | -]hh[:mm[:ss] ][dzn]
where
Page 126
C.3 - PI Toolkit Usage on PI Server
Tzn = Three-letter time-zone name such as PST. You must specify the correct offset
from UTC.
Hh = Difference in hours between UTC and local time. Optionally signed.
Mm = Minutes. Separated from hh by a colon (:).
Ss = Seconds. Separated from mm by a colon (:).
Dzn = Three-letter daylight-savings-time zone such as PDT. These three letters can be
anything you like. If DST is never in effect in the locality, set TZ without a value for
dzn.
For example, to set TZ to correspond to the current time zone in Germany, you can use
one of the following statements:
set TZ=GST1GDT
set TZ=GST-1GDT
These strings use GST to indicate German standard time, assume that Germany is one
hour ahead of UTC, and assume that DST is in effect.
If TZ is not set, _tzset attempts to use the time zone information specified by the
operating system. If _tzset cannot obtain this information, it uses PST8PDT by default,
which signifies Pacific Time zone.
Localtime corrects for the local time zone if the user first sets the global environment
variable TZ.
C.3 PI Toolkit Usage on PI Server
This section assumes knowledge of the PI Toolkit. Refer to the PI System Manual, Volume
II, for OpenVMS for details.
GetCompSpecs ( )
See comments for the PI API function pipt_compspecs ( ).
GetCompSpecsEng ( )
See comments for the PI API function pipt_compspecs ( ).
GetDigCode ( )
See comments for the PI API function pipt_digcode ( ).
GetDigPointers( )
See comments for the PI API function pipt_digpointers ( ).
GetEngCode( )
This function returns with engUnitCode equal to 0.
PI Server Reference Guide Page 127
Appendix C: PI API and Toolkit Usage
GetEngUnits( )
This function returns with engUnitCode equal to pt if pt is less than 32768, else it returns
with engUnitCode equal to 0.
GetEngUnString (engUnitCode, engUnitStr, error)
See comments for the PI API function pipt_engunstring ( ).
GetExcSpecsEng( )
See comments for the PI API function pipt_excspecseng ( ).
Page 128
APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT
CLASSES
D.1 Predefined Attribute Sets
D.1.1 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 Reference Guide Page 129
Appendix D: Predefined Attribute Sets and Point Classes
D.1.2 base
Attribute Type Default
Archiving BYTE 1
Changedate TimeStamp 31-Dec-69 16:00:00
Changer Uint16 0
Compdev Float32 2.
Compmax Uint32 28800
Compmin Uint16 0
Compressing BYTE 1
Creationdate TimeStamp 31-Dec-69 16:00:00
Creator Uint16 0
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
Shutdown BYTE 1
Span Float32 100.
Step BYTE 0
Typicalvalue Float32 50.
Zero Float32 0.
D.1.3 classic
Attribute Type Default
Convers Float32 1.
Filtercode Int16 0
Instrumenttag String
location1 Int32 0
location2 Int32 0
Page 130
D.1 - Predefined Attribute Sets
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.
D.1.4 sqcalm_parameters
Attribute Type Default
AutoAck String yes
ChartType Int32 0
ClearOnLimitChange String true
ClearOnStart String false
CLTag String
CommentTag String
LCLTag String
LSLTag String
Mixture String
OneSideofCL String
Options String
OutsideControl String
OutsideOneSigma String
OutsideTwoSigma String
PIProductLimits String no
ProductTag String
ReferenceTag String
ResetTag String
SQCAlarmPriority Int32 0
Srcptid Int32 0
Stratification String
PI Server Reference Guide Page 131
Appendix D: Predefined Attribute Sets and Point Classes
TestStatusTag String
Trend String
UCLTag String
USLTag String
WaitOnLimitChange String false
D.1.5 totals
Attribute Type Default
CalcMode String timeweighted
CompValue 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
RateSampleMode String natural
ReportMode String Running
Srcptid Int32 0
TotalCloseMode String clock
Zerobias Float32 0.
D.2 Predefined Point Classes
Alarm Base Classic SQC_Alarm Totalizer
base base base base base
alarmparam classic sqcalm_parameters totals
Page 132
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
PI Server Reference Guide Page 133
Technical Support and Resources
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a
Page 134
INDEX OF TOPICS
Absolute Time, 111 base class, 41
Access permissions, 49 changeDate, 55
attributes, 49 changer, 55
Accumulators changing tag names, 42
data types for, 43 changing zero/span, 46
Adm directory, 6 compDev, compMin,
Annotation, 20 compMax, 47
file, 21 compressing, 47
Anti-virus software Compression, 18, 91
OSIsoft recommendation, 7 convers attribute, 51
API Node, 10 creationDate, 55
API, see PI API, 5 creator, 55
Apisnap, 5, 20 ctr_lmap, 52
Application Programming Interface ctr_progid, 52
see PI API, 5 ctr_strmap, 52
Applications, point attributes for, dataAccess, 49
51 dataGroup, 49
Architecture defaults, 52
SQL Subsystem, 97 Descriptor, 44
Archive digitalSet, 45
archiving flag, 48 displayDigits, 49
Files, 19 engUnits, 46
foreign data sources, 17 exception reporting, 87
flag, 53 exDesc, 44
Size for classic points, 50
Considerations, 20 for COM connectors, 52
write cache, 13 for user-written programs, 51
Archiving attribute, 48 instrument tag attribute, 50
Archiving flag, 48 location attributes, 50
Argument newTag, 44
Token pointID, 55
SQL Subsystem, 100 PointSource, 46
Attributes PointType, 43
and point classes, 41 ptAccess, 49
archiving, 48 PtClassName, 42
PI Server Reference Guide Page 135
Index of Topics
ptGroup, 49 Classes
recNo, 55 PtClassName attribute, 42
scan, 47 Classes, base point class, 41
shutdown, 50 Classic Point
sourceTag, 47 Definitions, 98
span, 45 Classic Point class, 50
squareRoot attribute, 50 classicctr point class, 52
srcptid attribute, 51 classicctr.dif, 52
step, 48 Client Applications
system-assigned, 55 Security, 95
tag name restrictions, 42 COM connectors, 14
totalcode attribute, 51 classicctr.dif file, 52
typicalValue, 45 creating point class for, 52
userInt and userReal attributes, longword mapping parameter,
51 52
zero, 45 mapped points, 52
Bad Input digital state, 23 point attributes for, 52
Bad status, 23 program ID parameter, 52
Base class, 41 string mapping parameter, 52
Base Point Class COM objects, 14
Point Attributes, 98 Combined Time Format, 114
Batch Database, 38 Command
bin directory, 6 Ptclass, 41
Blob point type, 43 Command Line Arguments
Buffering SQL Subsystem, 100
PI API, 6 UNIX, SQL Subsystem, 102
Build number, 4 Windows, SQL Subsystem,
C language, 6 102
Capitalization CompDev, 90, 91
case sensitivity in searches, 42 Point attribute, 53
digital state sets, 25 CompDev attribute, 47
Case sensitivity CompDevPercent, 53, 91
digital state names, 25 CompDevPercent attribute, 47
for tags, 42 CompMax, 90, 91
ChangeDate, 53 Point attribute, 53
point attribute, 55 CompMax attribute, 47
Point attribute, 55 CompMax Point attribute range of
values, 51
Changer, 53
CompMin, 90, 91
point attribute, 55
Point attribute, 53
Changing zero/span, 46
CompMin attribute, 47
Chsrc file
Compressing attribute, 47
UNIX, 8
Page 136
Index of Topics
Compression, 47, 90 from foreign data sources,
Deviation, 91, 92 16
flag, 47, 53 Data Archive
foreign data sources, 18 Database, 19
Maximum, 91 Expensive queries, 107
Minimum, 91 Data Compression
out of order events, 48 specifications, 47
Specifications, 53 Data flow
swinging door, 91 overview, 9
Windows Data output
recommendation against, sourceTag attribute, 47
7 Data permissions, 49
Computer platform Data sources
Information, 134 non-PI, 14
Concurrency, 98 Data types
Configuration for accumulators, 43
SQL Subsystem, 99 for negative integers, 43
Configuration files pointType attribute, 43
shutdown.dat, 50 DataAccess
Configuration parameters, 25 Point attribute, 49
Constraints on tag names, 42 DataAccess Point Attribute, 53
Conventions, naming tags, 42 Database
Convers point attribute, 51, 53, 98 Batch, 38
Conversion Firewall, 37
factor, 54 Group, 38
CreationDate, 53 Module, 38
point attribute, 55 Point, 19, 20
Creator, 53 Proxy, 37
point attribute, 55 Snapshot, 20
ctr_lmap, 15 Trust, 37
ctr_lmap attribute, 52 User, 38
ctr_progid, 15 Databases
ctr_progid attribute, 52 non-PI, 14
ctr_strmap, 15 timeout database, 25
ctr_strmap attribute, 52 DataGroup
Current snapshot values, 5 Point attribute, 49, 53
dat directory, 6 DataOwner
Data Point attribute, 49, 53
compression, 47, 90 Daylight Savings Time, 112, 126
foreign data sources, 14 Changes, 115
retrieval PI Client Applications,
119
PI Server Reference Guide Page 137
Index of Topics
to Standard Time, PI 3 Point attribute, 53
Server, 118 DisplayDigits attribute, 49, 50
Default Documentation
Digital State Set, 23 conventions, v
point attributes, 52 for interfaces, vi
Descriptor Engineering units, 46
Point attribute, 53 EngUnitCode, 128
Descriptor attribute, 44 EngUnits
Deviation Point attribute, 53
Compression, 92 EngUnits attribute
Differences about, 46
in PI Systems single quotes in, 46
SQL Subsystem, 98 EngUnitStr, 128
Digcode, 24 Environment variable, 8, 25
Digital code value, 24 Event
Digital point type, 43 Out of order, 91
Digital State processing, 11
Decoding, 126 Event Queue, 11, 12
Retrieving from PI Server, 126 Events
Retrieving from PI2, 126 definition of, 9
Sending to PI Server, 125 shutdown events, 50
Sending to PI2, 125 significant event, 10
strings, 23 ExcDev, 87, 89
Table, 23 Point attribute, 53
Editing, 24 ExcDev attribute, 89
Digital State Set, 23 ExcDevPercent, 53
defining, 24 ExcDevPercent attribute, 89
deleting, 24 Exception Deviation, 89
Digital state sets, 45 Exception Maximum, 89
case sensitivity, 25 Exception reporting
Digital states about, 87
digitalSet attribute, 45 foreign data sources, 17
Digital tag, 24, 92 minimum, 92
DigitalSet, 53 specifications, 47
DigitalSet attribute, 45 turning off, 90
DIGSET_nn, 24 ExcMax, 87
Digstartcode, 125 Point attribute, 53, 89
Directories ExcMax Point attribute range of
PI file system, 6 values, 51
structure, 6 ExcMin, 87
UNIX, 8 Point attribute, 53, 89
DisplayDigits ExDesc, 47
Page 138
Index of Topics
Point attribute, 53 getEngUnString, 128
ExDesc attribute, 44 getExcSpecsEng( ), 128
Executables for the PI System, 8 Group
Expensive Queries assigning users to, 38
clearing, 107 Database, 38
UNIX, 108 file, UNIX, 8
Extended descriptor Security, 95
Point attribute, 53 Handle. See Statement Handle
File System Compression I/O
recommendation against, 7 Timeout, 23
Files Initialization
archive, 19 SQL Subsystem, 100
PI file system, 6 Installation
Filtercode, 53 PI-SQL Checklist, 100
Point Attribute, 98 Instrument tag
Filtercode point attribute, 51 point attribute, 50
Filtering Instrument Tag
turning off exception Point attribute, 53
reporting, 90 int16 point type, 43
Filtering data int32 point type, 43
Exception reporting, 87 Integer point type, 43
Filtering, zero/span, 46 Interface
Firewall, 7, 95 definition of, 5
Database, 37 PerfMon, 5
float16 Ping, 5
changing zero/span, 46 Random and ramp soak, 1
out of range data, 46 sending digital states, 125
span attribute, 45 Sending to PI Server, 125
zero attribute, 45 Simulators, 5
float16 point type, 43 SNMP, 5
float32 Interfaces
Point type, 54 downloading documentation
float32 point type, 43 for, vi
float64 point type, 43 exception reporting, 87
formatting values PointSource attribute, 46
displayDigits attribute, 49 Interpolation, 124
getCompSpecs ( ), 127 of numeric values, 48
getCompSpecsEng ( ), 127 IP Address, 37
getDigCode ( ), 127 ipisql Utility, 103
getDigPointers( ), 127 options for, 104
getEngCode( ), 127 Istat, 126
getEngUnits( ), 128 Korn Shell, 8
PI Server Reference Guide Page 139
Index of Topics
Lab point source, 46 Calculation for timestamp, 117
LibC.ansi.sl OSIsoft
UNIX, 8 Error codes, 125
Libraries, 8 Out of order events
Localtime, 115, 126, 127 compression, 48
Location Codes Out of range
Point attribute, 50, 54, 98 for float16, 46
location1 point attribute, 50 Output to other systems
location2, 54 sourceTag attribute, 47
location2 point attribute, 50 Over Range, 45, 46
location3 point attribute, 50 digital state, 23
location4 point attribute, 50 Parameters
location5 point attribute, 50 COM program ID, 52
log directory, 6 longword mapping, 52
Log files server configuration, 25
location, 8 string mapping, 52
LOG option Password, 38, 95
SQL Subsystem, 106 file, UNIX, 8
Login, remote Performance
command-line tools, 4 impact of file system
Longword mapping parameter, 52 compression, 7
Mapped point, 15, 52 Performance Equations
Maximum use in SQL Subsystem, 99
Compression, 91 Performance tuning
Messages configuration parameters, 25
Timeout, 36 Permissions
Microsoft Common Object Model point and data, 49
(COM) technology, 14 PI 2
Minimum Daylight Savings Time
Compression, 91 Changes, 115
Module Database, 38 timestamps, 115
Naming tags, restrictions, 42 PI API, 121
Negative integers Buffering, 6
data types for, 43 Timestamp Translation to
Windows and UNIX PI
New Event Processing, 11
Systems, 117
NewTag, 54
Timestamps, 115
NewTag attribute, 44
PI point number, 51
No Data digital state, 23
PI Server
NT Services
databases, 19
pisqlss, 102
Daylight Savings Time to
ODBC Driver, 97 Standard Time, 118
Offset
Page 140
Index of Topics
Standard Time to Daylight pipt_pointid ( ), 124
Savings Time, 117 pipt_pointsource ( ), 124
Time Format, 111 pipt_recordtype ( ), 124
Timestamps, 117 pipt_rescode ( ), 124
Toolkit Usage, 127 pipt_tag ( ), 124
PI System pipt_taglong ( ), 124
API Time, 115 pipt_tagpreferred, 124
piadmin, 54 pipt_totalspecs ( ), 124
piapi32.dll, 8 pipt_updates ( ), 125
piar_replacevalue, 122 pipt_wildcardsearch ( ), 125
piartool PI-SDK, 97
remote login, 4 pisetpass utility, 95
piconfig, 20 pisn_getsnapshot ( ), 125
piel_addevnt ( ), 122 pisn_getsnapshots, 125
piel_evntactn ( ), 122 pisn_putsnapshot ( ), 125
pigetmsg pisn_putsnapshotq ( ), 125
remote login, 4 pisn_putsnapshots ( ), 125
pigrp, 8 pisn_sendexceptionq ( ), 125
pilistupd pisn_sendexceptions ( ), 125
remote login, 4 pisnap, 5
PINet/OpenVMS pisnap.bat, 20
Nodes pisnap.sh, 20
Time conversions, 117 pisnapss, 20
PI-ODBC Driver pisqlss, 97, 100
Minimum version, 97 configuring, 99
piparams.default continue command, 108
UNIX, 8 NT services, 99
PIPoint pause command, 108
Table, 98 performance tuning, 100
PIproxy records, 38 pisql.ini, 100
pipt_compspecs, 122 starting as an NT service, 102
pipt_compspecseng, 122 PISysDat
pipt_dates ( ), 122 pisql.ini, 100
pipt_descriptor ( ), 121, 122 PITimeout Table, 36
pipt_digcode ( ), 122 pitm_systime ( ), 126
pipt_digcodefortag ( ), 123 Point
pipt_engunitstring ( ), 123 deleting, 20
pipt_engunstring( ), 123 security, 18, 95
pipt_excspecseng, 123 Source data attribute, 54
pipt_exdesc ( ), 123 Point Attributes
pipt_findpoint ( ), 123 archiving, 48
pipt_nextptwsource ( ), 123
PI Server Reference Guide Page 141
Index of Topics
base class, 41 shutdown, 50
changeDate, 55 sourceTag, 47
changer, 55 span, 45
changing tag names, 42 Squareroot, 99
changing zero/span, 46 squareRoot attribute, 50
classic, 50 srcptid attribute, 51
compressing, 47 step, 48
Convers, 98 system assigned, 55
convers attribute, 51 tag name restrictions, 42
creationDate, 55 tag, case sensitivity, 42
creator, 55 Totalcode, 99
ctr_lmap, 52 totalcode attribute, 51
ctr_progid, 52 typicalValue, 45
ctr_strmap, 52 userInt and userReal attributes,
dataAccess, 49 51
dataGroup, 49 zero, 45
defaults, 52 Point Class, 15
Descriptor, 44 Point classes
digitalSet, 45 base class, 41
displayDigits, 49 classic, 50
engUnits, 46 classicctr point class, 52
exDesc, 44 for COM connectors, 52
Filtercode, 98 PtClassName attribute, 42
filtercode attribute, 51 Point Configuration, 15
for classic points, 50 Point Database, 19
for COM connectors, 52 default attribute values, 52
instrument tag attribute, 50 Point types
location attributes, 50 for accumulators, 43
Location Code, 98 for negative integers, 43
newTag, 44 PointID, 54
pointID, 55 point attribute, 55
Pointid, 98 Point attribute, 55, 98
PointSource, 46 Points
pointType, 43 about, 41
ptAccess, 49 access permissions, 49
PtClassName, 42 archiving attribute, 48
ptGroup, 49 attribute defaults, 52
recNo, 55 base class, 41
Recordtype, 99 case sensitivity, 42
Res, 99 changing tag names, 42
scan, 47 changing zero/span, 46
classic point class, 50
Page 142
Index of Topics
compDev, compMin, Priorities
compMax, 47 in SQL configuration methods,
compressing attribute, 47 100
compression on/off, 47 Profile
convers attribute, 51 File
data types, 43 Unix, 8
dataAccess, 49 Program ID parameter, 52
dataGroup, 49 Programs, point attributes for, 51
Descriptor attribute, 44 Proxy Access
digitalSet attribute, 45 Security, 96
displayDigits attribute, 49 Proxy Database, 37
engUnits attribute, 46 pt Created digital state, 23
exDesc attribute, 44 ptAccess
filtercode attribute, 51 Point attribute, 49, 54
instrument tag attribute, 50 ptclass command, 41
interpolation of values, 48 ptClassName attribute, 42
location attributes, 50 ptGroup
mapped, 52 Point attribute, 49, 54
naming restrictions, 42 ptOwner
newTag attribute, 44 Point attribute, 49, 54
PointSource attribute, 46 Queries
ptAccess, 49 SQL Subsystem, 104
PtClassName attribute, 42 Range
ptGroup, 49 the span attribute, 45
scan attribute, 47 the zero attribute, 45
shutdown attribute, 50 Real point type, 43
sourceTag attribute, 47 RecNo, 54
span attribute, 45 point attribute, 55
squareRoot attribute, 50 Point attribute, 55
srcptid attribute, 51 Records
step attribute, 48 record number attribute, 55
totalcode attribute, 51 Recordtype point attribute, 99
turn off data collection, 47 Redirector, 14
typicalValue attribute, 45 Relative Time, 111
userInt and userReal attributes, Remote adminstration, 4
51 Res point attribute, 99
viewing snapshot value, 5 Rescode, 124
zero attribute, 45 Restrictions on tag names, 42
PointSource attribute, 46 Scan attribute, 47
PointType, 54 Scan Flag, 54
PointType attribute, 43 Scan time
Precision, 11 slow, 92
PI Server Reference Guide Page 143
Index of Topics
Script files Initialization file, 100
classicctr.dif, 52 LOG option, 106
Security, 95 NT services, 99
access permissions, 49 statement handles, 97
Firewall, 37 Submitting Queries, 104
foreign data sources, 18 TRACE Option, 106
Servers Troubleshooting, 103
Time Conversions among, 115 tuning, 99
Shutdown Square root code
digital state, 23 Point attribute, 54, 99
flag, 50 SquareRoot
Point attribute, 54 point attribute, 50
Shutdown attribute, 50 srcptid attribute
Shutdown Events, 23 and sourceTag attribute, 47
Shutdown.dat file, 50 srcptid point attribute, 54
Significant events, 10 srcptid point attribute, 51
Simulator interfaces, 5 Standard Time, 115
Slow scan time, 92 to Daylight Savings Time, PI 3
SMT Server, 117
about, vi, 24 State 16383, 24
Snapshot State sets, 45
definition of, 11 Statement Handle, 97
from foreign data sources, 16 Handle ID
viewing current values, 5 PI-SQL, 107
Snapshot Subsystem Step
database, 20 flag, 93
definition of, 11 Point attribute, 54
Source tag, point number, 51 Step attribute, 48
Source, point source, 46 Step flag, 48
SourceTag, 54 String
SourceTag attribute, 47 Data Types, 121
Span String mapping parameter, 52
Point attribute, 54 String point type, 43
Span attribute, changing, 46 Subsecond timestamps, 121
SQL Subsystem, 97 Subsystem
architecture, 97 PI-SQL, 97
argument, 100 Snapshot, 11
Command line arguments, 100 Subsystems
configuration, 99 dependencies among, 1
methods, conflicts in, 100 Swinging door compression, 91
Generating a Trace, 106 System
state set, 45
Page 144
Index of Topics
State Set, 24 ptGroup, 49
Time, 119 scan attribute, 47
System Management Tools, vi, 24 shutdown attribute, 50
System-assigned attributes, 55 sourceTag attribute, 47
Table span attribute, 45
Digital State, 23, 24 step attribute, 48
PIPoint, 98 turn off data collection, 47
Tables typicalValue attribute, 45
timeout, 25 viewing snapshot value, 5
Tag zero attribute, 45
Digital, 92 Technical Support, 133
system digital state set, 23 Time
Tag attribute, changing, 42 API Time, 115
Tag names between events, 91
capitalization, 42 Changes
Tagname Daylight Savings to
Point attribute, 54 Standard, 118
Tagnames PI 2 Systems, 115
constraints, 42 PI Client Applications,
119
in external systems, 50
conversions, 115
Tags. See points
Format, 111
archiving attribute, 48
Local time, 115
changing names, 42
System Time, 119
changing zero/span, 46
transitions
compDev, compMin,
compMax, 47 from Open VMS and PI
API to Windows and
compressing attribute, 47
UNIX, 117
compression on/off, 47
PI 2 Systems, 115
constraints, 42
PI Server Systems, 117
dataAccess, 49
translations
dataGroup, 49
PINet nodes, 117
Descriptor attribute, 44
Zone, 115, 126
digitalSet attribute, 45
Timeout database, 25
displayDigits attribute, 49
Timeout table, 25
engUnits attribute, 46
Timestamp
exDesc attribute, 44
across time zones on PI 2
in external systems, 50 System, 116
interpolation of values, 48 Conversions
mapped, 52 algorithm, 117
newTag attribute, 44 PI 3 & PI 2, 115
PointSource attribute, 46 PI Server, 117
ptAccess, 49
PI Server Reference Guide Page 145
Index of Topics
Subsecond, 121 Universal Interface
year 2000, 120 downloading documentation
Timestamp point type, 43 for, vi
Timing parameters, 25 UNIX
UNIX, 36 directory and file structure, 8
Toolkit Usage, 127 UNIX directory structure, 8
Totalcode point attribute, 51 User
Totalcode Point Attribute, 99 Database, 38
TRACE Option User programs, point attributes for,
51
SQL Subsystem, 106
UserInt1 point attribute, 51
Trend
UserInt2, 54
seasonal time changes, 120
UserInt2 point attribute, 51
Trends
UserReal1, 55
formatting numbers, 49
UserReal1 point attribute, 51
Troubleshooting
UserReal2, 55
SQL Subsystem, 103
UserReal2 point attribute, 51
Tuning the PI Server
UTC, 126
configuration parameters, 25
Utility
Turning off exception reporting, 90
ipisql, 103
Types
piconfig, 20
about point types, 43
pisetpass, 38
for accumulators, 43
pisnap.bat, 20
for negative integers, 43
pisnap.sh, 20
TypicalValue
Version
Point attribute, 54
PI Server, 4
TypicalValue attribute, 45
Visual Basic, 6
TZ environment variable, 126
Windows
UCT, 117
Directory and file structure, 8
Under Range, 45, 46
Year 2000
Under Range digital state, 23
Timestamps, 120
UniInt
Zero
downloading documentation
for, vi Point attribute, 55
Units, engineering, 46 Zero attribute, 45
Universal Coordinated Time, 115, Zero attribute, changing, 46
117, 126
Page 146
PI Server Applications User Guide
PI3 Server
Version 3.4.370
PI Performance Equations Scheduler
PI Performance Equations Recalculator
PI Performance Equations Syntax and Functions Reference
PI Steam Functions Reference
PI Batch Database
PI Totalizer Subsystem
PI Alarm Subsystem
PI Real-Time SQC
© 1998-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PI Server Applications User Guide explains how to use PI Server Applications.
PI Server Applications are supplemental subsystems that you can run in conjunction with the
PI Server to provide additional functionality. PI Server Applications are not necessary to
run the PI Server, and are typically licensed separately.
The PI Server Applications included in this guide are:
PI Performance Equations Scheduler
PI Performance Equations Recalculator
PI Steam Functions Module
PI Batch Database
PI Totalizer Subsystem
PI Alarm Subsystem
PI Real-Time Statistical Quality Control (SQC)
This guide provides full administration and end-user instructions for the PI Server
Applications listed above. An additional PI Server Application, the PI Batch Generator
Interface (PIBaGen), is not discussed in this guide. For information regarding PIBaGen, see
the PI Batch Generator User Guide.
Installation Note
The PI Server and Server Applications are distributed together as one installation. Your
ability to use any one of the PI Server Applications depends upon your EULA (End-user
License Agreement.) Contact OSIsoft Technical Support for licensing information.
PI Server Applications User Guide Page iii
Preface - Using this Guide
The PI Server Documentation Set
The PI Server Documentation Set includes seven user guides, described below.
Tip: Updated user guides, which provide the most up-to-date information, are
available for download from the OSIsoft Technical Support Web site
(http://techsupport.osisoft.com).
Title Subject Matter
Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security and
trusts, and performance. It includes a glossary and resource guide.
PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.
PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data Archive,
monitoring system health, managing backups, interfaces, security, and
moving and merging servers. Includes comprehensive instructions for using
command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth
troubleshooting and repair information.
PI Server Reference A comprehensive reference guide for the system administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).
Auditing the PI An administration guide that explains the Audit Database, which provides a
Server secure audit trail of changes to PI System configuration, security settings,
and Archive Data. It includes administration procedures to enable auditing, to
set subsystem auditing mode, to create and archive database files, and to
export audit records.
PI Server A guide to key add-on PI Server Applications: Performance Equations (PE),
Applications User Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality
Guide Control). Includes a reference guide for Performance Equations, and Steam
calculation functions.
PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
Page iv
Preface - Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI Client Tools Use the client tool, PI ProcessBook, to verify that all
PI System Elements data has been recovered.
PI Server Subsystems All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text Files, Directories, Paths The backup script is located in the \PI\adm directory.
Emphasis Archive files can be either fixed or dynamic. The
New Terms archive receiving current data is called the Primary
Archive.
Fields
See Section 4.2, Create a New Primary Archive.
References to a chapter or section
Bold Italic text References to a publication See the PI Server Reference Guide.
Bold text System and Application The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
Procedures and Key Commands On the Tools menu, click Advanced Options.
Press CTRL+ALT+DELETE to reboot
Interface components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: Code examples use the piartool -ss command. For example:
"Consolas" Commands to be typed on the
font command line (optionally with
arguments or switches)
System input or output such as
excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
PI Server Applications User Guide Page v
Preface - Using this Guide
Related Documentation
OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. PI Server Applications................................................................................................1
Chapter 2. PI Performance Equations Scheduler.......................................................................5
Chapter 3. PI Performance Equations Recalculator ................................................................19
Chapter 4. PI Performance Equations Syntax and Functions Reference ..............................45
Chapter 5. PI Steam Functions Reference ..............................................................................185
Chapter 6. PI Batch Database...................................................................................................239
Chapter 7. PI Totalizer Subsystem...........................................................................................255
Chapter 8. PI Alarm Subsystem ...............................................................................................291
Chapter 9. PI Real-Time SQC....................................................................................................333
PI Server Applications User Guide Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Table of Tables...............................................................................................................................xvii
Table of Figures ..............................................................................................................................xix
Chapter 1. PI Server Applications................................................................................................1
1.1 PI Server Applications Overview .....................................................................................1
1.1.1 PI Performance Equations Scheduler ....................................................................1
1.1.2 PI Performance Equations Recalculator ................................................................1
1.1.3 PI PE Syntax and Functions Reference .................................................................2
1.1.4 PI Steam Functions Reference ..............................................................................2
1.1.5 PI Batch Database..................................................................................................2
1.1.6 PI Totalizer Subsystem...........................................................................................2
1.1.7 PI Alarm Subsystem ...............................................................................................3
1.1.8 PI Real-Time SQC..................................................................................................3
Chapter 2. PI Performance Equations Scheduler.......................................................................5
2.1 About Calculated Points ...................................................................................................6
2.2 About the PE Subsystem..................................................................................................6
2.2.1 Start and Stop the PE Subsystem..........................................................................6
2.3 Procedure to Create Calculated Points...........................................................................7
2.4 Determine Scan Classes and Point Source ....................................................................8
2.4.1 Find the PE Subsystem Point Source ....................................................................8
2.4.2 Specify the Optional Instance ID ............................................................................9
2.4.3 Find the PE Subsystem Scan Classes...................................................................9
2.5 Choose a Scheduling Method ........................................................................................11
2.6 Set Attributes for Calculated Points..............................................................................11
2.6.1 Set the Point Source.............................................................................................12
2.6.2 Set the Location3 Attribute: Timestamp ...............................................................12
2.6.3 Set the Location4 Attribute: Scan Class...............................................................12
2.6.4 Set the ExDesc Attribute: Calculation Expressions..............................................13
PI Server Applications User Guide Page ix
Table of Contents
2.6.5 Set the Scan Attribute...........................................................................................14
2.6.6 Set the Shutdown Attribute...................................................................................14
2.6.7 Examples of Calculation Expressions ..................................................................14
2.7 Tips and Troubleshooting ..............................................................................................15
2.7.1 Tips for Creating Calculated Points......................................................................16
2.7.2 Common Performance Equation Problems and Errors........................................16
2.7.3 Prevent Scheduling Errors....................................................................................17
2.7.4 Prevent Skipped Calculations ..............................................................................17
2.7.5 When Data Types Don't Match.............................................................................18
Chapter 3. PI Performance Equations Recalculator ................................................................19
3.1 Recalculator Overview ....................................................................................................19
3.1.1 Glossary of Recalculation Terms .........................................................................20
3.2 PE Recalculator Functionality........................................................................................21
3.2.1 Point Dependency Considerations .......................................................................21
3.2.2 Time Range Considerations .................................................................................22
3.2.3 Clock-Scheduling vs. Event-based Scheduling....................................................23
3.2.4 Step Point Attribute...............................................................................................23
3.2.5 Compression / Exception......................................................................................23
3.2.6 Scan and Archiving Attributes ..............................................................................23
3.2.7 Location1 ..............................................................................................................23
3.3 Types of PE Point / Time Relationships........................................................................24
3.3.1 Type 1: Simple Point Relationship .......................................................................24
3.3.2 Type 2: Multi-level Dependency Point Relationship.............................................27
3.3.3 Type 3: Recursive Point Relationship ..................................................................28
3.3.4 Type 4: Relative Point Relationship .....................................................................28
3.3.5 Type 5: Special Event Point Relationship ............................................................29
3.3.6 Type 6: Time Range Point Relationship...............................................................30
3.3.7 Type 7: Multi-level Time Dependency ..................................................................30
3.3.8 Type 8: Absolute Time Reference Point Relationship..........................................31
3.4 Special PE Time Functions.............................................................................................31
3.4.1 Modify a Timestamp .............................................................................................31
3.4.2 Parsetime Function...............................................................................................31
3.4.3 Extract a Number from a Timestamp ...................................................................32
3.5 Examples of Archive Retrieval / Search Functions .....................................................32
3.6 Recalculation Limitations ...............................................................................................32
3.6.1 Source Variables without Archive Values.............................................................32
Page x
Table of Contents
3.6.2 Exact Simulation of the Original Scan Cycles ......................................................33
3.6.3 Modifications of the Performance Equation..........................................................33
3.6.4 Archive and Time Functions .................................................................................33
3.6.5 Unsupported Dynamic Functions .........................................................................33
3.6.6 Incomplete Timestamps .......................................................................................33
3.6.7 Blob Support.........................................................................................................34
3.7 Recalculator Point Configuration ..................................................................................34
3.7.1 Point Name...........................................................................................................34
3.7.2 Extended Descriptor .............................................................................................34
3.7.3 Point Source .........................................................................................................34
3.7.4 Scan......................................................................................................................34
3.7.5 Archiving ...............................................................................................................34
3.7.6 Location1 ..............................................................................................................34
3.7.7 Location4 ..............................................................................................................35
3.7.8 PointType..............................................................................................................35
3.7.9 Step ......................................................................................................................35
3.7.10 Other Attributes ....................................................................................................35
3.8 Start Recalculator as a Service ......................................................................................35
3.8.1 Configure Startup and Shutdown .........................................................................36
3.8.2 Specify Options with a Startup Script File ............................................................37
3.8.3 Specify Options with the Windows Registry .........................................................40
3.8.4 Run Multiple Instances .........................................................................................41
3.9 Start Recalculator Manually ...........................................................................................42
3.9.1 Recalculator Startup Options ...............................................................................42
3.9.2 Manual Recalculations .........................................................................................42
3.10 Stop Recalculator ............................................................................................................43
3.11 Optimize Recalculator Performance..............................................................................44
3.12 Error and Information Messages ...................................................................................44
Chapter 4. PI Performance Equations Syntax and Functions Reference ..............................45
4.1 Performance Equations Syntax .....................................................................................45
4.1.1 Performance Equation Syntax..............................................................................45
4.1.2 Performance Equation Operands.........................................................................46
4.1.3 Tagname Operands..............................................................................................47
4.1.4 String Operands ...................................................................................................48
4.1.5 Time Expression Operands ..................................................................................49
4.1.6 Function Operands ...............................................................................................51
PI Server Applications User Guide Page xi
Table of Contents
4.1.7 List of all Performance Equation Operators .........................................................52
4.1.8 Operator Priority ...................................................................................................58
4.1.9 Data Types ...........................................................................................................58
4.1.10 Error Values..........................................................................................................59
4.1.11 Test the Performance Equation Syntax................................................................59
4.2 Performance Equations Functions................................................................................60
4.2.1 Function Arguments .............................................................................................60
4.3 List of Built-in Functions ................................................................................................61
4.3.1 Functions Grouped By Type.................................................................................61
4.3.2 Functions Listed Alphabetically ............................................................................65
4.4 Performance Equations Functions Reference .............................................................70
Chapter 5. PI Steam Functions Reference ..............................................................................185
5.1 Steam Functions Overview...........................................................................................185
5.1.1 Steam Functions Naming Convention................................................................186
5.2 Range of Steam Functions ...........................................................................................187
5.2.1 Functions that use Temperature and Pressure as Independent Variables........187
5.2.2 Functions that use Enthalpy or Entropy as an Independent Variable ................188
5.3 Steam Property Reference States................................................................................189
5.4 Steam Functions Reference .........................................................................................190
Chapter 6. PI Batch Database...................................................................................................239
6.1 PI Batch Overview .........................................................................................................239
6.1.1 The PI Batch Subsystem (BSS), PI Batch Database (PBD), and PI Batch
Generator (PIBaGen) .........................................................................................240
6.1.2 Compatibility of PI-API Batch Applications for PI2 (OpenVMS) Servers ...........241
6.1.3 Glossary of Batch Terms ....................................................................................241
6.2 Installation......................................................................................................................241
6.3 Configuration .................................................................................................................241
6.3.1 Unit Configuration...............................................................................................241
6.3.2 Alias Configuration .............................................................................................247
6.4 Batch Data Information .................................................................................................250
6.4.1 PI Batch Data (PIBATCH) Table ........................................................................250
6.4.2 Common Operations ..........................................................................................251
6.5 Batch Subsystem Operation ........................................................................................253
6.5.1 Check for Unit Consistency ................................................................................253
6.5.2 Monitor Activation Tags for Transitions ..............................................................253
6.5.3 Evaluate BIDExpr and ProdExpr ........................................................................253
Page xii
Table of Contents
6.6 Client Access to Batch Subsystem Batches ..............................................................254
6.7 Complete Example ........................................................................................................254
Chapter 7. PI Totalizer Subsystem...........................................................................................255
7.1 Totalizer Subsystem Overview ....................................................................................255
7.1.1 Totalizer vs. Performance Equations .................................................................256
7.2 Totalizer ConfigurationOverview .................................................................................258
7.2.1 Creation of a Totalizer Point ...............................................................................258
7.2.2 Totalizer Input Values.........................................................................................259
7.3 Totalizer Point Class Attributes ...................................................................................260
7.3.1 SourceTag ..........................................................................................................263
7.3.2 RateSampleMode...............................................................................................263
7.3.3 TotalCloseMode .................................................................................................266
7.3.4 ReportMode........................................................................................................273
7.3.5 Function ..............................................................................................................274
7.3.6 CalcMode............................................................................................................277
7.3.7 ZeroBias .............................................................................................................281
7.3.8 Period .................................................................................................................281
7.3.9 Offset ..................................................................................................................282
7.3.10 MovingCount ......................................................................................................282
7.3.11 Period2 ...............................................................................................................282
7.3.12 Offset2 ................................................................................................................282
7.3.13 PctGood..............................................................................................................282
7.3.14 Conversion .........................................................................................................283
7.3.15 FilterExpr ............................................................................................................283
7.3.16 EventExpr ...........................................................................................................284
7.3.17 CompValue.........................................................................................................284
7.3.18 Options ...............................................................................................................284
7.4 Build Totalizer Points....................................................................................................286
7.4.1 SMT Totalizer Editor Plug-in ..............................................................................286
7.4.2 PI TagConfigurator .............................................................................................287
7.4.3 Piconfig ...............................................................................................................287
7.5 Program Operation........................................................................................................288
7.5.1 Startup ................................................................................................................288
7.5.2 Error Messages ..................................................................................................288
7.5.3 Response to Scan Flag ......................................................................................288
PI Server Applications User Guide Page xiii
Table of Contents
7.6 PI for OpenVMS Upgrade Considerations ..................................................................288
7.6.1 Features in PI3 versus PI for OpenVMS ............................................................289
7.6.2 Compatibility with PI for OpenVMS ....................................................................289
7.7 Demonstration Points ...................................................................................................290
Chapter 8. PI Alarm Subsystem ...............................................................................................291
8.1 Alarm Subsytem Overview ...........................................................................................292
8.1.1 Alarm Points .......................................................................................................292
8.2 Alarm Point Configuration............................................................................................294
8.2.1 SourceTag ..........................................................................................................295
8.2.2 Test1, Test2, Test3, Test4..................................................................................295
8.2.3 Action1, Action2, Action3, Action4 .....................................................................304
8.2.4 ExDesc ...............................................................................................................306
8.2.5 DigitalSet ............................................................................................................306
8.2.6 ReferenceTag.....................................................................................................306
8.2.7 AutoAck ..............................................................................................................306
8.2.8 DeadBand...........................................................................................................307
8.2.9 Options ...............................................................................................................307
8.2.10 ControlTag ..........................................................................................................307
8.2.11 ControlAlg ...........................................................................................................308
8.3 Alarm State Sets ............................................................................................................308
8.3.1 Condition.............................................................................................................308
8.3.2 Acknowledgement Status ...................................................................................308
8.3.3 Priority.................................................................................................................309
8.4 Alarm Groups.................................................................................................................312
8.4.1 Alarm Group Point Configuration .......................................................................313
8.5 Build Alarm Points ........................................................................................................314
8.5.1 PI TagConfigurator .............................................................................................314
8.5.2 Piconfig ...............................................................................................................315
8.6 Build Alarm Group Points.............................................................................................315
8.6.1 PI TagConfigurator .............................................................................................315
8.6.2 Piconfig ...............................................................................................................316
8.7 Override Default PointSource Values for Alarms.......................................................316
8.8 Build Alarm Digital State Sets ......................................................................................317
8.9 Program Operation........................................................................................................319
8.9.1 Startup ................................................................................................................319
8.9.2 Alarm Notification ...............................................................................................319
Page xiv
Table of Contents
8.9.3 Error Messages ..................................................................................................320
8.9.4 Demonstration Points .........................................................................................321
8.10 PI for OpenVMS Upgrade Considerations ..................................................................321
8.10.1 New Alarm Subsystem Features in PI Server 3.4 ..............................................321
8.11 Alarm State Set Encoding and Decoding....................................................................321
8.11.1 Conversion to Digital State code ........................................................................322
8.11.2 Conversion from Digital State Code ...................................................................323
8.11.3 Sample Alarm Digital State Sets ........................................................................323
8.11.4 Digital Base Set ..................................................................................................327
Chapter 9. PI Real-Time SQC....................................................................................................333
9.1 Introduction to Statistical Quality Control ..................................................................334
9.2 Case Study for PI Real-Time SQC................................................................................334
9.3 Real-Time SQC Definitions and Terminology.............................................................335
9.4 Tests for Unnatural Patterns ........................................................................................337
9.4.1 Western Electric Unnatural Pattern Tests ..........................................................337
9.4.2 Pattern Types and Tests ....................................................................................338
9.5 PI Real-Time SQC Configuration..................................................................................340
9.5.1 Required and Optional Points ............................................................................341
9.6 Pattern Tests ..................................................................................................................341
9.7 SQC Alarm Priority and Precedence ...........................................................................342
9.7.1 Priority.................................................................................................................342
9.7.2 Precedence ........................................................................................................342
9.8 Create a New SQC Alarm ..............................................................................................343
9.9 Start and Run the PI Alarm Subsystem.......................................................................343
9.9.1 Initial Subsystem Startup....................................................................................344
9.9.2 Subsystem Startup .............................................................................................345
9.9.3 Subsystem Shutdown.........................................................................................346
9.10 Associated Point Configuration...................................................................................347
9.10.1 Tools to Create and Edit Associated PI Points...................................................347
9.10.2 Summary of Associated PI Points for SQC Alarms............................................347
9.10.3 Configure the Associated Points ........................................................................348
9.11 PI SQC Alarm Point Configuration...............................................................................351
9.11.1 Methods for Configuring PI SQC Alarm Points ..................................................351
9.11.2 SQC Alarm Point Class ......................................................................................352
9.11.3 Pattern Test Configuration..................................................................................356
9.11.4 Associated-Point Tagnames...............................................................................358
PI Server Applications User Guide Page xv
Table of Contents
9.12 PI Real-Time SQC Chart Types ....................................................................................359
9.12.1 Charts of Individuals ...........................................................................................359
9.12.2 Moving Average, Moving Range and Moving Standard Deviation.....................360
9.12.3 X-Bar, Range and Standard Deviation ...............................................................360
9.12.4 EWMA.................................................................................................................360
9.13 Default SQC Alarm Digital States ................................................................................360
9.14 Log Messages ................................................................................................................363
9.14.1 View Log Messages ...........................................................................................363
9.14.2 Log Message Reference ....................................................................................363
Technical Support and Resources...............................................................................................367
Index of Topics...............................................................................................................................369
Page xvi
TABLE OF TABLES
Table 2–1. Attributes that Require a Special Setting for Calculated Points.............................11
Table 3–1. Glossary of Recalculation Terms ...........................................................................20
Table 3–2. Types of PE Point / Time Relationships.................................................................24
Table 3–3. Recalculator Startup Options .................................................................................38
Table 3–4. Recalculator Debug Levels and Output .................................................................40
Table 4–1. Operands in Performance Equations.....................................................................46
Table 4–2. Examples of Time Syntax ......................................................................................50
Table 4–3. PE Operators, Listed by Type, with Examples ......................................................52
Table 4–4. PE Arithmetic Operators ........................................................................................53
Table 4–5. Valid Operations on Time Values ..........................................................................54
Table 4–6. Relational Operators in Performance Equations ...................................................55
Table 4–7. Prefix Operators .....................................................................................................56
Table 4–8. Conjunction, Disjunction and Inclusion Operators .................................................57
Table 4–9. Operator Priority.....................................................................................................58
Table 4–10. Functions Grouped by Type.................................................................................62
Table 4–11. Functions Listed Alphabetically............................................................................65
Table 5–1. Engineering Units.................................................................................................185
Table 5–2. Supported Functions ............................................................................................186
Table 5–3. Digital States Returned ........................................................................................187
Table 5–4. Input Range for Each Function ............................................................................187
Table 6–1. PIBAUNIT Table Attributes ..................................................................................242
Table 6–2. Configuration Differences from PI BA in PI2 (OpenVMS)....................................245
Table 6–3. PIBAALIAS Table Attributes ................................................................................248
Table 6–4. PIBATCH Table Attributes ...................................................................................250
Table 7–1. Five Major Parameters that Affect Totalizer.........................................................258
Table 7–2. Totalizer Point Class Attribute Set .......................................................................260
Table 7–3. Allowed Combinations of TotalCloseMode and ReportMode ..............................273
Table 7–4. Viable Function and CalcMode Options...............................................................274
Table 7–5. Conversion Factors for Units ...............................................................................283
PI Server Applications User Guide Page xvii
Table of Tables
Table 7–6. PI for OpenVMS and PI for NT and UNIX Equivalents ........................................289
Table 8–1. Alarm Point Class Attributes ................................................................................294
Table 8–2. Example Test Comparisons and the Alarm Status ..............................................296
Table 8–3. Viable Argument Data Types for Operators.........................................................297
Table 8–4. Comparisons of the Is_In Operator......................................................................301
Table 8–5. Comparisons of the Not_In Operator ...................................................................302
Table 8–6. Comparisons of the Includes Operator ................................................................303
Table 8–7. Comparisons of the CondEQ Operator................................................................304
Table 8–8. Examples Using First Syntax (Condition Priority) ................................................305
Table 8–9. Examples Using Second Syntax (StateName) ....................................................305
Table 8–10. Combiner Logic Examples .................................................................................306
Table 8–11. Sample Alarm Conditions ..................................................................................308
Table 8–12. Three-state Acknowledgement Status ...............................................................309
Table 8–13. Single Priority Alarm State Set...........................................................................309
Table 8–14. Example Three-priority-level System .................................................................309
Table 8–15. Alarm Digital State Set with Three Priorities......................................................310
Table 8–16. Example Digital Alarm State Set with One Priority ............................................311
Table 8–17. Example Digital Alarm Set with Three Priorities ................................................311
Table 8–18. PointFunc Options..............................................................................................313
Table 8–19. Example Alarm Group........................................................................................313
Table 8–20. One Priority Alarm Set .......................................................................................323
Table 8–21. Three Priority Alarm Set.....................................................................................324
Table 8–22. Single Priority Alarm Set (Digital Base Set) .......................................................327
Table 8–23. Three Priority Alarm Set (Digital Base Set)........................................................329
Table 9–1. Precedence of SQC Alarm's Pattern Tests.........................................................343
Table 9–2. Summary of Associated Points ...........................................................................347
Table 9–3. TestStatusTag Bits Indicate SQC Alarm State ...................................................349
Table 9–4. Examples of TestStatusTag values ....................................................................349
Table 9–5. Values of the ResetTag.......................................................................................350
Table 9–6. SQC_Alarm Point Class Attributes .....................................................................352
Table 9–7. Valid ChartType Values ......................................................................................355
Table 9–8. Pattern Test Configuration Examples .................................................................357
Table 9–9. Default DigitalSet for SQC Alarms ......................................................................360
Table 9–10. Informational Messages ....................................................................................363
Table 9–11. Error Messages: Serious Errors........................................................................364
Page xviii
TABLE OF FIGURES
Figure 3–1. Recalculation Period on Type = Simple, Step=1, No Compression .....................25
Figure 3–2. Recalculation Period on Type = Simple, Step=0, No Compression .....................26
Figure 3–3. Recalculation Period on Type = Simple, Step=0, PE Point with Compression ....27
Figure 3–4. Type = Relative Time Shift....................................................................................29
Figure 3–5. Type = Relative Time Reference ..........................................................................30
Figure 4–1. Block Diagram of ARMA Calculation Function .....................................................77
Figure 7–1. Exception Reporting............................................................................................256
Figure 7–2. Time Weighted Calculation for Totalizer and Performance Equation.................257
Figure 7–3. Flow Diagram for the Creation of a Totalizer Point.............................................259
Figure 7–4. Natural Sampling ................................................................................................263
Figure 7–5. Scan1 Sampling..................................................................................................264
Figure 7–6. Scan2 Sampling..................................................................................................265
Figure 7–7. Event Sampling...................................................................................................265
Figure 7–8. TotalCloseMode of Clock....................................................................................266
Figure 7–9. TotalCloseMode of EventChange.......................................................................267
Figure 7–10. TotalCloseMode of EventTrue ..........................................................................268
Figure 7–11. TotalCloseMode of NsampleMoving (1) ...........................................................269
Figure 7–12. TotalCloseMode of NSampleMoving (1)...........................................................270
Figure 7–13. TotalCloseMode of NSampleBlock ...................................................................271
Figure 7–14. TotalCloseMode of TimeMoving and RateSampleMode of Natural .................272
Figure 7–15. TotalCloseMode of TimeMoving and RateSampleMode of Scan2...................272
Figure 7–16. TimeWeighted Total for Natural and Scan1 with Step=0 .................................278
Figure 7–17. Time-Weighted Total for Natural and Scan2 with Step=1 ................................278
Figure 7–18. Event-Weighted Total for Natural .....................................................................279
Figure 7–19. Event-Weighted Average for Scan1 .................................................................279
Figure 7–20. Digital States with RateSampleMode of Natural...............................................280
Figure 7–21. Digital States with RateSampleMode of Scan1 or Scan2.................................281
Figure 7–22. Time-Weighted Total with Scan1 and CloseAtEvent........................................285
Figure 7–23. PI TagConfigurator Creation of Totalizer Point.................................................287
PI Server Applications User Guide Page xix
Table of Figures
Figure 7–24. Export Tags Dialog Box ....................................................................................287
Figure 8–1. Flow Diagram of Alarm Points ............................................................................293
Figure 8–2. Calculation of Rate of Change............................................................................300
Figure 8–3. Deadbands for Upper and Lower Alarm Limits...................................................307
Figure 8–4. PI TagConfigurator Creation of Alarm Point .......................................................315
Figure 8–5. PI Tag Configurator.............................................................................................316
Figure 8–6. Editing Default PointSource Values for Alarms ..................................................317
Figure 8–7. Example PI ProcessBook Display of Alarms ......................................................320
Figure 9–1. San Francisco Bay Salinity .................................................................................337
Figure 9–2. SQC Chart Zone Definition .................................................................................338
Figure 9–3. One Point Outside 3 Sigma Limit (Instability) .....................................................338
Figure 9–4. Two of Three Points in Zone A or Beyond (Instability) .......................................339
Figure 9–5. Four of Five Points in Zone B or Beyond (Instability) .........................................339
Figure 9–6. Eight Successive Points Fall on One Side of the Center Line (Instability) .........339
Figure 9–7. Fifteen Consecutive Points in Zone C (Stratification) .........................................340
Figure 9–8. Eight Points on Both Sides of Center with None in Zone C (Mixture) ................340
Figure 9–9. Limits for Pattern Tests .......................................................................................342
Page xx
Chapter 1. PI SERVER APPLICATIONS
1.1 PI Server Applications Overview
The power of the PI System is enhanced by the PI Server Applications, which work on top of
the PI Server. PI Server Applications are a set of processing tools that help you get more out
of your data by automating specific processes.
The PI Server Applications and reference sections included in this guide are:
Chapter 2 – PI Performance Equations Scheduler
Chapter 3 – PI Performance Equations Recalculator
Chapter 4 – PI PE Syntax and Functions Reference
Chapter 5 – PI Steam Functions Reference
Chapter 6 – PI Batch Database
Chapter 7 – PI Totalizer Subsystem
Chapter 8 – PI Alarm Subsystem
Chapter 9 – PI Real-Time Statistical Quality Control (SQC)
1.1.1 PI Performance Equations Scheduler
The Performance Equations (PE) Scheduler provides an equation syntax and library of
built-in functions that allow you to perform a wide variety of calculations on PI data.
Performance Equations can work with frequently-updating Snapshot and Archive values,
whereas tools such as spreadsheets only have access to Archive data and limited access to
Snapshot update values.
Each Performance Equation is associated with a PI point, and the calculation results are
stored in the PI Archive. The performance equation point may be configured to be evaluated
periodically by the PE Scheduler (time-based). Alternatively, it may be configured to be
evaluated when an event is received on a specified trigger point (event-based).
1.1.2 PI Performance Equations Recalculator
The Performance Equations is designed to adjust values of Performance Equation points
automatically. The adjustment occurs when Archive values of points that are used in
Performance Equation expressions are added, changed, or deleted. You can also use
Recalculator as an offline utility to reprocess explicit periods of time for specific points.
PI Server Applications User Guide Page 1
Chapter 1 - PI Server Applications
1.1.3 PI PE Syntax and Functions Reference
PI Performance Equations allows you to easily implement sophisticated, real-time
calculations, using data in the PI System. Calculations can include unit performance, real-
time cost accounting, real-time yield accounting, batch summary, conversions and
totalizations not performed by PI Totalizer, logical operations, and calculating aggregates.
This chapter provides comprehensive instructions for using Performance Equations syntax
and functions.
1.1.4 PI Steam Functions Reference
The PI Steam Functions module is an extension to the PI Performance Equations Scheduler.
Steam Functions provide a complete set of functions for deriving the thermodynamic
properties of steam and water. PI Steam Functions support both English and SI units, and are
based on the ASME (American Society of Mechanical Engineers) Steam Tables, 6th Ed.
This chapter provides a comprehensive reference for setting up Steam calculations.
1.1.5 PI Batch Database
Most processes have repeatable time segments or stages. PI Batch Database technology
maps process or manufacturing events to slices of time and data, and stores these in the PI
Data Archive. Identifying these process stages and measuring their repeatability is the
purpose of PI Batch. Building this fundamental association enables powerful data and process
analysis for both traditional and non-traditional batch processes.
While industries such as chemical and pharmaceutical use PI Batch to track and analyze
batches, it is also widely used in non-batch applications to identify and track process events.
PI Batch tracks and stores batch and process based events hierarchically as Batches, Unit
Batches, or Sub Batches.
PI Batch is used in conjunction with its companion client application PI BatchView, which
allows you to view and compare events that have been collected by PI Batch and stored in the
PI System.
1.1.6 PI Totalizer Subsystem
The Totalizer Subsystem performs common calculations such as totals, averages, minimum
and maximum values, and standard deviations. The output of a calculation is stored in a PI
point.
The main difference between a Performance Equations point and a Totalizer point is that
Performance Equations are based on Archive events, while Totalizer results are based on
Snapshot events.
PI Totals are the most accurate way to represent production summary data. Totalizers can be
started and reset based on time and event, and ensure the highest accuracy in the calculation
of flow volumes and other critical variables used to monitor product transfers or production
performance. Totalizer is especially practical for totaling measurements or other process
variables at the end of specific time periods, such as the end-of-day yields.
Page 2
1.1 - PI Server Applications Overview
1.1.7 PI Alarm Subsystem
The Alarm Subsystem provides the capability to establish alarms for PI points. PI Alarm
allows you to track, manage and acknowledge alarm conditions caused by processes that
exceed user-specified parameters.
PI Alarm keeps a constant eye on process conditions. PI Alarm can monitor many variables
such as temperatures, volumes, flow rates, product quality or raw material consumption.
Alarms can be triggered by the duration of an event or deviation from norm.
PI Alarm will assess the condition as well as the priority of an event, as you define it.
Depending on the longevity and/or severity of the event, it can notify specific personnel. PI
Alarm includes client functionality through the PI-API to alert operators to selected alarms.
Data from PI Alarm are displayed in its companion client application, PI AlarmView. Alarm
conditions are historized together with an acknowledgement status.
1.1.8 PI Real-Time SQC
PI Real-Time Statistical Quality Control (SQC) uses numerical methods to monitor the
characteristics of a process, making sure they remain within pre-determined boundaries.
When Real-Time SQC perceives an unacceptable deviation in a process, PI Real-Time SQC
Alarms alert the appropriate personnel.
The PI Real-Time SQC component makes it easy to apply the Western Electric Pattern Tests
to all of your process or laboratory data collected by the PI System. PI Real-Time SQC
continually reviews any SQC tests in the PI System. It stores test results and a record of SQC
control limits back into your PI System. The results are available for viewing and analysis via
PI ProcessBook and the PI SQC Add-In.
The SQC Subsystem is a part of the PI Alarm Subsystem, which provides continual
evaluation of SQC pattern tests and the management of alarms generated from them.
PI Server Applications User Guide Page 3
Chapter 2. PI PERFORMANCE EQUATIONS SCHEDULER
This chapter explains how to create calculated points using the PI Performance Equations
(PE) Scheduler. The PE Scheduler allows you to implement sophisticated online calculations
without having to program in high-level languages.
The PE Scheduler provides an equation syntax and library of built-in functions that allow you
to perform a wide variety of calculations on PI data. (See Chapter 4: PI Performance
Equations Syntax and Functions Reference.) Performance Equations can work with
frequently-updating Snapshot and Archive values, whereas tools such as spreadsheets only
have access to Archive data and limited access to Snapshot update values.
PE Scheduler allows you to easily implement sophisticated, real-time calculations, such as:
• Unit performance
• Real-time cost accounting
• Real-time yield accounting
• Grade-based costing
• Batch summary
• Conversions and totalizations not performed by PI Totalizer
• Logical operations
• Calculating aggregates
Each Performance Equation is associated with a PI point, and the calculation results are
stored in the PI Archive as a calculated point, or PE point. You can configure a PE point to
be evaluated periodically by the Performance Equation Scheduler on a time-based basis, or
when an event is received on a specified trigger point, called event-based scheduling. The
Scheduling Method is discussed in Section 2.5.
This chapter includes the following topics:
Section 2.1, About Calculated Points, on page 6
Section 2.2, About the PE Subsystem, on page 6
Section 2.3, Procedure to Create Calculated Points, on page 7
Section 2.4, Determine Scan Classes and Point Source, on page 8
Section 2.5, Choose a Scheduling Method, on page 11
Section 2.6, Set Attributes for Calculated Points, on page 11
Section 2.7, Tips and Troubleshooting, on page 15
PI Server Applications User Guide Page 5
Chapter 2 - PI Performance Equations Scheduler
Typically, you use Performance Equations in one of two ways:
To create Calculated Points - points that have the PE subsystem as their source. The
PE Scheduler determines the value of these points by performing PE calculations
specified during the creation of the calculated point.
Programmatically - via the PI-SDK, PI DataLink or PI ProcessBook. Refer to product
documentation for applicable Performance Equations instructions.
2.1 About Calculated Points
Calculated points perform calculations on one or more PI points. Calculated points are similar
to other PI points, but they use the Performance Equation Subsystem as the point source. (The
point source is specified in pipeschd.bat in the \pi\bin directory.) The PE Scheduler performs
the calculations specified for the point at the scheduled time (based on "time" or "event") and
sends the result to the Snapshot.
Note: In this guide, Calculation Points are also referred to as PE Points and these
two terms are used interchangeably.
To create a calculated point, you put a calculation expression in the Extended Descriptor
(ExDesc) attribute field and you set the point source to the point source for the PE subsystem.
The value for the calculated point at any given time is the result of this calculation
expression. The PE Scheduler calculates a new value for the point according to the schedule
you define for it, either at regular intervals or using an event trigger.
You can use calculated points in other calculations, graph them in trend displays, or include
them in reports, just like any other point.
2.2 About the PE Subsystem
The PE Scheduler works a lot like an interface, except that it runs locally, on the PI Server. It
has an associated point source location and scan classes. The PE Scheduler evaluates the
calculation expression for each calculated point according to the schedule you configure for
that point, and sends the resulting value and timestamp to the Snapshot. Calculated points are
subject to exception and compression tests, just as other points are.
Like an interface, the PE Subsystem needs to be running in order to calculate data and send it
to the Snapshot. The PE Scheduler executable is located in the PI/bin directory and is called
pipeschd.exe.
2.2.1 Start and Stop the PE Subsystem
The PI startup script starts the PE subsystem, along with the other PI Server subsystems. Like
other PI subsystems, if your PI Server is Windows-based it’s a good idea to run the PE
subsystem as a Windows service, so that it can run in the background, independent of any
particular login session.
Page 6
2.3 - Procedure to Create Calculated Points
On Windows computers, the PE subsystem typically runs as a Windows service and you
manage it as you would any other Windows Service. The PE Scheduler service is called the
PI Performance Equation Scheduler. Open the Services control panel (Control Panel >
Administrative Tools > Services), right-click on the PI Performance Equation Scheduler
service, then start, stop or restart the service.
On UNIX, use the ps command to determine the process ID, and then use the kill command
to stop the process:
$ ps -aef | grep pipeschd
piadmin 25688 1 1 Sep 14 ? 35:22 ./pipeschd /Q /ps=C /ec=24 /f=00:
$ kill -2 25688
2.3 Procedure to Create Calculated Points
To perform a calculation on PI data, you must create a PI point; put your calculation
expression in the ExDesc attribute field; set the PointSource attribute to the point source
specified in the pipschd.bat file; and set location4 to the Scan class.
Follow these steps to perform a calculation on PI data:
1. Determine the scan classes and point source. (See Determine Scan Classes and Point
Source on page 8.)
2. Choose a scheduling method. You can use either clock-based scheduling or event-
based scheduling. (See Choose a Scheduling Method on page 11.)
3. Create the point, and set the required attributes. (See Set Attributes for Calculated
Points on page 11.) Create a new PI point using the PI tool of your choice, such as PI
Tag Configurator or piconfig. Set the required attributes as follows:
• PointSource: Set PointSource to the point source location specified in
pipeschd.bat on Windows, or pipeschd.sh on UNIX. The default point source
location for calculated points is the ASCII character, C, but you can edit
pipeschd.bat to use another single alphanumeric ASCII character.
• Location4: If you're using clock-based scheduling for this calculation, put the
appropriate scan class in location4. The available scan classes are listed in
pipeschd.bat. If you're using event-based scheduling, leave location4 blank.
PI Server Applications User Guide Page 7
Chapter 2 - PI Performance Equations Scheduler
• ExDesc: Put your calculation expression in the Extended Descriptor (ExDesc)
attribute field. The exact ExDesc expression depends on what type of scheduling
(clock- or event-based) the point uses.
• PointClass: classic
4. Test the PI PE calculation expression. You can use the pipetest utility to check
whether an equation is syntactically correct. (See Run the pipetest Utility, on page
59.)
2.4 Determine Scan Classes and Point Source
PE Points use the scan classes and point source configuration for the PE Subsystem defined
in pipeschd.bat on Windows, and pipeschd.sh on UNIX. By default, pipeschd.bat is located
in the directory PI\bin where PI\ is the path to the main directory in your PI installation.
2.4.1 Find the PE Subsystem Point Source
To find the correct PE point source location for your PE points, open pipeschd.bat with a text
editor and look for the entry /ps= (see below, circled). The point source is usually C, but it
can be any single alphanumeric character.
Note: Make a note of the character. This is the value you must use for the
PointSource attribute on all calculated points.
Change the Point Source
From a PI Administrator account, you can change the point source for PEs. Do not do this
unless absolutely necessary. If you change the point source location, any existing calculated
points will not work unless you change the PointSource attribute to match the new location.
To change the point source location for your calculated points, follow these steps:
1. Stop the PE Subsystem.
2. Change the point source to any single alphanumeric character. This is the value you
must use for the PointSource attribute on all calculated points.
3. Make a note of the character and be sure to publish the new number to everyone who
creates PE points for this server.
Page 8
2.4 - Determine Scan Classes and Point Source
4. Edit all existing calculated points to reflect the new point source.
5. Start the PE Subsystem.
2.4.2 Specify the Optional Instance ID
Within pipeschd.bat, you can optionally specify an instance ID (/id=n). When the instance ID
is specified, PI PE Scheduler only loads and calculates PE points with Location1 attribute
matching the /id value.
2.4.3 Find the PE Subsystem Scan Classes
All the scan classes available for a calculated point are listed in pipeschd.bat. If you don't see
the scan class you need for a particular calculated point, you can add a new scan class
(requires PI Administrator privileges.)
What is a Scan Class?
A scan class is a code that the PE Subsystem and other PI interfaces use to specify
scheduling. Scan classes consist of a period, which specifies the interval between calculations
and, optionally, an offset that specifies a start time for the calculations to begin – along with a
code that specifies the UTC time to use for scheduling:
Scan Class Period
The period specifies the interval between calculations. The first two digits are the hours, the
second two the minutes, and the third two the seconds. For example, the scan class can
specify that the calculation take place every hour (01:00:00), every three minutes (00:03:00),
every 52 seconds (00:00:52), etc.
Scan Class Offset
The offset specifies a start time for the calculation. The offset is optional. If no offset is
included in the scan class, the first calculation takes place immediately. The offset is counted
from midnight of the current day and, as with the period, the first two digits are the hours, the
second two the minutes, and the third two the seconds. So, for example, the offset can specify
that the first calculation occur at midnight (00:00:00), at 1AM (01:00:00), at 1PM (13:00:00),
at 2:05PM (14:05:00), at 25 seconds past noon (12:00:25), etc.
Scan Class UTC Time Flag
The UTC time flag specifies that the scheduling should sync with Universal Time
Coordinate (UTC). The UTC time is optional. If a scan class has a frequency of more than an
hour, make it a UTC scan class by adding a comma followed by a capital U:
(/f=08:00:00,07:00:00,U). If you don't do this, then your scheduling might be inaccurate the
PI Server Applications User Guide Page 9
Chapter 2 - PI Performance Equations Scheduler
next time there is a change to (or from) daylight savings time. UTC scan classes don't have
this problem because they force the scan class scheduling to sync with UTC, rather than local
time.
Find the PE Scan Classes
To see all currently available scan classes for your calculated points, follow these steps.
Open pipeschd.bat with a text editor and look for all the entries that begin with the characters
"backslash" f (/f). These are the scan classes. Choose the scan class that you want to use for
the calculated point and set the location4 attribute to the appropriate value.
The position within the startup command line defines the scan classes; that is, the first /f=
refers to scan class 1, the second /f= refers to scan class 2, etc. Simply add more /f=
parameters to define more scan classes. The calculated point is assigned to a scan class using
the location4 attribute. For example, if location4 is set to 2, the PE point will be evaluated
every 2 minutes.
Add New Scan Classes
You can add new scan classes, if you have PI Administrator privileges. Stop the PE
Subsystem before editing pipeschd.bat.
Add your new scan class at the end of the line containing scan classes, as the last scan class in
the list. If you add a new scan class earlier in the list, you change the location4 values for the
existing scan classes. You can add as many new scan classes as you like to the end of the
scan class list in pipeschd.bat.
Restart the PE Subsystem when you finish editing pipeschd.bat.
Page 10
2.5 - Choose a Scheduling Method
2.5 Choose a Scheduling Method
The attributes you set for a calculated point depend in part on the type of scheduling you use
for the point. Each calculated point must use either clock (time-based) scheduling or event
scheduling:
Clock Scheduling: With clock scheduling, you use scan classes to schedule the
calculation. The PE Scheduler calculates a new value for the point at the specified
intervals, such as every hour, every five seconds, every 20 minutes, etc. You can
optionally specify an initial start time for the calculation interval.
For clock-scheduled points, define the PE calculation expression in the ExDesc
attribute field and specify a scan class in the location4 attribute field. (See Set the
ExDesc Attribute for Clock-Scheduled Points and Set the Location4 Attribute: Scan
Class, on page 12.)
Event Scheduling: With event scheduling, you configure the calculation to occur
when a specified point gets a new Snapshot value. For example, you might want a
calculation performed whenever the point ba:level.1 receives an update event.
For event-scheduled points, put both the PE expression and the trigger tag name in
the ExDesc attribute field (see Set the ExDesc Attribute for Event-Scheduled Points
on page 13) and set the location3 attribute field to specify the timestamp of the point.
(See Set the Location3 Attribute: Timestamp, on page 12).
2.6 Set Attributes for Calculated Points
Table 2–1 lists the attributes that require a special setting for calculated points.
Table 2–1. Attributes that Require a Special Setting for Calculated Points
Attribute Requirement
ptClassName Classic.
PointSource Set to value specified in pipeschd.bat file (or
pipeschd.sh on UNIX). The default value is C.
location3 Output timestamp setting for event-based
scheduling.
location4 Put the scan class here for clock-scheduled
points. Leave blank for event-based points.
ExDesc This is where you put your performance
equation.
scan Set the scan attribute to 1 (the default value)
shutdown Marker inserted in Archive at shutdown.
All point attributes that are not listed in Table 2–1 work just the same as they do for other
points. However, the following attributes do not apply to calculated points:
• Location2
PI Server Applications User Guide Page 11
Chapter 2 - PI Performance Equations Scheduler
• Location5
• UserInt1
• UserInt2
• UserReal1
• UserReal2
• EventTag
• InstrumentTag
• SquareRoot
2.6.1 Set the Point Source
The PointSource attribute for calculated points is defined in pipeschd.bat, discussed in Find
the PE Subsystem Point Source on page 8. The default value is C; however you can change
the defined value to any other single alphanumeric character by editing pipeschd.bat.
2.6.2 Set the Location3 Attribute: Timestamp
If the calculated point uses clock scheduling, do not set the location3 attribute. Use the
location3 attribute for event-scheduled points, to specify how PI determines the timestamp
for the calculated point. When location3 is set to 0 (the default value), set the timestamps for
the calculated point to the time when the expression is evaluated.
When location3 is set to a non-zero value, the expression is evaluated at the timestamp of the
triggering event and the timestamp of the resulting value is set to the timestamp of the
triggering event.
2.6.3 Set the Location4 Attribute: Scan Class
If the calculated point uses event scheduling, do not set the location4 attribute. If the point
uses clock scheduling, set a value for location4 to a positive non-zero integer that specifies a
valid scan class.
You select a particular scan class for a calculated point by setting the value of the location4
attribute for that point. All the scan classes available for a calculated point are listed in
pipeschd.bat (called pipeschd.sh on UNIX computers). To select the first scan class in the
list, set the location4 attribute to 1; to select the second scan class, set the location4 attribute
to 2; etc.
For an explanation of scan classes and how to configure them, see Find the PE Subsystem
Scan Classes, on page 9.
Page 12
2.6 - Set Attributes for Calculated Points
2.6.4 Set the ExDesc Attribute: Calculation Expressions
For each calculated point, specify the PE calculation for the PE Scheduler to perform. PE
calculation expressions use PE syntax and functions to define calculations, using data from
other points. PE calculation expressions are similar to arithmetical expressions. You can use
any of the standard arithmetic operators in a PE expression (such as +, -, or *) to add the
values of two points together, add a number to the value of a point, etc. You can also use
Performance Equation functions and Steam Table functions in your PE calculation
expressions (see Chapter 4, PI Performance Equations Syntax and Functions Reference, and
Chapter 5, PI Steam Functions Reference.)
You define the PE calculation expression in the Extended Descriptor (ExDesc) attribute field,
but the exact syntax you use depends on the type of scheduling you’re using. For clock-
scheduled points, you type only the PE calculation expression into the ExDesc attribute field,
but for event scheduling you must also specify the point that acts as the event trigger.
Note: If the equation begins with a single quote (') and you are working with PI Tag
Configurator, enclose the calculation expression in parentheses. Otherwise Excel will
remove the single quote.
Set the ExDesc Attribute for Clock-Scheduled Points
For clock-scheduled points, the ExDesc field contains only the calculation expression itself.
Several examples of simple calculation expressions are provided below.
The following example simply adds the current value of the sinusoid point to the current
value of the ba:level.1 point.
'sinusoid' + 'ba:level.1'
The following example takes the total time during the last hour that the sinusoid point had a
value between 30 and 70.
timegt('sinusoid', '*-1h', '*', 30) - timegt('sinusoid', '*-1h', '*',
70)
For more examples of calculation expressions, see Examples of Calculation Expressions on
page 14. For a complete reference on the PE syntax and functions, see Chapter 4, PI
Performance Equations Syntax and Functions Reference.
Set the ExDesc Attribute for Event-Scheduled Points
For event-scheduled points, the syntax for the ExDesc attribute field is:
event = tagname, CalculationExpression
where tagname is the name of the point that triggers the calculation and
CalculationExpression is the calculation expression that PE Scheduler uses to calculate the
value for the point.
For example, to set up a one-hour average of the sinusoid point that triggers whenever
sinusoid gets a new Snapshot value, use the following expression in the ExDesc attribute
field:
PI Server Applications User Guide Page 13
Chapter 2 - PI Performance Equations Scheduler
event=sinusoid,TagAvg('sinusoid', '*-1h', '*')
The PE Scheduler uses the Snapshot value as the event trigger. This means that events that do
not enter the Snapshot do not trigger the calculation. For example, an event that does not pass
the exception reporting does not trigger a new calculation.
Character Limits on the Extended Descriptor Attribute
For both clock and event scheduling methods, there is a set limit on the number of characters
that you can use for the extended descriptor. These limits depend on the tool you use to create
your calculated point, rather than on the PE subsystem itself. In the PI TagConfigurator, the
limit is 4096 characters.
Regardless of the limits on the extended descriptor, we recommend that you keep expressions
less than 300 characters, if possible. Expressions that are much longer than that tax the
system. If you need a longer expression, consider breaking down your equation into parts and
creating calculated points to handle each of the parts. Be careful to schedule the calculations
so that PE Scheduler can perform them in the correct order. See Prevent Scheduling Errors
on page 17, for more information.
2.6.5 Set the Scan Attribute
Always set the scan attribute to 1 for calculated points. When the scan attribute is set to 0, PI
will not perform the calculations or generate any values for the point. Note that 1 is the
default value for the scan attribute, so you can usually just leave this attribute as-is.
2.6.6 Set the Shutdown Attribute
Performance Equations are not calculated if the PI Server is not running, so you should
always set the Shutdown attribute to 1. When Shutdown is set to 1, the system inserts a
shutdown event with the timestamp of the PI Server shutdown. Note that the shutdown event
is inserted only when the PI Server itself stops — it is not inserted if the PE Subsystem stops
independently of the PI Server.
2.6.7 Examples of Calculation Expressions
This section provides some helpful hints and examples for writing Performance Equations.
Totalization of Digital Point Example
In this example, the goal is to obtain the total of the number of times a point goes into a
digital state for the month. Accumulator is the PE point. OnOffSwitch is the digital point that
uses a Digital State Set with two digital states: ON and OFF.
If day(‘*’)=1 and day(PrevEvent(‘Accumulator’, ‘*’))<>1 then 0 else if
PrevVal(‘OnOffSwitch’, ‘*’) <> “ON” and ‘OnOffSwitch’ = “ON” then
'Accumulator' +1 else NoOutput()
This performance equation checks whether it is the first of the month and whether the last
event did not occur on the first of the month. If it is the first of the month, Accumulator
resets. Otherwise if the previous value of OnOffSwitch is not the digital state ON and the
current value is ON, then Accumulator increments.
Page 14
2.7 - Tips and Troubleshooting
TagTot Example
In this example, the goal is to use the TagTot function to obtain a total on a point that has
engineering units other than the default per day. RateTag has engineering units of gallons per
hour and the objective is to get the number of gallons for the previous day.
If PctGood(‘RateTag’, ‘y’, ‘t’)>85 then TagTot(‘RateTag’, ‘y’, ‘t’)*24
else “Bad Total”
First, the performance equation checks the percent of good values starting from the midnight
yesterday to the midnight of the current day. If the percentage is greater than 85, then a total
of RateTag is calculated for that given period. The total is multiplied by 24 hours per day to
obtain the units of gallons. If the percentage is less than or equal to 85, the digital state of
Bad Total is given. In this example, although the RateTag would have an integer or real
point type, digital states only in the SYSTEM Digital State Set are allowed.
TagMax vs. Max Example
In this example, the objective is to obtain the maximum of a point for the month. One method
for doing this is the TagMax function, shown in the next paragraph. An alternative method,
also shown below, uses the Max function. Here’s the calculation expression with TagMax:
If Day(‘*’)=1 and Day(PrevEvent(‘RateTag’, ‘*’))<>1 then
TagMax(‘RateTag’, Bom(PrevEvent(‘RateTag’, ‘*’)), Bom(‘*’)-‘+1s’) else
NoOutput()
The performance equation first checks that it is the beginning of the month and then finds the
maximum of RateTag from the prior month up to one second before the beginning of the
current month. Notice that the beginning of the month function Bom was not used to check
for the first of the month. The following expression:
Bom(‘*’)= ‘*’
is not as accurate as the previous expression because the current time of the scan might not
exactly equal the beginning of the month. Also the TagMax function may use too many
resources accessing the Archive for data of the previous month and slow down the system.
Here’s the calculation expression with Max:
If Day(‘*’)=1 and Day(PrevEvent(‘RateTag’, ‘*’))<>1 then
Max(TagZero(‘RateTag’), ‘RateTag’) else Max(‘RateTag’, ‘MaxTag’)
This expression has the tagname of MaxTag and compares the point to be maximized
RateTag to the current maximum in MaxTag. If the current time is the first of the month,
MaxTag is reset by comparing the maximum between the current value of RateTag to the
tagzero of RateTag. This version of obtaining a maximum makes only one Archive call as
opposed to Archive calls to obtain one month of data.
2.7 Tips and Troubleshooting
This section contains the following topics:
Tips for Creating Calculated Points, on page 16
PI Server Applications User Guide Page 15
Chapter 2 - PI Performance Equations Scheduler
Common Performance Equation Problems and Errors, on page 16
Prevent Scheduling Errors, on page 17
Prevent Skipped Calculations, on page 17
When Data Types Don't Match, on page 18
2.7.1 Tips for Creating Calculated Points
To avoid problems with your Performance Equations, follow these guidelines:
Use the BadVal function to check to see if the value to be evaluated is bad, before
carrying out a calculation.
Use the PctGood function to check if the amount of data that is good, is within an
acceptable level.
Remember to escape anything that requires double quotes, with “double quotes”.
Cascade calculations that occur in the same scan class by using offsets.
Don’t use ambiguous timestamps.
Set the Step attribute to 1 if you wish to have your data tracked as a stair-step instead
of straight-line interpolation.
2.7.2 Common Performance Equation Problems and Errors
If you do not see results for a PE point, check the following:
Make sure the PE Subsystem is running.
Use the pipetest utility to check your equation syntax. Check your equation for any
of the following common errors:
• Are all PI times and tag names enclosed in single quotes?
• Did you spell your tag names and function names correctly?
• If the equation text begins with the single quote character ( ' ), did you enclose
the entire string in parentheses? Excel removes the leading single quote.
• Are you (not) using tag names that are also valid PI time expressions?
Check the log file pipc.log in the pipc\dat directory for Windows (pipeschd.log in
pi\log for UNIX) to see if there are errors in the equations during compilation. In the
log file, error at offset x indicates that a syntax error x characters from the beginning
of the equation has been detected.
When the Performance Equation evaluator cannot perform a calculation during runtime, it
returns the error value Calc Failed. This means that the PE point has the correct equation
syntax and is running. Some possible causes are:
Source tags have unexpected values. For example, the expression 'sinusoid' + 12
will result in Calc Failed if the value for the source tag sinusoid equals the digital
state Shutdown.
Page 16
2.7 - Tips and Troubleshooting
The source data do not meet the minimum pctgood value in a summary calculation.
For example, TagAvg('sinusoid', '*-1h', '*', 80) will result in Calc Failed if
less than 80% of the values for sinusoid are good for the last hour.
Runtime data type conversion fails. For example, suppose the PE point is a digital
point and has the expression 'StringTag'. If the string source tag StringTag has a
string that cannot be converted to a digital state either in the PE point’s digital state
set or the System Digital State Set, then the result will be Calc Failed.
2.7.3 Prevent Scheduling Errors
If two clock-scheduled calculations are evaluated at the same period and offset, there is no
way to determine which calculation should be performed first. If your calculated point
references other calculated points, you need to use an appropriate scan class offset to force PI
to evaluate the calculations in a specific sequence.
For example, suppose points A, B, and C all represent calculated points. Point C is calculated
as A/B (A divided by B), so point C should be calculated after points A and B are calculated. If
all three points have the same scan class, there is nothing that ensures that points A and B will
be calculated before point C is calculated. To trigger the point C calculation to take place
after the point A and point B calculations, you can use a scan class with a slight offset for
point C. For example, if you use the following scan classes for points A, B and C, then PI will
calculate point A and B every hour on the hour, and then calculate point C a second later.
Point Scan class
A /f=01:00:00,01:00:00
B /f=01:00:00,01:00:00
C /f=01:00:00,01:00:01
2.7.4 Prevent Skipped Calculations
Although the only limit on the number of performance equations on a PI Server is the number
points available to the PI Server, there are practical limits on the performance of PE
Scheduler. It is possible for the PE subsystem to get overloaded.
If a scan class is more than one scan period behind, it will skip the calculation in order to
catch up.
To see whether the PE Subsystem is skipping calculations, look at the pipc.log file located in
the pipc\dat directory (or pi\log\pipeschd.log on UNIX).
If you find that the PE Subsystem is skipping calculations, we recommend you use the Offset
attribute to stagger the calculation times so that large groups of calculations are not scheduled
for the same time. For example, by using offset times of 10 seconds, 20 seconds, 30 seconds,
and so forth, you can divide a set of five-minute calculations into thirty sub-groups to even
out the system loading.
PI Server Applications User Guide Page 17
Chapter 2 - PI Performance Equations Scheduler
2.7.5 When Data Types Don't Match
When a calculated point's type does not match the type of the calculation, PE Scheduler
converts the data type of the result to the data type of the calculated point (unless the result is
a digital state).
In other words, for string points, the PE subsystem converts the calculation result into a
string. For digital points, PE subsystem first converts the result into a digital state within the
digital state set for the calculated point. If this initial conversion is not successful, the PE
Subsystem converts the result into a digital state within the System Digital State Set. For
numeric points, the PE subsystem converts the calculation result to an appropriate numeric
value, such as integer or float.
If the data type conversion fails (for example, it is not possible to convert the string “ABC”
into a numeric value), then the calculation expression returns the digital state Calc Failed.
Page 18
Chapter 3. PI PERFORMANCE EQUATIONS
RECALCULATOR
The PI Performance Equations (PE) Recalculator is designed to adjust values of PE points
automatically. The adjustment occurs when Archive values of points that are used in PE
expressions are added, changed, or deleted. You can also use PE Recalculator as an offline
utility to reprocess explicit periods of time for specific points.
This chapter includes the following topics:
Section 3.1, Recalculator Overview, on page 19
Section 3.2, Recalculator Functionality, on page 21
Section 3.3, Types of PE Point / Time Relationships, on page 24
Section 3.4, Special PE Time Functions, on page 31
Section 3.5, Examples of Archive Retrieval / Search Functions, on page 32
Section 3.6, Recalculation Limitations, on page 32
Section 3.7, Recalculator Point Configuration, on page 34
Section 3.8, Start Recalculator as a Service, on page 35
Section 3.9, Start Recalculator Manually, on page 42
Section 3.10, Stop Recalculator, on page 43
Section 3.11, Optimize Recalculator Performance, on page 44
Section 3.12, Error and Information Messages, on page 44
3.1 Recalculator Overview
The PE Recalculator automatically adjusts values of PE points when values of points used in
PE expressions are added, changed, or deleted. Delayed or out-of-order Snapshot events can
also trigger recalculations.
Note: PE evaluations based on new Snapshot values are performed by the PE
Scheduler as described in Choose a Scheduling Method on page 11. Recalculator
covers all times before the Snapshot value of a PE point.
PI Server Applications User Guide Page 19
Chapter 3 - PI Performance Equations Recalculator
The Recalculator supports multi-level (but not recursive) dependencies and takes into account
the resulting time dependency. Explicit time dependency expressions and time-related
functions are supported as well. Some point attributes of the dependent PE point and the
source points are considered.
Like other standard PI subsystems, Recalculator runs on a PI Server Home Node, either as a
service, or manually as a console application. When Recalculator is started as a service,
messages are sent to the PI Message Subsystem and additional debug output may be sent to a
log file. When Recalculator is started as an application, messages are written to the console.
There are several limitations and side effects to keep in mind, due to compression and other
factors, which are described in this chapter.
It is important to realize that recalculation “is expensive” as it bypasses exception reporting,
may retrieve a lot of Archive data for many tags, and may generate many out-of-order events.
All of these factors place a significant overhead on a PI Server. In addition to these
considerations, check that any affected Archive file contains the point definitions and has
sufficient space.
3.1.1 Glossary of Recalculation Terms
The following recalculation terms are used in this chapter.
Table 3–1. Glossary of Recalculation Terms
Name Description
Dependent A PI point that normally receives its values from the PE Scheduler when it
Point evaluates an expression. These are also the points that are modified by the PE
Recalculator when necessary.
Source Point A PI point whose tag appears in a PE expression. In general, additions, changes,
and deletions of source point values trigger recalculations.
Absolute A date/time expression that evaluates to the same time regardless of the time of
Timestamp the calculation. Examples include '10-oct-99' and '01-jan-70.'
Relative A date/time expression defining an offset from the actual time of the calculation.
Timestamp Examples include '+7h' and '-30d'.
Note: One exception to this rule occurs when a Relative Timestamp appears as one of the
two time arguments of a PI PE Archive retrieval function. If the other time is an absolute time,
it becomes the basis time.
Basis Time The time to which the offset defined by the Relative Timestamp is applied. When
evaluating PE point values, the PE Recalculator will determine the basis time of
the dependent values to be corrected and will apply the offsets from that basis.
Combination A date/time expression consisting of an absolute timestamp and a relative
Time timestamp as an offset. Examples include 'T+7h.'
Performance Same as Dependent Point.
Equation
Point
Page 20
3.2 - PE Recalculator Functionality
Name Description
Inversion Changing the sign of a Relative Timestamp offset in order to define the period of
time requiring recalculation. For example, if an expression reads,
"TagVal('input', '*-1h')", then PE point values up to one hour after an
'input' event, or '*+1h', must be recalculated.
3.2 PE Recalculator Functionality
When the PE Scheduler starts, it finds the PE points by scanning the PI Point Database for
points with a specific point source, usually C.
Since the Recalculator sends events to the same PE points, it also scans the PI Point Database
on startup, scanning for the same point source. By default, all PE points are considered for
recalculation. If you wish, you may assign values to the Location1 attribute of any PE point.
The Recalculator can be configured to consider only points with a specific Location1
parameter value.
The PE Scheduler will sign up for exceptions for any event trigger points. The Recalculator
signs up for Archive events of all source points. The reason for the difference is that the
Recalculator must be aware of any changes to any source point, not just event trigger points.
Only events that were not handled in time by the PE Scheduler are considered by the
Recalculator. The timestamp of the source point event has to be older than the Snapshot time
of the corresponding dependent PE point. The delay caused by the normal scan cycle does not
trigger a recalculation.
Recalculation is done in two steps: For a source point event, first the affected PE point
periods are found. Then, all these periods are processed for existing events to replace, and
new events to insert. When inserting new events, their timestamps are derived from the
timestamps of the source events.
Generally, there are three main questions:
Which dependent PE points are affected?
What time range has to be recalculated?
How do other point attributes influence the recalculation?
These questions are discussed here and lead to a definition of different recalculation types.
The recalculation types are described in a subsequent section.
3.2.1 Point Dependency Considerations
Generally, all tags used in the ExDesc field of a PE point in the PI Point Database are
classified as source tags. These tags may be used in arithmetic expressions or as function
parameters.
With the PI Server, it is possible to dynamically construct tags by concatenating string
constants and values of one or more string points. The Recalculator is unable to process
expressions that use this construct.
PI Server Applications User Guide Page 21
Chapter 3 - PI Performance Equations Recalculator
3.2.2 Time Range Considerations
Time ranges are defined by two timestamp expressions, usually passed as two arguments to
the same PI PE function. Examples include TagAvg and FindEq. It occurs frequently that
the timestamp expression '*' is used. This is basis time for the calculation. For PE points
evaluated normally by the PE Scheduler, the basis time is the current time except for an
event-based PE point with Location3 set to one. In that case, the basis time is the trigger
event time. For the Recalculator, the basis time is in general the time of the new or changed
source point event.
Any new event for the source point not handled by the PE Scheduler will cause a series of
Archive events within the time range to be recalculated. The Recalculator must determine the
start and end time of the affected time range.
Time calculations resulting in a timestamp or in an interval can be inverted if no absolute
timestamps are involved. For example, consider a PE expression such as:
TagVal('input_pt', '*-1h')
If 'input_pt' receives a new event earlier than the Snapshot time of the PE point, its
timestamp is the basis time for recalculation. PE point events one hour after the 'input_pt'
event are affected. The minus sign is effectively inverted to a plus sign, as in '*+1h'.
Inversion also applies to time periods:
TagAvg('input_pt', '*', *-1h')
If a new event for 'input_pt' is received, its timestamp is the basis time, or '*' in the
expression. The new event affects the period '*' until '*+1h'.
If there are absolute times in an expression, it would mean that all PE point values would
have to be recalculated. In other words, if an absolute time appears in an expression, all
values after the timestamp of a new or changed event would need to be recalculated.
Time Range Examples
Tag Expression
TimeCalc If BadVal('xsource','*-8H') then NoOutput() else
Tagval('xsource','*-8H')
CalcInt TagAvg('xsource','*-1h','*')
AllCalc If BadVal('xsource') then Tagval('xsource','12-Jan-98
08:00’) else 'xsource'
TimeCalc: In the first example, if the value of xsource at 12-Jan-98 12:12:00 is changed,
TimeCalc at 12-Jan-98 20:12:00 (8 hours later) has to be recalculated.
CalcInt: In the second example, the expression has to be recalculated for a 1-hour period past
the time of a modification of xsource.
AllCalc: If the value of xsource at 12-Jan-98 08:00:00 were to be modified, then all values of
the PE point after 12-Jan-98 08:00 would have to be recalculated whenever xsource is in a
bad state.
Page 22
3.2 - PE Recalculator Functionality
3.2.3 Clock-Scheduling vs. Event-based Scheduling
If a PE point is clock-scheduled, a new source point event causes a search for existing PE
point events up to one scan cycle after the source point event to take place. The time between
calculations depends on the Location4 attribute indicating the scan cycle defined in
pipeschd.bat.. If there is no Archive event found in the searched period, a new one is created.
In event-based calculations, no scan classes are defined and Location4 is ignored. If an event
within a default period (10 sec) does not exist, a new one is created for simple dependencies.
3.2.4 Step Point Attribute
The Step attribute defines how a trend of data values appears between events stored by PI
Server.
If Step = 0, data values are linearly interpolated between archived events for numeric points.
Changing a source point value implies changing all archived PE point values between the
previous and the next event of the source point.
If Step = 1, data values value between archived events are considered to be the same as the
previous event. Changing a source point event influences a dependent PE point between the
modified source point event and its next event. Data values prior to the modified event are not
affected.
3.2.5 Compression / Exception
Because of exception reporting and compression, not every original PE point event is found
in the PI Data Archive. The Recalculator cannot simulate the original exception or
compression algorithm because it no longer has the original Snapshot values. It recalculates
for all events of all source points, plus all existing PE point events, plus start/end of the
affected period.
There might be more Archive events after a recalculation. This might fail or take rather long
when performed on Archive periods that are no longer covered by the primary Archive file.
3.2.6 Scan and Archiving Attributes
Set the Scan attribute to 0 to turn off the PE Scheduler. The Archiving flag causes no events
to be sent to the PI Data Archive for storage.
If the Scan attribute is set to 0, then there are no values generated by the PE Scheduler at
some time in the past. If Archiving is 0, values generated by the PE Scheduler are not stored.
The times at which the Scan and Archiving attributes were edited are not recorded.
Note: The ability to recalculate events may be affected if either of these attributes
are set to 0. It is impossible to accurately correct history if there were no original
events to adjust.
3.2.7 Location1
The Location1 attribute may be used to exclude points or to schedule multiple instances of
the Recalculator for performance reasons. This corresponds to the number in the /in startup
PI Server Applications User Guide Page 23
Chapter 3 - PI Performance Equations Recalculator
parameter or in the Instance Registry setting. By default, all PE points are examined for
recalculation.
3.3 Types of PE Point / Time Relationships
The types of the relationship between a PE point and time are summarized below, and
explained in subsequent sections.
Table 3–2. Types of PE Point / Time Relationships
Relationship Short Description
Simple The expression consists of arithmetic operations and functions.
There are no time parameters except '*'.
Multilevel Point Dependency A PE point is source for another point. Archive modifications
should trigger another recalculation.
Recursive One of the source points in the expression is the PE point.
Relative Time Shift The period to be recalculated is shifted according to the PE. No
additional event for PE point is created at source event time.
Special Event If the source event range covers the indicated event (e.g., 'T'),
the period to be recalculated is determined according to the PE.
Otherwise, the dependency relation can be ignored.
Time Period Reference The PE contains Archive functions with start and end time. Start
and End time have to be relative to a basis time ('*', 'T', etc.)
Multilevel Time Dependency The time parameter of an Archive function is the result of
another function.
Absolute Time Reference Automatic recalculation is not supported. This type of expression
can only be recalculated manually.
3.3.1 Type 1: Simple Point Relationship
This type of recalculation covers all arithmetic functions and operations and all functions
working on actual values only. Bad digital states are evaluated as with normal Performance
Equations. Other errors will not change existing Archive events.
The question of the affected time range of the PE point has to be resolved even in this case.
Tag Expression
TestCalc 100 - 'sinusoid'
T2Calc TagVal('TestCalc' , '*') * (('sinusoid'-50.0)/50.0)
Finding Corresponding Timestamps
The main task is to find the timestamps for the modified source points that define the period
of time that needs to be recalculated. In general, the timestamp of a PE point event is different
from the timestamp of a source point. For the Simple recalculation type, the following
situations depending on point attributes are considered:
Page 24
3.3 - Types of PE Point / Time Relationships
The PE always uses the values prior to the beginning of the scan cycle. In the
example above, T2Calc is always one cycle behind TestCalc. The cycle is defined
by the scan class of the PE points and by the scan parameters in pipeschd.bat.
To insert a value, PE uses the system time, not the timestamp of an event trigger
point by default.
As the calculated point may depend on more than one source point, the Archive is examined
for events until the next event of the modified source point. All these events have to be
recalculated. See Figure 3–1.
Inserting New Archive Events
When a new data event has been inserted for the source point, a new event of the dependent
PE point may need to be inserted as well. The Recalculator searches the Archive for the next
dependent PE point event after the trigger event. A point event found within one scan cycle
will be modified; otherwise a new event for the dependent PE point will be inserted. An
inserted event is set at the source event’s timestamp +1 sec.
Additional input
Source 1
Source 2
Dependent
A new event is We recalculate
inserted. this event too!
Figure 3–1. Recalculation Period on Type = Simple, Step=1, No Compression
Source Data with Step=0
If the Step attribute is 0, a modification even affects the time prior to the changed value. The
Recalculator examines the Archive in the range from the previous event to the next event of
the modified source point. All events of the PE point in this period have to be recalculated.
Notice that a PE point event prior to the initiating source point may be modified. See the
exclamation point (!) in Figure 3–2.
Note: With Step = 0, entering a single event into the Data Archive always affects the
period between the previous and the next unmodified event. If you intend to enter a
single peak or to mark the last “originally good value”, you have to enter additional
events.
PI Server Applications User Guide Page 25
Chapter 3 - PI Performance Equations Recalculator
Modified input
Source
Dependent
!
We recalculate all events
in this range!
Figure 3–2. Recalculation Period on Type = Simple, Step=0, No Compression
Exception Reporting Algorithm
The PE Scheduler sends data to the Snapshot by exception to create events for dependent PE
points. Depending on the exception parameters, this may result in suppressing new events if
there are no relevant changes to the previous value. The compression algorithm minimizes
the amount of available Archive events. In the following considerations, this is generally
called Compression. The effect of the exception algorithm is not considered separately.
Compression on Calculated Values
There are no events in the Archive as long as the interpolated line between two events fits to
the "real" values. The exception/compression algorithm cannot be simulated when the actual
values are no longer available.
This implies extra considerations:
The modified range of the PE point may be even larger than the affected source point
range.
Depending on the unmodified source point’s event, a recalculation may yield
different results compared to the straight-line result of recalculating only the given
events of the PE point.
Page 26
3.3 - Types of PE Point / Time Relationships
These considerations are shown in Figure 3–3.
M odified
Source
?2 ?2 Source
D ependent
?1
?3 ?3
A dditional O riginal result based
on sam e source
Figure 3–3. Recalculation Period on Type = Simple, Step=0, PE Point with Compression
Recalculator inserts extra events at the beginning and the end of the modified period (?3) if
necessary, so there are no new results without changed input. Due to the compression
algorithms, the new values may still be slightly different from the original interpolated
values.
Recalculator inserts extra events according to the modified source point event. Recalculator
does not insert additional events due to unmodified source events (?2).
Recalculator recalculates all existing dependent events in the time range affected by the
modified source event (?1). It does not simulate the exception reporting and compression
algorithm.
Conditional Dependency
“If-then-else” constructions are evaluated only during recalculation. The point and time
dependency is stated by parsing the expression in the ExDesc parameter for all cases on
startup.
3.3.2 Type 2: Multi-level Dependency Point Relationship
A Æ B Æ C Æ …
(“x Æ y” means x influences y, y is dependent, and x is source)
Normally, no other special considerations are required if PE points are used as source points
again. As new values of PE points are sent to the archive, there is an event on which the
Recalculator has signed up, so the standard mechanism does all the work.
Recursive Point Relationship is checked for this dependency, too.
PI Server Applications User Guide Page 27
Chapter 3 - PI Performance Equations Recalculator
3.3.3 Type 3: Recursive Point Relationship
A Æ B Æ A or directly A Æ A
Such a recursive dependency is legal; you may use it for counting, etc. The result depends
normally on “if-then-else” and on scan cycle parameters.
If a recursive dependency is detected, no automatic recalculation occurs. You may start a
complete recalculation manually by using the /execute option and stating the desired time
range. The result, however, depends on previous values and recalculations.
Examples
Tag Expression
TestCalc If BadVal('TestCalc') then 0 else (if 'TestCalc' > 9999 then 0
else 'TestCalc' + 1)
EvCount Event=CountMe, if BadVal('EvCount') then 0 else ('EvCount' + 1)
TestCalc increments by one on every scan cycle and resets if the value is bad or is larger than
9999.
EvCount shows the number of events for the point CountMe.
The BadVal() constructions are required to quit any non-numeric initial state (Shutdown,
PtCreated).
These recursive calculations are very sensitive to the previous state of the variable and may
give different results when they have already been recalculated before. In example 2
(EvCount), there is no possibility to detect all events from the Archive. Additionally, they
would generally result in a recalculation of the whole period up to now.
For these reasons, PE points depending recursively on themselves are generally excluded
from recalculations.
There is no explicit limit on the number of levels to detect a recursive dependency.
A Æ B Æ C Æ … (any number of PE points) … Æ Z Æ A
3.3.4 Type 4: Relative Point Relationship
* - n X ; X ∈ {S, M, H, D }
This relationship type is also known as a time shift relationship. For example:
Tagval('s_pt', '*-3h')
Inverting results in * + nX, so the Recalculator schedules recalculations at '*+3h', when
's_pt' receives an Archive modification event.
Page 28
3.3 - Types of PE Point / Time Relationships
Modified input
‘*+3h’
Source
‘*+3h’ Dependent
We recalculate all events in
this range!
Figure 3–4. Type = Relative Time Shift
The algorithm described for type = Simple (without explicit time dependency) is applied to a
period shifted by the indicated offset. Extra events are not created.
For the example here, this results in a recalculation period for the dependent PE point from
t1=(prevevent(source) + 3h) to t2=(nextevent(source) + 3h). See Figure 3–4.
Note: Future references '*+nX' are syntactically correct. Based on actual values,
they result in ‘No Data’ or ‘Bad’. On recalculation, they may result in numeric
values. These are processed normally without error messages.
3.3.5 Type 5: Special Event Point Relationship
B ± n X ; B ∈ {T, Y, 1 .. 31, Mon, Tue, … }
This relationship type is also known as a Relative Time Reference.
The recalculation period may be one complete day relative to the given timestamp. The sign
of the offset fraction is inverted. Note that only changes effective at the specified special time
result in a recalculation.
Examples
Tag Expression
BASEVAL TagVal(‘xsource’,’T’)
DIFFVAL 'xsource' – TagVal('xsource','T')
BASEVAL holds the midnight value of xsource of each day. If this value changes, all
Archive values of BASEVAL for that day have to be modified. Every recalculation on this
day yields the same new result. If there are changes of xsource at other timestamps, nothing
is recalculated.
PI Server Applications User Guide Page 29
Chapter 3 - PI Performance Equations Recalculator
DIFFVAL has to be recalculated for the whole day, when xsource at midnight is modified.
Other changes of xsource affect values of DIFFVAL only at the event timestamp of xsource,
and the period of time between the previous and next events of xsource. The period of time
between the new xsource event and the next xsource event would have to be recalculated if
the Step point attribute is 1. See Figure 3–5.
This change Modified input
influences one day
xsource
DIFFVAL
00:00 00:00
We recalculate all events in this range!
Figure 3–5. Type = Relative Time Reference
3.3.6 Type 6: Time Range Point Relationship
In the example below, any change of xsource affects the value of YSUM for the whole next
day's period.
Tag Expression
YSUM TagTot ('xsource','Y', 'T')
This dependency type requires that both time parameters be relative to the calculation time.
Expressions like '-1h' are valid as one of the time parameters. They are interpreted relative to
the other.
3.3.7 Type 7: Multi-level Time Dependency
The time parameter of an archive function is the output of another function. For example, this
expression finds the average value of sinusoid from the time yesterday at which the value of
'starttrigger' was 50 to the current time:
TagAvg('sinusoid', FindEq('starttrigger','y','t',50), '*')
For recalculation purposes, the relation to the point sinusoid is considered a Type 1 (Simple)
point relation. As the detection of the affected period does not consider the time dependency,
not all possibly affected PE events are automatically recalculated. For example an edited
Page 30
3.4 - Special PE Time Functions
value of sinusoid does not force the recalculation of the dependent PE point for the whole
next day.
The calculation itself uses the time parameters correctly, so requesting a recalculation
manually could be used as a workaround, if necessary.
3.3.8 Type 8: Absolute Time Reference Point Relationship
In the first example below, if the value of xsource at 01-Jan-98 is changed, the Recalculator
would have to calculate everything from the timestamp stated in the PE expression up to now.
In the second example below, other changes of xsource affect the value of DIFFVAL only at
the timestamp of xsource and the interval of time between the previous and next events of
xsource.
Tag Expression
BASEVAL TagVal('xsource','01-Jan-98')
DIFFVAL 'xsource' – TagVal('xsource','01-Jan-00')
A change in an absolute timestamp in an expression does not cause recalculation of the whole
Archive automatically. If this function is desired, you have to run the Recalculator as a
console application, stating which point and time period has to be recalculated.
3.4 Special PE Time Functions
Some of the time functions in the PE library change the data type of their arguments, or
extract information from timestamps. This category of time functions requires special
consideration.
3.4.1 Modify a Timestamp
There are several time functions that modify a given timestamp including Bod (), Bom (),
Bonm (), Noon (). If the timestamp parameter is relative to calculation time (normally * or
something based on it), the result refers to a special timestamp relative to the parameter. If
this timestamp is modified, the Recalculator must recalculate a whole day or a whole month.
This is similar to the "B ± n X " problem above (Type 4: Relative Time Reference). If the
timestamp parameter is absolute, the result is an absolute timestamp; an automatic
recalculation is suppressed (Type 8: Absolute Time Reference).
3.4.2 Parsetime Function
Parsetime () converts any string to a timestamp. If the input string is a constant and complete
time expression, this has the same effect as a direct time parameter in single quotes. Here
Parsetime() is not necessary (PI2 compatibility).
If the input string is an incomplete constant time expression, we have something relative to
‘*’ that evaluates similar to the previous functions.
PI Server Applications User Guide Page 31
Chapter 3 - PI Performance Equations Recalculator
If the input string is a variable, evaluation at compile time is impossible: Any automatic
recalculation is suppressed.
3.4.3 Extract a Number from a Timestamp
Other functions extract a number out of a timestamp, including Day (), DaySec (), Hour (),
YearDay () .
These functions don’t affect the recalculation period. If the results are used in other time
expressions, they have the same effect as any other variables. The effects can only be
evaluated during the recalculation process.
3.5 Examples of Archive Retrieval / Search Functions
A simple form of filter, assuming no compression, with scan-based values; this avoids
recursive use of the PE point:
('xsource' + (PrevVal('xsource', '*')*9) / 10
Yesterday’s average value:
TagAvg('xsource', 'Y', 'T')
Performs an integration (sum) on xsource since tsource’s value first exceeded 10.0
yesterday; assuming xsource has a per day EngUnit:
TagTot(xsource, FindGt(tsource,'Y','T',10.0),'T')*24
These functions have several time parameters, defining a time range of Archive values to use.
See the limits of the Time Range Reference type, earlier in this chapter.
PrevEvent(), or NextEvent () return an absolute timestamp outside a given time range. This
means theoretically that we cannot determine the reverse time. Practically they return the
neighbor timestamp to the input timestamp. This is the same algorithm the recalculation
performs anyway (if source point’s Step=0). Therefore, no extra time dependency is
evaluated. This applies also to the functions PrevVal() and NextVal().
Note: Multilevel functions, such as PrevVal('tagname'), or PrevEvent('tagname')-
1s) are calculated properly, but determining the affected recalculation period is not
supported properly.
3.6 Recalculation Limitations
There are some restrictions and limitations on the Recalculator’s ability to reprocess
Performance Equation expressions. This section outlines these limitations.
3.6.1 Source Variables without Archive Values
If any of the source variables do not have Archive values, the recalculation results in No
Data. This is not inserted into the Archive. If the original PE Scheduler calculation created
Archive events, they are preserved. Recalculation of these equations is not performed.
Page 32
3.6 - Recalculation Limitations
3.6.2 Exact Simulation of the Original Scan Cycles
A point event found within one scan cycle will be modified; otherwise a new event for the
dependent PE point will be inserted. An inserted event is set at the source event’s timestamp
+1 sec.
3.6.3 Modifications of the Performance Equation
When you modify a PE, recalculation is not initiated. Whenever recalculation does occur, the
current expression is used. Previous expressions are not retained.
If you want to apply a new formula to past values, you must run the Recalculator explicitly
on the desired point and period.
3.6.4 Archive and Time Functions
These generally result in recalculating some period between the input event and now. If these
functions are used, they can cause a heavy amount of system load. As noted earlier, the
recalculation of the whole Archive up to now because of absolute timestamps is suppressed
on automatic recalculation.
Timestamps as a result of other embedded functions are not supported completely. If the
timestamp expression cannot be evaluated at compile time (subsystem start), a dependency
Type 1 (i.e. Simple) is assumed. This applies to expressions like:
TagVal('input_tag', PrevEvent('input_tag','*')-3600)
Not all affected PE point events might be found correctly. See the description of Type 7:
Multilevel Time Dependency for another example.
It is syntactically correct to have relative time expressions referencing future values. PE
Scheduler works on No Data and gets a Calc Failed result. If the Recalculator has to perform
this calculation, this is not considered specially. A numerical value might be returned and
stored in the archive. So there are different results without any change in the source data.
3.6.5 Unsupported Dynamic Functions
Recalculator does not support the following functions: Arma (), Delay (), Impulse (), and
MedianFilt ().
3.6.6 Incomplete Timestamps
An incomplete absolute timestamp (e.g., ‘25’ = midnight on the 25th of the actual month)
refers to the actual time of compilation, which gives different results depending on the time
of recalculation. For more details, see Set the Location3 Attribute: Timestamp, on page 12.
Avoid these expressions.
The calculation is independent of the Archive time for which it will be used.
As incomplete timestamps are not absolute dates, they don’t lead to a total recalculation of
any dependent PE point. As they are not valid relative time expressions, inverting of time
dependency is not performed.
PI Server Applications User Guide Page 33
Chapter 3 - PI Performance Equations Recalculator
3.6.7 Blob Support
Like the PE Scheduler, the Recalculator does not handle Blob type points.
3.7 Recalculator Point Configuration
Points used by the Recalculator are completely defined by the requirements of the PE
subsystem. For more information regarding point configuration, see Chapter 2, PI
Performance Equation.
In addition, the Location1 parameter is used. The Location1 value does not influence the
operation of the PE Scheduler.
The Recalculator uses the Point Name and Step parameters from the source points. The
Recalculator signs up for events of the source points, which may belong to any point source.
The Recalculator is scheduled with the point source class of PE points, and uses the following
parameters of the dependent PE points: Extended Descriptor (ExDesc), Point Source, Scan
flag, Archiving flag, Location 4, and Point Type, as described below.
3.7.1 Point Name
The point names for the PE point and the source points follow the normal PI point-naming
conventions.
3.7.2 Extended Descriptor
The Extended Descriptor (Exdesc) contains the Performance Equation. It is analyzed to find
source points and time expressions. It is calculated to get the new Archive values.
3.7.3 Point Source
All points defined in the PI Point Database for use with this module must share the point
source of the PE subsystem. The Point Source is a single character. The standard for the PE
Subsystem is C.
3.7.4 Scan
The Scan flag must be set to 1 for the PE Scheduler to work on this point. The Recalculator
does not use or change the Scan flag.
3.7.5 Archiving
Archiving has to be set to 1 for the PE Scheduler to create Archive events of this point. The
Recalculator does not use or change the Archiving flag, but the Archiving flag must be set to
1.
3.7.6 Location1
By default, the Recalculator considers all PE points as candidates for recalculation and does
not use this attribute value. However, if there is a parameter "/IN=n" where n > 0) in the
startup file or an Instance value in the Registry, only points with the corresponding value in
Page 34
3.8 - Start Recalculator as a Service
Location1 are recalculated. This feature can be used to assign PE points into recalculation
groups.
Note: It is possible to start multiple instances of the Recalculator. Every instance
should be controlled by a different /in parameter.
3.7.7 Location4
This parameter specifies the scan class used by PE Scheduler.
3.7.8 PointType
As with the PE Scheduler, the point types Int16, Int32, Float16, Float32, Float64, Digital
and String may be used.
3.7.9 Step
This value for the source point is used to determine if any event any time prior to the
scheduled event must be examined. See Point Dependency Considerations, on page 21.
3.7.10 Other Attributes
The Recalculator does not use any other point attributes. They may be used by the PE
Scheduler and retain their normal meanings for other operations.
The following attributes are not used:
• Location2
• Location3
• Location5
• UserInt1
• UserInt2
• UserReal1
• UserReal2
• EventTag
• InstrumentTag
• Square root code
3.8 Start Recalculator as a Service
The Recalculator can run as a Windows service, to automatically recalculate PE points that
have source points that receive edits, deletions, or new delayed or out-of-order events.
The Recalculator module is normally installed automatically when the PI Server is installed.
This section explains how to configure the PE Recalculator startup.
PI Server Applications User Guide Page 35
Chapter 3 - PI Performance Equations Recalculator
3.8.1 Configure Startup and Shutdown
The Recalculator is not set to start automatically upon system startup, even if you chose to
have the PI Server start automatically. To start Recalculator automatically, edit the startup
and shutdown scripts, and change the startup settings for the Recalculator service. You should
do both since you may start the PI Server by starting the computer, or by running the startup
script when the computer is already running.
Startup and Shutdown Scripts
Edit \pi\adm\ pisrvsitestart.bat and add the line:
net start pirecalc
Edit \pi\adm\ pisrvsitestop.bat and add the line:
net stop pirecalc
Edit \pi\adm\ pisitestart.bat and add the line:
start "PI Recalculator Subsystem" /min cmd /k ..\bin\pirecalc.exe
Configure Automatic Startup
The Recalculator may be configured for automatic startup by either of two methods:
Using the Control Panel Services Applet
Open the Control Panel and start the services applet. Locate the PI Recalculator
Subsystem in the list of services. Click the Startup button:
Page 36
3.8 - Start Recalculator as a Service
Click the Automatic radio button. The Recalculator will start automatically on your next
reboot.
Using Recalculator Command-Line Arguments
The Recalculator executable supports command-line arguments that can be used to configure
it to run as a Windows service.
Issue the following commands:
\pi\bin\pirecalc –remove
\pi\bin\pirecalc –install –auto -depend piarchss
–display "PI Recalculator Subsystem"
3.8.2 Specify Options with a Startup Script File
When the Recalculator starts, it searches for \pi\bin\pirecalc.bat. This file may contain startup
and debugging options, and can also be used as the startup file when starting the Recalculator
manually. This file is not created automatically when the PI Server is installed or upgraded.
Note: When specifying file names in the script, be sure to use full path names.
You can also set some of these options by editing the Windows NT/2000 Registry. See
Section 3.8.3, Specify Options, for details.
Recalculator Startup Options
Table 3–3 shows the command line switches for the PE Recalculator. These options are
detailed after the table.
PI Server Applications User Guide Page 37
Chapter 3 - PI Performance Equations Recalculator
Some of these options are best used only when the Recalculator is started manually. See
section 3.9, Start Recalculator Manually, for details.
Table 3–3. Recalculator Startup Options
Parameter Description
/in=0 Interface number (corresponds to Location1 point
attribute). Omitting this parameter or a value of 0 means
ignore Location1 values.
/output=c:\….\pirecalc.log Module-specific debug log file pathname. The default
output is to the screen, if run as console application.
/ex[ecute]=tag,start[,stop][,TEST] Recalculate a specific PE point and exit. This option can
accept one timestamp to specify a point in time, or two
timestamps to specify a range. Adding the word 'TEST'
causes the display of recalculated results with no
storage in PI.
Wildcard characters can be used in the tag. If present,
an /in= startup parameter is checked, too.
This option may only be used only in manual mode.
/deb=0 Debug level. See Table 3–4 for debug level options.
These parameters of pipeschd.bat are also read and interpreted:
/f=… Scan Class frequency, optional use of multiple /f=…
-no default values provided -
/ps=C Point Source
Note: Command-line parameters are case-insensitive. You can use a leading -
(hyphen) instead of / (forward slash) as well.
Command-Line Parameter Reference
/ps = C
Specifies the point source of the points on which the module will operate. This parameter is
taken from the PE Scheduler startup script file, pipeschd.bat.
/in = 1
This parameter corresponds to the Location1 attribute of a point. If you omit this parameter
or set it to zero, all PE points, determined by the /ps parameter in pipeschd.bat, are checked
for recalculations.
/f = 00:00:30[,00:00:00]
This parameter is set in pipeschd.bat. It defines the scan frequency for different scan classes.
There is no limit on the number of scan classes. An offset may be added.
Page 38
3.8 - Start Recalculator as a Service
These parameters in combination with the Location4 point attribute determine where an
existing PE event is searched, or if a new event is created. The offset portion is not used.
/output = c:\pi\log\pirecalc.log
The /output option causes Recalculator to generate debug output and error messages and
send them to PI\log\pirecalc.log. If you omit this parameter and start Recalculator (manually)
as a console application, output is sent to the console window.
If you start Recalculator as a service and the output parameter is missing, output goes to the
PI System Message Log. Use the PIGetMsg utility or PIHealthCheck to retrieve this
information. Debug messages are not sent to the PI System Message Log.
/execute = tagmask,starttime[,endtime][,TEST]
The “/execute” mode allows you to test or modify single Dependent PE points. Use this
option only when you manually start the Recalculator.
For example: "/execute=tag1,12-dec-98 15:00:00" means, recalculate the PE point tag1
at the given timestamp, then exit.
For starttime and endtime the PI time syntax is allowed.
Note: Do not use quotes around tagname and time. If this option contains space
characters (timestamps require a space between date and time), enclose the whole
option in double quotes.
Tagmask is searched among the tags with the same point source as stated in
parameter /ps in pipeschd.bat.
If a parameter /in is present, Location1 is checked, too.
Tagmask can contain wildcard characters * and ?. All matching points are
recalculated.
If there are two time parameters, they define a time range to be recalculated.
If there is a single time parameter and no event exists at that time - within limits
given by the corresponding scan cycle, a new Archive event is created.
If the additional sub-parameter TEST is applied, the results are not stored in the Data
Archive but are printed only, according to the /output parameter.
This mode doesn’t work when run as a service.
The option keyword may be abbreviated up to "/ex=".
/deb=0
The module is able to print additional debug information into the module-specific log file,
depending on the debug level used. The amount of log information increases with the value.
All information of lower levels is included.
Table 3–4 lists allowed debug values, and output.
PI Server Applications User Guide Page 39
Chapter 3 - PI Performance Equations Recalculator
Table 3–4. Recalculator Debug Levels and Output
Debug
Level Output
0 Start / Version / Number of points / Stop (As sent to Message Subsystem). Test mode
results. Internal errors.
1 Additional information about module operation. Examples: startup parameter / defaults,
results of dependency check on start/update.
2 Information about problems that will be handled by the module and will not cause data
loss. Start of a recalculation period.
3 Display result dependency. More calculation period info.
4 Print out each calculation the program performs. Only for onsite test purposes. Use this
mode if directed by OSI Tech Support. Log file might increase rather quickly.
5 More information than Level 4.
6…8 Additional internal debugging information
9 Maximum internal dump output.
3.8.3 Specify Options with the Windows Registry
To control Recalculator when started as a service, you can specify startup options in the
Windows NT/2000 Registry rather than creating a startup script file. Registry values are not
created automatically when the PI Server is installed or upgraded. Use the RegEdit
application to update the Registry.
You can include the following startup parameters in the Registry key
KLM\SYSTEM\CurrentControlSet\Services\pirecalc:
Startup Parameter Registry Value Name Data Type
/output DebugLogFile REG_SZ
/deb DebugLevel REG_DWORD
/in Instance REG_DWORD
Note: Startup file settings located in pi\bin\pirecalc.bat have priority over Registry
settings.
If there is no path information for DebugLogFile, the standard PI Server log directory \PI\log\
is assumed.
Page 40
3.8 - Start Recalculator as a Service
The example above shows the Recalculator service configured for a debug level of 1, with a
debug log file specified.
A normal installation has neither Registry keys nor the pirecalc.bat file.
3.8.4 Run Multiple Instances
To recalculate several subsets of Performance Equation points you may wish to run multiple
instances of pirecalc. Create a startup script for each instance, such as:
\pi\bin\pirecalc.bat
\pi\bin\pirecalc2.bat
\pi\bin\pirecalc3.bat
They should differ by the /in=# startup parameter. If they are intended to start console
applications, they may refer to the same executable, \pi\bin\pirecalc.exe. See Section 3.9,
Start Recalculator Manually, for more information.
To run multiple instances of Recalculator, create copies of pirecalc.exe and rename them, for
example:
\pi\bin\pirecalc2.exe
\pi\bin\pirecalc3.exe
Then install them as services by running
\pi\bin\pirecalc2.exe –install –auto -depend piarchss
–display "PI Recalculator Subsystem (Subset 2)"
It is necessary that corresponding .exe and .bat files have the same base names and reside in
the same directory \pi\bin\. You may change the display (icon) names. OSIsoft recommends
you start them with "PI." They must be unique.
Edit the start and shutdown scripts: see the instructions in Section 2.2.1, Start and Stop the
PE Subsystem, for more information. The notes there about automatic vs. manual service start
apply to the additional instances as well.
To rename the originally installed instance, you have to remove the service first. Use the
command:
PI Server Applications User Guide Page 41
Chapter 3 - PI Performance Equations Recalculator
\pi\bin\pirecalc.exe –remove
And proceed as described above.
Alternatively to different .bat files, you may add the Instance=# Registry value as described
in Section 3.8.3, Specify Options. The Registry key pirecalc2 might look like this:
3.9 Start Recalculator Manually
You can start Recalculator as a console application instead of, or as well as, a Windows
service. This is useful if you want to watch debug message output on the screen, or to
reprocess Performance Equation expressions on demand.
3.9.1 Recalculator Startup Options
When started manually, the Recalculator interprets the same startup options as when run as a
service. See Recalculator Startup Options, on page 37.
An example of a startup script is as follows:
pirecalc.exe /deb=1 /output=c:\pi\log\pirecalc.out
You can start the Recalculator by running a batch file (such as \pi\bin\pirecalc.bat)
containing these startup options.
You can recalculate a subset of PE points if they have the same Location1 parameter. This is
specified with the /in startup parameter. Different subsets can be processed in parallel by
other instances of pirecalc, that are run as console or as a service. Running several console
application instances in parallel simply requires different startup scripts, containing different
/in parameters.
3.9.2 Manual Recalculations
This section describes recalculation operations that you can perform when you start
Recalculator manually.
Page 42
3.10 - Stop Recalculator
Recalculate a Single PE Point over a Period of Time
Use the /execute option with two timestamps. For example:
/execute=MyAvgTag,"01-dec-98","01-jan-99"
Recalculate a Single PE Point at a Specific Time
Use the /execute option with a single timestamp:
PIRECALC "/exec=petag,timestamp"
A new value is added if there is no event in the Archive at or directly (within one scan period)
after the timestamp. For example:
/execute=MyOtherTag,"30-nov-98 23:59:59"
Test Recalculation over a Period of Time
Recalculator shows the expected value of a PE point by recalculating it, but does not store the
result in the PI Data Archive:
pirecalc /exec=T2Calc,Y+7h,Y+15h,TEST
Recalculator shows T2Calc’s values from yesterday at nine o’clock in the morning, to three
o'clock in the afternoon. The Archive remains unmodified and might contain different values.
T2Calc is assumed to be a dependent PE point.
Test Recalculation at a Specific Time
Recalculator shows the expected value of a PE point by recalculating it, but does not store the
result in the PI Data Archive:
pirecalc /exec=T2Calc,Y+9h,TEST
The Recalculator shows T2Calc’s value from yesterday morning at nine o’clock. The
Archive remains unmodified and might contain a different value. T2Calc is assumed to be a
dependent PE point.
3.10 Stop Recalculator
If you start Recalculator in single execution mode (that is, manually with the parameter
/execute), the module stops itself when finished. If you start Recalculator as a console
application, use the <Ctrl>-C or <Ctrl>-<Break> key command.
If you start Recalculator as service, you can stop it via the Control Panel, or with the
command: (where PI\ is the full path of the PI directory)
PI\bin\pirecalc –stop
or
net stop pirecalc
PI Server Applications User Guide Page 43
Chapter 3 - PI Performance Equations Recalculator
3.11 Optimize Recalculator Performance
Recalculator is intended to operate as a background task on already existing Archive events.
To limit the system load, recalculation is divided into several steps with decreasing priority:
Find the PE point and period to be calculated, whenever triggered by a source event.
Perform calculations of periods found in the previous step.
Check for point attribute updates.
These steps are triggered in different cycles and are limited to a number of operations per
cycle. You cannot change the parameters controlling this behavior.
To speed up the performance of the single execution mode, select an appropriate subset of
dependent PE points using the point attribute Location1 and the /in= startup parameter.
3.12 Error and Information Messages
You can view Recalculator system (log) messages in two locations.
The standard PI System Message Log contains general information and error
messages, such as: subsystem start / stop, used point source character, and number of
points handled. Use pigetmsg or PIHealthCheck to read the Message Log.
You can instruct Recalculator to generate a user-configurable message log file.
Output messages to any filename with the /output startup parameter. (If you start
Recalculator as an application, the output defaults to the console window.) Configure
the error and debug information recorded with the /deb=level startup parameter. The
log also records results if you use the /execute=tagname,period,TEST startup
argument.
Page 44
Chapter 4. PI PERFORMANCE EQUATIONS SYNTAX AND
FUNCTIONS REFERENCE
The Performance Equations (PE) Scheduler allows you to easily implement sophisticated,
real-time calculations, using data in the PI System. (See Chapter 2, PI Performance
Equations Scheduler.)
The PE Scheduler includes an equation syntax and a library of built-in functions, which allow
you to easily perform a wide variety of calculations on PI data. Typical calculations include
unit performance, real-time cost accounting, real-time yield accounting, heat and material
balances, batch summary, conversions and totalizations not performed by PI Totalizer, logical
operations, and calculating aggregates.
This chapter provides comprehensive instructions for using Performance Equations syntax
and functions, and includes the following topics:
Section 4.1, Performance Equations Syntax, on page 45
Section 4.2, Performance Equations Functions, on page 60
Section 4.3, List of Built-in Functions, on page 61
Section 4.4, Performance Equations Functions Reference, on page 70
4.1 Performance Equations Syntax
Performance Equations syntax includes the following topics:
Performance Equation Syntax, on page 45
Performance Equation Operands, on page 46
List of all Performance Equation Operators, on page 52
Data Types, on page 58
Test the Performance Equation Syntax, on page 59
4.1.1 Performance Equation Syntax
Writing a Performance Equation calculation expression is very similar to writing an
expression in arithmetic. In fact, you can use any of the standard arithmetic operators in a PE
expression (such as +, -, or *) to add the values of two points together, add a number to the
value of a point, etc.
PI Server Applications User Guide Page 45
Chapter 4 - PI Performance Equations Syntax and Functions Reference
As with arithmetic expressions, the building blocks of a PE calculation expression are
operands and operators. Performance equations are simply expressions in which operators act
on operands. A basic PE expression takes the form: operand operator operand – as shown
here:
The PE Scheduler evaluates the first example as the value of TagA plus the value of TagB.
The second example is 3 minus the value of TagC. The third example is 7 times the square
root of TagD.
You can construct more complex PE expressions, just as you can in arithmetic. The PE
Scheduler performs most operations in the same order as they'd be performed in a
mathematical expression. For a complete listing of PE operator priority, see Operator
Priority, on page 58.
Use parentheses to group together expressions you want to evaluate first:
The first example above evaluates as the sum of the values of TagA and TagB, divided by the
difference of 3 minus TagC. The second example is TagA divided by the sum of TagA and
TagB. The third example is 3 plus the product of 7 and the square root of TagD.
4.1.2 Performance Equation Operands
The operands that the PE Scheduler recognizes are listed in Table 4–1. (As indicated under
Syntax Requirements, certain operands must always be enclosed in single or double quotes.)
Table 4–1. Operands in Performance Equations
Operand Type Syntax Examples
Requirements
Numbers (none) 1342
98.6
.0015
1.2e2
Page 46
4.1 - Performance Equations Syntax
Operand Type Syntax Examples
Requirements
Tagnames In single quotes 'sinusoid'
'ba:level.1'
'ba.phase.1'
PI Time Expressions In single quotes '01-dec-03'
'16-jul-94'
'*'
Strings In double quotes "string string string"
"Now is the Winter of Our
discontent…"
"sinusoid"
Functions Must be a PE TagVal('sinusoid')
function
TagAvg('sinusoid')
Cos('sinusoid')
Number Operands
You can use numbers in Performance Equations. The PE Scheduler processes all numbers as
floating point numbers. Examples of numbers include:
3.14159
299792458
299792458.
0.671
.671
6.71e-1
Note: The second and third examples are equal, as are the fourth, fifth, and sixth.
4.1.3 Tagname Operands
You can use tagnames in Performance Equations to represent values from the Snapshot. You
must put the tagname in single quotes, unless you are using the tagname as a string, in which
case you must enclose it in double quotes. The PE Scheduler evaluates the tagname according
to its use it in an expression, as a function argument, or as a time expression.
Tagnames in Expressions
If you use the tagname in an expression, PE evaluates the tagname as that point's value at the
current time. For example:
3 + 'sinusoid'
is equal to the value of sinusoid at the current time (see note), plus three. The same value
results from the expression:
3 + TagVal('sinusoid', '*')
PI Server Applications User Guide Page 47
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Note: The exception is when this expression is used in a PE point, the PE point is
event-based, and the Location3 attribute is set to one.
Tagnames as Function Arguments
If you use the tagname as an argument in one of the PE built-in functions, then the PE
subsystem evaluates the tagname according to the type of value expected by that particular
function.
For example, if the function expects a tagname, then PE passes a tagname to the function. If
the function expects any other data type such as a string or a number, PE Scheduler gets the
current value of the point and passes that to the function—as whatever data type is expected.
For example, the Concat function expects two or more strings as arguments. It concatenates
all the arguments into a single string:
Concat('sinusoid', 'ba:level.1')
To evaluate this expression, the PE Subsystem takes the current value of the sinusoid point
and the ba:level.1 point and passes these to the Concat function as strings. Concat then
returns a string that is composed of the value of the sinusoid point followed by the value of
the ba:level.1 point. If the current values of these points are, respectively, 85.329 and 30.478,
Concat returns the following string:
85.32930.478
Tagnames that Are Valid Time Expressions
Wherever possible, choose tagnames that cannot possibly be interpreted as time expressions.
The tagname t-151d, for example, is also a valid time expression meaning today minus 151
days. If you must work with tagnames that are also valid time expressions, use the built-in
function TagNum to ensure that the PE subsystem does not treat the tagname as a time. For
example, Abs(TagNum("t-151d")) would return the absolute Snapshot value of point t-
151d. Note that TagNum interprets a double-quoted string as the argument.
To the PE subsystem, an expression within single quotes can correspond either to a time or a
tagname. The PE Scheduler treats expressions in single-quotes as tagnames for all the built-in
functions that take a point as the first argument. (Examples include TagVal, TagAvg, and
AlmCondition). In all other cases, the PE subsystem first attempts to resolve the expression
as a time. If the expression is not a valid time, then the PE subsystem tries to resolve it to a
tagname. If the point does not exist, the subsystem returns the error Calc Failed.
For example, TagVal('t-151d') returns the Snapshot value for the point t-151d, if it exists.
However, the expression t-151d returns the date corresponding to 151 days before today—
because it is a valid time expression.
4.1.4 String Operands
Strings are sequences of any printable characters. Strings are always enclosed in double-
quotes. Some examples are:
"This is a string"
"sinusoid"
Page 48
4.1 - Performance Equations Syntax
"14-Dec-97"
Note: Character strings might look like tagnames or time expressions, as in the
second and third examples above. In some cases, the string in the third example
might be interpreted as a time. The difference is that a character string is enclosed in
double quotes (for example, "string") while a tagname must be enclosed in single
quotes (for example, 'tagname') and a time expression may be enclosed in either
single or double quotes.
4.1.5 Time Expression Operands
In a PE, you can use any standard PI time expression if you enclose it in single quotes. The
following topics briefly explain PI time expressions and how to work with them in PEs. For
more information about PI time, see the PI Server System Management Guide.
PI Time Expressions
Tips for Working with PI Time Expressions
Times as Strings
Quick Reference Table of Time Syntax Examples
PI Time Expressions
PI allows three basic types of time expressions: relative time, combined time, and absolute
time.
Relative Time
Relative time expressions are some number of a number of days, hours, minutes, or
seconds, specified with either a leading plus sign or a leading minus sign.
The reference time, or starting time, for the relative time expression is usually the current
time. In PEs, we recommend you use a combined time expression, rather than a relative
time expression.
+1d
-24h
-3m
+24s
Combined Time
A combined time expression is a specific reference time, followed by a relative time
expression. In Performance Equations, you enclose the combined time expression in
single quotes (or double quotes, if you are passing the time expression to a PE function as
a string).
'*+8h'
'18-dec-02 -3m'
'T+32s'
PI Server Applications User Guide Page 49
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Combined time expressions should contain only a single operator. If you add additional
operators, you get unpredictable results. For example, the following are not valid time
expressions:
'*+1d+4h'
'T-1d+12h'
Absolute Time
Absolute time expressions are everything else—in other words, any time expression that
is neither a relative nor a combined time expression is an absolute time expression. When
using absolute time expressions in PEs, put the time expression in single quotes.
'*'
'14-Dec-97'
TagVal('Sinusoid', "1-Jun-2000")
'11-Nov-96 2:00:00.0001'
't'
Tips for Working with PI Time Expressions
When working with time expressions in PEs, please follow these important guidelines:
Use absolute or combined time expressions, rather than relative time expressions. If
you don't, depending on the context of the expression, you might get an error
message or PI might choose a starting time that is not what you expect.
Relative and combined time expressions do not provide any special processing for
clock or calendar events such as daylight savings time boundaries. If you need
intervals based on local clock time, use Noon( ) and Bod( ) functions.
Relative and combined time expressions contain only a single operator: either a
single plus sign (+) or a single minus sign (-). If you add additional operators, you get
unpredictable results. For example, the following are not valid time expressions:
'*+1d+4h'
'T-1d+12h'
Times as Strings
You can also pass a time expression as a string to a function that expects a string. In this case,
enclose the time expression in double quotes, rather than single quotes.
Performance Equations Time Syntax Reference
The following table provides PI time syntax examples.
Table 4–2. Examples of Time Syntax
Description Code Example Example Description
Now * * Now—current time
Page 50
4.1 - Performance Equations Syntax
Description Code Example Example Description
Midnight at specified dd 25 Midnight the 25th of the
date and current current month
month
Midnight at specified dd-mmm-yy 25-aug-02 Midnight on August 25th
date 2002
Specified time at dd-mmm-yy hh:mm:ss 25-aug-02 Noon on August 25th 2002
specified date 12:00:00
Specified hour at h: 8: 8:00 at current date
current date
Specified hour and dd h: 25 8: 8:00 on the 25th day of the
day of current month, current month
year and minute
Today at 00:00:00 t t+7h Today at 7 a.m.
Yesterday at 00:00:00 y y+15h Yesterday at 3 p.m.
Day of the week at sa,su,mo,tu,w,th,f mo+6.5h Monday at 6:30 a.m.
00:00:00
Time interval (days) #.#d 1.3d 1.3 days
Time interval (hours) #.#h 1.5h One hour and a half
Time interval #.#m 32m 32 minutes
(minutes
Time interval #.#s 49s 49 seconds
(seconds)
4.1.6 Function Operands
The PE Scheduler provides built-in functions that perform a variety of operations. You can
use any of these functions as an operand in a Performance Equation.
Numbers and Strings as Digital States
Digital state values consist of a state set specifier and a state number within that set. Each set
has a list of text names for the states. You can set a digital point with an expression that
results in either a number (specifying the offset) or a string (specifying the state name).
Comparing the Value of Digital and Numeric Points to Strings
In PEs, you can use expressions that compare the value of a digital or numeric point to a
string. For example, if the string "Run" is in the state set for digital point PumpStatTag, then
the following expression is valid:
If 'PumpStatTag' <> "Run" then 1 else 0
The state set for a numeric point is the System State Set. The System State Set is the default
state set for all points and it contains a collection of all the states that any point can use.
Examples are Shutdown, Over Range, I/O Timeout, etc. For example, the expression
PI Server Applications User Guide Page 51
Chapter 4 - PI Performance Equations Syntax and Functions Reference
'sinusoid' = "Shutdown"
is true if the numeric point sinusoid contains the digital state Shutdown from the System
Digital State Set.
Comparing a Digital State to a String Point
If you want to compare a digital state to a string point, use the DigState function to convert a
string to a digital state explicitly. For example, the following are different:
If 'StringTag' = "Shutdown" then 0 else 1
If 'StringTag' = DigState("Shutdown") then 0 else 1
The former is true if the string point contains the string "Shutdown" while the latter is true if
the point contains the digital state Shutdown.
Setting the Digital State for a Numeric or Digital Point
You can use a string to set the digital state for a numeric or digital point. When you do this,
PE Scheduler looks first in that point's state set for a state that corresponds to the string. If the
state does not exist in the point's state set, PE Scheduler searches the System Digital State Set
for the state string. If PE Scheduler cannot find the state string in either the Digital State Set
for that point or in the System Digital State Set, it returns Calc Failed. The state set for a
numeric point is the System Digital State Set.
4.1.7 List of all Performance Equation Operators
You use PE operators in PE expressions to act on operands such as tagnames, numbers, and
time expressions. Operator priority works basically as it does in math—multiplication and
division are performed before addition and subtraction, etc. You can also use parentheses to
group operations, just as you do in math. For a complete explanation of operator priority, see
Operator Priority on page 58.
Table 4–3 lists all the PE operators, according to type, with examples.
Table 4–3. PE Operators, Listed by Type, with Examples
Meaning
Operator Operator Syntax Example (A, B, C and D are all operands)
Type
Arithmetic + A + B Addition: A + B
– A – B Subtraction: A minus B
* A * B Multiplication: A times B
/ A / B Division: A divided by B
^ A ^ B Raising to a power: A to the power of B
(AB)
Mod A mod B Modulus: the remainder of A divided by
B
Relational < A < B Less than: returns true if A is less than
B
Page 52
4.1 - Performance Equations Syntax
Meaning
Operator Operator Syntax Example (A, B, C and D are all operands)
Type
= A = B Equal to: returns true if A equal to B
> A > B Greater than: returns true if A is greater
than B
<= A <= B Less than or equal to: returns true if A is
less than or equal to B
<> A <> B Not equal to: returns true if A is not
equal to B
>= A >= B Greater than or equal to: returns true if
A is greater than or equal to B
Prefix Not NOT A Complementation: returns true if A is 0
and False otherwise
– - A Negation (as prefix operator): returns
the negative of A
Conjunction, And A and B Conjunction: returns true if operands A
Disjunction & B both evaluate to true. If both A and
and Inclusion B are integers, returns the result of a
bitwise AND operation.
Or A or B Inclusive disjunction: returns true if
either operand A or operand B
evaluates to true. If both A and B are
integers, returns the result of a bitwise
OR operation.
in .. A in B..D Membership in a range: returns true if
the value of A is between B and D
in ( ) A in (B1, B2, Membership in a discrete set: returns
…BN) true if the value of A matches any of the
values enclosed in the parentheses.
If-Then-Else if then if A then B If-then-else expression: returns B if A is
Expressions else else D true—otherwise it returns D
Arithmetic Operators
PE operators include the simple arithmetic operators in Table 4–4.
Table 4–4. PE Arithmetic Operators
Operator Meaning Notes
+ Addition
– Subtraction
* Multiplication
/ Division
PI Server Applications User Guide Page 53
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Operator Meaning Notes
^ Raising to a power
mod Modulus The mod operator returns the remainder after its left
operand is divided by its right operand. For example, 17
mod 3 equals 2.
For a complete list of all PE operators, see List of all Performance Equation Operators on
page 52.
Arithmetic Operations on Time Values
You can perform certain arithmetic operations on times, such as adding two time expressions,
or subtracting one absolute time expression from another. The result of the operation is one of
the following:
A Timestamp. A timestamp is just a date and time in the PI timestamp format. For
example: 25-aug-02 12:00:00
A Period. A period is a number of seconds.
A Number.
Table 4–5 shows valid operations and results, where N represents a number, T represents an
absolute or combined time expression, and P represents a period.
Table 4–5. Valid Operations on Time Values
Operator Expression Result Example
+ T+ P T '*' + '+3h'
T+ N T '*' + 10
P + N P ('t'- 'y') + 10
P + P P ('t'- 'y') + ('t'-'y')
- (infix) T - P T '*' – '+3h'
T - N T '*' – 10
T - T P 't' – 'y'
P - N P ('t'- 'y') – 10
P - P P ('t'- '*') - ('t'-'y')
* P * N P ('t' –'y') * 5
N * P P 5 * ('+1d' –'+1h')
/ P / P N ('t'- '*') / ('t'-'y')
Page 54
4.1 - Performance Equations Syntax
Operator Expression Result Example
P / N P ('t'- '*') / 2
N / P N 2 / ('t'- '*')
mod T mod P T (see note) '*' mod ('*'-'t')
T mod N T (see note) '*' mod 2
P mod P P ('*'-'y') mod ('*'-'t')
P mod N P ('*'-'y') mod 3
- (prefix) -P P -('*'-'y')
Note: The timestamp returned is the result of T mod P or T mod N added to January
1, 1970 Universal Coordinate Time (UTC). So depending on the time zone, different
results are expected; in some case, even an error value is returned. In PI for
OpenVMS systems, the use of T mod P or T mod N returns P.
Relational Operators
A relational operator (one of <, =, >, <=, <>, and >=) returns a value of 0 for false or 1 for
true. You can use these operators to compare numbers, times, digital states, or character
strings. With relational operators, you can compare bad values, or values of different types
without generating an error.
Table 4–6. Relational Operators in Performance Equations
Operator Meaning
< Less than
= Equal to
> Greater than
<= Less than or equal to
<> Not equal to
>= Greater than or equal to
Comparing Bad Values
If you're comparing two operands of the same type, and one or both operands has a bad value,
the expression returns 0, rather than an error value.
Comparing Operands of Different Types
When you use the <> operator to compare any two operands of different types, the expression
always returns a 1 (i.e., 'true'). When you use any other relational operator (anything except
<>) to compare two operands of different types, the expression returns a 0 (i.e., 'false') except
in the following cases:
PI Server Applications User Guide Page 55
Chapter 4 - PI Performance Equations Syntax and Functions Reference
If one of the two operands is the digital type, then the PE subsystem compares the
digital operand to the digital state of the other operand, if it exists. For example:
'sinusoid' = DigState("Shutdown")
If the sinusoid point has a digital state Shutdown, then this expression returns a value
of 1 (i.e., true). Otherwise, it returns a value of 0 (i.e., false)
If one of the two operands is the string type and the other is neither digital nor string
type, then the PE subsystem compares the string operand to the digital state of the
other operand, if it exists. This allows the string substitution of its corresponding
digital state; i.e., Shutdown and DigState("Shutdown") would be the same.
Time Comparisons
You can perform all comparisons, including in, on times.
'*+20m' >= '*+300s'
PrevEvent('tag1', '*') > PrevEvent('tag2', '*')
If a comparison is true, the result is 1; otherwise, it is 0.
Prefix Operators
A prefix operator is simply an operator that appears to the left of its operand, for example, "-
x".
Table 4–7. Prefix Operators
Operator Meaning
– Negation
Not Complementation: Returns 1 if operand is 0 (or rounding to 0) and 0 otherwise
The expression following a prefix operator should be numeric. If you use a tagname as the
operand, make sure that the point returns a number. Note too, that even points that typically
return a number, sometimes return a digital state, such as Shutdown. Valid examples include:
-3
Not 7
-TagVal ('sinusoid')
Not Cos('ba:level.1')
-StateNo('DigitalTag')
Not TagBad('StringTag'))
The last two examples use digital and string points (DigitalTag and StringTag) but these are
used as arguments to functions that return numbers (StateNo and TagBad).
Conjunction, Disjunction and Inclusion Operators
You can use and, or, in .., and in() operators in PEs.
Page 56
4.1 - Performance Equations Syntax
Table 4–8. Conjunction, Disjunction and Inclusion Operators
Operator Meaning Returns
and Conjunction Returns true if operands A & B both evaluate to true. If
both A and B are integers, returns the result of a bitwise
AND operation.
or Inclusive disjunction Returns true if either operand A or operand B evaluates
to true. If both A and B are integers, returns the result
of a bitwise OR operation.
in .. Membership in a range The in .. operator returns 1 if true and 0 if false.
in ( ) Membership in a discrete The in () operator returns 1 if true and 0 if false.
set
Inclusion Operator Examples
The following are two examples that use inclusion operators.
If 1 in 0 .. 2 Then 1 Else 0
The result is 1, since 1 is between 0 and 2.
If 1 in (0, 2) Then 1 Else 0
The result is 0, since 1 does not equal either 0 or 2.
Using the Inclusion Operator with Digital State Functions
You can use the in .. operator with functions that return digital states, in which case the
operator uses the offset within the Digital State Set for comparison. The digital states must all
be in the same Digital State Set. Lexical comparisons are made with character strings.
Time Comparisons
You can use the Inclusion operators (in.., in()) on time expressions. If the comparison is
true, the result is 1; otherwise, it is 0.
If-Then-Else Expressions
The if–then–else operator is a compound operator whose operands are used as follows:
if expr0 then expr1 else expr2
where expr0, expr1, and expr2 are expressions. If expr0 is true (nonzero), this operator
returns the value of expr1; it returns the value of expr2 if expr0 is false (zero).
Here are some examples:
if 'tag1' > 50 then "overlimit" else "good"
if 'tag1'= 1 then Sin('tag2') else if 'tag1'= 2 then Cos('tag2') else
Tan('tag2')
if 'tag3'<> "shutdown" then (if 'tag1' > 'tag2' then 'tag1' else 'tag2')
else "error"
'*' + (if 'tag2' = 0 then 3600 else 0)
PI Server Applications User Guide Page 57
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Note: You must include the 'if,' the 'then,' and the 'else.' Nested operations are
supported.
4.1.8 Operator Priority
The PE Scheduler executes operators in order of priority, from highest to lowest. When
multiple operators have the same priority, the order of execution is either from left-to-right or
right-to-left, depending on the operator, as listed in the following table.
Table 4–9. Operator Priority
Operator Priority Order
-(prefix) 9 (done first) L-R
^ 8 R-L
Not 7 L-R
*, /, mod 6 L-R
+ , – 5 L-R
<, =, >, <=, <>, >= 4 L-R
in .., in( ) 3 L-R
And 2 L-R
Or 1 (done last) L-R
Note: The Not operator has a priority between ^ and *. This differs from
conventional priority schemes.
You can use parentheses anywhere to affect the order of calculation. Regardless of operator
priority, operations within parentheses are evaluated before operations outside those
parentheses. For example, (2+3) * 5 equals 25 while 2 + 3 * 5 equals 17.
4.1.9 Data Types
The PE Scheduler recognizes the following data types:
Number
Character string
Tagname
Time
Period
Every variable has one of these data types; every function returns one of these data types. The
PE Scheduler cannot typically use one data type where another is expected. For example, you
Page 58
4.1 - Performance Equations Syntax
cannot add two character strings, or multiply two times together. Additionally, the built-in
functions might require particular data types for particular arguments.
Type Checking
At compile time, the PE subsystem checks type compatibility as far as possible. This process
catches some errors, such as trying to add a number to a character string.
However, not all type compatibility errors can be detected at compile time. The expression
'sinusoid' / 2.0
works well if sinusoid has a numeric value, but if sinusoid is equal to the digital state
Shutdown the expression returns an error (Calc Failed).
Note: Comparisons (expressions using relational operators) are an exception to this
rule. Every comparison is valid, regardless of its operand types.
4.1.10 Error Values
When the PE subsystem cannot perform a calculation during runtime, it returns the error
value Calc Failed. Error values propagate through most calculations. For example, an error
value plus one is an error value. Exceptions to this rule are:
The BadVal and Concat functions
The relational operators when a value of 0 is returned
To check for compile time errors on Windows-based computers, check the pipc.log file
located in the \pipc\dat\ directory. For UNIX check the pipeschd.log file located in \pi\log
directory.
4.1.11 Test the Performance Equation Syntax
The pipetest utility is a command line function that checks the syntax of a Performance
Equation. There is also an System Management Tool (SMT) plug-in to test a performance
equation. (See the SMT documentation for information.) It can operate interactively, take its
input from a file or check the extended descriptor of a point.
Run the pipetest Utility
The pipetest utility is located in the pi\adm directory. To start pipetest, open a command
window, change to the pi\adm directory, and type a pipetest command. For a complete list of
pipetest commands, type:
pipetest -?
The pipetest utility is limited to equations that are 4095 characters or less and you can not
use it to test dynamic response functions.
Using pipetest in Interactive Mode
To run the pipetest utility interactively from a command prompt window, open a command
window, change to the pi\adm directory, and type:
PI Server Applications User Guide Page 59
Chapter 4 - PI Performance Equations Syntax and Functions Reference
pipetest
At the pipetest equation prompt, type in the equation you want to test. If the equation syntax
is not valid, pipetest displays a syntax error. If the syntax is valid, pipetest displays the result
of the equation.
Using pipetest in File Input Mode
You can also put one or more performance equations in a simple text file, and pass the entire
file to pipetest using the –f switch. In the text file, you put each equation on a single line.
You can include comment lines by beginning the line with an exclamation mark (!).
Here's the text from an example pipetest file, called peTestEquations.txt:
! test calculation for point A
if BadVal('sinusoid') then 0 else ('sinusoid')/25
! test calculation for point B
TimeLT('sinusoid', 'y' , 't', TagVal('sinusoid', '*'))
To test the equations in the file, type:
pipetest –f peTestEquations.txt
Each input line in turn is echoed and the evaluated result is displayed.
Check a Point's ExDesc Parameter
To check the Performance Equation of a specific point or group of points, use the –t switch
followed by a tag mask. For example:
pipetest –t sinusoi*
will process all points whose tagnames begin with the letters "sinusoi". The pipetest utility
echoes the tagname, the value of the extended descriptor field, and the evaluated result. The
pipetest utility ignores the event=tagname expression so, for example, the expression
event='sinusoid', 1+2 is the same as 1+2.
Optionally, you can also specify a PointSource character. For example, to process all points
with a point source character of C, type:
pipetest –f * C
4.2 Performance Equations Functions
In addition to all the basic arithmetic operators, the PE subsystem provides a large number of
built-in functions that you can use to perform more complex operations, such as taking the
sine or cosine of a point value, taking the average of a tag's value over time, etc.
4.2.1 Function Arguments
Functions have one or more arguments, or inputs, which are enclosed in parenthesis
following the function name. Some of the arguments may be optional. If there are several
arguments, they are separated by commas:
functionName(argument1, argument2, argument3)
Page 60
4.3 - List of Built-in Functions
The following are examples of function expressions:
Max(3, 5, 12.6, 'sinusoid')
PrevEvent('sy:arc001', '*-2h')
Sqr(Abs(TagMax('tag', 'y', 't')))
Log(if 'tag'=2 then .5 else .2)
Functions can also be nested and joined in expressions:
Avg(TagVal('TagA', 'y'), TagVal('TagB', 'y'), TagVal('TagC', 'y') )
if TagVal('TagA', '*') < TagVal('TagB', '*') then sin('TagB') else
sin('TagA')
You can use a tagname in any argument where a number or character string is called for. A
tagname in single quotes is evaluated as if it had been written TagVal(tagname), which is the
same as TagVal('tagname', '*' ). This gets the point's value at the "current" time for the
calculation.
If the argument calls for a number, but the point's value is a digital state when the function is
evaluated, a run-time error (Calc Failed) is generated.
4.3 List of Built-in Functions
The PE Scheduler provides a wide range of built-in functions that make it easier for you to
perform calculations on PI data. (Note that you can also use Steam Table Functions in PEs.)
Note: Immediately below, are two tables that provide a complete listing of all built-in
PE functions. One table lists functions grouped by type, and the the other is
arranged alphbetically.
4.3.1 Functions Grouped By Type
Table 4–10 lists all functions categorically, as follows.
• Math functions
• Other Math Functions
• Aggregate Functions
• Miscellaneous Functions
• PI Archive Retrieval
• PI Archive Search
• PI Archive Statistics
• Point Attributes
• Time Functions
• Dynamic Response
• Alarm Status Functions
• String Functions
• String Conversion
PI Server Applications User Guide Page 61
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Table 4–10. Functions Grouped by Type
Function Type Name Meaning
Math Asin Arc sine
Functions
Acos Arc cosine
Atn Arc tangent
Atn2 Arc tangent (two arguments)
Cos Cosine
Cosh Hyperbolic cosine
Exp Exponential
Log Natural logarithm
Log10 Common logarithm
Sin Sine
Sinh Hyperbolic sine
Sqr Square root
Tanh Hyperbolic tangent
Tan Tangent
Other Math Abs Absolute value
Functions
Float Conversion of string to number
Frac Fractional part of number
Int Integer part of number
Poly Evaluate polynomial
Round Round to nearest unit
Sgn Numerical sign
Trunc Truncate to next smaller unit
Aggregate Avg Average
Functions
Max Maximum
Median Median selector
Min Minimum
PStDev Population standard deviation
SStDev Sample standard deviation
Total Sum
Miscellaneous BadVal See if a value is bad (not a number or time)
Functions
Curve Get value of a curve
DigState Get digital state from a string
Page 62
4.3 - List of Built-in Functions
Function Type Name Meaning
IsDST Test whether a time is in local daylight savings time period
IsSet Test if a PI value is annotated, substituted, or questionable
StateNo The code number of a digital state
TagBad See if a point has an abnormal state
PI Archive NextEvent Time of a point's next Archive event
Retrieval
NextVal Point's next value after a time
PrevEvent Time of a point's previous Archive event
PrevVal Point's previous value before a time
TagVal Point's value at a time
PI Archive FindEq Timestamp when point = value
Search
FindGE Timestamp when point >= value
FindGT Timestamp when point > value
FindLE Timestamp when point <= value
FindLT Timestamp when point < value
FindNE Timestamp when point ~= value
TimeEq Total period when point = value
TimeGE Total period when point >= value
TimeGT Total period when point > value
TimeLE Total period when point <= value
TimeLT Total period when point < value
TimeNE Total period when point ~= value
PI Archive EventCount Number of Archive events
Statistics
PctGood Percent of good time in a period
Range Range of minimum to maximum value
StDev Time-weighted standard deviation
TagAvg Time-weighted average
TagMean Event-weighted average
TagMax Maximum value in a period
TagMin Minimum value in a period
TagTot Time integral over a period
Point TagDesc Get a point's descriptor
Attributes
TagEU Get a point's engineering unit string
TagExDesc Get a point's extended descriptor
PI Server Applications User Guide Page 63
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Function Type Name Meaning
TagName Get a point's name
TagNum Get a point's ID
TagSource Get a point's point source character
TagSpan Get a point's span
TagType Get a point's type character
TagTypVal Get a point's typical value
TagZero Get a point's zero value
Time Bod Timestamp for beginning of the day for given time
Functions
Bom Timestamp for beginning of the month for given time
Bonm Timestamp for first of the next month for given time
Day Day of the month from a time
DaySec Seconds since midnight from time
Hour Hour from a time
Minute Minute from a times
Month Month from a time
Noon Timestamp for local noon of day of a times
ParseTime Convert character string to time
Second Second from a times
Weekday Day of the week from a times
Year Year from a time
Yearday Day of the year from a time
Dynamic Arma Dynamic response from Auto Regressive Moving Average
Response model
Delay Introduce time delay
MedianFilt Select the median value of time series
Impulse Dynamic response characterized by impulse response shape
Alarm Status AlmAckStat Alarm acknowledgement status code
Functions
AlmCondition Condition code number for Alarm State
AlmCondText Alarm condition as text
AlmPriority Alarm priority number
String Ascii ASCII character code for a character
Functions
Char String for ASCII character code(s)
Compare Wild comparison of two strings
Page 64
4.3 - List of Built-in Functions
Function Type Name Meaning
DigText Text for a digital state
Format Formatting of a numerical number
InStr Instance of a sub-string
LCase Conversion of all characters to lower case
Len Length of a string
Left First characters in a string
LTrim Removal of blanks on the left side of a string
Mid Extraction of a sub-string from a string
Right Last characters in a string
RTrim Removal of blanks on the right side of a string
Trim Removal of blanks on both sides of a string
UCase Conversion of all characters to upper case
String Concat Concatenate two or more strings
Conversion
String String representing any PI value
Text Concatenation of strings for a series of PI value arguments
4.3.2 Functions Listed Alphabetically
Table 4–11. Functions Listed Alphabetically
Name Meaning
Abs Absolute value
Acos Arc cosine
AlmAckStat Alarm acknowledgement status code
AlmCondition Condition code number for Alarm State
AlmCondText Alarm condition as text
AlmPriority Alarm priority number
Arma Dynamic response from Auto Regressive Moving Average model
Ascii ASCII character code for a character
Asin Arc sine
Atn Arc tangent
Atn2 Arc tangent (two arguments)
Avg Average
BadVal See if a value is bad (not a number or time)
PI Server Applications User Guide Page 65
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Name Meaning
Bod Timestamp for beginning of the day for given time
Bom Timestamp for beginning of the month for given time
Bonm Timestamp for first of the next month for given time
Char String for ASCII character code(s)
Compare Wild comparison of two strings
Concat Concatenate two or more strings
Cos Cosine
Cosh Hyperbolic cosine
Curve Get value of a curve
Day Day of the month from a time
DaySec Seconds since midnight from time
Delay Introduce time delay
DigState Get digital state from a string
DigText Text for a digital state
EventCount Number of Archive events
Exp Exponential
FindEq Timestamp when point = value
FindGE Timestamp when point >= value
FindGT Timestamp when point > value
FindLE Timestamp when point <= value
FindLT Timestamp when point < value
FindNE Timestamp when point ~= value
Float Conversion of string to number
Format Formatting of a numerical number
Frac Fractional part of number
Hour Hour from a time
Impulse Dynamic response characterized by impulse response shape
InStr Instance of a sub-string
Int Integer part of number
IsDST Test whether a time is in local daylight savings time
IsSet Test if a PI value is annotated, substituted, or questionable
LCase Conversion of all characters to lower case
Len Length of a string
Page 66
4.3 - List of Built-in Functions
Name Meaning
Left First characters in a string
Log Natural logarithm
Log10 Common logarithm
LTrim Removal of blanks on the left side of a string
Max Maximum
Median Median selector
MedianFilt Select the median value of time series
Mid Extraction of a sub-string from a string
Min Minimum
Minute Minute from a time
Month Month from a time
NextEvent Time of a point's next Archive event
NextVal Point's next value after a time
Noon Timestamp for local noon of day of a time
ParseTime Convert character string to time
PctGood Percent of good time in a period
Poly Evaluate polynomial
PrevEvent Time of a point's previous Archive event
PrevVal Point's previous value before a time
PStDev Population standard deviation
Range Range of minimum to maximum value
Right Last characters in a string
Round Round to nearest unit
RTrim Removal of blanks on the right side of a string
Second Second from a time
Sgn Numerical sign
Sin Sine
Sinh Hyperbolic sine
Sqr Square root
SStDev Sample standard deviation
StateNo The code number of a digital state
StDev Time-weighted standard deviation
String String representing any PI value
PI Server Applications User Guide Page 67
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Name Meaning
TagAvg Time-weighted average
TagBad See if a point has an abnormal state
TagDesc Get a point's descriptor
TagEU Get a point's engineering unit string
TagExDesc Get a point's extended descriptor
TagMax Maximum value in a period
TagMean Event-weighted average
TagMin Minimum value in a period
TagName Get a point's name
TagNum Get a point's ID
TagSource Get a point's point source character
TagSpan Get a point's span
TagTot Time integral over a period
TagType Get a point's type character
TagTypVal Get a point's typical value
TagVal Point's value at a time
TagZero Get a point's zero value
Tan Tangent
Tanh Hyperbolic tangent
Text Concatenation of strings for a series of PI value arguments
TimeEq Total period when point = value
TimeGE Total period when point >= value
TimeGT Total period when point > value
TimeLE Total period when point <= value
TimeLT Total period when point < value
TimeNE Total period when point ~= value
Total Sum
Trim Removal of blanks on both sides of a string
Trunc Truncate to next smaller unit
UCase Conversion of all characters to upper case
Weekday Day of the week from a time
Year Year from a time
Yearday Day of the year from a time
Page 68
4.3 - List of Built-in Functions
PI Server Applications User Guide Page 69
Chapter 4 - PI Performance Equations Syntax and Functions Reference
4.4 Performance Equations Functions Reference
Abs
Return the absolute value of an integer or real number.
Format
Abs(x)
Arguments
x
Must be an integer or real number.
Returns
The absolute value of x.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Abs(1)
Abs(-2.2)
Abs('tag1')
Abs('tag1'- 'tag2')
Page 70
4.4 - Performance Equations Functions Reference
Acos
Return the inverse (or arc) cosine of an integer or real number. The inverse cosine of x is the
angle in radians whose cosine is equal to x.
Format
Acos(x)
Arguments
x
Must be a real number between -1.0 and 1.0, inclusive.
Returns
The inverse cosine of x, in radians.
Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value.
Examples
Acos(1-.5)
Acos(-.5)
If 'tag1' < 1 and 'tag1' > -1 then Acos('tag1') else 0
See Also
Asin, Atn, Atn2, Cos, Cosh, Sin, Sinh, Tan, Tanh
PI Server Applications User Guide Page 71
Chapter 4 - PI Performance Equations Syntax and Functions Reference
AlmAckStat
Return the acknowledgement status code for an alarm point.
Format
AlmAckStat(alm)
Arguments
alm
An alarm tagname.
Returns
The acknowledgement status code for the given Alarm State. Possible values are:
0 - acknowledged (or no alarm)
1- unacknowledged
2 - missed alarm
Exceptions
If the argument is not a digital state tagname, an error condition is returned.
Examples
AlmAckStat('alarmtag')
See Also
AlmCondition, AlmCondText, AlmPriority
Page 72
4.4 - Performance Equations Functions Reference
AlmCondition
Returns the condition code for an Alarm State.
Format
AlmCondition(alm)
Arguments
alm
An alarm tagname.
Returns
The code number of the condition for the alarm tagname.
Exceptions
If the argument is not a digital state tagname, an error is returned.
Examples
AlmCondition('alarmtag')
See Also
AlmAckStat, AlmCondText, AlmPriority
PI Server Applications User Guide Page 73
Chapter 4 - PI Performance Equations Syntax and Functions Reference
AlmCondText
Return the string for the condition of an Alarm State.
Format
AlmCondText(alm)
Arguments
alm
An alarm tagname.
Returns
The condition text for the condition represented by the alarm status.
Exceptions
If the argument is not a digital state tagname, an error condition is returned.
Examples
AlmCondText('alarmtag')
See Also
AlmAckStat, AlmCondition, AlmPriority
Page 74
4.4 - Performance Equations Functions Reference
AlmPriority
Return the priority of an Alarm State.
Format
AlmPriority(alm)
Arguments
alm
A digital state value from a PI Alarm State Set.
Returns
The priority of the given alarm. Priorities are small positive integers. Priority 0 is an alarm
that is never unacknowledged.
Exceptions
If the argument is not from a valid Digital State Set for alarms, an error condition is returned.
Examples
AlmPriority('alarmtag')
See Also
AlmAckStat, AlmCondition, AlmCondText
PI Server Applications User Guide Page 75
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Arma
Calculate dynamic response for Auto Regressive Moving average model as shown in Figure
4–1.
Format
Arma(in, runflag, (a1, a2, … aN),(b0, b1, b2, … bN))
Arguments
The denominator and numerator coefficient series are enclosed in parenthesis with a comma
between the two. There must be only one more term (b0) in the numerator than denominator.
Both in and runflag may be any expression that evaluates to a number.
in
Must be an integer or real number.
runflag
Non-zero enables filter to run.
a1,a2,…
Coefficients of past output terms.
b0, b1,b2…
Coefficients of the present and past input terms of the model.
Returns
The next output value in time series response to past and present input.
ut = a1 * ut-1 + a2 * ut-2 + … + an * ut-n + b0 * yt +
b1 * yt-1 + b2 * yt-2 + … + bn * yt-n
Where ut is model output at time t, now. ut-1 is output one sample interval in the past. yt is
the input signal at time t. If runFlag expression result is 0, the model is reset. Depending on
the number of coefficients used, Arma stores the inputs and outputs until an evaluation of the
model is available. For example, in
Arma( 'input_tag', 1, ( 0. ,1), ( 1, -1 ,1))
Arma stores two previous values of the input and output. Hence when the point is first
created, no good results will be given until two prior values of the input have been stored.
From then on, the two most current previous values will be stored.
Exceptions
Arma will give different results depending on which type of scheduling is used. In scan class
scheduling, the interval between time series values depends on the scan class and gives values
at evenly spaced time intervals. On the other hand, event based scheduling is dependent on a
trigger from another point. If the exception deviation is not zero, the intervals for events will
be not be evenly spaced in time and hence Arma will give results that are not trustworthy.
Page 76
4.4 - Performance Equations Functions Reference
Arma is not supported in the pipetest utility or in PI DataLink. If the input point is not a real
number or integer, Arma will return an error.
Examples
Derivative: Arma('input_tag', 1, (0.), (1, -1))
Integration: Arma('input_tag', 1, (1.), (.05, 0.))
Second order filter: Arma('input_tag', 1, (.25,.25), (.1,.25,.15 ))
Input Signal Output
b0 Σ
∆ ∆
b1 a1
∆ ∆
b2 a2
∆ ∆
b3 a3
...
...
∆ ∆
bn an
Figure 4–1. Block Diagram of ARMA Calculation Function
PI Server Applications User Guide Page 77
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Ascii
Return the ASCII character code of the first character of a string.
Format
Ascii(String)
Arguments
string
Any expression evaluating to a string.
Returns
The character code of the first character of the string.
Exceptions
If the argument is not a string, an error value is returned.
Examples
Ascii( "D" ) = 68
Ascii( string('cdm158' ) )
Page 78
4.4 - Performance Equations Functions Reference
Asin
Return the inverse (or arc) sine of a number. The inverse sine of x is the angle in radians
whose sine is equal to x.
Format
Asin(x)
Arguments
x
Must be a real number between -1.0 and 1.0, inclusive.
Returns
The inverse sine of x, in radians.
Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value.
Examples
Asin(TagVal('tag1','y'))
Asin(-0.5)
Asin('tag1')
See Also
Acos, Atn, Atn2, Cos, Cosh, Sin, Sinh, Tan, Tanh
PI Server Applications User Guide Page 79
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Atn
Return the inverse (or arc) tangent of an integer or real number. The inverse tangent of x is
the angle in radians whose tangent is equal to x.
Format
Atn(x)
Arguments
x
Must be an integer or real number.
Returns
The inverse tangent of x, in radians.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Atn(1)
Atn(-2.2)
Atn('tag1')
Atn('tag1'- 'tag2')
See Also
Acos, Asin, Atn2, Cos, Cosh, Sin, Sinh, Tan, Tanh
Page 80
4.4 - Performance Equations Functions Reference
Atn2
Calculate the inverse (or arc) tangent of a pair of numbers, which represent a point on the
plane. If you draw a line between the point whose Cartesian coordinates are (a, b) and the
origin, the angle between that line and the x-axis is the inverse tangent of (a, b).
Format
Atn2(a, b)
Arguments
a
Must be an integer or real number.
b
Must be an integer or real number.
Returns
The inverse tangent of (a, b), in radians.
Exceptions
If a or b is not an integer or real number, returns an error value.
Examples
Atn2(TagVal(‘tag1’,‘y’),TagVal(‘tag1’, ‘y’))
Atn2(1,1)
Atn2(‘tag1’, ‘tag2’)
See Also
Acos, Asin, Atn, Cos, Cosh, Sin, Sinh, Tan, Tanh
PI Server Applications User Guide Page 81
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Avg
Return the average of all the arguments.
Format
Avg(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers, times, or periods but all must be the same data type.
Returns
The average of the arguments. The result is the same data type as the operands.
Exceptions
Arguments whose run-time values are character strings or digital states are not included in the
average. If all values are character strings or digital states, Avg returns an error value.
Examples
Avg(TagVal('tag1','y'),TagVal('tag1', 'y'),1,2)
Avg('y', 't', '14-Dec-97', '14 8:00')
Avg('tag1', 'tag2')
Page 82
4.4 - Performance Equations Functions Reference
Badval
Test a value to see if it is bad. For real and integer points, a bad value is a digital state value.
For Digital points, a bad value is a digital state value outside its own Digital State Set.
Format
Badval(x)
Arguments
x
A value to be tested.
Returns
1 if the value is bad
0 if the value is not bad
Exceptions
Returns 1 for blob points. Returns 0 for character strings.
Examples
BadVal('tag1')
BadVal('digitaltag')
BadVal(TagVal('stringtag', '14-Dec-97 8:00:00'))
PI Server Applications User Guide Page 83
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Bod
Gets the timestamp for midnight at the start of a day.
Format
Bod(time)
Arguments
time
A time expression.
Returns
Timestamp for the start of the day.
Exceptions
None.
Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.
Examples
Bod('*')
Bod('y')
Bod(FindEq('tag1', '14-Dec-97', '+17d',50))
See Also
Bom, Bonm, Noon
Page 84
4.4 - Performance Equations Functions Reference
Bom
Gets the timestamp for midnight at the beginning of the month.
Format
Bom(time)
Arguments
time
A time expression.
Returns
Timestamp for the start of the month.
Exceptions
None.
Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.
Examples
Bom('*')
Bom(PrevEvent('tag', '*'))
Bom(FindEq('tag1', '14-Dec-97', '+17d',50))
See Also
Bod, Bonm, Noon
PI Server Applications User Guide Page 85
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Bonm
Gets the timestamp for midnight at the beginning of the next month.
Format
Bonm(time)
Arguments
time
Time expression.
Returns
Timestamp for the start of the next month.
Exceptions
None.
Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.
Examples
Bonm('*')
Bonm('y')
Bonm(FindEq('tag1', '14-Dec-97', '+17d',50))
See Also
Bod, Bonm, Noon
Page 86
4.4 - Performance Equations Functions Reference
Char
Build a string from ASCII character codes.
Format
Char( n1 [, n2, … ] )
Arguments
n1, n2, ...
Numeric numbers or expressions.
Returns
A string built from the character codes.
Exceptions
If an argument is not a number, returns an error.
Examples
Char(65) = "A"
Char(80, 73) = "PI"
Char(6 * 9) = "6"
PI Server Applications User Guide Page 87
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Compare
Compare two strings with wild characters ("*" and "?").
Format
Compare(str1, str2 [,casesen])
Arguments
str1, str2
Strings. Str2 may contain wild characters.
casesen (optional)
Flag indicating if the comparison is case sensitive.
casesen = 0 the comparison is case insensitive (default)
casesen = 1 the comparison is case sensitive
Returns
1 if Str1 = Str2
0 otherwise
Exceptions
Wild characters in str1 are not treated as wild.
Examples
compare("?","a") = 0
compare("What","wh") = 0
compare("What","wha?") = 1
compare("What","wh*") = 1
compare("What","wh*", 1) = 0
Page 88
4.4 - Performance Equations Functions Reference
Concat
Concatenate two or more strings.
Format
Concat(s1, s2, ..., sn)
Arguments
s1...sn
Must be character strings, or expressions yielding character strings.
Returns
The character strings, concatenated together. This function does not insert blanks between its
arguments. If you need blanks, you must add them yourself.
Note
Consider using Text, which is more general and more precise in many cases than Concat.
Examples
Concat("shut", "down") = "shutdown"
See Also
Text
PI Server Applications User Guide Page 89
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Cos
Return the trigonometric cosine of an integer or real number.
Format
Cos(x)
Arguments
x
Must be an integer or real number, which represents an angle in radians.
Returns
The cosine of x.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Cos('tag1')
Cos(1)
Cos(1.1)
See Also
Acos, Asin, Atn, Atn2, Cosh, Sin, Sinh, Tan, Tanh
Page 90
4.4 - Performance Equations Functions Reference
Cosh
Return the hyperbolic cosine of an integer or real number.
Format
Cosh(x)
Arguments
x
Must be an integer or real number.
Returns
The hyperbolic cosine of x.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Cosh('tag1')
Cosh(.9)
Cosh(1)
See Also
Acos, Asin, Atn, Atn2, Cos, Sin, Sinh, Tan, Tanh
PI Server Applications User Guide Page 91
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Curve
Returns the y value of a curve given the x value.
Format
Curve( x, (x1,y1) (x2,y2) … (xn,yn) )
Arguments
x
Expression evaluating to a number.
x1, y1
The first point on the curve. The xi's and yi's are numeric constants evaluated at compile
time. The values set for xi's must be in ascending order.
Returns
Returns the y value on the curve corresponding to the value of x. Linear interpolation is used
between points defining the curve. If the value of x is less than x1 then y1 is returned and if it
is greater than xn, yn is returned. The points are assumed to be ordered in the x direction
from smallest to largest.
Exceptions
If the value of x is not an integer or real number, an error value is returned.
Examples
curve('tag1', (0,100) (100,0) ) //inverter
curve('tag3', (25,25) (75,75) ) //limiter
Page 92
4.4 - Performance Equations Functions Reference
Day
Extract the day of the month from a time expression.
Format
Day(time)
Arguments
time
A time expression.
Returns
The day of the month of time, in the range 1–31.
Exceptions
None.
Examples
Day('*')
Day('t')
Day(FindGt('tag1', '*-30d', '*',50))
See Also
DaySec, Hour, Minute, Month, Second, Weekday, Year, Yearday
PI Server Applications User Guide Page 93
Chapter 4 - PI Performance Equations Syntax and Functions Reference
DaySec
Extract the number of seconds since midnight from a time expression.
Format
DaySec(time)
Arguments
time
A time expression.
Returns
The number of seconds of time since midnight, in the range 0–86399.
Exceptions
None.
Usage Note
This function is the same as the Time function in the PI 2.x Performance Equation package.
For example, if the current time is 8:30 am, DaySec('*') returns 30600.
Examples
DaySec('*')
DaySec('t')
DaySec(FindGt('tag1', '*-30d', '*',50))
See Also
Day, Hour, Minute, Month, Second, Weekday, Year, Yearday
Page 94
4.4 - Performance Equations Functions Reference
Delay
Delay line, the output tracks the input. For use in real time calculations, in pipeschd.exe for
example, this function might be a better choice than Prevvalue.
Format
Delay( x, runflag, n )
Arguments
x
Must be an integer or real number.
runflag
Non-zero enables filter to run.
n
Length of the delay, integer.
Returns
The input signal delayed by n calculation intervals. For scan class scheduling, the calculation
interval is based on the scan class. For event based scheduling, the calculation interval will be
dependent on the trigger and the exception deviation.
Exceptions
Delay is not supported in the pipetest utility or in PI DataLink. If the input point is not a real
number or integer, Delay will return an error. Delay will return Calc Failed until n scans
have elapsed after startup.
Examples
Delay('tag1',1,2)
PI Server Applications User Guide Page 95
Chapter 4 - PI Performance Equations Syntax and Functions Reference
DigState
Translate a character string representing a digital state into its corresponding digital state.
Format
DigState(s1 [, x])
Arguments
s1
A character string representing a digital state.
x (optional)
A digital point in which the character string represents a digital state. If omitted, all Digital
State Sets, starting with the System Digital Set, are searched for the given string.
Returns
A digital state
Exceptions
If the character string does not represent a digital state in the Digital State Set of the reference
digital point, the function returns Calc Failed. If digital point is omitted and character string
does not represent a digital state in any of the digital sets, Calc Failed is returned.
Examples
DigState("digitalstring", 'digitaltag')
StateNo(DigState("digitalstring", 'digitaltag'))
Page 96
4.4 - Performance Equations Functions Reference
DigText
Obtain the text corresponding to the current digital state of a point.
Format
DigText(tagname)
Arguments
tagname
A tagname that represents a digital state variable.
Returns
The text for the digital state.
Exceptions
If the argument is not a digital state tagname, an error condition is returned.
Examples
DigText('alarmtag')
DigText('cdm158' )
DigText('nondigitaltag') would not compile and returns an error message
PI Server Applications User Guide Page 97
Chapter 4 - PI Performance Equations Syntax and Functions Reference
EventCount
Find the number of Archive events for a point over a given time.
Format
EventCount(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point must represent a continuous variable.
starttime
Must be a time expression representing the beginning of the time range to search.
endtime
Must be a timestamp, greater than starttime; the end of the time range to search.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must
good.
Returns
Number of Archive events for the point within the specified interval.
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.
Caution
When endtime is a future time (for example, '*+1h'), TagCount might include the system
digital state No Data and thus is larger the number of events stored in the PI Archive. Avoid
using a future time if possible.
Examples
EventCount('tag1', 'y', '*')
EventCount('tag1', '14-Dec-97', '+1d',70)
EventCount('tag1', '14-Dec-97', '15-Dec-97')
Page 98
4.4 - Performance Equations Functions Reference
Exp
Return the exponential of an integer or real number. This is the number ex, where e =
2.7182818...
Format
Exp(x)
Arguments
x
Must be an integer or real number.
Returns
The exponential of x.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Exp('tag1')
Exp(TagVal('tag1','14-Dec-97'))
Exp(11)
PI Server Applications User Guide Page 99
Chapter 4 - PI Performance Equations Syntax and Functions Reference
FindEq
Find the first time, within a range, when a point is equal to a given value.
Format
FindEq(tagname, starttime, endtime, value)
Arguments
tagname
A tagname enclosed in single quotes.
starttime
A time expression representing the beginning of the time range to search Relative times are
relative to endtime if endtime is not itself a relative time.
endtime
A time expression representing the end of the time range to search. Relative times are relative
to starttime if starttime is not itself a relative expression. If endtime is earlier than starttime,
the range is searched backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was equal to
the given value.
Exceptions
If the point was never equal to the given value, FindEq returns an error value.
Usage Note
FindEq interpolates between Archive events, if necessary, to find the value it is looking for.
Examples
FindEq('tag1', 't', '*',40.0)
FindEq('digitaltag', '-1d', '*', TagVal('digitaltag', '14-Dec-97'))
FindEq('digitaltag', '14-Dec-97', '*', "On")
Page 100
4.4 - Performance Equations Functions Reference
FindGE
Find the first or last time, within a range, when a point is greater than or equal to a given
value.
Format
FindGE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
A time expression representing the beginning of the time range to search or a time relative to
endtime, if endtime is a time.
endtime
A time expression representing the end of the time range to or a time (in seconds) relative to
starttime, if starttime is a time. If endtime is earlier than starttime, the range is searched
backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was greater
than or equal to the given value.
Exceptions
If the point was always less than the given value, FindGE returns an error value.
Usage Note
FindGE interpolates between archive events, if necessary, to find the value it is looking for.
Examples
FindGE('tag1', 't', '*',40.0)
FindGE('digitaltag', '-1d', '*', TagVal('digitaltag', '14-Dec-97'))
FindGE('tag1', '-1d', '*','tag2')
PI Server Applications User Guide Page 101
Chapter 4 - PI Performance Equations Syntax and Functions Reference
FindGT
Find the first time, within a range, when a point is greater than a given value.
Format
FindGT(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
A time expression representing the beginning of the time range to search. Can be a time
relative to endtime if endtime is a time.
endtime
End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was greater
than the given value.
Exceptions
If the point was never greater than the given value, FindGT returns an error value.
Usage Note
FindGT interpolates between Archive events, if necessary, to find the value it is looking for.
Examples
FindGT('tag1', 't', '*',40.0)
FindGT('tag1', '-1d', '*',40.0)
FindGT('digitaltag', '-1d', '*', TagVal('digitaltag', 'y'))
Page 102
4.4 - Performance Equations Functions Reference
FindLE
Find the first time, within a range, when a point is less than or equal to a given value.
Format
FindLE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search; time expression or time relative to endtime if endtime
is a time.
endtime
End of the time range to search, timestamp or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was less than
or equal to the given value.
Exceptions
If the point was always greater than the given value, FindLE returns an error value.
Usage Note
FindLE interpolates between Archive events, if necessary, to find the value it is looking for.
Examples
FindLE('tag1', 't', '*',40.0)
FindLE('tag1', -3600, '*',40.0)
FindLE('tag1', 'Saturday', '*',40.0)
PI Server Applications User Guide Page 103
Chapter 4 - PI Performance Equations Syntax and Functions Reference
FindLT
Find the first time, within a range, when a point is less than a given value.
Format
FindLT(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search; time expression or time relative to endtime if endtime
is a time.
endtime
End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was less than
the given value.
Exceptions
If the point was never less than the given value, FindLT returns an error value.
Usage Note
FindLT interpolates between Archive events, if necessary, to find the value it is looking for.
Examples
FindLT('tag1', 't', 3600,40.0)
FindLT('tag1', -1h, '*',40.0)
FindLT('tag1', '14-Dec-97 01:00:00.0001, '*',40.0)
Page 104
4.4 - Performance Equations Functions Reference
FindNE
Find the first time, within a range, when a point is unequal to a given value.
Format
FindNE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search; time expression or time relative to endtime if endtime
is a timestamp.
endtime
End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value
Must be an integer or real number or digital state (character string), the value to search for.
Returns
The timestamp closest to starttime, within the given range, for which the point was unequal to
the given value.
Exceptions
If the point was always equal to the given value, FindNE returns an error value.
Examples
FindNE('tag1', 'y', '*',40.0)
FindNE('tag1', '14-Dec-97', '*',40.0)
FindNE('tag1', '14-Dec-97', 'Monday',40.0)
PI Server Applications User Guide Page 105
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Float
Convert a string to a number.
Format
Float(x)
Arguments
x
A string or number.
Returns
A number for a numeric string and Calc Failed for a non-numeric string. If x is already a
number, x is returned.
Examples
Float(12.3) = 12.3
Float('sinusoid')
Float("-12.3") = -12.3
Page 106
4.4 - Performance Equations Functions Reference
Format
Convert a number to string according to a format expression.
Format
Format(num, format [,num_type ])
Arguments
num
A number (real or integer).
format
Format-control string. This is the same as that used by the C language function Sprintf.
num_type (optional)
Number-type character. This must be either R(eal) or I(nteger). The default is R.
Returns
A formatted string.
Examples
Format('sinusoid', "%3.3f", "R") = "66.890"
Format(45, "%3.3d") = "045"
Format(45, "%3.3d", "I") = "045"
Format(45, "%3.3d", "R") = "000" (Don't do this!)
PI Server Applications User Guide Page 107
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Frac
Returns the fractional part of a real number. Returns 0 for integers.
Format
Frac(x)
Arguments
x
Must be an integer or real number.
Returns
The fractional part of x.
Exceptions
If x is not an integer or real number, returns an error value.
Usage Note
By definition: Int(x) + Frac(x) = x.
Examples
Frac('tag1')
Frac(1.1)
Frac(TagVal('tag1', '14-Dec97'))
Page 108
4.4 - Performance Equations Functions Reference
Hour
Extract the hour from a time expression.
Format
Hour(time)
Arguments
time
A time expression.
Returns
The hour of time, in the range 0–23.
Exceptions
None.
Examples
Hour('*')
Hour('Saturday')
Hour('t')
See Also
Day, DaySec, Minute, Month, Second, Weekday, Year, Yearday
PI Server Applications User Guide Page 109
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Impulse
Dynamic response specified by the impulse response.
Format
Impulse(tagname, runflag, i1,i2 … )
Arguments
tagname
Must be a tagname for a numerical point.
runflag
Non-zero enables filter to run.
i1, i2, …
Unit impulse response specifying dynamic model, text sequence of numbers.
Returns
Dynamic model output as function of time.
u(t)=i1*u(t-1) + i2*u(t-2) + …
Where u(t) is the current output and u(t-1) is the output one sample interval in the past.
Exceptions
Impulse gives different results depending on which type of scheduling is used. In clock
scheduling, the interval between time series values depends on the scan class and gives values
at evenly spaced time intervals.
On the other hand, event-based scheduling is dependent on a trigger from another point. If the
exception deviation is not zero, the intervals for events are not evenly spaced in time—hence
Impulse gives results that are not trustworthy. Impulse is not supported in the pipetest utility
or in PI DataLink. If the input point is not a real number or integer, Impulse returns an error.
Examples
Impulse('tag1',1,1,1,1)
Page 110
4.4 - Performance Equations Functions Reference
InStr
Determine the location within a string where a sub-string match is first found.
Format
InStr([start,] str1, str2 [,casesen])
Arguments
start (optional)
An integer specifying which character in str1 to start the comparison. Must be larger than or
equal to 0.
str1, str2
Two strings and/or points with string pointtypes to be compared.
casesen (optional)
Flag indicating if the comparison is case sensitive.
casesen = 0 the comparison is case insensitive (default)
casesen = 1 the comparison is case sensitive
Returns
0 if str2 is not a sub-string of str1 starting from the start position; otherwise, the location of
character where str2 first matches the characters in str1 from the start position.
Exceptions
Wild characters are not treated as wild.
Examples
InStr("What", "At") = 3
InStr("What What What", "What") = 1
InStr("what", "At", 1) = 0
InStr(4,"what","At") = 0
InStr('StringTag', "Error") = 1 (if the tag value for 'stringtag' is
"Error")
InStr('StringTag',"StringTag") = 0 (if the tag value for 'stringtag' is
"Error")
PI Server Applications User Guide Page 111
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Int
Return the integer part of an integer or real number.
Format
Int(x)
Arguments
x
A number or string.
Returns
The integer part of x. If x is a string, it is first converted into a number.
Exceptions
If x is not a number or a numeric string, returns Calc Failed.
Examples
Int('tag1')
Int(1)
Int(2.1)
Int("2.1")
Page 112
4.4 - Performance Equations Functions Reference
IsDST
Determine if a time expression is in a daylight saving time (DST) period on the local
machine.
Format
IsDST(time)
Arguments
time
A time expression.
Returns
1 if the time is in a DST period and 0 otherwise.
Exceptions
If the argument is not a time value, an error condition is returned.
Examples
IsDST('*')
IsDST('*-182.5d')
IsDST('t')
IsDST('timestringtag')
PI Server Applications User Guide Page 113
Chapter 4 - PI Performance Equations Syntax and Functions Reference
IsSet
Determine if a PI value is annotated, substituted, or questionable.
Format
IsSet(pivalue, select)
Arguments
pivalue
Any PI value. May be an integer, real number, digital state, or character string.
select
A string but only the first character is considered. "a" for annotated; "s" for substituted; and
"q" for questionable. It is case-insensitive.
Returns
1 if true and 0 otherwise.
Exceptions
None.
Examples
IsSet('sinusoid', "a")
IsSet('sinusoid', "annotated")
IsSet('sinusoid', "annotatted is mispelled")
IsSet('stringtag',"annotatiiion is mispelled but it does not matter.")
IsSet('stringtag',"A")
IsSet('alarmtag1',"q")
IsSet('stringtag',"s")
Page 114
4.4 - Performance Equations Functions Reference
LCase
Convert a string to a lowercase string.
Format
LCase(strexp)
Arguments
strexp
Must be a string.
Returns
A string that has been converted to lowercase.
Exceptions
If the argument is not a string, returns an error value.
Examples
LCase("Stringtag") = "stringtag"
LCase('Stringtag') = "error" if the Snapshot value for the stringtag
equals "Error"
See Also
UCase
PI Server Applications User Guide Page 115
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Left
Determine a specified number of characters of a string from the left.
Format
Left(str, len)
Arguments
str
A string.
len
An integer.
Returns
len characters of the string from the left.
Exceptions
If the arguments are not of the required types, returns an error.
Examples
Left("Stringtag", 3) = "Str"
Left('Stringtag', 3) = "Err" if the Snapshot value for the stringtag
equals "Error"
See Also
Mid, Right
Page 116
4.4 - Performance Equations Functions Reference
Len
Determine the length of a string.
Format
Len(str)
Arguments
str
A string.
Returns
The length of a string.
Exceptions
If the argument is not a string, returns an error value.
Examples
Len("Stringtag") = 9
Len('Stringtag') = 5 if the Snapshot value for the stringtag equals
"Error"
PI Server Applications User Guide Page 117
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Log
Return the natural (base-e = 2.7182818...) logarithm of an integer or real number.
Format
Log(x)
Arguments
x
Must be an integer or real number greater than zero.
Returns
The natural logarithm of x.
Exceptions
If x is zero or negative, or not a number, returns an error value.
Examples
Log('*')
Log(14)
Log(TagVal('tag1', '14-Dec-97'))
See Also
Log10
Page 118
4.4 - Performance Equations Functions Reference
Log10
Return the common (base-10) logarithm of an integer or real number.
Format
Log10(x)
Arguments
x
Must be an integer or real number greater than zero.
Returns
The common logarithm of x.
Exceptions
If x is zero or negative, or not a number, returns an error value.
Examples
Log10('*')
Log10(14)
Log10(TagVal('tag1', '14-Dec-97'))
See Also
Log
PI Server Applications User Guide Page 119
Chapter 4 - PI Performance Equations Syntax and Functions Reference
LTrim
Remove the leading blanks from a string.
Format
LTrim(str)
Arguments
str
A string.
Returns
A string with leading blanks removed.
Exceptions
If str is not a string, an error value is returned.
Examples
LTrim(" Stringtag") = "Stringtag"
LTrim("Stringtag ") = "Stringtag "
LTrim('Stringtag') = "Error" if the Snapshot value for the stringtag
equals " Error"
See Also
RTrim, Trim
Page 120
4.4 - Performance Equations Functions Reference
Max
Return the maximum of arguments.
Format
Max(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers, times, or time periods, but all must be the same.
Returns
The maximum of the arguments. The result has the same data type as the arguments.
Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
Max returns an error value.
Examples
Max('*', 'y', 'Saturday')
Max(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Max('*'-'*-h', 't'-'y', TimeEq('tag1', 'y', 't',50))
See Also
Min
PI Server Applications User Guide Page 121
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Median
Return the median (middle) value of three or more arguments.
Format
Median(x1, x2, ..., xn)
Arguments
x1...xn
May be only integers, real numbers, times, or time periods, but all arguments must be the
same data type.
Returns
The median value of the input arguments. If the number of arguments is even, the average of
the two middle values is returned.
Exceptions
Arguments whose run-time values are digital states are ignored. The function must have
greater than two arguments that evaluate to non-digital states; otherwise, Median returns an
error value.
Usage Note
Median allows for mixed integer and real data types. Median follows the data type of the first
argument. Hence if the first argument is a point that evaluates to an integer then all the other
entries will be converted to integers by truncation (not by rounding).
Examples
Median('*', 'y', 'Saturday')
Median(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Median('*'-'*-1h', 't'-'y', TimeEq('tag1', 'y', 't',50))
Page 122
4.4 - Performance Equations Functions Reference
MedianFilt
Return the median value of the last specified number of values of a time series.
Format
MedianFilt( tagname, runflag, number )
Arguments
tagname
Must be a numerical point.
runflag
Non-zero enables filter to run.
number
The number of series elements to be considered. A numeric constant greater than or equal to
3.
Returns
The median value of the last number values in the series of values.
Exceptions
Arguments whose run-time values are digital states are ignored. MedianFilt is not supported
in the pipetest utility or in PI DataLink. If all values are digital states, MedianFilt returns an
error value.
Examples
MedianFilt('tag1',1,3)
PI Server Applications User Guide Page 123
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Mid
Return a sub-string within a string.
Format
Mid(str, start [,len])
Arguments
str
A string.
start
An integer specifying the position of the first character within the string. The first character in
the string is number 1.
len (optional)
The maximum length of the returned string. The default is the length of the string.
Returns
len characters of the string to the left of (and including) the first character whose position is
specified by start.
Exceptions
If the arguments are not of the required types, an error value is returned. The maximum
number of characters that can be returned is 999.
Examples
Mid("Stringtag", 3) = "ringtag"
Mid("Stringtag", 3, 2) = "ri"
Mid('Stringtag', 1, 1) = "E" if the Snapshot value for the stringtag
equals "Error"
See Also
Left, Right
Page 124
4.4 - Performance Equations Functions Reference
Min
Return the minimum of arguments.
Format
Min(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers, times, or time periods, but all must be the same data type.
Returns
The minimum of the arguments. The result has the same data type as the arguments.
Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
Min returns an error value.
Examples
Min('*', 'y', 'Saturday')
Min(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Min('*'-'*-1h', 't'-'y', TimeEq('tag1', 'y', 't',50))
See Also
Max
PI Server Applications User Guide Page 125
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Minute
Extract the minute from a time expression.
Format
Minute(time)
Arguments
time
A time expression.
Returns
The minute of time, in the range 0–59.
Exceptions
None.
Examples
Minute('*')
Minute('1')
Minute('*-1h')
See Also
Day, DaySec, Hour, Month, Second, Weekday, Year, Yearday
Page 126
4.4 - Performance Equations Functions Reference
Month
Extract the month from a time expression.
Format
Month(time)
Arguments
time
A time expression.
Returns
The month of time, in the range 1–12.
Exceptions
None.
Examples
Month('*')
Month('1')
Month('*-1h')
See Also
Day, DaySec, Hour, Minute, Second, Weekday, Year, Yearday
PI Server Applications User Guide Page 127
Chapter 4 - PI Performance Equations Syntax and Functions Reference
NextEvent
Find the time of a point's next Archive event after a given time.
Format
NextEvent(tagname, time)
Arguments
tagname
A tagname.
time
A time expression.
Returns
The timestamp of the next Archive event for tagname after time.
Exceptions
If point has no Archive data after time, returns an error value.
Examples
NextEvent('tag1','*')
NextEvent('digitaltag', '*')
See Also
NextVal, PrevEvent, PrevVal, TagVal
Page 128
4.4 - Performance Equations Functions Reference
NextVal
Find the value of a point's next Archive event after a given time.
Format
NextVal(tagname, time)
Arguments
tagname
A tagname.
time
A time expression.
Returns
The value of the next Archive event for tagname after time.
Exceptions
If point has no Archive data after time, returns an error value.
Examples
NextVal('tag1','*-1h')
NextVal('digitaltag', '14-Dec-97')
See Also
NextEvent, PrevEvent, PrevVal, TagVal
PI Server Applications User Guide Page 129
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Noon
A timestamp for noon on the day of a given time expression.
Format
Noon(time)
Arguments
time
A time expression.
Returns
A timestamp corresponding to noon of the day of the input time.
Exceptions
None.
Usage Note
This function is useful for establishing a unique clock time independent of the length of
particular days.
Examples
Noon('*')
Noon('14-Dec-97')
See Also
Bod, Bom, Bonm
Page 130
4.4 - Performance Equations Functions Reference
NoOutput
Do not send the current calculation result to PI.
Format
NoOutput()
Arguments
None
Usage Note
It is important to include the parentheses after this function (use NoOutput() instead of
NoOutput as NoOutput is an invalid syntax). This function applies only to the current
calculation. The output of this function in pipetest.exe is "NoOutput() Called".
Example
If 'PITag' < 100 or 'PItag' > 0 then 'PITag' else NoOutput()
PI Server Applications User Guide Page 131
Chapter 4 - PI Performance Equations Syntax and Functions Reference
ParseTime
Translate a PI time expression to a timestamp.
Format
ParseTime(s)
Arguments
s
Must be a character string in PI time format.
Returns
The timestamp corresponding to s.
Exceptions
If s is not a character string, or if there is a syntax error, returns an error value.
Usage Note
There is no difference between ParseTime("14-Nov-92") and the time expression '14-Nov-
92', except that the ParseTime call definitely takes more time. This is because the time
expression (enclosed in single quotes) is evaluated at compile time, not run time.
If you write ParseTime('14-Nov-92') (using single quotes, not double quotes) the parser will
detect an error, because the expression in single quotes is already translated to a timestamp at
compile time.
The expression ParseTime(":12:00:00") is not the same as the time expression ':12:00:00'.
The ParseTime expression is evaluated at runtime and translated using '*' as the relative time
base, while the time expression is evaluated at compile time and uses the time the expression
is parsed as the relative time base.
Examples
ParseTime("14-Dec-97")
ParseTime("t")
Page 132
4.4 - Performance Equations Functions Reference
PctGood
Find the time percentage, over a given range, when a point's archived values are good.
Format
PctGood(tagname, starttime, endtime)
Arguments
tagname
A tagname.
starttime
Must be a time expression, the beginning of the time range to search.
endtime
Must be a time expression, greater than starttime; the end of the time range to search.
Returns
An integer or real number from 0.0 to 100.0: the percentage of the given time when the point
had good values.
Examples
PctGood('tag1', 'y','*')
PctGood('tag1', '-1h', '*')
PI Server Applications User Guide Page 133
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Poly
Evaluate the polynomial c0 + c1x + c2x2 + … +cnxn.
Format
Poly(x, c0, ..., cn)
Arguments
x
The variable. It must be an integer or real number.
c0...cn
The coefficients. There must be at least one coefficient. All must be numbers.
Returns
The value of the polynomial.
Exceptions
If x or any coefficient is not an integer or real number, Poly returns an error value.
Examples
Poly('tag1',1,1)
Page 134
4.4 - Performance Equations Functions Reference
PrevEvent
Find the time of a point's previous Archive event before a given time.
Format
PrevEvent(tagname, time)
Arguments
tagname
A tagname.
time
A time expression.
Returns
The timestamp of the previous Archive event for tagname before time.
Exceptions
If point has no Archive data before time, returns an error value.
Examples
PrevEvent('tag1', '*')
PrevEvent('tag1','14-Dec-97')
See Also
NextEvent, NextVal, PrevVal, TagVal
PI Server Applications User Guide Page 135
Chapter 4 - PI Performance Equations Syntax and Functions Reference
PrevVal
Find the value of a point's previous Archive event before a given time.
Format
PrevVal(tagname, time)
Arguments
tagname
A tagname.
time
A time expression.
Returns
The value of the previous Archive event for tagname before time.
Exceptions
If point has no Archive data before time, returns an error value.
Examples
PrevVal('tag1', '*')
PrevVal('tag1','14-Dec-97')
See Also
NextEvent, NextVal, PrevEvent, TagVal
Page 136
4.4 - Performance Equations Functions Reference
PStDev
Return the standard deviation of two or more arguments, where those arguments represent the
whole population. The standard deviation of a population x1...xn is
where µ is the mean of the arguments, i.e.,
∑x i
Format
PStDev(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers or time expressions, but all must be the same.
Returns
The standard deviation of the arguments. If the arguments are numbers, the result is a
number; if the arguments are times or time periods, the result is a time period.
Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
PStDev returns an error value.
Usage Note
In most cases you should use Sstdev instead of PstDev. Sstdev calculates the standard
deviation of a sample.
Examples
PStDev('tag1', 'tag2')
PStDev('*','14-Dec-97', 'y')
PStDev('*'-'y','14-Dec-97'-'*', '-1h')
See Also
SStDev
PI Server Applications User Guide Page 137
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Range
Find the difference between a point's maximum and minimum values during a given time,
according to values stored in the PI Archive.
Format
Range(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point should represent a continuous variable.
starttime
Must be a time expression, the beginning of the time range to search.
endtime
Must be a time expression, greater than starttime; the end of the time range to search.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must
good.
Returns
The difference between the point's maximum and minimum values during the given time.
Exceptions
If the point has no good values or the pctgood minimum is not reached in the given time
range, returns an error value.
Caution
The OverRangeStat and UnderRangeStat digital states are not taken into account when
calculating this value.
Examples
Range('tag1', 'y', '*')
Range('tag1','-1h', 'y')
Range('tag1','y', '+1h',70)
Page 138
4.4 - Performance Equations Functions Reference
Right
Determine a specified number of characters of a string from the right.
Format
Right(str, len)
Arguments
str
A string.
len
An integer.
Returns
len characters of the string from the right.
Exceptions
If the arguments are not of the required types, an error value is returned.
Examples
Right("Stringtag", 3) = "tag"
Right('Stringtag', 4) = "rror" if the Snapshot value for the stringtag
equals "Error"
Right("Stringtag", 20) = "Stringtag"
See Also
Left, Mid
PI Server Applications User Guide Page 139
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Round
Round a number or time to the nearest unit.
Format
Round(x [, unit])
Arguments
x
Must be an integer or real number or time expression.
unit (optional)
The size of the unit to round to. If x is a number, unit must be a number. If x is a time
expression or time period, unit must be a time period. If unit is omitted, Round rounds to the
nearest integer (for a number) or second (for a time period).
Returns
The nearest value to x which is an integer multiple of unit. Returns the same data type as x.
For more information, see the examples below.
Exceptions
If x is a string, or if unit is of the wrong data type, returns an error value.
Examples
Expression Value Comments
Round(12.499) 12.0 Round to nearest integer
Round(12.500) 13.0 Half a unit rounds up
Round(12.8, 10) 10.0 Round to nearest ten
Round('14-Dec-97 11:47, '+1h') 14-Dec-97 12:00 Round to nearest hour (returns timestamp)
Round('18:47' –'15:00','+1h') 10800 Round period to nearest hour (returns
period in seconds)
Note: Round to the nearest day results in a timestamp of the closest day in UTC time and not
local time.
Usage Note
If x is time and unit is omitted this routine has no effect: times are accurate only to 1 second.
See Also
Trunc
Page 140
4.4 - Performance Equations Functions Reference
RTrim
Trim trailing blanks from a string.
Format
RTrim(str)
Arguments
str
A string.
Returns
The source string with trailing blanks removed.
Exceptions
If str is not a string, an error value is returned.
Examples
RTrim("Stringtag ") = "Stringtag" "
RTrim(" Stringtag") = " Stringtag"
RTrim('Stringtag') = "Error" if the Snapshot value for the stringtag
equals "Error "
See Also
LTrim, Trim
PI Server Applications User Guide Page 141
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Second
Extract the second from a time expression.
Format
Second(time)
Arguments
time
A time expression.
Returns
The second of time, in the range 0–59.
Exceptions
None.
Examples
Second('*')
Second('y')
Second('*-1h')
See Also
Day, DaySec, Hour, Minute, Month, Weekday, Year, Yearday
Page 142
4.4 - Performance Equations Functions Reference
Sgn
Return a representation of the numerical sign of a number.
Format
Sgn(x)
Arguments
x
Must be an integer or real number.
Returns
-1 if x < 0.
0 if x = 0.
1 if x > 0.
Exceptions
If x is not an integer or real number, returns an error value.
Examples
Sgn('tag1')
Sgn(1)
Sgn(0)
PI Server Applications User Guide Page 143
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Sin
Return the trigonometric sine of a number.
Format
Sin(x)
Arguments
x
Must be an integer or real number, which represents an angle in radians.
Returns
The sine of x.
Exceptions
If x is not a number, returns an error value.
Examples
Sin('tag1')
Sin(1)
Sin(1.1)
See Also
Acos, Asin, Atn, Atn2, Cos, Cosh, Sinh, Tan, Tanh
Page 144
4.4 - Performance Equations Functions Reference
Sinh
Return the hyperbolic sine of a number.
Format
Sinh(x)
Arguments
x
Must be an integer or real number.
Returns
The hyperbolic sine of x.
Exceptions
If x is not a number, returns an error value.
Examples
Sinh('tag1')
Sinh(1)
Sinh(0.9)
See Also
Acos, Asin, Atn, Atn2, Cos, Cosh, Sin, Tan, Tanh
PI Server Applications User Guide Page 145
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Sqr
Return the square root of a number.
Format
Sqr(x)
Arguments
x
Must be an integer or real number greater than or equal to zero.
Returns
The square root of x.
Exceptions
If x is negative, or is not a number, returns an error value.
Examples
Sqr('tag1')
Sqr(2)
Sqr(2.1)
Page 146
4.4 - Performance Equations Functions Reference
SStDev
Return the standard deviation of two or more arguments, where those arguments represent a
sample of a larger population. The standard deviation of a sample x1...xn is equal to
∑ (x − µ)
2
i
n −1
Where µ is the sample mean, i.e.,
∑x i
Format
SStDev(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers or time expressions, but all must be the same.
Returns
The sample standard deviation of the arguments. If the arguments are numbers, the result is a
number; if they are times or time periods, the result is a time period (number of seconds).
Exceptions
Arguments whose run-time values are digital states are ignored. If there are not at least two
numeric values, SStDev returns a zero.
Usage Note
In the rare case where you have the entire population, rather than a sample, you might use the
function PstDev, rather than SStDev.
Examples
SStDev('tag1', 'tag2', TagVal('tag1', 'y'))
SStDev('y', 't', '14-Dec-97')
SStDev(1, 2, 1.1)
See Also
PStDev
PI Server Applications User Guide Page 147
Chapter 4 - PI Performance Equations Syntax and Functions Reference
StateNo
Translate a digital state into its corresponding state number.
Format
StateNo(digstate)
Arguments
digstate
A digital state value.
Returns
The offset into the Digital State Set corresponding to digstate.
Exceptions
If a point is passed as digstate that is not a digital point, returns an error value.
Usage Note
A digital state may appear more than once in the digital state Table. In this case, the value
that StateNo returns may vary. If digstate is the value of a digital point, StateNo returns a
code number appropriate for that point.
Examples
StateNo('digitaltag')
StateNo(TagVal('digitaltag', '*-1h'))
Page 148
4.4 - Performance Equations Functions Reference
StDev
Find the time-weighted standard deviation of a point over a given time, according to values
stored in the PI Archive.
Format
StDev(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point must represent a continuous variable.
starttime
Must be a time expression representing the beginning of the time range to search.
endtime
Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must be
good.
Returns
The point's time-weighted standard deviation over the given time.
Exceptions
If the point has no good values or the PctGood minimum is not reached for the given time
range, returns an error value.
Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood function to find out what percentage of the values is good.
Examples
StDev('tag1', 'y', '*')
StDev('tag1', '14-Dec-97', '+1d',85)
StDev('tag1', '14-Dec-97', '15-Dec-97')
See Also
PctGood
PI Server Applications User Guide Page 149
Chapter 4 - PI Performance Equations Syntax and Functions Reference
String
Convert any value to a string.
Format
String(anyvalue)
Arguments
anyvalue
Any expression. It may be of any of the normal PI System data types.
Returns
The string representing the value argument.
Exceptions
None.
Examples
String(12.23) = "12.23"
String('sinusoid')
String('pidigital')
String('*')
String("Hello, PI user!") = "Hello, PI user! "
Page 150
4.4 - Performance Equations Functions Reference
TagAvg
Find the time-weighted average value of a point over a given time, according to values stored
in the PI Archive.
Format
TagAvg(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point must represent a continuous variable.
starttime
Must be a time expression representing the beginning of the time range to search.
endtime
Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must be
good.
Returns
The point's time-weighted average value over the given time.
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.
Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood function to find out what percentage of the values are good.
Examples
TagAvg('tag1', 'y', '*')
TagAvg('tag1', '14-Dec-97', '+1d',70)
TagAvg('tag1', '14-Dec-97', '15-Dec-97')
See Also
PctGood
PI Server Applications User Guide Page 151
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagBad
Test if a point has an abnormal state at a given time. If the point's type is R or I, any digital
state is abnormal. If the point is type D, the states that are defined for that point are normal;
all others are abnormal.
Format
Tagbad(tagname [, time])
Arguments
tagname
A tagname.
time (optional)
A time expression. If omitted, the current time ('*') is used.
Returns
0 if the point's state at time is normal, 1 if it is abnormal.
Exceptions
If point does not exist, or has no archived value at time, returns an error value.
Usage Note
Badval can test any value or expression; TagBad can only test a point.
Examples
TagBad('tag1', '*')
TagBad('digitaltag', '14-Dec-97')
TagBad('tag1', 'y')
See Also
Badval
Page 152
4.4 - Performance Equations Functions Reference
TagDesc
Get a point's descriptor from the Point Database.
Format
TagDesc(tagname)
Arguments
tagname
A tagname.
Returns
The point's descriptor.
Exceptions
If point does not exist, returns an error value.
Examples
TagDesc('tag1')
TagDesc('digitaltag')
PI Server Applications User Guide Page 153
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagEU
Get a point's engineering unit string from the Point Database.
Format
TagEU(tagname)
Arguments
tagname
A tagname.
Returns
The point's engineering units.
Exceptions
If point does not exist, returns an error value.
Examples
TagEU('tag1')
Page 154
4.4 - Performance Equations Functions Reference
TagExDesc
Get a point's extended descriptor from the Point Database.
Format
TagExDesc(tagname)
Arguments
tagname
A tagname.
Returns
The point's extended descriptor.
Exceptions
If point does not exist, returns an error value.
Examples
TagExDesc('tag1')
PI Server Applications User Guide Page 155
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagMax
Find the maximum value of a point during a given time, according to values stored in the PI
Archive.
Format
TagMax(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname.
starttime
A time expression indicating the beginning of the time range to search. Relative times are
relative to endtime, if endtime is not itself a relative time. For example:
TagMax('tag1', '-1h', '*',95)
Here, the starttime is one hour before the endtime, which is now ('*').
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must be
good.
Returns
The point's maximum value during the given time.
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.
Caution
The OverRange digital state is not taken into account when calculating this value.
Examples
TagMax('tag1', 'y', '*')
TagMax('tag1', '-1h', '*',95)
TagMax('tag1', '14-Dec-97', '+1h')
Page 156
4.4 - Performance Equations Functions Reference
TagMean
Find the average value of a point over a given time, according to values stored in the PI
Archive.
Format
TagMean(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point must represent a continuous variable.
starttime
Must be a time expression representing the beginning of the time range to search.
endtime
Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must
good.
Returns
The point's average value over the given time. Notice that the average is not time-weighted.
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value. Unlike some other summary functions, TagMean does not
interpolate any value on the boundary. Thus, if there is no Archive event between the
specified interval, an error value is returned.
Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood function to find out what percentage of the values is good.
Examples
TagMean('tag1', 'y', '*')
TagMean('tag1', '14-Dec-97', '+1d',70)
TagMean('tag1', '14-Dec-97', '15-Dec-97')
See Also
PctGood
PI Server Applications User Guide Page 157
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagMin
Find the minimum value of a point during a given time, according to values stored in the PI
Archive.
Format
TagMin(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point should represent a continuous variable.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
Relative times are relative to starttime, if starttime is not itself a relative time. This time must
be after starttime.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must
good.
Returns
The point's minimum value during the given time.
Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.
Caution
The UnderRange digital state is not taken into account when calculating this value.
Examples
TagMin('tag1', 'y', '*')
TagMin('tag1', '-1h', '*',90)
TagMin('tag1', '14-Dec-97', '+1h')
Page 158
4.4 - Performance Equations Functions Reference
TagName
Get a point's name from the Point Database.
Format
TagName(tag)
Arguments
tagname
A tagname.
Returns
The point's name.
Exceptions
If point does not exist, returns an error value.
Examples
TagName('tag1')
PI Server Applications User Guide Page 159
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagNum
Get a point's number from the Point Database.
Format
TagNum(string)
Arguments
string
A tagname in double quotes.
Returns
The point's number.
Exceptions
If point does not exist, returns an error value.
Examples
TagNum("tag1")
Page 160
4.4 - Performance Equations Functions Reference
TagSource
Get a point's point source character from the Point Database.
Format
TagSource(tagname)
Arguments
tagname
A tagname.
Returns
The point's point source character.
Exceptions
If point does not exist, returns an error value.
Examples
TagSource('tag1')
PI Server Applications User Guide Page 161
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagSpan
Get a point's span from the Point Database.
Format
TagSpan(tagname)
Arguments
tagname
A tagname.
Returns
The point's span. If the point's type is Digital this is an integer whose value is the number of
digital states defined for the point.
Examples
TagSpan('tag1')
TagSpan('digitaltag')
Page 162
4.4 - Performance Equations Functions Reference
TagTot
Find the totalized value (time integral) of a point over a given time, according to values
stored in the PI Archive.
Format
TagTot(tagname, starttime, endtime [, pctgood])
Arguments
tagname
A tagname. This point must represent a continuous process flow.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time.
pctgood (optional)
Minimum time percentage over the given time range, that the point's archived values must be
good.
Returns
The point's totalized value over the given time.
Exceptions
If the point has no good values or the PctGood minimum is not reached for the given time
range, returns an error value.
Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood function to find out what percentage of the value is good.
Usage Note
The system chooses a scale factor such that the integral will be correct only if the flow is
expressed in units per day. If the flow is expressed in units per hour, or per some other time
unit, you must multiply this result by a conversion factor. The conversion factor equals the
number of actual flow time units in a day.
For instance, if you totalize a point measured in gallons per minute, you must multiply the
result of TagTot by 1440 to get the answer in gallons. This conversion factor is not related to
the time period you are totalizing over; it is strictly a function of the point's engineering units.
PI Server Applications User Guide Page 163
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Some PI sites have the default total period configured to be per-hour rather than per-day. If
you are at one of these sites, your conversion factor will differ.
Examples
TagTot('tag1', 'y', '*')
TagTot('tag1', '-1h', '*',85)
TagTot('tag1', '14-Dec-97', '+1h')
See Also
PctGood
Page 164
4.4 - Performance Equations Functions Reference
TagType
Get a point's type character (I, R, or D) from the Point Database.
Format
TagType(tagname)
Arguments
tagname
A tagname.
Returns
The point's type character.
Exceptions
If point does not exist, returns an error value.
Examples
TagType('tag1')
TagType('digitaltag')
PI Server Applications User Guide Page 165
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagTypVal
Get a point's typical value from the Point Database.
Format
TagTypVal(tagname)
Arguments
tagname
A tagname.
Returns
The point's typical value. If the point's type is R or I, this is a number; if the point's type is D,
this is a digital state (character string).
Exceptions
If point does not exist, returns an error value.
Examples
TagTypVal('tag1')
TagTypVal('digitaltag')
Page 166
4.4 - Performance Equations Functions Reference
TagVal
Find a point's Archive value at a given time.
Format
TagVal(tagname [, time])
Arguments
tagname
A tagname.
time (optional)
A time expression. If you omit this argument, '*' is used.
Returns
The archived value of tagname at time. This value is interpolated unless the point has
resolution code 4.
Exceptions
If point does not exist, or has no archived value at time, returns an error value.
Examples
TagVal('tag1')
TagVal('digitaltag')
TagVal('tag1','*')
See Also
NextEvent, NextVal, PrevEvent, PrevVal
PI Server Applications User Guide Page 167
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TagZero
Get a point's zero value from the Point Database.
Format
TagZero(tagname)
Arguments
tagname
A tagname.
Returns
The point's zero value. If the point's type is R or I, this is a number; if the point's type is D,
this is a digital state (character string).
Exceptions
If point does not exist, returns an error value.
Examples
TagZero('tag1')
TagZero('digitaltag')
Page 168
4.4 - Performance Equations Functions Reference
Tan
Return the trigonometric tangent of a number.
Format
Tan(x)
Arguments
x
Must be an integer or real number, which represents an angle in radians.
Returns
The tangent of x.
Exceptions
If x is not a number, returns an error value.
Examples
Tan('tag1')
Tan(1)
Tan(1.1)
See Also
Acos, Asin, Atn, Atn2, Cos, Cosh, Sin, Sinh, Tanh
PI Server Applications User Guide Page 169
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Tanh
Return the hyperbolic tangent of a number.
Format
Tanh(x)
Arguments
x
Must be an integer or real number.
Returns
The hyperbolic tangent of x.
Exceptions
If x is not a number, returns an error value.
Examples
Tanh('tag1')
Tanh(1)
Tanh(1.1)
See Also
Acos, Asin, Atn, Atn2, Cos, Cosh, Sin, Sinh, Tan
Page 170
4.4 - Performance Equations Functions Reference
Text
Concatenate strings representing argument values.
Format
Text(val1 [, val2, … ])
Arguments
val1, val2, …
Any expression. These may be of any of the normal PI System data types.
Returns
A string that is the concatenation of strings representing the argument values.
Examples
Text('sinusoid')
Text("The value for tag sinusoid is at ", '*', " is ", 'sinusoid') =
"The value for tag sinusoid at 1-Jun-00 17:07:18 is 89.09"
See Also
Concat
PI Server Applications User Guide Page 171
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TimeEq
Find the total time, within a range, when a point is equal to a given value.
Format
TimeEq(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was exactly equal to the given
value.
Exceptions
None.
Examples
TimeEq('tag1', 't', '*',40.0)
TimeEq('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeEq('digitaltag', '14-Dec-97', '*', "On")
See Also
TimeGE, TimeGT, TimeLE, TimeLT, TimeNE
Page 172
4.4 - Performance Equations Functions Reference
TimeGE
Find the total time, within a range, when a point is greater than or equal to a given value.
Format
TimeGE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was greater than or equal to the
given value.
Exceptions
None.
Usage Note
TimeGE interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.
Examples
TimeGE('tag1', 't', '*',40.0)
TimeGE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeGE('digitaltag', '14-Dec-97', '*', "On")
See Also
TimeEq, TimeGT, TimeLE, TimeLT, TimeNE
PI Server Applications User Guide Page 173
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TimeGT
Find the total time, within a range, when a point is greater than a given value.
Format
TimeGT(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was greater than the given value.
Exceptions
None.
Usage Note
TimeGT interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.
Examples
TimeGT('tag1', 't', '*',40.0)
TimeGT('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeGT('digitaltag', '14-Dec-97', '*', "On")
See Also
TimeEq, TimeGE, TimeLE, TimeLT, TimeNE
Page 174
4.4 - Performance Equations Functions Reference
TimeLE
Find the total time, within a range, when a point is less than or equal to a given value.
Format
TimeLE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was less than or equal to the
given value.
Exceptions
None.
Usage Note
TimeLE interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.
Examples
TimeLE('tag1', 't', '*',40.0)
TimeLE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeLE('digitaltag', '14-Dec-97', '*', "On")
See Also
TimeEq, TimeGE, TimeGT, TimeLT, TimeNE
PI Server Applications User Guide Page 175
Chapter 4 - PI Performance Equations Syntax and Functions Reference
TimeLT
Find the total time, within a range, when a point is less than a given value.
Format
TimeLT(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was less than the given value.
Exceptions
None.
Usage Note
TimeLT interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.
Examples
TimeLT('tag1', 't', '*',40.0)
TimeLT('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeLT'digitaltag', '14-Dec-97', '*', "On")
See Also
TimeEq, TimeGE, TimeGT, TimeLE, TimeNE
Page 176
4.4 - Performance Equations Functions Reference
TimeNE
Find the total time, within a range, when a point is unequal to a given value.
Format
TimeNE(tagname, starttime, endtime, value)
Arguments
tagname
A tagname.
starttime
Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime
End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value
Must be an integer or real number or digital state (character string); the value to search for.
Returns
The time period within the given range, for which the point was unequal to the given value.
Exceptions
None.
Examples
TimeNE('tag1', 't', '*',40.0)
TimeNE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-97'))
TimeNE('digitaltag', '14-Dec-97', '*', "On")
See Also
TimeEq, TimeGE, TimeGT, TimeLE, TimeLT
PI Server Applications User Guide Page 177
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Total
Return the sum of two or more arguments.
Format
Total(x1, x2, ..., xn)
Arguments
x1...xn
May be numbers or time periods, but all must be the same.
Returns
The total of the arguments. The result has the same data type as the arguments.
Exceptions
Arguments whose run-time values are digital states are not included in the total. If all values
are digital states, Total returns an error value.
Examples
Total('tag1', 'tag2', TagVal('tag1', 'y'),40.0)
Total('t'-'y', '+1h')
Page 178
4.4 - Performance Equations Functions Reference
Trim
Trim blanks on both sides of a string.
Format
Trim(str)
Arguments
str
A string.
Returns
The source string with leading and trailing blanks removed.
Exceptions
If str is not a string, an error value is returned.
Examples
Trim(" Stringtag ") = "Stringtag"
Trim(" Stringtag is a string tag. ") = "Stringtag is a string tag."
See Also
LTrim, RTrim
PI Server Applications User Guide Page 179
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Trunc
Truncate a number or time to the next lower unit.
Format
Trunc(x [, unit])
Arguments
x
Must be an integer or real number, time expression, or time period.
unit (optional)
The size of the unit to truncate to. If x is a number, unit must be a number. If x is a time
expression or time period, unit must be a time period. If unit is omitted, Trunc truncates to
the next lower integer (for a number) or second (for a time period).
Returns
The largest value smaller than x which is an integer multiple of unit. Returns the same data
type as x. For more information, see the examples below.
Exceptions
If x is a string, or if unit is of the wrong data type, returns an error value.
Examples
Expression Value Comments
Trunc(12.999) 12.0 Truncate to next lower integer
Trunc(18.75, 10) 10.0 Truncate to next lower ten
Trunc('14-Dec-97 14-Dec-97 Truncate to next lower hour
11:47','+1h') 11:00
Trunc('18:47' – 10800 Truncate period to next lower hour
'15:00','+1h') (returns period in seconds)
Note: Trunc to the next lower day results in a timestamp of the next lower day in
UTC time, not local time.
Usage Note
If x is a time, and unit is omitted, this routine has no effect, as times are only accurate to one
second.
See Also
Round
Page 180
4.4 - Performance Equations Functions Reference
UCase
Convert a string to an uppercase string.
Format
UCase(strexp)
Arguments
strexp
Must be a string value.
Returns
An uppercase string.
Exceptions
If the argument is not a string, returns an error value.
Examples
UCase("Stringtag") = "STRINGTAG"
UCase('Stringtag') = "ERROR" if the Snapshot value for the stringtag
equals "Error"
See Also
LCase
PI Server Applications User Guide Page 181
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Weekday
Extract the day of the week from a timestamp.
Format
Weekday(time)
Arguments
time
A time expression.
Returns
The day of the week of time, in the range 1–7, where 1 represents Sunday.
Exceptions
None.
Examples
Weekday('*')
Weekday('t')
See Also
Day, DaySec, Hour, Minute, Month, Second, Year, Yearday
Page 182
4.4 - Performance Equations Functions Reference
Year
Extract the year from a time expression.
Format
Year(time)
Arguments
time
A time expression.
Returns
The year of time, in the range 1970–present.
Exceptions
None.
Examples
Year('*')
Year('t')
See Also
Day, DaySec, Hour, Minute, Month, Second, Weekday, Yearday
PI Server Applications User Guide Page 183
Chapter 4 - PI Performance Equations Syntax and Functions Reference
Yearday
Extract the day of the year from a time expression. The day of the year (also known as a
Julian day) is an integer ranging from 1 to 366, where 1 represents January 1.
Format
Yearday(time)
Arguments
time
A time expression.
Returns
The day of the year of time, in the range 1–366, where 1 represents January 1.
Exceptions
None.
Examples
Yearday('*')
Yearday('t')
See Also
Day, DaySec, Hour, Minute, Month, Second, Weekday, Year
Page 184
Chapter 5. PI STEAM FUNCTIONS REFERENCE
The PI Steam Functions module is an extension to the PI Performance Equations Scheduler.
Steam Functions provide a complete set of functions for deriving the thermodynamic
properties of steam and water within Performance Equations. PI Steam Functions support
both English and SI units, and are based on the ASME (American Society of Mechanical
Engineers) Steam Tables, 6th Ed.
This chapter provides a comprehensive reference for setting up Steam calculations, and
includes the following sections:
Section 5.1, Steam Functions Overview, on page 185
Section 5.2, Range of Steam Functions, on page 187
Section 5.3, Steam Property Reference States, on page 189
5.1 Steam Functions Overview
The PI PE Steam Functions Module (PI Steam) makes available functions that calculate the
thermodynamic properties of steam within Performance Equations. The steam functions are
also available in a COM library, PISteamFunctions.dll, which is distributed by other OSIsoft
products, such as ACE.
For each steam function, there are two function calls: one in English units and another in SI
units. The engineering units for the variables in the steam functions are listed in Table 5–1.
Table 5–2 lists the supported functions in PI Steam.
Table 5–1. Engineering Units
Variable English Unit SI Unit Conversion Factor (Eng to SI)
Temperature degree F degree C (T - 32) / 1.8
Pressure psia kpa 6.894757
Volume ft3/lbm cc/g 62.42796
Enthalpy BTU/lbm J/g 2.326
Entropy BTU/lbm/R J/g/K 4.1868
PI Server Applications User Guide Page 185
Chapter 5 - PI Steam Functions Reference
Table 5–2. Supported Functions
Name Function Description
StmEng_tsatp Saturation temperature as a function of pressure.
StmEng_hsatp Saturation enthalpy as a function of pressure.
StmEng_ssatp Saturation entropy as a function of pressure.
StmEng_vsatp Saturation vapor specific volume as a function of pressure.
StmEng_psatt Saturation pressure as a function of temperature.
StmEng_hsatt Saturation enthalpy as a function of temperature.
StmEng_ssatt Saturation entropy as a function of temperature.
StmEng_vsatt Saturation vapor specific volume as a function of temperature.
StmEng_vpt Vapor specific volume as a function of pressure and temperature. (For saturated and super
heated steam.)
StmEng_vptl Water specific volume as a function of pressure and temperature.
StmEng_vph Vapor specific volume as a function of pressure and enthalpy. (For wet and dry steam.)
StmEng_vps Vapor specific volume as a function of pressure and entropy. (For wet and dry steam.)
StmEng_hpt Enthalpy as a function of pressure and temperature. (For saturated and super heated steam.)
StmEng_hptl Liquid enthalpy as a function of pressure and temperature. (For water.)
StmEng_hps Enthalpy as a function of pressure and entropy. (For wet and dry steam.)
StmEng_spt Entropy as a function of pressure and temperature. (For saturated and super heated steam.)
StmEng_sptl Liquid entropy as a function of pressure and temperature. (For water.)
StmEng_sph Entropy as a function of pressure and enthalpy. (For wet and dry steam.)
StmEng_tph Temperature as a function of enthalpy and pressure. (For wet and dry steam.)
StmEng_tps Temperature as a function of entropy and pressure. (For wet and dry steam.)
StmEng_xph Steam quality (vapor fraction) as a function of enthalpy and pressure. (For wet steam.)
StmEng_xps Steam quality (vapor fraction) as a function of entropy and pressure. (For wet steam.)
StmEng_hpx Enthalpy as a function of pressure and steam quality. (For wet steam.)
StmEng_spx Entropy as a function of pressure and steam quality. (For wet steam.)
5.1.1 Steam Functions Naming Convention
The formulas have the same naming convention as those callable by user program, i.e.
STMENG_XXX for English units and STMSI_XXX for SI units. The formulas return the
steam properties values and accept real number as arguments (i.e., argument type R). In case
of error, the formulas return the digital states as shown in Table 5–3.
Page 186
5.2 - Range of Steam Functions
Table 5–3. Digital States Returned
Digital State Description
INP OUTRANGE Input condition out of computation range
NOT CONVERGE Calculation failed to converge in iterative loop.
These digital states are standard and are installed with PI Server. The format for each formula
is listed in the reference section.
5.2 Range of Steam Functions
Table 5–4 lists the valid range in English units of the input variables for each of the steam
functions. The PI Steam functions should compute the same results as the equations given in
the ASME Steam Tables, 6th Edition. Besides the accuracy quoted by the ASME Steam
Tables, you should be aware of the issues raised in Functions that use Temperature and
Pressure as Independent Variables on page 187, and Functions that use Enthalpy or Entropy
as an Independent Variable on page 188.
5.2.1 Functions that use Temperature and Pressure as Independent Variables
For the HPT, SPT and VPT functions, the steam has to be superheated or saturated dry. If
the temperature and pressure are on the saturated curve, the calculated entropy, enthalpy or
volume is the property of saturated vapor. If the input temperature is less than the saturated
temperature for the input pressure, an Input Out of Range error is returned (i.e., digital state
INPOUTRANGE for PI formulas or error code -1 for user-callable functions). Since
measurements are not exact, these PT functions can tolerate an error margin:
if (0 > Tsat - Tin > error margin) then saturated steam
The default error margin is 0.5 degree F.
Table 5–4. Input Range for Each Function
Pressure Enthalpy Entropy
Function Temp (deg f) (psia) (btu/lb) (btu/lb/r) Quality
StmEng_tsatp 0.088589 to
3208.2
StmEng_hsatp 0.088589 to
3208.2
StmEng_ssatp 0.088589 to
3208.2
StmEng_vsatp 0.088589 to
3208.2
StmEng_psatt 32. to 705.47
StmEng_hsatt 32. to 705.47
StmEng_ssatt 32. to 705.47
PI Server Applications User Guide Page 187
Chapter 5 - PI Steam Functions Reference
Pressure Enthalpy Entropy
Function Temp (deg f) (psia) (btu/lb) (btu/lb/r) Quality
StmEng_vsatt 32. to 705.47
StmEng_vpt, 32. to 1600 0.088589 to
StmEng_vptl 16000.
StmEng_vph 0.088589 to -1 to 1860.
16000.
StmEng_vps 0.088589 to -0.1 to 3.0
16000.
StmEng_hpt, 32. to 1600 0.088589 to
StmEng_hptl 16000.
StmEng_hps 0.088589 to -0.1 to 3.0
16000.
StmEng_spt, 32. to 1600 0.088589 to
StmEng_sptl 16000.
StmEng_sph 0.088589 to -1 to 1860.
16000.
StmEng_tph 0.088589 to -1 to 1860.
16000.
StmEng_tps 0.088589 to -0.1 to 3.0
16000.
StmEng_xph 0.088589 to -1 to 1860.
3208.2
StmEng_xps 0.088589 to -0.1 to 3.0
3208.2
StmEng_hpx 0.088589 to 0 to 1
3208.2
StmEng_spx 0.088589 to 0 to 1
3208.2
5.2.2 Functions that use Enthalpy or Entropy as an Independent Variable
For the VPH, VPS, HPS, SPH, TPH and TPS functions, the valid ranges cover both the
superheated and the wet steam. However, even though the ASME listed valid range for
enthalpy goes from -1 to 1860 BTU/lbm and the entropy ranges from -0.1 to 3.0
BTU/lbm/degR, there are some combination of pressure and enthalpy or entropy that
correspond to compressed water rather than steam. Hence, these input conditions will
generate an error state.
For the wet steam region, the ASME routines use the Clapeyron equation and the saturated
vapor values to compute the result. For the VPH and VPS functions, the computed volume
can differ by a few percents as compared to the volume calculated from the saturated vapor
volume, saturated liquid volume and the vapor fraction. The difference in the computed
volume increases as the moisture content of the vapor mixture increases. However, since the
Page 188
5.3 - Steam Property Reference States
practical use of the steam function involves steam with vapor fraction higher than 0.5, the
ASME equation is not modified.
For the HPS and SPH functions in the wet steam region, the ASME routines use the equation
(Hvap = T*Svap) and the saturated vapor values to compute the result. The functions do not
check if the input enthalpy or entropy is less than those of the saturated liquid and the
extrapolated value is returned.
For the TPH and TPS function in the wet steam region, the ASME routines just check
whether the input enthalpy or entropy is less than that of the saturated vapor at the given
pressure. If the input enthalpy or entropy is less than the saturated vapor value, the saturated
temperature is returned as the answer. The functions do not consider the case where the input
enthalpy or input entropy is less than that of the saturated liquid an error state.
Similarly, for the XPH and XPS functions, the ASME routines do not consider the input
enthalpy or entropy out of bound even when they are greater than saturated vapor properties
or less than saturated liquid properties. The functions return 1.0 as the vapor fraction when
the input enthalpy or entropy is greater than the saturated vapor properties. Input enthalpy or
entropy less than the saturated liquid properties results in negative vapor fraction rather than
an error state.
Though the ASME routines have inadequate checks for the wet steam region, OSI did not
modify these routines because in reality, the steam functions are not used in regions where
the input checks would cause a problem.
One final feature, for pressure above the critical point (3208.2 psia), the VPH, VPS, HPS,
SPH, TPH and TPS functions compute valid results for states corresponded to temperature
greater than 682 degrees F. but less than the critical temperature, 705.47 degrees F, even
though these states are considered compressed water rather than steam.
5.3 Steam Property Reference States
The ASME establishes the following reference states:
Triple Point
Triple point of water is at 273.16 degree K or 0.01 degree C or 0.018 degree F.
Celsius Scale
The Celsius temperature is exactly Tk - 273.15.
Critical Point
Critical point of steam is at 647.3 degree K and 22,120 kpa, or 705.47 degree F and 3208.3
psia.
Reference State
The specific internal energy and specific entropy of the liquid phase were fixed at zero at the
triple point of water.
PI Server Applications User Guide Page 189
Chapter 5 - PI Steam Functions Reference
5.4 Steam Functions Reference
This section provides a detailed reference of Steam Functions.
StmEng_TsatP
Calculates the saturation temperature as a function of pressure—all variables expressed in
English units.
Format
StmEng_TsatP(P)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
Returns
Computed saturation temperature in degrees F. or Error digital state.
Sample Values
Pressure Temperature
10. 193.21
100. 327.82
1000. 544.58
Page 190
5.4 - Steam Functions Reference
StmEng_HsatP
Calculates the saturated vapor specific enthalpy as a function of pressure—all variables
expressed in English units.
Format
StmEng_HsatP(P)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
Returns
Computed specific enthalpy for saturated vapor in BTU/lbm or Error digital state.
Sample Values
Pressure Vapor Enthalpy
10. 1143.4
100. 1187.2
1000. 1192.9
PI Server Applications User Guide Page 191
Chapter 5 - PI Steam Functions Reference
StmEng_SsatP
Calculates the saturated vapor specific entropy as a function of pressure—all variables
expressed in English units.
Format
StmEng_SsatP(P)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
Returns
Computed saturated vapor specific entropy in BTU/lbm/R or Error digital state.
Sample Values
Pressure Entropy
10. 1.7879
100. 1.6027
1000. 1.3910
Page 192
5.4 - Steam Functions Reference
StmEng_VsatP
Calculates the saturated vapor specific volume as a function of pressure—all variables
expressed in English units.
Format
StmEng_VsatP(P)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
Returns
Saturated vapor specific volume in ft3/lbm or Error digital state.
Sample Values
Pressure Volume
10. 38.42
100. 4.431
1000. 0.44596
PI Server Applications User Guide Page 193
Chapter 5 - PI Steam Functions Reference
StmEng_PsatT
Calculates the saturation pressure as a function of temperature—all variables expressed in
English units.
Format
StmEng_PsatT(T)
Arguments
T
Steam temperature in degree F. The valid range is 32 to 705.47 degree F.
Returns
Computed saturation pressure of the steam in psia or Error digital state.
Sample Values
Temperature Pressure
100. 0.9492
400. 247.26
700. 3094.33
Page 194
5.4 - Steam Functions Reference
StmEng_HsatT
Calculates the saturated vapor specific enthalpy as a function of temperature—all variables
expressed in English units.
Format
StmEng_HsatT(T)
Arguments
T
Steam temperature in degree F. The valid range is 32 to 705.47 degree F.
Returns
Computed specific enthalpy for saturated vapor in BTU/lbm or Error digital state.
Sample Values
Temperature Vapor Enthalpy
100. 1105.1
400. 1201.0
700. 995.2
PI Server Applications User Guide Page 195
Chapter 5 - PI Steam Functions Reference
StmEng_SsatT
Calculates the saturated vapor specific entropy as a function of temperature—all variables
expressed in English units.
Format
StmEng_SsatT(T)
Arguments
T
Steam temperature in degree F. The valid range is 32 to 705.47 degree F.
Returns
Computed saturated vapor specific entropy in BTU/lbm/R or- Error digital state.
Sample Values
Temperature Entropy
100. 1.9825
400. 1.52735
700. 1.1390
Page 196
5.4 - Steam Functions Reference
StmEng_VsatT
Calculates the saturated vapor specific volume as a function of temperature—all variables
expressed in English units.
Format
StmEng_VsatT(T)
Arguments
T
Steam temperature in degree F. The valid range is 32 to 705.47 degree F
Returns
Computed saturated vapor specific volume in ft3/lbm or Error digital state
Sample Values
Temperature Volume
100. 350.39
400. 1.863
700. 0.0752
PI Server Applications User Guide Page 197
Chapter 5 - PI Steam Functions Reference
StmEng_VPT
Calculates the vapor specific volume as a function of pressure and temperature—all variables
expressed in English units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) will be resulted for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.
Format
StmEng_VPT(P, T)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T
Steam temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed vapor specific volume in ft3/lbm or Error digital state.
Sample Values
Pressure Temperature Volume
300. 1000. 2.8585
800. 1000. 1.047
1400. 1000. 0.5809
5000. 1000. 0.13118
Page 198
5.4 - Steam Functions Reference
StmEng_VPTL
Calculates the liquid specific volume as a function of pressure and temperature—all variables
expressed in English units. Only use for liquid water condition. An error of -1 (or input out of
range digital state) will be resulted for input temperature higher than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.
Format
StmEng_VPTL(P, T)
Arguments
P
Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T
Water temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed liquid specific volume in ft3/lbm or Error digital state.
Sample Values
Pressure Temperature Volume
300. 100. 0.016115
800. 100. 0.016091
1400. 100. 0.016062
5000. 100. 0.015897
PI Server Applications User Guide Page 199
Chapter 5 - PI Steam Functions Reference
StmEng_VPH
Calculates the vapor specific volume as a function of pressure and enthalpy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_VPH(P, H)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H
Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.
Returns
Computed vapor specific volume in ft3/lbm or Error digital state.
Sample Values
Pressure Enthalpy Volume State
300. 1526.2 2.8585 Superheated
800. 1511.4 1.047 Superheated
1400. 1493.2 0.5809 Superheated
5000. 1364.6 0.13118 Superheated
300. 1122. 1.3904 90 % vapor
Note: The computed result may differ slightly from that computed using the
saturated liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.
Page 200
5.4 - Steam Functions Reference
StmEng_VPS
Calculates the vapor specific volume as a function of pressure and entropy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_VPS(P, S)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S
Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.
Returns
Computed vapor specific volume in ft3/lbm or Error digital state.
Sample Values
Pressure Entropy Volume State
300. 1.7964 2.8585 Superheated
800. 1.6807 1.047 Superheated
1400. 1.6096 0.5809 Superheated
5000. 1.4001 0.13118 Superheated
300. 1.4183 1.3904 90 % vapor
Note: The computed result may differ slightly from that computed using the
saturated liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.
PI Server Applications User Guide Page 201
Chapter 5 - PI Steam Functions Reference
StmEng_HPT
Calculates the vapor specific enthalpy as a function of pressure and temperature—all
variables expressed in English units. Only use for superheated or dry saturated steam. An
error of -1 (or input out of range digital state) will be resulted for input temperature lower
than the saturation temperature for the input pressure. However, the function computes for the
full range of temperature for input pressure greater than the critical pressure.
Format
StmEng_HPT(P, T)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T
Steam temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed vapor specific enthalpy in BTU/lbm or Error digital state.
Sample Values
Pressure Temperature Enthalpy
300. 1000. 1526.2
800. 1000. 1511.4
1400. 1000. 1493.2
5000. 1000. 1364.6
Page 202
5.4 - Steam Functions Reference
StmEng_HPTL
Calculates the liquid specific enthalpy as a function of pressure and temperature—all
variables expressed in English units. Only use for compressed water. An error of -1 (or input
out of range digital state) will be resulted for input temperature higher than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.
Format
StmEng_HPTL(P, T)
Arguments
P
Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T
Water temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed liquid specific enthalpy in BTU/lbm or Error digital state.
Sample Values
Pressure Temperature Enthalpy
300. 100. 68.788
800. 100. 70.106
1400. 100. 71.684
5000. 100. 81.081
PI Server Applications User Guide Page 203
Chapter 5 - PI Steam Functions Reference
StmEng_HPS
Calculates the vapor specific enthalpy as a function of pressure and entropy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_HPS(P, S)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S
Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.
Returns
Computed vapor specific enthalpy in BTU/lbm or Error digital state.
Sample Values
Pressure Entropy Enthalpy State
300. 1.7964 1526.2 Superheated
800. 1.6807 1511.4 Superheated
1400. 1.6096 1493.2 Superheated
5000. 1.4001 1364.6 Superheated
300. 1.4183 1122. 90 % vapor
Note: Even if the input entropy is less than that of the saturated liquid, the function
still computes the enthalpy by extrapolation without setting an error state.
Page 204
5.4 - Steam Functions Reference
StmEng_SPT
Calculates the vapor specific entropy as a function of pressure and temperature—all variables
expressed in English units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) will be resulted for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.
Format
StmEng_SPT(P, T)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T
Steam temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed vapor specific entropy in BTU/lbm/R or- Error digital state.
Sample Values
Pressure Temperature Entropy
300. 1000. 1.7964
800. 1000. 1.6807
1400. 1000. 1.6096
5000. 1000. 1.4001
PI Server Applications User Guide Page 205
Chapter 5 - PI Steam Functions Reference
StmEng_SPTL
Calculates the liquid specific entropy as a function of pressure and temperature—all variables
expressed in English units. Only use for compressed water. An error of -1 (or input out of
range digital state) will be resulted for input temperature higher than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.
Format
StmEng_SPTL(P, T)
Arguments
P
Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T
Water temperature in degree F. The valid range is 32 to 1600 degree F.
Returns
Computed liquid specific entropy in BTU/lbm/R or- Error digital state.
Sample Values
Pressure Temperature Entropy
300. 100. 0.12936
800. 100. 0.12905
1400. 100. 0.12868
5000. 100. 0.12645
Page 206
5.4 - Steam Functions Reference
StmEng_SPH
Calculates the vapor specific entropy as a function of pressure and enthalpy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_SPH(P, H)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H
Computed vapor specific enthalpy in BTU/lbm. The valid range is -1.0 to 1860 BTU/lbm.
Returns
Computed vapor specific entropy in BTU/lbm/R or- Error digital state.
Sample Values
Pressure Enthalpy Entropy State
300. 1526.2 1.7964 Superheated
800. 1511.4 1.6807 Superheated
1400. 1493.2 1.6096 Superheated
5000. 1364.6 1.4001 Superheated
300. 1122. 1.4183 90 % vapor
Note: Even if the input enthalpy is less than that of the saturated liquid, the function
still computes the entropy by extrapolation without setting an error state.
PI Server Applications User Guide Page 207
Chapter 5 - PI Steam Functions Reference
StmEng_TPH
Calculates the steam temperature as a function of pressure and enthalpy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_TPH(P, H)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H
Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.
Returns
Computed steam temperature in degree F. or Error digital state.
Sample Values
Pressure Enthalpy Temperature State
300. 1526.2 1000. Superheated
800. 1511.4 1000. Superheated
1400. 1493.2 1000. Superheated
5000. 1364.6 1000. Superheated
300. 1122. 417.35 90 % vapor
Note: Even if the input enthalpy is less than that of the saturated liquid, the function
still returns the saturated temperature as the answer without setting an error state.
Page 208
5.4 - Steam Functions Reference
StmEng_TPS
Calculates the steam temperature as a function of pressure and entropy—all variables
expressed in English units. Use for both superheated or wet steam.
Format
StmEng_TPS(P, S)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S
Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.
Returns
Computed steam temperature in degree F. or Error digital state.
Sample Values
Pressure Entropy Temperature State
300. 1.7964 1000. Superheated
800. 1.6807 1000. Superheated
1400. 1.6096 1000. Superheated
5000. 1.4001 1000. Superheated
300. 1.4183 417.35 90 % vapor
Note: Even if the input entropy is less than that of the saturated liquid, the function
still returns the saturated temperature as the answer without setting an error state.
PI Server Applications User Guide Page 209
Chapter 5 - PI Steam Functions Reference
StmEng_XPH
Calculates the steam quality (vapor fraction) as a function of pressure and enthalpy—all
variables expressed in English units. Use only for wet steam.
Format
StmEng_XPH(P, H)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
H
Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.
Returns
Computed steam quality (vapor fraction) or Error digital state.
Sample Values
Pressure Enthalpy Steam Quality
300. 1122.0 0.9
800. 1130.4 0.9
1400. 1117.7 0.9
Note: If the input enthalpy is greater than that of the saturated vapor, the function
returns 1.0 as vapor fraction. If the input enthalpy is less than that of the saturated
liquid, the function would compute negative vapor fraction without setting an error
state.
Page 210
5.4 - Steam Functions Reference
StmEng_XPS
Calculates the steam quality (vapor fraction) as a function of pressure and entropy—all
variables expressed in English units. Use only for wet steam.
Format
StmEng_XPS(P, S)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
S
Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R or
Error digital state.
Returns
Computed steam quality (vapor fraction).
Sample Values
Pressure Entropy Steam Quality
300. 1.4183 0.9
800. 1.3458 0.9
1400. 1.2923 0.9
Note: If the input entropy is greater than that of the saturated vapor, the function
returns 1.0 as vapor fraction. If the input entropy is less than that of the saturated
liquid, the function would compute negative vapor fraction without setting an error
state.
PI Server Applications User Guide Page 211
Chapter 5 - PI Steam Functions Reference
StmEng_HPX
Calculates the steam specific enthalpy as a function of pressure and quality (vapor fraction)—
all variables expressed in English units. Use only for wet steam.
Format
StmEng_HPX(P, X)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
X
Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.
Returns
Computed specific enthalpy of the steam in BTU/lbm or Error digital state.
Sample Values
Pressure Steam Quality Enthalpy
300. 0.9 1122.0
800. 0.9 1130.4
1400. 0.9 1117.7
Page 212
5.4 - Steam Functions Reference
StmEng_SPX
Calculates the steam specific entropy as a function of pressure and quality (vapor fraction)—
all variables expressed in English units. Use only for wet steam.
Format
StmEng_SPX(P, X)
Arguments
P
Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
X
Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.
Returns
Computed specific entropy of the steam in BTU/lbm/R or- Error digital state.
Sample Values
Pressure Steam Quality Entropy
300. 0.9 1.4183
800. 0.9 1.3458
1400. 0.9 1.2923
PI Server Applications User Guide Page 213
Chapter 5 - PI Steam Functions Reference
StmSI_TsatP
Calculates the saturation temperature as a function of pressure—all variables expressed in SI
units.
Format
StmSI_TsatP(P)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
Returns
Computed saturation temperature in degree C. or Error digital state.
Sample Values
Pressure Temperature
50. 81.345
1000. 179.88
10000. 310.96
Page 214
5.4 - Steam Functions Reference
StmSI_HsatP
Calculates the saturated vapor specific enthalpy as a function of pressure—all variables
expressed in SI units.
Format
StmSI_HsatP(P)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
Returns
Computed specific enthalpy for saturated vapor in J/g.
Sample Values
Pressure Vapor Enthalpy
50. 2646.0
1000. 2776.2
10000. 2727.7
PI Server Applications User Guide Page 215
Chapter 5 - PI Steam Functions Reference
StmSI_SsatP
Calculates the saturated vapor specific entropy as a function of pressure—all variables
expressed in SI units.
Format
StmSI_SsatP(P)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
Returns
Computed saturated vapor specific entropy in J/g/K or Error digital state.
Sample Values
Pressure Entropy
50. 7.5947
1000. 6.5828
10000. 5.6198
Page 216
5.4 - Steam Functions Reference
StmSI_VsatP
Calculates the saturated vapor specific volume as a function of pressure—all variables
expressed in SI units.
Format
StmSI_VsatP(P)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
Returns
Computed saturated vapor specific volume in cc/g or Error digital state.
Sample Values
Pressure Volume
50. 3240.2
1000. 194.29
10000. 18.041
PI Server Applications User Guide Page 217
Chapter 5 - PI Steam Functions Reference
StmSI_PsatT
Calculates the saturation pressure as a function of temperature—all variables expressed in SI
units.
Format
StmSI_PsatT(T)
Arguments
T
Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.
Returns
Computed saturation pressure of the steam in kpa or Error digital state.
Sample Values
Temperature Pressure
50. 12.335
200. 1554.9
350. 16535.
Page 218
5.4 - Steam Functions Reference
StmSI_HsatT
Calculates the saturated vapor specific enthalpy as a function of temperature—all variables
expressed in SI units.
Format
StmSI_HsatT(T)
Arguments
T
Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.
Returns
Computed specific enthalpy for saturated vapor in J/g or Error digital state.
Sample Values
Temperature Vapor Enthalpy
50. 2592.2
200. 2790.9
350. 2567.7
PI Server Applications User Guide Page 219
Chapter 5 - PI Steam Functions Reference
StmSI_SsatT
Calculates the saturated vapor specific entropy as a function of temperature—all variables
expressed in SI units.
Format
StmSI_SsatT(T)
Arguments
T
Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.
Returns
Computed saturated vapor specific entropy in J/g/K or Error digital state.
Sample Values
Temperature Entropy
50. 8.0776
200. 6.4278
350. 5.2177
Page 220
5.4 - Steam Functions Reference
StmSI_VsatT
Calculates the saturated vapor specific volume as a function of temperature—all variables
expressed in SI units.
Format
StmSI_VsatT(T)
Arguments
T
Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C
Returns
Computed saturated vapor specific volume in cc/g or Error digital state.
Sample Values
Temperature Volume
50. 12046.
200. 127.16
350. 8.7991
PI Server Applications User Guide Page 221
Chapter 5 - PI Steam Functions Reference
StmSI_VPT
Calculates the vapor specific volume as a function of pressure and temperature—all variables
expressed in SI units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) will be resulted for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.
Format
StmSI_VPT(P, T)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed vapor specific volume in cc/g or Error digital state.
Sample Values
Pressure Temperature Volume
2500. 600. 159.21
5000. 600. 78.616
10000. 600. 38.320
40000. 600. 8.0884
Page 222
5.4 - Steam Functions Reference
StmSI_VPTL
Calculates the liquid specific volume as a function of pressure and temperature—all variables
expressed in SI units. Only use for compressed water. An error of -1(or input out of range
digital state) will be resulted for input temperature higher than the saturation temperature for
the input pressure. However, the function computes for the full range of temperature for input
pressure greater than the critical pressure.
Format
StmSI_VPTL(P, T)
Arguments
P
Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed liquid specific volume in cc/g or Error digital state.
Sample Values
Pressure Temperature Volume
2500. 100. 1.04245
5000. 100. 1.04116
10000. 100. 1.03861
40000. 100. 1.02438
PI Server Applications User Guide Page 223
Chapter 5 - PI Steam Functions Reference
StmSI_VPH
Calculates the vapor specific volume as a function of pressure and enthalpy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_VPH(P, H)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H
Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.
Returns
Computed vapor specific volume in cc/g or Error digital state.
Sample Values
Pressure Enthalpy Volume State
2500. 3685.1 159.21 Superheated
5000. 3664.5 78.616 Superheated
10000. 3622.7 38.320 Superheated
40000. 3346.4 8.0884 Superheated
2500. 2617.0 72.04 90 % vapor
Note: The computed result may differ slightly from that computed using the
saturated liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.
Page 224
5.4 - Steam Functions Reference
StmSI_VPS
Calculates the vapor specific volume as a function of pressure and entropy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_VPS(P, S)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S
Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.
Returns
Computed vapor specific volume in cc/g or Error digital state.
Sample Values
Pressure Entropy Volume State
2500. 7.5956 159.21 Superheated
5000. 7.2578 78.616 Superheated
10000. 6.9013 38.320 Superheated
40000. 6.0135 8.0884 Superheated
2500. 5.8837 72.04 90 % vapor
Note: The computed result may differ slightly from that computed using the
saturated liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.
PI Server Applications User Guide Page 225
Chapter 5 - PI Steam Functions Reference
StmSI_HPT
Calculates the vapor specific enthalpy as a function of pressure and temperature—all
variables expressed in SI units. Only use for superheated or dry saturated steam. An error of
-1 (or input out of range digital state) will be resulted for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.
Format
StmSI_HPT(P, T)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed vapor specific enthalpy in J/g or Error digital state.
Sample Values
Pressure Temperature Enthalpy
2500. 600. 3685.1
5000. 600. 3664.5
10000. 600. 3622.7
40000. 600. 3346.4
Page 226
5.4 - Steam Functions Reference
StmSI_HPTL
Calculates the liquid specific enthalpy as a function of pressure and temperature—all
variables expressed in SI units. Only use for compressed water. An error of -1 (or input out of
range digital state) will be resulted for input temperature higher than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.
Format
StmSI_HPTL(P, T)
Arguments
P
Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed liquid specific enthalpy in J/g or Error digital state.
Sample Values
Pressure Temperature Enthalpy
2500. 100. 420.86
5000. 100. 422.74
10000. 100. 426.50
40000. 100. 449.22
PI Server Applications User Guide Page 227
Chapter 5 - PI Steam Functions Reference
StmSI_HPS
Calculates the vapor specific enthalpy as a function of pressure and entropy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_HPS(P, S)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S
Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.
Returns
Computed vapor specific enthalpy in J/g or Error digital state.
Sample Values
Pressure Entropy Enthalpy State
2500. 7.5956 3685.1 Superheated
5000. 7.2578 3664.5 Superheated
10000. 6.9013 3622.7 Superheated
40000. 6.0135 3346.4 Superheated
2500. 5.8837 2617.0 90 % vapor
Note: Even if the input entropy is less than that of the saturated liquid, the function
still computes the enthalpy by extrapolation without setting an error state.
Page 228
5.4 - Steam Functions Reference
StmSI_SPT
Calculates the vapor specific entropy as a function of pressure and temperature—all variables
expressed in SI units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) will be resulted for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.
Format
StmSI_SPT(P, T)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed vapor specific entropy in J/g/K or Error digital state.
Sample Values
Pressure Temperature Entropy
2500. 600. 7.5956
5000. 600. 7.2578
10000. 600. 6.9013
40000. 600. 6.0135
PI Server Applications User Guide Page 229
Chapter 5 - PI Steam Functions Reference
StmSI_SPTL
Calculates the liquid specific entropy as a function of pressure and temperature—all variables
expressed in SI units. Only use for compressed water. An error of -1 (or input out of range
digital state) will be resulted for input temperature higher than the saturation temperature for
the input pressure. However, the function computes for the full range of temperature for input
pressure greater than the critical pressure.
Format
StmSI_SPTL(P, T)
Arguments
P
Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T
Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.
Returns
Computed liquid specific entropy in J/g/K or Error digital state.
Sample Values
Pressure Temperature Entropy
2500. 100. 1.305
5000. 100. 1.30304
10000. 100. 1.29919
40000. 100. 1.27714
Page 230
5.4 - Steam Functions Reference
StmSI_SPH
Calculates the vapor specific entropy as a function of pressure and enthalpy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_SPH(P, H)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H
Computed vapor specific enthalpy in J/g. The valid range is -2.326 to 4326.36 J/g.
Returns
Computed vapor specific entropy in J/g/K or Error digital state.
Sample Values
Pressure Enthalpy Entropy State
2500. 3685.1 7.5956 Superheated
5000. 3664.5 7.2578 Superheated
10000. 3622.7 6.9013 Superheated
40000. 3346.4 6.0135 Superheated
2500. 2617.0 5.8837 90 % vapor
Note: Even if the input enthalpy is less than that of the saturated liquid, the function
still computes the entropy by extrapolation without setting an error state.
PI Server Applications User Guide Page 231
Chapter 5 - PI Steam Functions Reference
StmSI_TPH
Calculates the steam temperature as a function of pressure and enthalpy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_TPH(P, H)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H
Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.
Returns
Computed steam temperature in degree C. or Error digital state.
Sample Values
Pressure Enthalpy Temperature State
2500. 3685.1 600. Superheated
5000. 3664.5 600. Superheated
10000. 3622.7 600. Superheated
40000. 3346.4 600. Superheated
2500. 2617.0 223.94 90 % vapor
Note: Even if the input enthalpy is less than that of the saturated liquid, the function
still returns the saturated temperature as the answer without setting an error state.
Page 232
5.4 - Steam Functions Reference
StmSI_TPS
Calculates the steam temperature as a function of pressure and entropy—all variables
expressed in SI units. Use for both superheated or wet steam.
Format
StmSI_TPS(P, S)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S
Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.
Returns
Computed steam temperature in degree C. or Error digital state.
Sample Values
Pressure Entropy Temperature State
2500. 7.5956 600. Superheated
5000. 7.2578 600. Superheated
10000. 6.9013 600. Superheated
40000. 6.0135 600. Superheated
2500. 5.8837 223.94 90 % vapor
Note: Even if the input entropy is less than that of the saturated liquid, the function
still returns the saturated temperature as the answer without setting an error state.
PI Server Applications User Guide Page 233
Chapter 5 - PI Steam Functions Reference
StmSI_XPH
Calculates the steam quality (vapor fraction) as a function of pressure and enthalpy—all
variables expressed in SI units. Use only for wet steam.
Format
StmSI_XPH(P, H)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
H
Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.
Returns
Computed steam quality (vapor fraction) or Error digital state.
Sample Values
Pressure Enthalpy Steam Quality
2500. 2617.0 0.9
5000. 2630.2 0.9
10000. 2595.8 0.9
Note: If the input enthalpy is greater than that of the saturated vapor, the function
returns 1.0 as vapor fraction. If the input enthalpy is less than that of the saturated
liquid, the function would compute negative vapor fraction without setting an error
state.
Page 234
5.4 - Steam Functions Reference
StmSI_XPS
Calculates the steam quality (vapor fraction) as a function of pressure and entropy—all
variables expressed in SI units. Use only for wet steam.
Format
StmSI_XPS(P, S)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
S
Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.
Returns
Computed steam quality (vapor fraction) or Error digital state.
Sample Values
Pressure Entropy Steam Quality
2500. 5.8837 0.9
5000. 5.6682 0.9
10000. 5.3939 0.9
Note: If the input entropy is greater than that of the saturated vapor, the function
returns 1.0 as vapor fraction. If the input entropy is less than that of the saturated
liquid, the function would compute negative vapor fraction without setting an error
state.
PI Server Applications User Guide Page 235
Chapter 5 - PI Steam Functions Reference
StmSI_HPX
Calculates the steam specific enthalpy as a function of pressure and quality (vapor fraction)—
all variables expressed in SI units. Use only for wet steam.
Format
StmSI_HPX(P, X)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
X
Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.
Returns
Computed specific enthalpy of the steam in J/g or Error digital state.
Sample Values
Pressure Steam Quality Enthalpy
2500. 0.9 2617.0
5000. 0.9 2630.2
10000. 0.9 2595.8
Page 236
5.4 - Steam Functions Reference
StmSI_SPX
Calculates the steam specific entropy as a function of pressure and quality (vapor fraction)—
all variables expressed in SI units. Use only for wet steam.
Format
StmSI_SPX(P, X)
Arguments
P
Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
X
Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.
Returns
Computed specific entropy of the steam in J/g/K or Error digital state.
Sample Values
Pressure Steam Quality Entropy
2500. 0.9 5.8837
5000. 0.9 5.6682
10000. 0.9 5.3939
PI Server Applications User Guide Page 237
Chapter 6. PI BATCH DATABASE
Most processes have repeatable time segments or stages. The PI Batch Subsystem maps
process or manufacturing events to slices of time and data, and stores these batch- and
process-based events hierarchically in the PI Data Archive as Batches, Unit Batches, or Sub
Batches. This capability enables powerful data and process analysis for both traditional and
non-traditional batch processes.
Many manufacturing companies find it useful to track their products in discrete batches rather
than as a time-continuous product. PI Batch can define and record sequences such as events
in discrete manufacturing, paper reels, steel coils, product or grade changes, turbine startups,
and lab runs. While industries such as chemicals and pharmaceuticals use PI Batch to track
and analyze batches, it is also widely used in non-batch applications to identify and track
process events. Along with the use of audit trail support, PI Batch and the PI System become
an integral component of a validated reporting environment in compliance with 21 CFR Part
11.
This chapter describes the functionality provided by the PI Batch Subsystem, from
configuration to interaction with the resulting batch data, and includes the following topics:
Section 6.1, PI Batch Overview, on page 239
Section 6.2, Installation, on page 241
Section 6.3, Configuration, on page 241
Section 6.4, Batch Data Information, on page 250
Section 6.5, Batch Subsystem Operation, on page 253
Section 6.6, Client Access to Batch Subsystem Batches, on page 254
Section 6.7, Complete Example, on page 254
6.1 PI Batch Overview
Traditional batch applications are common in industries like chemical, food and beverage,
and pharmaceutical manufacturing. Batch processing has also been used in applications in
which a sequence of steps occurs, such as burner startup and shutdown, to determine whether
or not proper sequencing took place. Furthermore, batch processing has been used in
applications that are not typically considered pure batch processes to correlate process data
that has been generated during say an 8-hour shift or a 24-hour time period. Comparison of
various parameters during such shifts or time periods often leads to valuable insight about the
underlying process.
PI Server Applications User Guide Page 239
Chapter 6 - PI Batch Database
PI Batch is used in conjunction with its companion Client application, PI BatchView, which
allows you to search, select, trend, and compare events that have been collected by PI Batch
and stored in the PI System. Earlier versions of PI BatchView were based on the PI-API, and
more recent versions are based on the PI-SDK.
Batch activity is indexed on the following parameters:
• Time
• Unit
• Batch ID
• Product ID
Once the batch activity is recorded, specific batches or groups of batches can be searched and
retrieved. The batch search results may then be used to frame process data from the PI
Archive in the context of the selected batches.
6.1.1 The PI Batch Subsystem (BSS), PI Batch Database (PBD), and PI Batch
Generator (PIBaGen)
The PI Batch Subsystem (BSS) was introduced with PI Server 3.1. It provides batch
processing functionality: configuration, monitoring, and query processing. It continues to be
installed and supported, but it is no longer the only (or preferred) technology for batch
processing.
For information about the PI Batch Subsystem, read this chapter.
The PI Batch Database (BDB) was introduced with PI Server 3.3 and PI-SDK 1.1. It
provides enhanced batch information processing support.
For information about the PI Batch Database, refer to the PI-SDK User Manual.
The PI Batch Generator (PIBaGen) Interface was introduced with the PI Batch Database.
It is now included with PI Server Applications. It is a PI-SDK-based interface that reads
process unit configuration from the PI Module Database and writes into the PI Batch
Database. The interface monitors the PI Server for events that trigger the beginning of a batch
and then stores information about each batch, such as Batch ID and Product ID, into the PI
Data Archive.
For information about the PI Batch Generator, refer to the PI Batch Generator
(PIBaGen) User Manual.
The PI Batch Database and the PI Batch Generator are independent of the PI Batch
Subsystem. All three of these system components may be used in parallel.
For a comparison of the PI Batch Subsystem and PI Batch Database refer to PI
Batch Database Support of the PI Batch Subsystem. This document also explains
how to access BSS batches from the BDB, and vice versa.
To search, select, trend, and compare batches of interest, client products such as PI-
BatchView are available.
Page 240
6.2 - Installation
6.1.2 Compatibility of PI-API Batch Applications for PI2 (OpenVMS) Servers
PI-API batch applications developed against PI BA in a PI2 Server (OpenVMS) will still
function correctly when run against a PI3 Server with the PI Batch Subsystem.
6.1.3 Glossary of Batch Terms
The following Batch terms are used in this chapter.
Term Definition
Batch A batch represents a span of time on a unit.
Unit Defines the name of the equipment set on which the batch activity takes place. Unit
definitions are not limited to a single piece of equipment. For example, a unit could
be a single reactor or a group of reactors and related equipment.
BatchID This is a name given to a batch of material. The BatchID is not required to be unique.
ProductID Describes a specific material or class of materials. This term is used in batch
applications that use equipment to produce a variety of different materials. A
ProductID is not required for a batch definition, but it does provide a useful search
index.
6.2 Installation
The PI Batch Subsystem is automatically installed on new installations or upgrades of the PI3
Server, but a valid license is required in order to use it. The pibatch.exe executable is located
in \PI\bin. The installation itself will not result in the creation of any units or batches, but the
installed piconfig script \PI\adm\pibatch.dif can be used to configure an example unit and
enable the creation of sample batches. The pibatch.dif script is discussed in more detail in
section 6.7.
The PI Batch Subsystem must started first, to configure any units or to create batches. Startup
will typically occur automatically either at boot time or when the PI Server startup script is
executed.
6.3 Configuration
All configuration for the PI Batch Subsystem must be performed with the command-line
utility piconfig. See chapter 11, The Piconfig Utility, in the PI Server System Management
Guide, for information about using the piconfig utility.
6.3.1 Unit Configuration
The starting point for all batch configurations is the unit, the piece or set of equipment where
batches occur. There are two fundamental rules for units:
The unit name must be unique.
The unit may only process one batch at a time.
PI Server Applications User Guide Page 241
Chapter 6 - PI Batch Database
PI Batch Unit (PIBAUNIT) Table
The configuration for all units is stored in the data file \PI\dat\pibaunit1.nt and is accessed
exclusively via the piconfig table named PIBAUNIT. The configuration for a unit involves
several attributes of information, and the following list includes each attribute's name, data
type, default value ("D:"), and current value ("C:"):
* (Ls - ) PIconfig> @table PIBAUNIT
* (Ls - PIBAUNIT) PIconfig> @?atr
1 - UnitName String D: C:
2 - NEWUnitName String D: C:
3 - ActiveTag String D: C:
4 - ActiveType String D: pulse C:
5 - BIDExpr String D: C:
6 - DataAccess String D: o:rw g:r w:r C:
7 - DataGroup String D: piadmin C:
8 - DataOwner String D: piadmin C:
9 - Description String D: C:
10 - EvalDelay String D: 0 C:
11 - MergeConsecutive String D: 0 C:
12 - ProdExpr String D: C:
13 - UnitAccess String D: o:rw g:r w:r C:
14 - UnitGroup String D: piadmin C:
15 - UnitOwner String D: piadmin C:
Table 6–1 provides a complete description of each of the unit attributes.
Table 6–1. PIBAUNIT Table Attributes
Attribute Description
UnitName This defines the unique unit name, which is the primary index of the
PIBAUNIT table. The name cannot include the ‘\’ character but can be
renamed.
NEWUnitName Used to rename an existing unit.
ActiveTag The PI tag that defines whether a batch is active or inactive on this unit.
Two different units cannot have the same batch activation tag.
ActiveType This attribute defines when a batch begins (becomes Active) or ends
(becomes Inactive) on a unit. The transition is a function of the data type
and value of the batch activation tag. The two possible types are Pulse
(default) and Step.
PULSE The Inactive / Active transition occurs according to the
following table. A change in value within the same status
range has no effect on the status of the unit.
ActiveTag Batch becomes Batch becomes Active
data type Inactive
Integer Value = 0 Value <> 0
Digital Value = first Value <> first digital state
digital state
Float -1 < Value < 1 Value <= -1 or Value >= 1
Page 242
6.3 - Configuration
Attribute Description
String Value = "" Value <> ""
STEP Units with this type are normally active: every time the
ActiveTag receives a new value, the current batch is
completed and a new batch is started. New batches will
cease being created for each new value when the ActiveTag
receives the Stop Value.
ActiveTag data type Stop Value
Integer Value = 0
Digital Value = first digital state
Float -1 < Value < 1
String Value = ""
BIDExpr This defines the expression consisting of PI Tags and text to generate a
batch identifier (BatchID) when a batch starts on a unit. See the section,
Rules for Defining BIDExpr and ProdExpr, for more information.
ProdExpr This defines the expression consisting of PI tags and text to generate a
product identifier (ProductID) when the batch starts on a unit. See the
section, Rules for Defining BIDExpr and ProdExpr, for more information.
EvalDelay Delay (default is zero), in seconds, to wait before evaluating BIDExpr and
ProdExpr after the batch starts. If the batch duration is shorter than the
evaluation delay, the BIDExpr and ProdExpr will be evaluated when the
batch ends. This attribute is useful if the BatchID and ProductID are not
defined until after the batch starts.
MergeConsecutive If the value of this attribute is non-zero (default is zero) and the
ActiveType is Pulse, consecutive batches with the same BatchID are
considered to be one batch. The first assigned ProductID is used for the
entire batch. This attribute is useful for batches that are halted
temporarily and then restarted before the actual batch completes.
Description A textual description of the unit.
DataAccess Similar to tag security, this security attribute controls access to the batch
data for the unit for the owner, group, and world. The format is the
following: "o:<access> g:<access> w:<access>" where the <access>
mask is either "rw" for read-write access, "w" for write-only access, "r" for
read-only access, or "" for no access. The default access string is "o:rw
g:r w:r".
DataGroup This security attribute indicates which group of PI users can access batch
data for the unit. The default data group is piadmin.
DataOwner This security attribute indicates which individual PI user owns the batch
data for the unit. The default data owner is piadmin.
UnitAccess Same as DataAccess, except this controls access to the configuration for
the unit. The default access string is also "o:rw g:r w:r".
UnitGroup This security attribute indicates which group of PI users can access the
configuration for the unit. The default unit group is piadmin.
UnitOwner This security attribute indicates which individual PI user owns the
configuration for the unit. The default unit owner is piadmin.
PI Server Applications User Guide Page 243
Chapter 6 - PI Batch Database
Rules for Defining BIDExpr and ProdExpr
If only one type of product is made on a given unit, a simple fixed text string will suffice for
ProdExpr. Typically, however, a given unit supports many different products, so the
ProductID must be generated from the value of one or more PI tags when the batch begins.
Similarly, a different BatchID will likely need to be generated even though it is not required
to be unique.
To generate multiple BatchIDs or ProductIDs requires an expression similar to the following:
" 'R1:PRODA'/4 + \"_\" + 'R1:PRODB'/5 + \"-A\" "
Note: The backslashes preceding the inner double quotes are needed; otherwise,
they would be misinterpreted to be the final double quote of the entire expression.
Such an expression combines the values of the PI tags R1:PRODA and R1:PRODB with
some additional text to generate a product name. Some example values of the PI tags and the
resulting ProductID (or BatchID) are:
R1:PRODA R1:PRODB ProductID
5 765.99 0005_00765-A
BLACK YELLOW BLAC_YELLO-A
ABC XYZ_X ABC _XYZ_X-A
12345 Shutdown ####_Digital
State Set-A
The following is a complete list of the syntax rules and limitations for specifying both
BIDExpr and ProdExpr expressions:
The entire expression must be enclosed in double quotes.
PI points must be enclosed in single quotes.
Static text strings must be enclosed in double quotes. Backslashes must precede the
double quotes surrounding text strings to prevent misinterpretation of the final double
quote for the entire expression.
A number following the field size indicator, '/', indicates the number of characters the
field will occupy. A value of 0 or an unspecified field width indicates that all
characters are required.
The values for integer tags are right-justified and zero-filled if the number of digits is
less than the field size. If the number of integer digits exceeds the field size, the field
is filled with '#'s.
The values for float tags are truncated and then converted to integers, which means
the field size rules for integers then apply.
The values for digital or string tags are left-justified and filled with trailing spaces if
the number of characters is less than the field size. If the number of characters
exceeds the field size, the text is truncated.
Page 244
6.3 - Configuration
If any tag has a bad status, the field is filled with '#'s.
Any leading or trailing blanks in the resulting BatchID or ProductID are truncated.
The resulting BatchID or ProductID should not contain any of the following
characters: * ? or \. These characters will interfere with wildcard searches.
Support for Web Processes
The PI Batch Subsystem supports batches for paper machines and other web processes like
textiles and film. For these types of batches, the batch active tag should be of type Step. This
tag may be used to record the sequential batch number on a particular machine (unit), taking
on a new value when a new batch is started. The batch start time will be the timestamp of the
value of the tag, and the batch end time will be one second before the timestamp of the next
value in the Archive.
Configuration Differences from PI BA in PI2 (OpenVMS)
The PI Batch Subsystem configuration differs from PI BA in PI2 (OpenVMS). The
differences and the reasons for the differences are summarized in Table 6–2.
Table 6–2. Configuration Differences from PI BA in PI2 (OpenVMS)
Difference from PI BA in PI2 Reason
Removal of the list of TAG Tag aliases are included in the PI3 Server. Therefore, they are not
aliases for the UNIT. duplicated in the PI Batch Subsystem.
Removal of the STEP and These functions are not supported in the PI Batch Subsystem.
CYCLETIME tags. Instead, this functionality is provided by Performance Equations.
Addition of the type of the The starting and stopping of a batch on a unit is indicated by the
batch active tag value of the unit’s batch active tag.
For PI BA in PI2, all of the batch active tags were of type pulse.
That is, when the value of the batch active tag is 0 (or its digital
equivalent) the unit is considered inactive. When the batch active
tag is 1 (or its digital equivalent), the unit is considered active.
Batch active tags of type Step are not restricted to the values of
0 and 1. To support web processes, described above, the batch
active tag takes on a new value when a batch is started, ending
the previous batch.
Common Operations
The following sub-sections demonstrate the common tasks of creating, listing, renaming,
editing, and deleting units.
Create Units
Recall that the only attributes with default values are the following: ActiveType, EvalDelay,
MergeConsecutive, and the six security attributes (DataAccess, DataGroup, DataOwner,
UnitAccess, UnitGroup, UnitOwner). If the default values for these attributes are
acceptable, then these attributes do not have to be specified when creating new units. The
following piconfig commands will create the unit TestUnit using the default attribute values:
PI Server Applications User Guide Page 245
Chapter 6 - PI Batch Database
* (Ls - ) PIconfig> @table PIBAUNIT
* (Ls - PIBAUNIT) PIconfig> @mode create
* (Cr - PIBAUNIT) PIconfig> @istr unitname,activetag,bidexpr,prodexpr,
description
* (Cr - PIBAUNIT) PIconfig> TestUnit,TestUnitTrigger,"\"TestUnitBID\"",
"\"TestUnitPID\"","This is a test unit."
*> TestUnit,TestUnitTrigger,"\"TestUnitBID\"","\"TestUnitPID\"","This is
a test unit."
When a new unit is created, a unique PI point (e.g. piba36) is created to store batch data in
the Archive just for that particular unit. One easy way to determine the name of this point,
which may be needed during troubleshooting, is to examine the PI Server Message Log at the
time the unit is created for a message similar to:
0 pipoints 27-Nov-05 22:46:27
>> Point Added by User (1) piadmin, piba36, PtId: 8406, RecNo: 4283
List Units
Use the following piconfig commands to list all the attributes for TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode list
* (Ls - PIBAUNIT) PIconfig> @ostr *
* (Ls - PIBAUNIT) PIconfig> @select unitname=TestUnit
* (Ls - PIBAUNIT) PIconfig> @ends
TestUnit,TestUnitTrigger,pulse,"TestBID",o:rw g:r w:r,piadmin,piadmin,
This is a test unit.,0,0,"TestPID",o:rw g:r w:r,piadmin,piadmin
Rename Units
Renaming units requires the use of the NEWUnitName attribute in edit mode. The following
piconfig commands rename TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode edit
* (Ed - PIBAUNIT) PIconfig> @istr unitname,newunitname
* (Ed - PIBAUNIT) PIconfig> TestUnit,TestUnit1
*> TestUnit,TestUnit1
Because a unit's name is not used to store the actual batch data, renaming a unit will be
wholly transparent to batch data searches and retrieval.
Edit Units
Any unit attribute except for UnitName can be edited directly using the attribute's name. The
following piconfig commands will edit the security attributes DataAccess and UnitAccess
for TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode edit
* (Ed - PIBAUNIT) PIconfig> @istr unitname,dataaccess,unitaccess
* (Ed - PIBAUNIT) PIconfig> TestUnit,"o:rw g:rw w:","o:rw g:rw w:"
*> TestUnit,"o:rw g:rw w:","o:rw g:rw w:"
Page 246
6.3 - Configuration
Editing a unit will also result in editing of the unique PI point (e.g. piba36) used to store the
unit's batch data in the archive. Examining the PI Server message log around the time of a
unit edit should yield a message similar to:
0 pipoints 27-Nov-05 23:17:22
>> Point Edited by User (1) piadmin, piba36, Point Id: 8406
Delete Units
OSIsoft does not recommend deleting units, especially those that have valid batch data.
Nevertheless, the following piconfig commands will delete TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode delete
* (Dl - PIBAUNIT) PIconfig> @istr unitname
* (Dl - PIBAUNIT) PIconfig> TestUnit
*> TestUnit
In case of user error, deleting a unit will not automatically result in the deletion of the unique
PI point used to store the unit's batch data in the Archive. Instead, the batch data storage point
will simply be renamed. Examining the PI Server Message Log around the time of a unit
deletion should yield a message similar to:
0 pipoints 27-Nov-05 23:30:04
>> Point Renamed by User (1) piadmin, New Tag piba36_del, Old Tag
piba36, PointId: 8406
To completely delete the unit and all of its batch data would require the second manual step
of deleting the renamed batch data storage point (e.g. piba36_del) for that particular unit.
6.3.2 Alias Configuration
PI points are often named to reflect the instrument data source in order to provide an obvious
mapping between the two. However, in practice, except possibly for the instrument or process
engineers, it is much easier to reference a particular attribute by its unit name and common
name. Furthermore, in many cases, the unit name is implied, so the common name itself is an
unambiguous reference to the physical attribute.
For example, as shown below, a plant may have three very similar reactors with the same
three important attributes: level, temperature, and flow. The corresponding PI points for the
attributes would be different for each reactor.
Unit Name Common Attribute Name PI Point Name
Reactor1 Level LIC:129732.PV
Reactor1 Temperature TIC:135432.PV
Reactor1 Flow FIC:245433.PV
Reactor2 Level LIC:297324.PV
Reactor2 Temperature TIC:254326.PV
Reactor2 Flow FIC:245432.PV
Reactor3 Level LIC:397321.PV
PI Server Applications User Guide Page 247
Chapter 6 - PI Batch Database
Unit Name Common Attribute Name PI Point Name
Reactor3 Temperature TIC:354399.PV
Reactor3 Flow FIC:345439.PV
Aliases in the PI Batch Subsystem provide the mechanism to enable the more natural
reference to an attribute's common name instead of the more obscure instrument name.
PI Batch Alias (PIBAALIAS) Table
The configuration for all aliases is stored in the data file \PI\dat\pibaalias.nt and is accessed
exclusively via the piconfig table named PIBAALIAS. Compared to unit configuration, alias
configuration is very simple, involving only a couple of attributes listed below. The list
includes each attribute's name, data type, default value ("D:"), and current value ("C:").
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @?atr
1 - Alias String D: C:
2 - NEWAlias String D: C:
3 - Tag String D: C:
A complete description of each of the alias attributes appears below in Table 6–3.
Table 6–3. PIBAALIAS Table Attributes
Attribute Description
Alias The alias name has two components: unit name and common name.
The syntax for an alias is the following: \\unit name\common name.
The unit name must correspond to an existing unit in the PIBAUNIT
table.
NEWAlias Used to rename an existing alias.
Tag The name of the PI point associated with the alias. The PI point must
already exist
Common Operations
The following sub-sections demonstrate the common tasks of creating, listing, renaming,
editing, and deleting aliases.
Create Aliases
The following piconfig commands will create three aliases on unit Reactor1, one for each of
the attributes level, temperature, and flow:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode create
* (Cr - PIBAALIAS) PIconfig> @istr alias,tag
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\level,LIC:129732.PV
*> \\Reactor1\level,LIC:129732.PV
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\temperature,TIC:135432.PV
*> \\Reactor1\temperature,TIC:135432.PV
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\flow,FIC:245433.PV
Page 248
6.3 - Configuration
*> \\Reactor1\flow,FIC:245433.PV
List Aliases
Because aliases include the unit name, a wildcard (default: '*') is often used to select or list
specific aliases. The following piconfig commands list all aliases defined for Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode list
* (Ls - PIBAALIAS) PIconfig> @ostr alias,tag
* (Ls - PIBAALIAS) PIconfig> @select alias=\\Reactor1\*
* (Ls - PIBAALIAS) PIconfig> @ends
\\Reactor1\flow,FIC:245433.PV
\\Reactor1\level,LIC:129732.PV
\\Reactor1\temperature,TIC:135432.PV
The wildcard can be used to list a variety of other alias combinations. For example, @select
alias=* will list all aliases for all units; @select alias=\\*\temperature will list all
aliases with a common name of temperature.
Rename Aliases
Renaming of aliases is performed in edit mode using the NEWAlias attribute. The following
piconfig commands rename the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode edit
* (Ed - PIBAALIAS) PIconfig> @istr alias,newalias
* (Ed - PIBAALIAS) PIconfig> \\Reactor1\temperature,\\Reactor1\CoreTe
mp
*> \\Reactor1\temperature,\\Reactor1\CoreTemp
Edit Aliases
Edit mode is also used when changing the corresponding PI point for an alias. The following
piconfig commands change the PI tag associated with the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode edit
* (Ed - PIBAALIAS) PIconfig> @istr alias,tag
* (Ed - PIBAALIAS) PIconfig> \\Reactor1\temperature,TIC:234531.PV
*> \\Reactor1\temperature,TIC:234531.PV
Delete Aliases
The following piconfig commands delete the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode delete
* (Dl - PIBAALIAS) PIconfig> @istr alias
* (Dl - PIBAALIAS) PIconfig> \\Reactor1\temperature
*> \\Reactor1\temperature
PI Server Applications User Guide Page 249
Chapter 6 - PI Batch Database
6.4 Batch Data Information
All batch data for all units is stored in the Data Archive. When a unit is created, it is assigned
a unique Archive point named pibaN, where N is the unit’s unique integer ID, for storing
batch data specific to that unit. Each completed batch consists of two events written to the
appropriate pibaN point: an event at the start time of the batch with a System Digital State of
ActiveBatch; and an event at the end time of the batch with the actual batch data stored as a
Blob object.
6.4.1 PI Batch Data (PIBATCH) Table
The batch data events should typically never be accessed directly from the archive. Instead,
batch data should be accessed via the piconfig table named PIBATCH. The below list
includes the name, data type, default value (D:), and current value (C:) of each of the batch
data attributes.
* (Ls - ) PIconfig> @table PIBATCH
* (Ls - PIBATCH) PIconfig> @?atr
1 - UnitName String D: C:
2 - NEWUnitName String D: C:
3 - BID String D: C:
4 - BIDsearch String D: C:
5 - Count String D: 50 C:
6 - Handle String D: C:
7 - ProdID String D: C:
8 - ProdIDsearch String D: C:
9 - SearchStart String D: C:
10 - SearchStop String D: C:
11 - StartStatus String D: C:
12 - StartTime String D: C:
13 - StopStatus String D: C:
14 - StopTime String D: C:
A complete description of each of the batch data attributes appears below in Table 6–4.
Table 6–4. PIBATCH Table Attributes
Attribute Definition
UnitName The name of the unit associated with a batch. In
searches, the wildcard search string for unit
names.
NEWUnitName This attribute is not supported.
BID The name or identifier of a batch. This is evaluated
when a batch starts (+ evaluation delay).
BIDsearch The wild card search string for BatchIDs.
Count The maximum number of batches to retrieve in a
search. If not specified, the default number of
batches returned is 50.
Page 250
6.4 - Batch Data Information
Attribute Definition
Handle The unique identifier for a single batch. The format
is the following: <uniqueID>-<StopTime in UTC>.
The unique ID is the same integer (N) used in the
name pibaN of the unit's Archive point.
ProdID The name or identifier of a batch's product. This is
evaluated when a batch starts (+ evaluation delay).
ProdIDsearch The wild card search string for ProductIDs.
SearchStart The start time of a search.
SearchStop The end time of a search.
StartStatus An integer indicating the status of a batch's start
time: 0 = Not Set; 1 = Unknown; 2 = OK.
StartTime The time a batch started.
StopStatus An integer indicating the status of a batch's end
time: 0 = Not Set; 1 = Unknown; 2 = OK.
StopTime The time a batch completed.
6.4.2 Common Operations
The following sub-sections demonstrate the common tasks of creating, listing, editing, and
deleting batches.
Create Batches
New batches may only be created for existing units, and the start and stop times are subject to
the following three conditions:
The start time must be before the stop time.
The time span of the batch must not overlap an existing batch on the same unit.
There must be a registered Archive that covers the time span of the batch.
BID and ProdID are optional but typically very useful attributes. A Handle should not be
specified, for it will be generated. The following piconfig commands will create a batch for
TestUnit2:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode create
* (Cr - PIBATCH) PIconfig> @istr unitname,bid,prodid,starttime,stoptime
* (Cr - PIBATCH) PIconfig> TestUnit2,"Batch-1","Prod-1","24-Dec-05
04:00","24-Dec-05 08:00"
*> TestUnit2,"Batch-1","Prod-1","24-Dec-05 04:00","24-Dec-05 08:00"
List Batches
Recall that the following five attributes can be specified as search input to narrow the list of
batches: UnitName, BIDSearch, ProdIDSearch, SearchStart, and SearchStop. A typical
PI Server Applications User Guide Page 251
Chapter 6 - PI Batch Database
search will specify at least UnitName, SearchStart, and SearchStop. The following
piconfig commands will list all batches for TestUnit2 since December 1, 2005:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode list
* (Ls - PIBATCH) PIconfig> @ostr unitname,bid,prodid,starttime,
stoptime,handle
* (Ls - PIBATCH) PIconfig> @ostr ...
* (Ls - PIBATCH) PIconfig> @istr unitname,searchstart,searchstop
* (Ls - PIBATCH) PIconfig> TestUnit2,1-dec-05,*
*> TestUnit2,1-dec-05,*
TestUnit2,Batch-1,Prod-1,24-Dec-05 04:00:00,24-Dec-05 08:00:00,35-
1135440000
TestUnit2,Batch-2,Prod-2,24-Dec-05 08:01:00,24-Dec-05 12:00:00,35-
1135454400
* End Repeat...
Note: The command @ostr … is required to force the output of multiple batches.
Without this command, only the first batch that matches the input criteria will be
output.
When listing batches, the Count attribute must also be taken into consideration. If Count is
not specified in the input structure, then a maximum of 50 batches will be output.
For user convenience, the installed piconfig script \PI\adm\pibalist.dif specifies the same
attributes in the input and output structures as those used in the above example, the typical
search.
Edit Batches
Any combination of the following four batch attributes may be edited: StartTime,
StopTime, BID, ProdID. Modification of StartTime or StopTime is subject to the same
three conditions identified in Create Batches, and if the time modification is valid, the
respective time status attribute will always be set to 2 = "OK".
In addition to the attributes that will be modified, the batch Handle must also be specified to
uniquely identify the target batch for modification. Because a Handle encapsulates
StopTime, modification of StopTime will render that batch Handle obsolete after the edit.
The following piconfig commands modify the BID and StopTime of the last December
batch for TestUnit2:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode edit
* (Ed - PIBATCH) PIconfig> @istr handle,bid,stoptime
* (Ed - PIBATCH) PIconfig> 35-1135454400,"Batch-2Mod","24-Dec-05
14:00:00"
*> 35-1135454400,"Batch-2Mod","24-Dec-05 14:00:00"
Page 252
6.5 - Batch Subsystem Operation
Delete Batches
As when editing batches, the Handle must be specified when deleting batches. After a delete,
the Handle will always be rendered obsolete. No other attributes need to be specified. The
following piconfig commands delete the last December batch for TestUnit2 (note the Handle
changed after modifying StopTime in the Edit Batches example):
* (Ls - ) PIconfig> @table PIBATCH
* (Ls - PIBATCH) PIconfig> @mode delete
* (Dl - PIBATCH) PIconfig> @istr handle
* (Dl - PIBATCH) PIconfig> 35-1135461600
*> 35-1135461600
6.5 Batch Subsystem Operation
The following sections describe the primary operating tasks of the Batch Subsystem.
6.5.1 Check for Unit Consistency
When the Batch Subsystem first starts up, it checks all defined units (stored in
\PI\dat\pibaunit1.nt) for consistency. The consistency check includes verifying the existence
of the batch activation tags as well as any tags referenced in the expressions for generating
BatchID and ProductID. Any unit indicated as active is also checked to verify that the same
batch is still running, and if there is a discrepancy, the Data Archive is updated appropriately.
Similarly, if any unit previously indicated as inactive is detected to have an actively running
batch, the Data Archive is updated accordingly as well. If any problems are encountered,
messages are sent to the PI Message Subsystem.
6.5.2 Monitor Activation Tags for Transitions
After startup is complete, the Batch Subsystem begins monitoring all batch activation tags for
exception reports. The Batch Subsystem will remain in this state until it is shut down. If the
Batch Subsystem detects a transition for a batch activation tag from an inactive to active
state, the unit is updated to record the start of the batch. Until batch completion, all the
information for a running batch is actually stored with the unit (in \PI\dat\pibaunit1.nt). If an
active to inactive state transition is detected, the batch is considered complete, and the Blob
object containing the complete batch structure is created and finally stored in the Data
Archive.
6.5.3 Evaluate BIDExpr and ProdExpr
The Batch Subsystem normally evaluates the BIDExpr and ProdExpr to generate the
BatchID and ProductID, respectively, when the batch activation tag transitions from an
inactive to active state. The evaluation of these expressions can be delayed for a unit by using
the EvalDelay attribute. After the evaluation time, changes to any tags involved in a
BIDExpr and ProdExpr are ignored.
PI Server Applications User Guide Page 253
Chapter 6 - PI Batch Database
6.6 Client Access to Batch Subsystem Batches
Other than with piconfig, read-only programmatic access to the batches created by the Batch
Subsystem is available directly with the PI-API. Read-only programmatic access is also
available via the PI-SDK, but only if the units are first registered with the Batch Database;
this registration procedure is detailed in the document PI Batch Database Support of the PI
Batch Subsystem.
The only API-based client application is the PI BatchView add-in for Excel, but of course,
custom API applications can always be written. All other client applications such as
BatchView for PI ProcessBook or the stand-alone BatchView Quick Search are SDK-based
applications, and therefore require unit registration with the Batch Database. See
corresponding user guides for more information.
6.7 Complete Example
Installation of the Batch Subsystem does not result in the creation of any units or batches. The
installed piconfig script \PI\adm\pibatch.dif creates a sample unit and enable the automatic
creation of sample batches. Of course, the actual configuration and batch data is contrived,
but the example provides a complete functional overview of the Batch Subsystem.
Before executing the script, ensure that the Batch Subsystem and all other PI Server
subsystems are fully started. To execute the script, simply enter the following at a command
prompt after changing to the \PI\adm directory:
piconfig < pibatch.dif
The script first creates two digital sets to model BatchIDs and ProductIDs and two digital
tags, one assigned to each set, to be used in the BIDExpr and ProdExpr attributes of the
sample unit. These digital tags are configured to be serviced by the Random Simulator
Interface (executable name: random), a default interface distributed with all PI Servers, so
this interface also needs to be configured and started for the example to work properly.
The script then creates a single sample unit named Reactor1 using the default point
BA:Active.1 as the batch activation tag. If the default points were not created at PI Server
installation time, then they can be created manually by executing the following at a command
prompt after changing to the \PI\adm directory:
piconfig input defaultpt.dif input defaultpt.dat exit
BA:Active.1 is serviced by the Ramp Soak Simulator Interface (executable name: rmp_sk),
another default interface distributed with all PI Servers, so this interface also needs to be
configured and started for the example to work properly.
The script finishes with the creation of a few aliases–Temperature, Level, and Concentration–
using other default points–BA:Temp.1, BA:Level.1, and BA:Conc.1, respectively.
If the script executed without errors and all the simulator interfaces are running, a new batch
for Reactor1 should be created approximately every 81 minutes.
Page 254
Chapter 7. PI TOTALIZER SUBSYSTEM
The PI Totalizer Subsystem (Totalizer) performs common calculations such as totals,
averages, minimum and maximum values, and standard deviations. Output of a calculation is
stored in a PI point.
The main difference between a Performance Equations point and a Totalizer point calculating
the same summary is that Totalizer calculates from realtime inputs (as opposed to archived
values.) Performance Equations are based on Archive events, while Totalizer results are
based on Snapshot events.
PI Totals are the most accurate way to represent production summary data. Totalizers can be
started and reset based on time and event, and ensure the highest accuracy in the calculation
of flow volumes and other critical variables used to monitor product transfers or production
performance. Totalizer is especially practical for totaling measurements or other process
variables at the end of specific time periods, such as the end-of-day yields.
This chapter includes the following topics:
Section 7.1, Totalizer Subsystem Overview, on page 255
Section 7.2, Totalizer ConfigurationOverview, on page 258
Section 7.3, Totalizer Point Class Attributes, on page 260
Section 7.4, Build Totalizer Points, on page 286
Section 7.5, Program Operation, on page 288
Section 7.6, PI for OpenVMS Upgrade Considerations, on page 288
Section 7.7, Demonstration Points, on page 290
7.1 Totalizer Subsystem Overview
Totalizer allows you to perform certain calculations on a point in the Snapshot, and to store
the results in another point. The process is called postprocessing. Postprocessing includes the
following types of summary calculation:
• Total
• Average
• Minimum
• Maximum
• Range
PI Server Applications User Guide Page 255
Chapter 7 - PI Totalizer Subsystem
• Standard Deviation
• Median
Additionally, Totalizer permits the counting of update events for a point. The types of
counting allowed are as follows:
• All Events
• Event Equal To a value
• Event Not Equal To a value
• Event Greater Than a value
• Event Greater Than or Equal To a value
• Event Less Than a value
• Event Less Than or Equal To a value
• Event change from Greater Than or Equal To to Less Than
• Event change from Less Than to Greater Than or Equal To
The Totalizer is a dedicated subsystem, pitotal. This subsystem signs up for exceptions,
which means that it is notified when a new value is added to the Snapshot for any of the
points to be postprocessed. After postprocessing, values, for example, average, total, or time
in state, are sent back to the PI Snapshot.
Note: Since pitotal uses Snapshots of the data, postprocessing uses uncompressed
data. Its results are more accurate than those computed later from values in the
archive.
7.1.1 Totalizer vs. Performance Equations
Totalizer may be more accurate because the values used in Totalizer calculations are taken
from the Snapshot, not after the application of compression as in the case of Performance
Equations. Figure 7–1 shows an interval of time for which an accumulation of a point occurs.
Within this accumulation interval, the point also undergoes exception reporting.
First event outside of
exception specs
Events sent to snapshot
Previous reported as result of first exception
event
ExDev
ExMin
ExMax
Events that fail exception test
Events that pass exception test
Figure 7–1. Exception Reporting
Page 256
7.1 - Totalizer Subsystem Overview
The values are sent to the Snapshot if they pass the exception test defined by the ExDev,
ExMin and ExMax attributes. In Figure 7–2, 10 of the 28 values fail the exception test and
are not sent to the Snapshot. The Totalizer utilizes the 18 values that are left for the
evaluation. On the other hand, the Performance Equation Scheduler uses the compressed
values (if compression is on). Figure 7–2 shows the difference in the resultant time-weighted
calculation for the Totalizer and the Performance Equation Scheduler.
Regions that are included
and excluded for a time-
weighted calculation using
PI Totalizer
Region considered in
Time-Weighted calculation
using Compressed Values
Events that fail compression test
Events that pass compression test
Figure 7–2. Time Weighted Calculation for Totalizer and Performance Equation
The region considered for the calculation is the area under the curve created by connecting
the 18 values left from the exception test. On the other hand, the region considered by the
Performance Equation calculation would be the area under the curve that is created by
connecting the six points that are left after the compression test. In general, the difference in
accuracy between the two calculations is about 1 to 2.5 percent.
The Totalizer may also be more efficient in many cases, especially when the summary
interval is large. Consider a year-to-day calculation. If the calculation is implemented as a
performance equation, the Archive data from the beginning of the year to the current time
needs to be retrieved to carry out the calculation. On the other hand, if the calculation is
implemented as a Totalizer point, then only the new Snapshot event is needed to do the
calculation.
PI Server Applications User Guide Page 257
Chapter 7 - PI Totalizer Subsystem
7.2 Totalizer ConfigurationOverview
Totalizer is very flexible, offering a wide range of operating modes. The behavior of a
particular point is primarily determined by five multiple-choice parameters:
Table 7–1. Five Major Parameters that Affect Totalizer
RateSampleMode CalcMode Function
Natural TimeWeighted Total
Scan1 EventWeighted Average
Scan2 AllEvents Minimum
Event EventChange Maximum
TimeTrue Range
TotalCloseMode ReportMode StdDeviation
Median
Clock PeriodEnd
EventEQ
EventChange Ramping
EventNE
EventTrue Running
EventGE
NSampleMoving RunEstimate
EventGT
NSampleBlock RunEst2
EventLE
TimeMoving
EventLT
Forever
EventGE_LT
EventLT_GE
Not counting the behavior influences of the Rate Point Data Type and Step parameter, the
number of combinations of the five parameters is 12,000 (5 x 5 x 6 x 16 x 5). However, not
all of the combinations are allowed. For example, a point that is computing a total with a
TotalCloseMode option of Forever does not allow the ReportMode of PeriodEnd because
the totalization cannot stop at the end of the period. The combinations of the allowed cases
are described later in this chapter.
7.2.1 Creation of a Totalizer Point
Totalization involves several steps, as follows:
1. Sample the value (RateSampleMode) from the input point called the rate point
(SourceTag).
2. Possibly exclude the value based on a filter (Filter Expression).
3. Accumulate the observed values as needed for the specified summary function
(Function and CalcMode).
4. Determine when the Totalizing period is complete and the accumulators need to be
reset (TotalCloseMode).
5. Report the result (ReportMode).
Page 258
7.2 - Totalizer ConfigurationOverview
Figure 7–3 shows a flow diagram for the steps that are involved in creating a Totalizer point.
TotalCloseMode
- Schedules the time for the
reset of the accumulation and
when the value is set to PI
Filter Expression Snapshot
- Filters out the values
sent to the accumulation
Function/
ReportMode
CalcMode
RateSampleMode - Determines
Source - Determines Totalizer
- Determines the manner in
Tag the type of Tag
the type of which the result
calculation that
sampling is sent to PI
is done for the
Snapshot
accumulation
Figure 7–3. Flow Diagram for the Creation of a Totalizer Point
7.2.2 Totalizer Input Values
Each Totalizer point has a single input called the source or rate point. This is the point whose
values are summed, counted, or otherwise accumulated to produce the required summary
value. The arrival of a new rate point value triggers the accumulation and reporting functions
of each Totalizer point. Most often this process will be “naturally” scheduled, that is every
new value reported to the system will be processed into the ongoing accumulation.
Filtering
Each point may have one filter expression. This expression is evaluated each time that a new
update value is received for each tag referenced in the expression. The results are stored in
time order until the next rate point value is received.
Accumulation
The accumulation step takes the previous and current rate point values into account when
adding to the accumulators. If a filter is specified, the stored filter expression results are also
considered. The details of the accumulation depend on the specified functions. The available
functions are: total, average, minimum, maximum, range, standard deviation, count (of
digital states), and timer.
Accumulation Interval
The accumulation interval is the interval of time for which a postprocessing calculation
occurs. Totals are often generated for intervals specified by a period and an initial start time.
Alternatively, the interval may be defined by external events using a trigger expression in PE
form.
Output
The output of the results is usually reported at the end of the accumulation interval. The
output can also be estimated before the completion of the accumulation interval. A running
result is also available.
PI Server Applications User Guide Page 259
Chapter 7 - PI Totalizer Subsystem
7.3 Totalizer Point Class Attributes
The points to which the Totalizer writes its postprocessed values must be of the Totalizer
Point Class. This class has both Base and Totalizer attributes. Table 7–2 lists the additional
attributes in the Totalizer Point Class attribute set. These Totalizer-specific parameters drive
the totalization process.
The data types for the five major attributes, RateSampleMode, TotalCloseMode,
ReportMode, Function, and CalcMode as well as the SourceTag, Options, and CompVal,
are strings and are not case-sensitive. The filter and event expressions use the Performance
Equation syntax. Period, Period2, Offset and Offset2 are relative timestamps while the rest
of the attributes are real numbers.
Table 7–2. Totalizer Point Class Attribute Set
Point Attribute Default Value or Notes
Valid Options
SourceTag Point to be postprocessed. (See Options, below in
this table, for SourceTag values.)
RateSampleMode Natural (default) Processes when new rate point value arrives.
Scan1 Time based samples based on Period2 and
Offset2, interpolated between update events.
Scan2 Time based samples based on Period2 and
Offset2, extrapolated from the value of the last
seen event.
Event Triggered only when EventExpr changes.
TotalCloseMode Clock (default) Accumulation interval based on Period and Offset
parameters.
EventChange Closes when EventExpr result changes value.
EventTrue Totalizer on while value of EventExpr is non-zero.
NSampleMoving Period based upon a fixed number of input values
that is set with the MovingCount parameter.
NSampleBlock Period based upon a block of input values. The
number of input values for the block is set with the
MovingCount parameter.
TimeMoving Moving time window based on Period.
Forever Never resets unless no previous valid point can be
found or Options attribute is settable (for total,
event counting or time only).
Page 260
7.3 - Totalizer Point Class Attributes
Point Attribute Default Value or Notes
Valid Options
ReportMode PeriodEnd No output until period end.
Ramping Running result update to PI Snapshot at the time of
the update (sawtooth).
Running (default) Running result update to PI Snapshot at one
second after the period start time.
RunEstimate Projected output based on current rate value.
RunEst2 Projected output based on average value.
Function Total (default) Numeric rate points only.
Average Numeric rate points only.
Minimum Numeric rate points only.
Maximum Numeric rate points only.
Range Numeric rate points only.
StdDeviation Numeric rate points only.
Median Numeric rate points only.
Events Numeric, digital, or string points.
EventEQ Numeric or Digital points.
EventNE Numeric rate points only.
EventGE Numeric rate points only.
EventGT Numeric rate points only.
EventLE Numeric rate points only.
EventLT Numeric rate points only.
EventGE_LT Change counter from >= to < (numeric or Digital
points).
EventLT_GE Change counter from < to >= (numeric or Digital
points).
CalcMode TimeWeighted Values used in calculation weighted in proportion
(default) to duration during period.
EventWeighted The value of each update carries the same weight.
AllEvents Count all events matching condition.
ChangeEvents Count only events that were changes of value from
the previous update.
TimeTrue Time in seconds event condition is true.
ZeroBias 0.0 Rate point value is zero below this value.
Period +1h Period of postprocessing used for
TotalCloseMode.
PI Server Applications User Guide Page 261
Chapter 7 - PI Totalizer Subsystem
Point Attribute Default Value or Notes
Valid Options
Offset +0m Offset from beginning of day of the start of
Totalizer.
MovingCount 2 Number of input values for NSampleMoving or
NsampleBlock.
Period2 +2m Used for RateSampleMode in Scan1 and Scan2.
Offset2 +0m Used for RateSampleMode in Scan1 and Scan2.
PctGood 85 Lower limit on the percentage of input data that
needs to be good.
Conversion 1 Conversion factor multiplies the accumulation
result.
FilterExpr Performance equation expression that filters the
rate point.
EventExpr Performance Equation expression used in
TotalCloseMode and RateSampleMode.
CompValue ON Comparison value for event counting and time
conditions expressed in the Function parameter.
Options Field contains zero or more keywords for optional Functions.
InFromTotalizer The rate point value is from an external (DCS)
Totalizer block.
UnderIsBad Under range condition on rate point is bad data
(default is zero).
NoClampZero Enable output to be less than zero.
CloseAtEvent Event ends accumulation interval.
Setable TotalCloseMode of Forever can be set externally.
OneAtStart Report is one value at 1 second into of the period
for the ReportMode of PeriodEnd.
OneAtEnd Report is one value at the end of the period for the
ReportMode of PeriodEnd.
UnderIsZero Source tag values are UnderRange (status code)
are considered to be at the source tag zero value.
OverIsTop Source tag values are OverRange (status code)
are considered to be at the source tag zero+span
value.
SourceStat Use a bad source tag status in place of “Bad
Total”.
LimitBack Limits the number of totalization periods that will be
reported between source tag events.
Page 262
7.3 - Totalizer Point Class Attributes
7.3.1 SourceTag
The SourceTag attribute specifies the rate point, which is the primary input for the
postprocessing. This rate point must already exist and must be specified when the Totalizer
point is configured. The rate point may be any numeric, digital, or string point types. The
value and timestamp used in the postprocessing calculation is taken when an update of the
rate point arrives.
7.3.2 RateSampleMode
The RateSampleMode attribute specifies when the individual values from the rate point will
be used in the calculation or will be added to the accumulation. The default option for the
RateSampleMode is Natural.
Natural (default)
Natural is the default and most common option. Figure 7–4 shows the update values of the
rate point. The values that are considered in the postprocessing calculation are the update
values that lie within the accumulation interval.
Update values of the rate point
Accumulation
Interval
Figure 7–4. Natural Sampling
Depending on the other attributes such as the TotalCloseMode, ReportMode, Function, and
CalcMode, the calculation of the result may or may not involve the update values of the rate
point outside the accumulation interval. These features are discussed later in the chapter.
Scan1
Scan1 uses the attributes Period2 and Offset2 to sample the rate point at evenly spaced time
intervals. Values that lie within two updates of the rate point values are linearly interpolated.
Hence, Scan1 does not compute the completed results until the rate point after the
accumulation interval end time, as shown in Figure 7–5.
PI Server Applications User Guide Page 263
Chapter 7 - PI Totalizer Subsystem
Accumulation
Interval
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate tag
Values of rate point
Figure 7–5. Scan1 Sampling
The values used in the calculation are the interpolated values at the timestamps set using
Period2 and Offset2. Also, note that the sample rate may or may not coincide with the
postprocessing period. For digital point counting, the digital state does not change until the
update event of the rate point is a different digital state. Hence, Scan1 will be similar to Scan2
in that the digital state at a particular scan of the rate point will be the last seen digital state of
the rate point.
Scan2
Scan2 is like Scan1 in that it also samples at evenly spaced time intervals using the attributes
Period2 and Offset2 except that sampled values are calculated from the last seen event. The
value is projected almost as though the Step option was set. Scan2 performs similarly to
Scan1 when counting digital states, as shown in Figure 7–6.
Page 264
7.3 - Totalizer Point Class Attributes
Accumulation
Interval
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate tag
Values of rate point
Figure 7–6. Scan2 Sampling
Event
Event uses the event expression specified in the EventExpr attribute to determine when to
sample the rate point. Sampling occurs when there is a change in the value of the event
expression, as shown in Figure 7–7.
Accumulation Interval
Scan rate based
change in value of
EventExpr
Interpolated values of rate tag
Values of rate point
Figure 7–7. Event Sampling
The values used in the calculation are linearly interpolated between values of the rate point
and timestamped at the time when the value of the event expression changes. Event performs
similarly to Scan1 in counting digital states.
PI Server Applications User Guide Page 265
Chapter 7 - PI Totalizer Subsystem
7.3.3 TotalCloseMode
The option set in the TotalCloseMode attribute determines the accumulation interval. The
Totalizer functions accumulate data over the accumulation interval. The calculation is “closed
out” at the end of the accumulation interval and the “next event” occurs.
Note: “Closed out” means that the result is calculated and reported and the internal
state of the accumulation function is reset. The “next event” refers to either a value of
the rate point updating or an event from the event expression or the filter expression
for the Totalizer point being updated.
Clock (default)
In TotalCloseMode of Clock, the Totalizer runs and resets at regular time intervals. The
times are specified through two attributes, Period and Offset. Period is the length of each
accumulation interval. Offset specifies the start of the first interval. The accumulation begins
at the start of the day on which the Totalizer is started plus the amount of time given in the
Offset parameter. Period is a relative time of any length. Clock is the default setting for this
option.
The Period parameter may be specified as local time or UTC (Universal Coordinated Time).
Periods longer than one hour that have no specifier are assumed to be local time. This allows
totalization intervals to start at the same time every day even when the clocks are reset for
Daylight Savings Time.
The Offset is a relative timestamp that is less than the Period. Figure 7–8 shows an example
of the Clock option of the TotalCloseMode.
Accumulation
Interval Values of rate point
Event from
EventExpr
Event from
FilterExpr
Figure 7–8. TotalCloseMode of Clock
In this example, although the accumulation ends, the actual close of the accumulation does
not occur until the rate point updates. This event can occur well after the end of the
accumulation interval. When the update event occurs, the calculated result is written to the
Archive with timestamps of the actual totalization interval.
Page 266
7.3 - Totalizer Point Class Attributes
For the RateSampleMode of Scan2, the close out of the accumulation occurs at the first
update event at or after the end of the period. In Natural, Scan1 and Event, the closeout of the
accumulation occurs only when the rate point value updates.
EventChange
This option connects the totalization period to external events. It requires a valid event
expression be defined in the EventExpr attribute. The current accumulation will end and
reset whenever the result of the event expression is different from that of the previous event
expression calculation.
If the expression includes PI tags referencing the Snapshot, it is evaluated on a natural
schedule. That is, it is recalculated whenever there is a new update for any of the tags.
Expressions that do not reference Snapshot values are evaluated at times specified by the
period and offset parameters but only when rate tag events beyond these times have been
received. PI time functions may be used in these expressions to establish many useful
intervals.
A naturally scheduled expression is only evaluated as each update is received for the real PI
tags in the expression. The times of these events are used in the evaluation of any time
functions in the expression. Tags that come from the same source (interface or remote PI
system) as that of the rate tag should be used to assure synchronization of these critical timing
events. The Option, CloseAtEvent may be used to force prompt closing of the Totalizer at the
period end time. Time-weighted totals will assume the rate tag to be constant at the last value
observed to the end of the period.
Expressions that contain no PI Snapshot references are evaluated at times specified by the
Period and Offset parameters. These calculations are only performed when new updates on
the rate tag are received. As each rate tag update arrives, its timestamp is compared with the
next time the expression is due for calculation. If the due time is prior to the event timestamp,
the expression is evaluated before the new event is fully processed.
Values of rate point
Accumulation
Interval
Time at which
result sent to PI
Event from EventExpr SnapShot for Time at which
RateSampleMode result sent to PI
of Scan2 and Snapshot for
Event RateSampleMode
of Natural and
Scan1
Figure 7–9. TotalCloseMode of EventChange
As shown in Figure 7–9 for Natural and Scan1, the result of the accumulation will be delayed
and not be sent to PI Snapshot until an update for the rate point is observed. If the event
PI Server Applications User Guide Page 267
Chapter 7 - PI Totalizer Subsystem
expression does not contain a point but only a time function, it will also be evaluated with the
RateSampleMode of Natural based on the rate point.
EventTrue
This option also requires a valid event expression to be defined in the EventExpr attribute. In
this case, as shown in Figure 7–10, an accumulation interval is started when the event
expression result is evaluated to be non-zero. Accumulation will continue until the event
expression is evaluated to give a zero result, at which point the Totalizer is closed out and
placed in a non-calculating state. The Totalizer point will be marked with the system status
condition “Good-Off” to indicate that no postprocessing data will be available for the
interval.
The times at which the event expression is evaluated is different depending on whether or not
a tag is specified in the event expression. See the description of the EventExpr attribute for
details about when the EventExpr is evaluated.
Values of rate point
Interval
Accumulation Accumulation
Labeled as
Interval #1 Interval #2
Good-Off
Time at which Time at which
result sent to PI Time at which result result sent to PI
SnapShot for sent to PI Snapshot SnapShot for
RateSampleMode for RateSampleMode RateSampleMode
of Scan2 and of Natural and Scan1 of Scan2 and
Event for for Accumulation Event for
Accumulation Interval #1 Accumulation
Interval #1 Interval #2
EventExpr <> 0 EventExpr = 0
Figure 7–10. TotalCloseMode of EventTrue
Similar to EventChange, the time at which the results are sent to PI Snapshot for
RateSampleMode of Scan2 and Event is when the event expression is equal to zero and
closes out the accumulation. The time at which RateSampleMode of Natural and Scan1
closes out the accumulation is when an update from the rate point occurs.
NSampleMoving
The accumulation interval is defined as the time required to sample the rate point a specified
number of times. The actual time will be based upon the RateSampleMode and the filter
expression. The number of values used in the calculation for this TotalCloseMode option is
set in the MovingCount attribute. The NSampleMoving option only supports the
ReportMode option of Ramping.
Page 268
7.3 - Totalizer Point Class Attributes
Figure 7–11 shows two accumulation intervals with the MovingCount set to 3. Also, a filter
expression is used to limit the values of the RateSampleMode option of Natural used in the
accumulation.
Accumulation Interval #2
Accumulation Interval #1
Filter Filter Filter
Values of rate point that
are filtered out Time at which result Time at which result
sent to PI SnapShot sent to PI Snapshot
Values of rate point Accumulation for Accumulation
Interval #1 Interval #1
Figure 7–11. TotalCloseMode of NsampleMoving (1)
The accumulation waits for the number of inputs defined by MovingCount and then
performs the calculation and sends the results to PI Snapshot. As a new sample arrives, the
value at the beginning of the accumulation is left out to incorporate the most recent value and
a new result is calculated and posted. In the above example, the values that are used do not
include the values excluded by the filter expression. For the RateSampleMode of Scan1,
Scan2, and Event, values that are included in the accumulation are interpolated from the
values of the rate point.
Figure 7–12 shows an example of RateSampleMode of Scan1 with a filter expression.
PI Server Applications User Guide Page 269
Chapter 7 - PI Totalizer Subsystem
Time at which result sent to PI Time at which result sent to PI
SnapShot for Accumulation SnapShot for Accumulation
Interval #1 is at the update of Interval #3 is at update of rate
rate point point even when filter is active
Accumulation Accumulation Interval
Interval #2 #4
Accumulation Accumulation
Interval #1 Interval #3
D
B E
C
Filter Filter Filter
Interpolated values of rate point
Time at which result sent to PI
Interpolated values of rate point that SnapShot for Accumulation
are filtered out Interval #2 is at update of rate
point
Values of rate point
Figure 7–12. TotalCloseMode of NSampleMoving (1)
Due to the configuration of the scan rate, the number of accumulations for the same number
of updates for the rate point doubles to four intervals. In the figure, the update values from the
rate points labeled as A and C are used to generate three interpolated values. Although the
update of the rate point C is within the time when the filter expression is true, it is used as a
reference point to generate interpolated values from update rate point values labeled as A and
C and also from C to E. Notice that the interpolated values (labeled as B and D) that occurred
when the filter expression was used, were excluded. Furthermore, in this example, the times
at which the results are sent to the Snapshot are at updates of the rate point.
NSampleBlock
The accumulation interval is defined as the time required to sample the rate point a specified
number of times. The actual time will be based upon the RateSampleMode and the filter
expression. The number of values used in the calculation for this TotalCloseMode option is
set in the MovingCount attribute. With NSampleBlock, the accumulation is in blocks of
events. The NSampleBlock option only supports the ReportMode option of PeriodEnd.
Figure 7–13 shows three accumulation intervals with the MovingCount set to 3. Also, a filter
expression is used to limit the values of the RateSampleMode option of Natural used in the
accumulation.
Page 270
7.3 - Totalizer Point Class Attributes
Figure 7–13. TotalCloseMode of NSampleBlock
The accumulation waits for the number of inputs defined by MovingCount and then
performs the calculation and sends the results to PI Snapshot. In the example (Figure 7–13),
the values that are used do not include the values excluded by the filter expression.
Accumulation Interval #1 shows the first accumulation interval after the start of the Totalizer,
the accumulation interval starts at the time of the first event and closes at the time of the last
event. The next accumulation level starts after the end of the prior accumulation interval and
stops after three new events (which are not filtered) are processed. Notice that this second
accumulation interval and subsequent accumulation intervals will all start at one second after
the close of the prior interval.
TimeMoving
This option is similar to the previous case except the time for accumulation is specified
rather than the number of samples. The accumulation time is specified in the Period attribute.
As a value for accumulation is received, the Totalizer goes back a certain amount of time that
is specified by the Period parameter and checks to see if the Totalizer has started or that the
rate point has been created for postprocessing. If either of the conditions is not true, then the
point is entered into a circular queue. When conditions (start of Totalizer and point created
for rate point) are true, then the accumulation interval is set and a value for the beginning of
the period is interpolated between two update values of the rate point.
Figure 7–14 demonstrates the beginning of a TimeMoving accumulation. In this example, the
first accumulation interval does not begin until the fourth update of the rate point because the
fourth point is the first instance where the accumulation interval does not extend to the start
of the Totalizer.
PI Server Applications User Guide Page 271
Chapter 7 - PI Totalizer Subsystem
Start of Totalizer
Accumulation
Interval
Filter Filter
Values of rate point that At this update of rate
point Accumulation Time at which result
are filtered out
Interval still goes sent to PI Snapshot
beyond start of for Accumulation
Values of rate point Totalizer Interval
Figure 7–14. TotalCloseMode of TimeMoving and RateSampleMode of Natural
The shaded region represents the area under the curve for which postprocessing for the
CalcMode option of TimeWeighted is calculated. This is discussed in CalcMode on page
277. In another example, the RateSampleMode is Scan2 whereby the value of the last update
of the rate point is used as 0the interpolated value.
At this update of rate points Time at which result
Accumulation Interval still sent to PI SnapShot
goes beyond start of Totalizer for Accumulation
Interval #2 is at
update of rate point
Accumulation
Start of Totalizer Interval #2
Accumulation
Interval #1
Time line for
scan rate of
Filter Filter
Scan2
Time line for natural Time at which result
scan rate of filter Interpolated values of rate point sent to PI SnapShot for
expression Accumulation Interval
Interpolated values of rate point that #1 is at scan rate of
are filtered out filter expression
Values of rate point
Figure 7–15. TotalCloseMode of TimeMoving and RateSampleMode of Scan2
Since the interpolated values of the rate point depend only on a prior update of the rate point,
the scan rate of the filter expression is also important. In the figure above, the time at which
Page 272
7.3 - Totalizer Point Class Attributes
the results for accumulation interval #1 is at the natural scan rate of the filter expression and
does not need to be delayed to the time of the update of the rate point. For this example, if the
filter expression did not exist, then both the results from accumulation interval #1 and #2
would have been sent to the Snapshot at the update of the rate point. The start of the Totalizer
is when the Totalizer Subsystem begins. If the file, pilasttot_T.dat does not exist in the pi\dat
directory, the start of the Totalizer would be at the time when the Totalizer last started. If the
file does exist, then the start of the Totalizer is at the time specified in the pilasttot_T.dat. The
only valid option for the ReportMode attribute is Ramping.
Forever
In this mode, the Totalizer never resets. When restarted, it continues from the value found in
the resultant point. This option works for total and all of the count and timing functions.
Some external force may change the Totalizer point only if the Option point attribute is set to
Setable. In this event, the new value will be used as the base for the next Totalizer result. The
only valid option for ReportMode is Ramping. The only functions allowed are Total,
Maximum, Minimum and event counting functions.
7.3.4 ReportMode
The option set in the ReportMode attribute specifies the manner in which the Totalizer
results will be sent to the PI Snapshot. Table 7–3 lists the allowed combinations of
TotalCloseMode and ReportMode where ‘X’ denotes the allowable option.
Table 7–3. Allowed Combinations of TotalCloseMode and ReportMode
ReportMode (X indicates combinations that are allowed)
TotalCloseMode Period End Ramping Running Run Estimate RunEst2
Clock X X X X X
EventChange X X X
EventTrue X X X
NSampleMoving X
NSampleBlock X
TimeMoving X
Forever X
PeriodEnd
No output is reported until the end of the accumulation period. At that time, the Totalizer
sends the calculated result twice by default. The value is sent once with a timestamp of the
start of the accumulation period plus one second, and again with a timestamp at the end of the
accumulation interval. The result on a trend display in PI ProcessBook is a horizontal line of
the result value through the period of the totalization. An Archive query for the result will
return the same value any time during the period. The Option parameter may be used to
change the default to write a value only at the beginning of the period (OneAtStart) or only at
the end of the period (OneAtEnd).
PI Server Applications User Guide Page 273
Chapter 7 - PI Totalizer Subsystem
Ramping
The Ramping option result is a running result that is sent to PI Snapshot when an update
event occurs. Using the Function option Total with Ramping will result in a sawtooth trend
on a trend display that ramps up and then resets.
Running (default)
The Running option result is output to the PI Snapshot as each rate point event is received. It
is sent with a timestamp of one second into the current totalization period. If the Archive
compression specification CompMin is set to one second, the successive values will not be
recorded in the Archive, but will be available for display. Running is the default setting for
ReportMode.
RunEstimate
A new result is sent to the PI Snapshot as each rate point event is processed. The value is an
estimate of the result if the rate point were to hold steady at its current value. RunEstimate
can only be used for the Function option of Total.
RunEst2
A new result is sent to the PI Snapshot as each rate point event is processed. The value is an
estimate of the result if the rate point were to hold steady at the average observed so far in
this accumulation interval. RunEst2 can only be used for the Function option of Total.
7.3.5 Function
The combination of Function and CalcMode parameters defines the primary behavior of a
Totalizer point. The first seven Function options (Total, Average, Minimum, Maximum,
Range, StdDeviation, and Median) are intended for use with numerical rate points only. The
first two CalcMode options (TimeWeighted and EventWeighted) define the kind of
accumulation.
The remaining functions ("Events:" EventEQ, EventNE, … ) are for counting events and are
primarily intended for use with digital rate points. Besides the Function option of Events,
they compare the rate point value to the CompValue parameter, which is expected to be the
text of a digital state. They will also work with numeric points and a valid number in
CompValue. Each is a counter for a CalcMode of AllEvents or ChangeEvent. The result is a
time when the CalcMode is TimeTrue. Internally, the time is accumulated in seconds. The
result is multiplied by the Conversion parameter before being sent to the PI Snapshot.
Table 7–4 shows the allowed combinations of Function and CalcMode options where X
denotes the allowed combinations.
Table 7–4. Viable Function and CalcMode Options
Math Counting Timing
Function Time Event All Change Time
Weighted Weighted Events Events True
Total X X
Page 274
7.3 - Totalizer Point Class Attributes
Math Counting Timing
Average X X
Minimum X X
Maximum X X
Range X X
StdDeviation X X
Median X
Events X X
EventEQ X X X
EventNE X X X
EventGE X X X
EventGT X X X
EventLE X X X
EventLT X X X
EventGE_LT X X X
EventLT_GE X X X
Some example combinations are as follows:
Function CalcMode Comp Value Result
EventEQ ChangeEvent Manual Number of times the rate point switched
to Manual
EventNE TimeTrue Manual Total time the rate point was in some
state other than Manual
Events AllEvents Total number of updates received by
the rate point
Total (default)
The result is the totalization of the rate point value. If CalcMode is EventWeighted, this is the
sum the values from the individual rate point value update events. TimeWeighted uses
trapezoidal integration to produce the total. Caution should be used in choosing the
RateSampleMode option. If the goal is for a total of the values of a rate point, the Natural
option should be used. The other RateSampleMode options will extrapolate values from
defined time points and may lead to incorrect totals.
Average
The result is the average of the rate point value. If the CalcMode is EventWeighted, the
average is the totaled individual update events and divided by the number of events. The
PI Server Applications User Guide Page 275
Chapter 7 - PI Totalizer Subsystem
CalcMode option of TimeWeighted considers the time between events, dividing by the area
under the curve by the time interval.
Maximum or Minimum
The result is the maximum or minimum observed value of the input. If the CalcMode is
EventWeighted, the result will be one of the input values. If there is a filter expression active
and the CalcMode is TimeWeighted, the result may be an interpolated value corresponding to
the time when the filter changed state.
For TotalCloseModes of NSampleMoving and TimeMoving, a sorted list of all of the values
seen during the period is maintained.
Range
The result is the difference between the maximum and minimum observed values of the
input. If the CalcMode is EventWeighted, the result will be one of the input values. If there is
a filter expression active and the CalcMode is TimeWeighted, the result may be an
interpolated value corresponding to the time when the filter changed state.
For TotalCloseModes of NSampleMoving and TimeMoving a sorted list of all of the values
seen during the period is maintained.
StdDeviation
The result is the standard deviation of the observed data. Both time- and event-weighted
forms are available.
For TotalCloseModes of NsampleMoving, an array of intermediate results is kept.
StdDeviation is not supported for TotalCloseMode option of TimeMoving with CalcMode
option of EventWeighted.
Median
The Median value is the middle observed value of the input. If there is an even number of
values in the sample, an average of the center two is selected. Using Median with a short time
interval can be very effective as a filter for noise removal.
For TotalCloseModes of NSampleMoving and TimeMoving a sorted list of all of the values
seen during the period is maintained.
Counting and Timing Functions
The following Function options are used for counting and timing operations. The allowed
CalcMode options are AllEvents, ChangeEvents, and TimeTrue.
Events
This Function option counts all event updates of the rate point that pass exception handling
and the filter expression. The allowed CalcMode options are AllEvents and ChangeEvents.
Caution should be used if the RateSampleMode option is not Natural. Using the other three
Page 276
7.3 - Totalizer Point Class Attributes
options of the RateSampleMode with Events will result in counting the interpolated values
as event updates.
EventXX
The set of Function options denoted as EventXX (EventEQ, EventNE, EventGE, EventGT,
EventLE, and EventLT) is used to count the number of update events that pass exception
handling. The filter expression or is used to find the time that the value of the rate point meets
the condition of the Function. As rate point events are received, they are compared to the
value in CompValue parameter to produce a true or false result.
For CalcMode of AllEvents, true events are simply counted. ChangeEvents will only count
those events that have values different than the immediately previous event. Consecutive
events with the same value will be skipped. For the TimeTrue mode, the true event starts a
timer and a false event stops it.
EventXX_XX
The set of Function options denoted as EventXX_XX (Event LT_GE and EventGE_LT) is
used as transition counters. They are used to count the number of times the update events
(that pass exception handling and the filter expression) pass through the value set in the
CompValue attribute or are used to find the time that the value of the rate point meets the
condition of the Function. As rate point events are received, they are compared to the value
in CompValue parameter to produce a true or false result.
For CalcMode of AllEvents, true events are simply counted. ChangeEvents will only count
those events that have values different than the immediately previous event. Repeat events
with the same value will be skipped. For the TimeTrue mode, the true event starts a timer and
a false event stops it.
7.3.6 CalcMode
The value set in the CalcMode parameter modifies the Function parameter. The first two
options (TimeWeighted and EventWeighted) can only be used with math functions while the
last three (AllEvents, EventChange, and TimeTrue) can only be used with counting functions.
TimeWeighted
The time between input values is (default)considered in totalization and average functions.
This is the normal option for accumulating flow signals into totals for the period. Figure 7–16
demonstrates a time-weighted total for both RateSampleMode options of Natural and Scan1.
PI Server Applications User Guide Page 277
Chapter 7 - PI Totalizer Subsystem
Accumulation
Interval
Time Weighted Total for
RateSampleMode of Natural with
step attribute of rate point = 0 or
RateSampleMode of Scan1
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate point
Values of rate point
Figure 7–16. TimeWeighted Total for Natural and Scan1 with Step=0
In both cases, the total will be similar. The area considered for totalization is the shaded
region. Furthermore, if the Step attribute of the rate point is 0, then that indicates that the
values between the update points are interpolated. If the value of the Step attribute is 1, then
the Scan1 RateSampleMode is overwritten and the totalization would be as if Scan2 was the
intended option. Figure 7–17 shows the plots for a totalization for the RateSampleMode
options of Natural and Scan2 with the Step option set at 1.
Addition area that
is considered for
Accumulation RateSampleMode
of Natural and
Interval
Rate point step =
1
Time Weighted Total for Scan2
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate point
Values of rate point
Figure 7–17. Time-Weighted Total for Natural and Scan2 with Step=1
When the Step attribute is “on” (equal to 1) then the value of the rate point remains the same
until a new update value is seen. This is similar to Scan2. For the example in the previous
figure, the totalization for Scan2 is shown in the shaded area. This, however, is different than
the area for Natural scanning with Step equal to 1. For this specific example, the totalization
Page 278
7.3 - Totalizer Point Class Attributes
considers both the two shaded patterned areas as well as the shaded area for Scan2. Even if
Step = 0 for Scan2, the totalization would be the same.
EventWeighted
Here each rate point value is taken to be a discrete addition to the accumulated result. Time
is not considered. Each event has the same weight. In the first example shown in Figure 7–18,
the RateSample mode is Natural and the Function is Total.
Accumulation
Interval
XB
XA B
A
Total = XA+XB
Figure 7–18. Event-Weighted Total for Natural
In this case the accumulation interval contained two updates of the rate point labeled as A and
B. Therefore, the result is the summation of the values (XA and XB) of the rate points.
In another example shown in Figure 7–19 the RateSampleMode is Scan1 and the Function
is Average.
XD
XC
Accumulation
XE Interval
XB
C D
XA E
B
A
EventWeighted XA+ XB + XC + XD + XE
Average =
5
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate point
Values of rate point
Figure 7–19. Event-Weighted Average for Scan1
PI Server Applications User Guide Page 279
Chapter 7 - PI Totalizer Subsystem
The scan rate generated five interpolated values labeled as XA through XE, and the average
would be the sum of the values divided by the number of interpolated events. Use caution if
you want to use the Function option of Total with EventWeighted and the RateSampleMode
options of Scan1, Scan2, and Event. In the above example, since the events were interpolated,
the total from the interval would be the summation from XA through XE.
AllEvents
With the Function option of Events, the CalcMode option AllEvents counts all value
updates. For the rest of the event functions that use the CompValue attribute for comparison
with the update value, this CalcMode option counts all the events for which the comparison
is true. This means that events that repeat the same value will be counted.
In Figure 7–20, the digital states can be represented on a timeline by plotting the digital state
offsets for the two digital states “on” and “off.”
Accumulation
Interval
Digital State Offset
OFF OFF
ON ON
Figure 7–20. Digital States with RateSampleMode of Natural
For the Function of Events, the count for the accumulation interval is 2. If the Function is
EventEQ and the CompValue is “on,” then the result is 1. For functions such as EventGT, the
comparison is made based on the digital state offset. Since “on” has a lower digital state
offset value than “off” for this example, using EventGT would result in counting the “off”
event that occurred within the accumulation interval.
In another example shown in Figure 7–21, the RateSampleMode is Scan1. The value of the
digital state at the time set by the scan rate is the digital state for the last seen update event.
Hence, using Scan1 or Scan2 would be similar.
Page 280
7.3 - Totalizer Point Class Attributes
Accumulation
Interval
OFF OFF OFF OFF
Scan rate based
ON ON ON ON ON on Period2 and
Offset2 attributes
Interpolated digital states of rate point
Digital states of rate point
Figure 7–21. Digital States with RateSampleMode of Scan1 or Scan2
The result of Function option Events is 5 and the result of EventEQ is 3 and the result of
EventGT is 2.
ChangeEvents
In the event class of functions, the count is only those updates that satisfy the condition and
that were real changes of value. Therefore, the count represents not the update events but the
changes of the update events. For the example shown in AllEvents where the
RateSampleMode could be either Scan1 or Scan2, the result of the function option Events is
2 and the result of EventGT is 1.
TimeTrue
This CalcMode option results in the duration of the conditions to be accumulated. Internally,
time is accumulated in seconds. The result is multiplied by the Conversion parameter before
being sent to the PI Snapshot. For the Function of EventEQ and CompValue of “on”,
TimeTrue will find the time within the accumulation interval that the digital state was “on”.
7.3.7 ZeroBias
The value of the rate point will be considered to be zero if less than this value.
7.3.8 Period
The Period attribute is used by the TotalCloseMode option of Clock to set the accumulation
interval. It accepts relative timestamps. For example, ‘+1h’, ‘+30m’, and ‘+1d’ will set the
accumulation interval to one hour, 30 minutes, and one day, respectively.
Periods longer than one hour are understood to be in local (wall clock) time. That is, for
periods that evenly divide into 24 hours, the totalization times will be the same from day to
day as the system changes to/from Daylight Savings Time (DST).
PI Server Applications User Guide Page 281
Chapter 7 - PI Totalizer Subsystem
Optionally, the time interval may be specified to be in local (wall clock) or UTC (fixed
period) terms. This is done by appending a /local or /utc to the parameter. Actually, only the l
or c is needed.
For example, ‘+8h /local’ specifies 8 hour shifts instead of absolute 8 hour periods. This
means that for the 8-hour totalization period that spans the time change from Daylight to
Standard, the actual period length would be 9 hours. When the time changes from Standard to
Daylight, the actual period would be 7 hours.
7.3.9 Offset
The relative timestamp set in the Offset attribute is used by the TotalCloseMode option of
Clock to determine when to begin the initial accumulation. The Offset is a relative timestamp
that must be less than the relative timestamp set in the Period attribute. For example, if
Offset is ‘+12h’ and Period is ‘+1d’, the Totalizer will begin the accumulation calculation at
noon on the day that the Totalizer starts and will accumulate data for a period of 24 hours.
7.3.10 MovingCount
The value in MovingCount attribute is used by the TotalCloseMode option of
NSampleMoving and NSampleBlock to determine the number of samples for the accumulation
interval.
7.3.11 Period2
The Period2 attribute is used by the RateSampleMode options of Scan1 and Scan2 to set the
sampling rate. It accepts relative timestamps. For example, ‘+1m’, ‘+30s’, and ‘+ 1h’ will set
the accumulation interval to one minute, 30 seconds, and one hour, respectively. The Period2
attribute also accepts the optional /local and /utc flags.
7.3.12 Offset2
The relative timestamp set in Offset attribute is used by the RateSampleMode option of
Scan1 and Scan2 to determine when to start sampling. Offset2 is a relative timestamp that
must be less than the relative timestamp set in the Period2 attribute. The Totalizer will use
the beginning of the day for which the Totalizer is started as the reference point for when to
account for Offset2 and move in intervals set by Period2 and sample at the next appropriate
beginning of a period. For example, if Offset2 is ‘+10s’, Period2 is ‘+1m’, and the start of the
Totalizer is at noon, the first sample will be taken at noon plus 10 seconds and the next
sample will be taken at 12:01:10.
7.3.13 PctGood
PctGood is a number between 0 and 100 (in percent). If rate tag values are bad for a larger
fraction of the totalization period, the output of the Totalizer will be marked bad.
Percent good is calculated based on the amount of time that the rate tag has a bad status over
the totalization period for TimeWeighted totals and for the event counting functions (Events,
EventEQ, EventNE, EventGE, EventGT, EventLE, EventLT, EventGE_LT, EventLT_GE) with
a CalcMode of TimeTrue.
Page 282
7.3 - Totalizer Point Class Attributes
Percent good is calculated based on the number of events that have a bad status for
EventWeighted totals and for the event counting functions with a CalcMode of AllEvents and
ChangeEvents.
In the case of TimeWeighted totals, the Totalizer adjusts the total to account for the missing
data. This extrapolation takes the resultant good data and divides it by the fraction of time
that the data was good. For example, if the total of the good data is 100 and the percentage of
the data that was good for the time period is 80%, then the total that is reported is 125. To
turn off extrapolation, set PctGood to 0. By setting PctGood to 0, the total that is reported
from the previous example would be 100.
7.3.14 Conversion
Conversion is a number that multiplies the raw Totalizer result. It is used to convert the
units of the rate tag to the proper units for the totalization.
For TimeWeighted totals, the total is computed with the assumption that the rate tag is in
“units/day.” If the units of the rate tag are not in units/day, then the units of the rate tag must
be converted to units/day using Conversion. For example, if the units of the rate tag are in
kg/hr (kilograms per hour) and the desired total is in g (grams), then Conversion must be set
to 2400. That is, (1 kg/hr) (24 hr/day)(1000 g/kg) = (2400 g/day).
For EventWeighted totals Conversion can be used to convert the units of the rate tag to the
desired units of the total. For example, if the units of the rate tag is in kilograms and the
desired total is in grams, then Conversion should be set to 1000.
Here are some typical conversion factors for common units.
Table 7–5. Conversion Factors for Units
Source Units Total Units Conversion
bbl per day bbl 1.0
lbs per hour lbs 24.
gal per min gal 1440
Cubic feet per sec. acre-ft 0.504167
7.3.15 FilterExpr
This is a mathematical expression in PI Performance Equation syntax. The expression is
compiled and given an initial evaluation based on the current Snapshot values of tags
referenced. It is re-evaluated whenever an update is received for any of its tags.
Rate tag point values are excluded from totalization during intervals that the expression result
is zero. That is, rate tag values for periods when the filter expression result is zero are not
included in the total. This behavior is consistent with the sense of filter expressions in PI-API
and PI DataLink. For averages, the time is also excluded from the calculation.
For efficiency of evaluation, Archive access functions are not allowed in filter expressions.
Archive access functions include such functions as TagVal and TagAve.
PI Server Applications User Guide Page 283
Chapter 7 - PI Totalizer Subsystem
The rate point is not filtered when the status of the filter expression is bad. The filter
expression is likely to be bad whenever some of the input points for the filter expression have
bad status.
Refer to Chapter 2, PI Performance Equation, for more information about the syntax of the
expressions.
Some examples of filter expressions are as follows:
'DigitalTag'= "ON"
'RateTag' > 50
7.3.16 EventExpr
This is a PE expression that defines event times used by EventChange and EventTrue for
the TotalCloseMode options. It also defines the times at which the rate point is scanned for
the RateSampleMode option of Event. The expression is naturally scheduled. That is, it will
be evaluated whenever a new value is received for any of its input values.
Event expressions are normally evaluated as new values are received for the tags they
reference. For TotalCloseMode of EventChange and EventTrue, an event expression that
references no Snapshot tags will be evaluated at times specified by the Period and Offset
parameters. Each time a rate tag value is received, if the event expression due time has
passed, the rate tag value is evaluated prior to processing the new update value.
Some examples of event expressions are as follows:
'R-2410_mode'
'DigitalTag' = "ON"
int( ('*' - '1-jan-2001')/(7 * '+24h') )
7.3.17 CompValue
The value set in the CompValue attribute is used for comparison in all the event counting
functions (e.g., EventGE, EventLE) except the Function option Events because Events counts
all update events and does not need a comparison value. The CompValue should match the
data type of the rate tag. It may be a digital state name, string, or a number.
7.3.18 Options
This field allows for entry of zero or more option words to select lesser-used functions.
InFromTotalizer
This option is set if the rate point is actually the integral of the flow signal to be totalized.
This is intended for use with the typical DCS accumulator block. The DCS can easily process
the flow at a very high sample rate. The updates to PI can be set for relatively large exception
deviation values with negligible loss of accuracy. These DCS blocks typically have a rollover
at some finite value. As that total is reached, the block output drops to the bottom of its range
and accumulation continues. The Totalizer observes this large value jump and calculates the
correct increment from the configured full-scale value of the rate point.
Page 284
7.3 - Totalizer Point Class Attributes
UnderIsBad
Consider values below the rate point zero level to be bad. If this option is not set, values are
considered valid. Negative values are set to zero or used if enabled by the NoClampZero
option.
NoClampZero
Do not clamp the output of the Totalizer to be greater than zero. Without this option, zero is
substituted for negative rate tag values.
CloseAtEvent
The close out of the accumulation interval is at the end of the period and the result of the
calculation is sent to the Snapshot. For time-weighted calculations, the value used at the end
of the period is the value of the last seen update of the rate point. Figure 7–22 shows an
example of a time-weighted total with Scan1 and the CloseAtEvent option.
Accumulation
Interval
Time at which
Time Weighted Total for result sent to PI
RateSampleMode of Natural with SnapShot
step attribute of rate point = 0 and
Option of CloseAtEvent
Scan rate based
on Period2 and
Offset2 attributes
Interpolated values of rate point
Values are from last seen
update value of rate point
Values of rate point
Figure 7–22. Time-Weighted Total with Scan1 and CloseAtEvent
This option will works only on event-driven TotalCloseModes of EventChange and
EventTrue.
Setable
The TotalCloseMode of Forever can be changed by some external force only when the
option field is set to Setable. In this case, the new value will be used as the base for the next
Totalizer result.
OneAtStart
The TotalCloseMode of PeriodEnd can be modified to only send a value only at the
beginning of the period (one second after the close of the last period) when the option field is
PI Server Applications User Guide Page 285
Chapter 7 - PI Totalizer Subsystem
set to OneAtStart. The default behavior of PeriodEnd is to send a value to the beginning and
the end of the period.
OneAtEnd
The TotalCloseMode of PeriodEnd can be modified to only send a value at the end of the
period when the option field is set to OneAtEnd. The default behavior of PeriodEnd is to send
a value to the beginning and the end of the period.
UnderIsZero
Some external systems have limited ranges for measured values but are able to report that the
signal is below the available range. This option causes the Totalizer to use the rate tag zero
value in place of updates with UnderRange status.
OverIsTop
Some external systems have limited ranges for measured values but are able to report that the
signal is above the available range. This option causes the Totalizer to use the rate tag top of
span value in place of updates with OverRange status.
SourceStat
When the PctGood minimum is not attained, the Totalizer normally reports “bad total” as a
status. With this option, a bad status actually received from the source tag will be used
instead. This supplies some reason for the failure to someone looking only at the Totalizer
results.
LimitBack
When LimitBack is set, the number of totalization periods that will be reported between
source tag events is limited to twenty. This is a partial solution to the problem some systems
encounter when restarting after being down for some time. The Totalizer may attempt to
write results for all of the totalization periods for the period when the system was down.
7.4 Build Totalizer Points
Totalizer points can be created in the same manner as other point types except that Totalizer
point attributes includes the Totalizer attributes as well as the point attribute for the Base
point class.
7.4.1 SMT Totalizer Editor Plug-in
This plug-in provides a user-friendly GUI to create a Totalizer point. Unlike
TagConfigurator discussed below, the editor strictly enforces the non-supported
combinations of options.
Page 286
7.4 - Build Totalizer Points
7.4.2 PI TagConfigurator
The easiest way to build many Totalizer points is using the PI TagConfigurator tool. See the
OSIsoft support Web site to download this tool. An example is shown in Figure 7–23.
Figure 7–23. PI TagConfigurator Creation of Totalizer Point
Note: under Export Tags of the PI SMT pull-down menu, the Point Class must be
Totalizer.
Figure 7–24. Export Tags Dialog Box
Furthermore, the PointSource attribute must also be explicitly set to T.
7.4.3 Piconfig
Alternatively, you can use the following script in the piconfig utility to create the same
Totalizer point:
@table pipoint
@ptclass totalizer
@mode create, t
@istru tag, pointsource, sourcetag, ratesamplemode, totalclosemode,
reportmode, function, calcmode
totnumtag, T, sinusoid, natural, clock, periodend, total, eventweighted
@ends
PI Server Applications User Guide Page 287
Chapter 7 - PI Totalizer Subsystem
7.5 Program Operation
7.5.1 Startup
The pitotal program is started with the rest of the system. The program periodically writes
its internal status to the file PI\dat\pilasttot_T.dat. This file is also written during a normal
system shutdown. At startup, pitotal looks for this file. If it is not found, all Totalizer points
are initialized to start at the current time without consideration of any prior history.
If the pilasttot_T.dat file is found, it is read to obtain partial accumulation results to include
when restarting points. For the most part, all points with simple time-based scheduling will be
able to restart. If the accumulation interval that was in progress when the file was written has
expired, an attempt is made to close that total and a shutdown event will be written after it.
Otherwise, the accumulation is restarted with the assumption that no data points have been
lost. If any point appears to have shutdown events after the time of the pilasttot_T file, then
restart is canceled in favor of total cold start. Points that are event-scheduled have no basis to
know if restart is valid. Shutdown events are written and the point is cold-started.
Any point that has been reconfigured while pitotal was offline would be cold-started. Point
Database edits may result in a re-initialization of the point. This will occur when a significant
parameter change is made.
7.5.2 Error Messages
All significant events in the life of a Totalizer point are noted in the PI server log. These
include point additions and edits, scan status changes, and error conditions. These events can
be monitored using the pigetmsg in the pi\adm directory. For UNIX, an additional log file
pitotal.log is also used. This file is located in the pi/log directory. See Chapter 2 in the PI
Server System Management Guide, for information about using the pigetmsg utility.
7.5.3 Response to Scan Flag
When an operating Totalizer point is turned off-scan, the Totalizer is closed out as though
this were the end of the period and a Scan Off event is written to the Archive. Going back
on-scan is a full initialization of the point; no partial results are carried forward. A Scan On
event is written to the Archive.
7.6 PI for OpenVMS Upgrade Considerations
The Totalizer can nominally do all the operations that the PI for OpenVMS version could do
and more. Simple time-based points should port with no difficulty. However, the advanced
Totalizer algorithms depend on very specific behavior of underlying implementations that are
quite different. Any PI for OpenVMS points that use filter and event expressions will need
special attention.
The following are known differences:
The meaning of the filter expression result has been reversed to match the logic of the
API. Now, input values are ignored (filtered out) when the filter expression result is
zero.
Page 288
7.6 - PI for OpenVMS Upgrade Considerations
The Performance Equation syntax used in the event and filter expressions is different.
The largest difference is the absence of a formula library in PI Server. See Chapter 2,
PI Performance Equation, for further details.
New functions are available for counting and timing of events. Use of these functions
may enable the elimination of many event and filter expressions.
The use of PI for OpenVMS option of moving Totalization with event- and clock-
scheduling is not supported.
7.6.1 Features in PI3 versus PI for OpenVMS
The Totalizer Subsystem includes new features that not included in PI for OpenVMS.
Totalizer points use a new point class with a new set of parameter names and
meanings.
A running account of the output.
The event expression that can be time-scheduled.
New event functions that can count and time values from Digital points.
Sampling of the rate point that can be time-scheduled.
Moving totals with several new scheduling options.
New numeric functions that include Maximum, Minimum, Median, and Range.
The input that may come from a typical DCS Totalizer block.
7.6.2 Compatibility with PI for OpenVMS
The PI Server Totalizer can do all of the functions offered by PI for OpenVMS
postprocessing. Simple Totalizers can be ported easily through a translation of parameter
names. Points that use event or filter expressions will need to be examined for compatibility
with the PI Server syntax.
In many cases it should be possible to get the desired functionality by using the new Totalizer
features rather than by re-writing expressions. These will be easier to document and use less
computing resource.
The meaning of the filter operation has been redefined. A true filter result, that is non-zero,
now passes the signal. Table 7–6 lists the available postprocessing options in PI for
OpenVMS and the PI Server equivalents.
Table 7–6. PI for OpenVMS and PI for NT and UNIX Equivalents
PI for OpenVMS PI Server
Postprocessing Type of
Type Scheduling Point Attribute Option to Set
Time-weighted Clock RateSampleMode Natural
PI Server Applications User Guide Page 289
Chapter 7 - PI Totalizer Subsystem
PI for OpenVMS PI Server
TotalCloseMode Clock
ReportMode PeriodEnd
CalcMode TimeWeighted
Event RateSampleMode Natural
TotalCloseMode EventChange
ReportMode PeriodEnd
CalcMode TimeWeighted
Discrete Clock RateSampleMode Natural
TotalCloseMode Clock
ReportMode PeriodEnd
CalcMode EventWeighted
Event RateSampleMode Natural
TotalCloseMode EventChange
ReportMode PeriodEnd
CalcMode EventWeighted
Moving Natural RateSampleMode Natural
TotalCloseMode NSampleMoving
ReportMode Ramping
CalcMode TimeWeighted
Clock Not Supported
Event Not Supported
7.7 Demonstration Points
Demonstration points for the Totalizer subsystem are available in the pi\adm directory in the
totalizerpts.dif file but are not automatically created when the system is installed. These
Totalizer demonstration points can be created by redirecting the file to the piconfig utility.
See Chapter 11, The Piconfig Utility, in the PI Server System Management Guide for
information about using the piconfig utility.
$ piconfig < totalizerpts.dif
Page 290
Chapter 8. PI ALARM SUBSYSTEM
The PI Alarm Subsystem (PI Alarm) provides the capability to establish alarms for PI
points. PI Alarm allows you to track, manage and acknowledge alarm conditions caused by
processes that exceed user-specified parameters.
PI Alarm can monitor many variables such as temperatures, volumes, flow rates, product
quality or raw material consumption. Alarms can be triggered by the duration of an event or
deviation from norm.
PI Alarm keeps a constant eye on process conditions. PI Alarm will assess the condition as
well as the priority of an event, as you define it. Depending on the longevity and/or severity
of the event, it can notify specific personnel. PI Alarm includes client functionality through
the PI-API to alert operators to selected alarms.
Data from PI Alarm are displayed in its companion client application, PI AlarmView. Alarm
conditions are historized together with an acknowledgement status. When Real-Time SQC
perceives an unacceptable deviation in the process, PI SQC Alarms alert the appropriate
personnel.
This chapter includes the following topics:
Section 8.1, Alarm Subsytem Overview, on page 292
Section 8.2, Alarm Point Configuration, on page 294
Section 8.3, Alarm State Sets, on page 308
Section 8.4, Alarm Groups, on page 312
Section 8.5, Build Alarm Points, on page 314
Section 8.6, Build Alarm Group Points, on page 315
Section 8.7, Override Default PointSource Values for Alarms, on page 316
Section 8.8, Build Alarm Digital State Sets, on page 317
Section 8.9, Program Operation, on page 319
Section 8.10, PI for OpenVMS Upgrade Consideration, on page 321
Section 8.11, Alarm State Set Encoding and Decoding, on page 321
PI Server Applications User Guide Page 291
Chapter 8 - PI Alarm Subsystem
8.1 Alarm Subsytem Overview
A PI System often brings together information from several sources and can perform
calculations that are not easily done elsewhere. Some sites may have alarm philosophies that
enable them to take advantage of the PI System to provide alerts on these higher level
functions.
PI Alarm provides the basic server-side functions of an alarm system. The alarm package
includes the following features:
• Current and archived Alarm States.
• Alarm Groups to organize and manage alarms
• A simple alarm detection program for monitoring numeric, digital, and string
points.
• Alarm client functionality available through the PI-API to alert operators to
selected alarms.
The alarm package is organized into two categories.
The first part is the Alarm Point. Alarms are displayed and archived as digital
points. A monitoring program observes updates to numeric, digital, and string points
and then tests each for configured alarm conditions.
The second part is the Alarm Group. A set of alarm points can be organized into
Alarm Groups. Statistics such as the number of alarm points and the number of
unacknowledged alarms can be obtained for each Alarm Group. Groups can be
members of other groups to form alarm hierarchies.
8.1.1 Alarm Points
An alarm point is a digital point that indicates the alarm status of a point in the PI System. PI
Alarm can monitor the values of other points and set the values of alarm points when defined
boundaries are exceeded. Numeric values exceeding limits or digital values changing to a
special state are two such boundaries.
The digital state of an alarm point may include both the priority and acknowledgement status
of the alarm condition.
The condition of an alarm is the type of limit that the alarm is triggering. Some
typical names of conditions are “high” and “low”. For example, if a numeric point is
greater than a certain numeric constant, the condition of the alarm can be high.
The acknowledgement status may be determined by whether a user has
acknowledged the alarm, not acknowledged the alarm, or not acknowledged the
alarm condition that no longer exists.
The priority is level of importance given to the particular alarm.
Each alarm point has a source point, which is the tag whose value is being monitored for
special changes. Figure 8–1 shows the flow diagram of an alarm point.
Page 292
8.1 - Alarm Subsytem Overview
Reference Alarm Digital
Tag State Set
Source
Test1 Action1
point
Test2 Action2
Combiner
Logic
Test3 Action3
Alarm
point
Test4 Action4
Figure 8–1. Flow Diagram of Alarm Points
The alarm point is naturally scheduled and signs up for updates of the source point. This
means that the alarm point is evaluated whenever the source point produces an exception. A
series of tests are done and an alarm is triggered if any of the tests are true. The digital state
of the alarm point is then set based on the combiner logic, which is discussed later in this
chapter.
Alarm Tests and Actions
An alarm is the result of a set of four tests on the current value of another point. Each alarm
tag has a primary source point that is the subject of these tests. Each alarm point can be
configured to perform four simple tests on new values received by the source tag. The tests
are individually configured for comparisons like "greater than," "equal," etc. Each time a
source tag value is received, the configured tests are performed. The result of each test is a
Boolean (true/false) value. The four test results are input to combiner logic that decides the
alarm status to be set. The answer depends on the configured priority of the test conditions,
the order of detection, and the acknowledgement status of the current alarm.
Combiner Logic
Combiner logic refers to the manner in which the digital state of an alarm is set when a test or
multiple tests are true. If more than one test condition is true, the rule for which Alarm State
to set is that priorities have precedence. When two conditions of the same priority are true, it
is the first (in order of the tests) that is used to set the Alarm State. Further details of the logic
are given in the Action1, Action2, Action3, and Action4 attributes for alarm points.
Acknowledgment
In this release, acknowledgment is accomplished by allowing the client program to write
acknowledged digital states corresponding to the Alarm Digital States directly to the alarm
points. For example, an Alarm Digital State that represents a high value in the source tag can
only be acknowledged by the corresponding high acknowledged digital state. The alarm
program will over-write the client input in case of an error.
PI Server Applications User Guide Page 293
Chapter 8 - PI Alarm Subsystem
See Section 8.3, Alarm State Sets, for more information about Alarm Digital States. Future
releases will provide an interface for acknowledgement and other functions through the PI-
SDK.
An auto-acknowledge for the alarm point is also possible. An auto-acknowledged point will
continue to display the current alarm condition, but the display status will never be
unacknowledged. Further details on auto-acknowledgement can be found in the AutoAck
attribute for alarm points.
8.2 Alarm Point Configuration
Alarm points have the point class of alarm. The point source is ‘@’ and the data type must
be digital.
Table 8–1 lists the attributes for the alarm point class.
Table 8–1. Alarm Point Class Attributes
Point Attribute Valid Options Description
SourceTag Source point used to test for alarm
Test1 GT Alarm if values greater than numeric value
Test2 LT Alarm if values less than numeric value
Test3
EQ Alarm if values equal numeric value, digital state or string
Test4
NE Alarm if values not equal numeric value, digital state or
string
StepGT Alarm if values stepped up more than numeric value
StepLT Alarm if values stepped down more than numeric value
RateGT Alarm if rate of change is greater than numeric value
RateLT Alarm if rate of change is less than numeric value
Is_in Alarm if value is in the digital state or string
Not_In Alarm if value is not in the digital state or string
Includes Alarm if values includes digital state or string
Change Alarm if value of point changes
CondEQ Alarm if condition is equal to string
CondNE Alarm if condition is equal to string
IsUnAck Alarm if unacknowledged
Action1 Condition nn Name of the alarm condition
Action2 nn = priority
Action3 StateName Valid name in Digital State Set.
Action4
ExDesc GroupTag Alarm Group of alarm point
Page 294
8.2 - Alarm Point Configuration
Point Attribute Valid Options Description
DigitalSet Name of the Alarm Digital State Set for point
ReferenceTag Tagname Point that will be used for comparison operators if
specified.
AutoAck Yes (default) Any alarm always shows as acknowledged.
No Full acknowledge operation supported.
DeadBand 0.0 (default) Threshold for point not to be in alarm
Options RT = num Used with the RateGT and RateLT to define the period of
the rate
ControlTag Point that is used to take the alarm out of service if
specified.
ControlAlg <reserved for future use>
Note: While the actual point class has the parameters, Test5 and Action5, only four
Test/Action pairs are implemented.
8.2.1 SourceTag
The point set in the SourceTag attribute is the primary source used in the testing for alarm
conditions. The point must already exist and must be specified when the Alarm Point is
configured. The point may be numeric, digital or string point types.
8.2.2 Test1, Test2, Test3, Test4
The set of four attributes Test1, Test2, Test3, and Test4 contains the test for the alarm
condition. The syntax for the attribute is the operator followed by an argument that is within
parenthesis, which is also followed by an optional time parameter.
Syntax: Operator ( Argument ) Time
The argument can be a numeric constant; string, digital state, or it may refer to another tag.
The following examples use the EQ (equals to) operator that is detailed later in this section.
EQ ( 12 )
EQ ( ON )
EQ ( “This is a string” )
In addition, the argument can be a reference to another point that has the data type of
numeric, string, or digital. If a reference is used, the argument is the tagname of the reference
point that is enclosed in single quotes or the keyword, ref. In the case where the keyword, ref
is used, the ReferenceTag attribute must be the tagname of the desired reference point. An
optional numeric constant offset can also be used only in the case when the keyword ref is
used and only if the reference point is a numeric point. This adds or subtracts a numeric
constant from the value of the reference point before the test is done.
EQ ( ‘tagname’ )
EQ ( ref )
PI Server Applications User Guide Page 295
Chapter 8 - PI Alarm Subsystem
EQ ( ref + 12 )
EQ ( ref – 14 )
An optional time parameter can also be used to delay the triggering of the alarm until the test
comparison is true for a given amount of time. The time parameter is a relative timestamp
that is added to the comparison. The time parameter consists of a plus sign, one or more
numbers, and a letter (s, m, h, or d). There may be no spaces between these elements.
EQ ( 12 ) +14m
EQ ( ‘tagname’ ) +11h
EQ ( ref + 70 ) +1h
EQ ( ON ) +1d
In the examples above, the first test triggers an alarm if the source tag is equal to 12 for over
14 minutes. The second test alarms when the source point is equal to the reference point
(referenced by tagname) for over 11 hours. The third test compares the source point with the
reference point plus 70 and if they are equal for over one hour then an alarm is triggered. In
the fourth test, an alarm triggers if the source point is ON for over one day.
All numeric point comparisons are performed using floating-point operations and all string
and digital state comparisons are performed using character operations. Comparisons of a
digital or string data type with a numeric data type returns an error at the time which the point
is compiled. Blob data types are not supported. Table 8–2 shows some examples of the
comparisons and whether an alarm will trigger.
Table 8–2. Example Test Comparisons and the Alarm Status
Operator Source Test Trigger Comparison
point value an
value alarm?
EQ 12 12 Yes numeric source and numeric test value
EQ 14 70 No numeric source and numeric test value
EQ 12 12 Error numeric source and digital test value
EQ 12 “12” Error numeric source and string test value
EQ OFF OFF Yes digital source and digital test value
EQ OFF “OFF” Yes digital source and string test value
EQ OFF “OFF ” No digital source and string test value (with
trailing space)
EQ Off OFF Yes digital source and digital test value
Each of the four tests is evaluated in numeric order from Test1 through Test4 and each test is
associated with an “action” attribute numerically. For example, if the test set in Test1
becomes true, the associated “action” would be the one set in the Action1 attribute. In
general, if there is only one test that is used for the alarm point, it would be set in Test1 but
there is no rule governing the where to apply the test for the alarm point. Test1 could be left
unused and Test2, Test3, or Test4 may be used. In the case where all four attributes are
unused, the alarm point will default to the digital state that represents “no alarm” for that
Page 296
8.2 - Alarm Point Configuration
point. If more than one test is true, the digital state of the alarm is governed by the combiner
logic rules mentioned earlier in this chapter and detailed in the Action1, Action2, Action3,
and Action4 attributes section of this chapter.
Table 8–3 shows the available options for the comparison operators with their descriptions as
well as their viable argument data types. An X in the table denotes that the data type is
allowable.
Table 8–3. Viable Argument Data Types for Operators
Argument Data Type
(X indicates Allowed)
Operator Description
Numeric Digital String
GT Greater Than X
LT Less Than X
EQ Equal To X X X
NE Not Equal To X X X
StepGT Step Greater Than X
StepLT Step Less Than X
RateGT Rate Greater Than X
RateLT Rate Less Than X
Is_In Is In the string or digital state X X
Not_In Is not in the string or digital state X X
Includes Includes the string or digital state X X
Change Change of State X X X
CondEQ Alarm condition equals X
CondNE Alarm condition not equal X
IsUnack Alarm condition is unacknowledged X
GT
The operator GT tests numeric constants as well as points that evaluate into numbers against
a numeric source point. An alarm is triggered if the value of the source point is greater than
the value set in the test. If a reference point is used, the tagname of the reference point is used
as the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point. A time parameter in the form of a
relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
GT ( 12 )
GT ( ‘tagname’ )
GT ( ref )
GT ( ref + 14 )
PI Server Applications User Guide Page 297
Chapter 8 - PI Alarm Subsystem
GT ( 70 ) +1h
LT
The operator LT tests numeric constants as well as points that evaluate into numbers against
a numeric source point. An alarm is triggered if the value of the source point is less than the
value set in the test. If a reference point is used, the tagname of the reference point is used as
the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point. A time parameter in the form of a
relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
LT ( 12 )
LT ( ‘tagname’ ) +14m
LT ( ref - 70 )
LT ( 11 ) +1h
EQ
The operator EQ tests can be performed with numeric constants, digital states, strings or a
reference to another point. An alarm is triggered if the value of the source point is equal to the
value set in the test. If a reference point is used, the tagname of the reference point is used as
the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point.
A time parameter in the form of a relative timestamp can delay the triggering of an alarm
until the comparison is true for that period of time.
EQ( 12.14 )
EQ ( OFF )
EQ ( ref )
EQ ( ref + 70 )
EQ ( “This is a string” ) +1h
NE
The operator NE tests can be performed with numeric constants, digital states, strings or a
reference to another point. An alarm is triggered if the value of the source point is not equal
to the value set in the test. If a reference point is used, the tagname of the reference point is
used as the argument. If the keyword ref replaces the numeric constant as the argument and
the ReferenceTag attribute contains the tagname of the reference point, a numeric constant
may be added or subtract to the value of the reference point. A time parameter in the form of
a relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
NE( 12 )
NE ( ON )
NE ( ‘tagname’ )
NE ( ref – 14.11 )
NE ( “This is a string” ) +70m
Page 298
8.2 - Alarm Point Configuration
StepGT
The operator StepGT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point changes
more than the value set in the test. If a reference point is used, the tagname of the reference
point is used as the argument. If the keyword ref replaces the numeric constant as the
argument and the ReferenceTag attribute contains the tagname of the reference point, a
numeric constant may be added or subtract to the value of the reference point. A time
parameter in the form of a relative timestamp can delay the triggering of an alarm until the
comparison is true for that period of time.
StepGT ( 12 )
StepGT ( ‘tagname’ ) +14m
StepGT ( ref - 70 )
StepGT ( 11 ) +1h
StepLT
The operator StepLT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point changes
less than the value set in the test. If a reference point is used, the tagname of the reference
point is used as the argument. If the keyword ref replaces the numeric constant as the
argument and the ReferenceTag attribute contains the tagname of the reference point, a
numeric constant may be added or subtract to the value of the reference point. A time
parameter in the form of a relative timestamp can delay the triggering of an alarm until the
comparison is true for that period of time.
StepLT ( 12 )
StepLT ( 'tagname' )
StepLT ( ref - 14 )
StepLT ( 70 ) +1h
RateGT
The operator RateGT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the rate of change of the source point
is greater than the value set in the test. The rate of change is calculated by dividing the
difference between discrete average of two successive periods by the period. Figure 8–2
shows an example of the calculation of the rate of change.
PI Server Applications User Guide Page 299
Chapter 8 - PI Alarm Subsystem
Period = 10 min Period = 10 min
8.5
6.5
Average = 6.5 6.0
6.0
diff = 1.5
5.0 Average = 5.0
2.5
Rate of Change = diff = 1.5 = .15
Period 10 Time at which alarm point
value sent to PI Snapshot
Figure 8–2. Calculation of Rate of Change
In the example, the average of the first period is 6.5 units and the average of the second
period is 5.0 units. Hence the rate of change is 1.5 units per minute. The values used in the
calculation are those sent to PI Snapshot as exceptions. The comparison test is made after the
second period at the time of the arrival of the next source point Snapshot value. The default
period is 10 minutes. The period can be changed by setting a new period in the options
attribute.
If a reference point is used, the tagname of the reference point is used as the argument. If the
keyword ref replaces the numeric constant as the argument and the ReferenceTag attribute
contains the tagname of the reference point, a numeric constant may be added or subtract to
the value of the reference point. A time parameter in the form of a relative timestamp can
delay the triggering of an alarm until the comparison is true for that period of time.
RateGT ( 12.8 )
RateGT ( 'tagname' )
RateGT ( ref + 14 )
RateGT ( 70 ) +1h
RateLT
The operator RateLT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point is less
than the value set in the test. If a reference point is used, the tagname of the reference point is
used as the argument. If the keyword ref replaces the numeric constant as the argument and
the ReferenceTag attribute contains the tagname of the reference point, a numeric constant
may be added or subtract to the value of the reference point. A time parameter in the form of
a relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time. The default period is 10 minutes. The period can be changed by setting a new
period in the options attribute.
Page 300
8.2 - Alarm Point Configuration
RateLT ( 12.8 )
RateLT ( 'tagname' )
RateLT ( ref + 14 )
RateLT ( 70 ) +1h
Is_In
The operator Is_In tests digital states, strings, or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings, and a string-to-string comparison is performed. The Is_In operator triggers an alarm
if the source point value is in the test value. For a reference point, the tagname of the
reference point is used as the argument. If the keyword, ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time.
Is_In ( "ON OFF" )
Is_In ( 'tagname' )
Is_In ( ref )
Is_In ( "This is a string" ) +1h
Table 8–4. Comparisons of the Is_In Operator
Operator Source point Test value Trigger an Comparison
value alarm?
Is_In Off “ON OFF” Yes digital source and
string test value
Is_In “string” “This is a Yes string source and
string” string test value
Is_In “str” “This is a Yes string source and
string” string test value
Is_In “strings” “This is a No string source and
string” string test value
Is_In 100 1002 Error numeric source and
digital test value
Is_In 100 “1002” Error numeric source and
string test value
Not_In
The operator Not_In tests digital states, strings, or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings and a string-to-string comparison is performed.
The Change operator triggers an alarm if the source point value is not in the test value. For a
reference point, the tagname of the reference point is used as the argument. If keyword ref is
used as the argument, the ReferenceTag attribute contains the tagname of the reference
point.
PI Server Applications User Guide Page 301
Chapter 8 - PI Alarm Subsystem
A time parameter in the form of a relative timestamp can delay the triggering of an alarm
until the comparison is true for that period of time.
Not_In ( "ON OFF" )
Not_In ( 'tagname' )
Not_In ( ref )
Not_In ( ON ) +1h
Table 8–5. Comparisons of the Not_In Operator
Operator Source point Test value Trigger an Comparison
value alarm?
Not_In ON “OFF ON” No digital source and
string test value
Not_In OF “OFF ON” No digital source and
string test value
Not_In ONE “OFF ON” Yes digital source and
string test value
Not_In “1” 12345678 No string source and
digital test value
Not_In 9 “12345678” Yes digital source and
string test value
Not_In 10 100 Error numeric source
and digital test
value
Not_In 10 “100” Error numeric source
and string test
value
Includes
The operator Includes tests digital states, strings or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings and a string to string comparison is performed. The Includes operator triggers an
alarm if the source point value includes the test value. For a reference point, the tagname of
the reference point is used as the argument. If keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time.
Includes ( HI )
Includes ( 'tagname' )
Includes ( ref )
Includes ( "This is a string" ) +1h
Page 302
8.2 - Alarm Point Configuration
Table 8–6. Comparisons of the Includes Operator
Operator Source point Test value Trigger an Comparison
value alarm?
Includes Hihi “HI” Yes digital source and
string test value
Includes High HI Yes digital source and
digital test value
Includes “VIN3234A” “VIN3234” Yes string source and
string test value
Includes “VIN3234A” “VIN3235” No string source and
string test value
Includes 1002 100 Error numeric source and
digital test value
Includes 1002 “100” Error numeric source and
string test value
Change
The operator Change tests numeric values, digital states, strings or points that evaluate into
numeric values, digital states or strings. All numeric comparisons are done as floating point
operations and comparisons of all digital states are converted into strings and a string-to-
string comparison is performed. The Change operator triggers an alarm if the source point
value is different from the previous value. A time parameter in the form of a relative
timestamp can delay the triggering of an alarm until the comparison is true for that period of
time.
Change ( )
Change ( ) +1h
CondEQ
The operator CondEQ tests alarm point conditions against alarm points. An alarm will
trigger if an alarm of another alarm point is equal to the test value. For a reference point, the
tagname of the reference point is used as the argument. If keyword ref is used as the
argument, the ReferenceTag attribute contains the tagname of the reference point. A time
parameter in the form of a relative timestamp can delay the triggering of an alarm until the
comparison is true for that period of time. The argument is an alarm condition. In the
following examples, an alarm is triggered if the condition of the source alarm point is low,
the condition of the source alarm point is equal to the condition of the reference point (ref),
and the condition of the source point is high for over one hour, respectively.
CondEQ ( low )
CondEQ ( 'alarmtagname' )
CondEQ ( ref )
CondEQ ( high ) +1h
Table 8–7 show examples of the CondEQ operator using the sample Alarm Digital State Set
given in the Alarm State Sets section of this chapter. The digital state for a new alarm with
PI Server Applications User Guide Page 303
Chapter 8 - PI Alarm Subsystem
the condition of low is low << and the digital state for an acknowledged alarm with the
condition of low and an urgent priority is ** low.
For more information about Alarm Digital States, see Section 8.3, Alarm State Sets.
Table 8–7. Comparisons of the CondEQ Operator
Operator Source point Test value Trigger an Comparison
value alarm?
CondEQ Low Low Yes digital source and
digital test value
CondEQ Low << Low Yes digital source and
digital test value
CondEQ ** low Low Yes digital source and
digital test value
CondEQ Low Lolo No digital source and
digital test value
CondNE
The operator CondNE tests alarm point against an alarm point. An alarm will trigger if an
alarm of another alarm point is not equal to the test value. For a reference point, the tagname
of the reference point is used as the argument. If keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time. The argument is an alarm condition. In the following examples, an
alarm is triggered if the condition of the source alarm point is not low, the condition of the
source alarm point is not equal to the condition of the reference point (ref), and the condition
of the source point is not high for over one hour, respectively.
CondNE ( low )
CondNE ( 'alarmtagname' )
CondNE ( ref )
CondNE ( high ) + 1h
IsUnack
IsUnack tests an alarm point against another alarm point. This operator has no arguments and
triggers an alarm if the source alarm point is unacknowledged.
In the following examples, an alarm is triggered if the source alarm point is unacknowledged
and goes unacknowledged for over one hour, respectively.
IsUnack ( )
IsUnack ( ) +1h
8.2.3 Action1, Action2, Action3, Action4
The set of four attributes Action 1, Action 2, Action 3 and Action 4 specify the digital state
that is set when the corresponding test set in the Test1, Test2, Test3, Test4 attributes trigger
an alarm. There are two forms of the attribute and their syntax is as follows.
Page 304
8.2 - Alarm Point Configuration
Syntax: Form 1) Condition Priority
Form 2) StateName
If an Alarm State Set is the Digital State Set for the alarm point, then the first form of the
attribute is used. In this case Condition is the alarm condition to be set for the alarm point
and Priority is the numeric priority level alarm. See Section 8.3, Alarm State Sets, for more
information about conditions and priorities. Table 8–8 gives examples of the use of the first
syntax and the resulting digital state that is set using the example Alarm Digital State Set
shown in Table 8–15.
Table 8–8. Examples Using First Syntax (Condition Priority)
Action1 Digital State Description
Hihi 1 __ hihi << New unacknowledged HIHI alarm with priority
level 1
Hihi 2 _* hihi << New unacknowledged HIHI alarm with priority
level 2
High 3 ** high << New unacknowledged HIGH alarm with priority
level 3
Low 0 LOW LOW alarm with priority 0 always returns just the
alarm condition
In the above examples, the digital state that is set is for a new alarm with the attribute
AutoAck set to NO. Furthermore, it is also possible to have a priority level of 0, which is
shown as the last example in Table 8–8. In that case, only the alarm condition is returned
regardless of the acknowledgement status.
The second case is not limited to the Alarm Digital State Set and any digital state set may be
utilized. The second case only requires that the attribute contain a digital state (StateName)
that belongs to the digital state set of the alarm point.
Table 8–9. Examples Using Second Syntax (StateName)
Action Digital State Description
1
Hihi HIHI Condition only. Similar to using the first syntax with priority 0
** high ** High Alarm Digital State
auto Auto Digital Set used is Modes {Manual, Auto, Cascade, Program, Prog-Auto}
The first two examples given in Table 8–9 use the Alarm Digital State Set from Table 8–15.
The last example used a default digital state set, Modes, with the digital states {Manual,
Auto, Cascade, Program, Prog-Auto}.
When more than one alarm is triggered simultaneously, the combiner logic determines the
digital state that is set by using the following rules:
• Priorities have precedence.
PI Server Applications User Guide Page 305
Chapter 8 - PI Alarm Subsystem
• When two conditions of the same priority are true, it is the first (in order of the
tests) that is used to set the Alarm State.
Table 8–10 gives examples of which “action” will be taken when more than one “action”
attribute is triggered. In these examples, it is assumed that all four tests were done and the
“actions” that were left blank are the result of alarms that were not triggered.
Table 8–10. Combiner Logic Examples
Action1 Action2 Action3 Action4 Result
Hihi 1 High 1 Hihi 1
Hihi 2 High 1 Hihi 2
auto Manual auto
In the first combiner logic example, all the priorities are the same; hence Action1 is set
because it is the first test that is true. In the second example, even though Action4 and
Action1 are both true, Action1 is used because it has a higher priority. The last example
demonstrates the second syntax where priority is not used; hence Action1 is set because it is
the first test that is true. Refer to Alarm State Sets on page 308 for more information about the
digital state that is set.
8.2.4 ExDesc
The tagname of the Alarm Group for the alarm point is set in the ExDesc. An alarm point
must belong to an Alarm Group and the Alarm Group must be created before the creation of
the alarm point. Refer to Alarm Groups on page 312 for additional information.
8.2.5 DigitalSet
The DigitalSet attribute specifies the name of the Alarm State Set that is to be associated
with the tag. An alarm point is required to have a digital set and the digital set must be
created before the creation of the alarm point. See Section 8.3, Alarm State Sets, for more
information about Alarm Digital States.
8.2.6 ReferenceTag
The tagname defined in the ReferenceTag attribute is used in the Test1, Test2, Test3, and
Test4 attributes as a reference point to trigger alarms. In the case where a reference is used,
the argument in the test is the keyword ref. In this case, the ReferenceTag attribute must be
the tagname of the desired reference point.
8.2.7 AutoAck
The two options that can be set for the AutoAck attribute are yes or no. The default is yes. If
the value in AutoAck attribute is yes then an alarm is automatically acknowledged. For a
three-acknowledgment status configuration in the Alarm State Set, the new and
unacknowledged missed statuses shown in Table 8–12 would never be assigned to an alarm
point value.
Page 306
8.2 - Alarm Point Configuration
8.2.8 DeadBand
The DeadBand attribute modifies the Test1, Test2, Test3, and Test4 attributes of GT and
LT. The DeadBand is a threshold, within the alarm limit, that the rate point must pass after
an alarm is triggered before the point is considered not to be in alarm. The default DeadBand
is 0.
Upper Alarm Limit
Deadband
Deadband
Lower Alarm Limit
Time at which Time at which upper Time at which Time at which
upper limit alarm limit alarm is no lower limit alarm is lower limit alarm is
is triggered longer in alarm triggered no longer in alarm
Figure 8–3. Deadbands for Upper and Lower Alarm Limits
8.2.9 Options
The option attribute is used to modify the period associated with the RateGT and RateLT
operators in the Test1, Test2, Test3, and Test4 attributes.
Syntax: RTime = timestamp
The following examples set the period to 1 hour, 5 minutes, and 30 seconds respectively.
RTime = +1h
Rtime = +5m
Rtime = +30s
8.2.10 ControlTag
The tagname defined in the ControlTag attribute is used in the combiner logic to disable
alarms. The tagname specified by the ControlTag attribute must refer to a numeric (any float
or integer) or digital point type. Any other point type will result in an Error state for the
alarm point. In the case where a control tag is used, the alarm can be taken out of service by
setting the value of the control tag to zero for numeric tags or the 0th state for digital tags.
Below is an example of using the ControlTag to disable an alarm when net generation drops
below a predetermined value. This could easily be applied to all alarms on a unit. Assume
that U2:NetGen.PV is the net generation on our example unit.
Configure a PE point, a digital point, with 2 states: Not Running and Running. Be sure that
Not Running is first digital state in the set. Set the point to be naturally scheduled, based on
our net generation value. The ExDesc of the PE will look similar to:
event=U2:NetGen.PV, if('U2:NetGen.PV' > 5) THEN "Running" ELSE "Not
Running"
PI Server Applications User Guide Page 307
Chapter 8 - PI Alarm Subsystem
If there are only 2 states in this digital set, and Not Running is the first one, the following
ExDesc will do the same thing.
event=U2:NetGen.PV, 'U2:NetGen.PV' > 5
Finally, enter the tagname of this PE as the ControlTag of any alarms that should be disabled
when net generation falls below 5.
8.2.11 ControlAlg
Reserved attribute for future implementation.
8.3 Alarm State Sets
An Alarm State Set is a Digital State Set constructed such that condition, acknowledgement,
and priority codes are all encoded in the digital states.
8.3.1 Condition
The condition of an alarm describes the manner in which an alarm is manifested. Table 8–11
shows some sample descriptions of the types of alarm conditions that may be implemented.
Table 8–11. Sample Alarm Conditions
Condition Example Description
Lolo The value of the point is way below normal
Low The value of the point is below normal
High The value of the point is above normal
Hihi The value of the point is way above normal
Rate The rate of change of the point is abnormal
Step The change in value of the point is abnormal
Change The value of the point has changed from the previous
8.3.2 Acknowledgement Status
The acknowledgement shows the status or the amount of attention that has been paid to the
alarm. The acknowledgement status is a modifier to the condition of the alarm. This release
of PI Alarm allows for 1 or 3 states of acknowledgement statuses. The three-state
acknowledgement status set consists of the New Alarm, the Acknowledged Alarm and
Unacknowledged Alarm that is missed. The one-state acknowledgement is defined by having
all alarms acknowledged. Table 8–12 shows the three-state acknowledgement status and
respective descriptions.
Page 308
8.3 - Alarm State Sets
Table 8–12. Three-state Acknowledgement Status
Acknowledgment Description
Status
New An alarm has been triggered and is unacknowledged.
Acknowledged The triggered alarm is acknowledged.
Unacknowledged The unacknowledged alarm was missed because the
Missed source point is no longer in alarm.
8.3.3 Priority
The priority describes the level of importance given to the triggered alarm or the severity
associated with the triggered alarm. Table 8–13 is an Alarm Digital State Set with a single
priority and three acknowledgement statuses.
Table 8–13. Single Priority Alarm State Set
New Alarm Acknowledged Alarm Unacknowledged Alarm Missed
Lolo << Lolo Lolo _x
Low << Low Low _x
High << High High _x
Hihi << Hihi Hihi _x
Rate << Rate Rate _x
Step << Step Step _x
Change << Change Change _x
Dig1 << Dig1 Dig1 _x
Dig2 << Dig2 Dig2 _x
In this scheme, the acknowledgement statuses are represented by symbols. New alarms are
denoted by the symbol “<<” at the end of the alarm conditions, while acknowledged alarms
are just denoted as the alarm conditions itself. Alarms that are missed because the source
point has gone out of an alarm condition are denoted by an underscore followed by an “x”
(“_x”) after the alarm condition.
For the case where more severity is placed on certain types of alarms as opposed to others,
the priority level can be expanded to multiple levels. Table 8–14 shows an example of a
three-priority system with their respective meanings.
Table 8–14. Example Three-priority-level System
Priority Example Description Sample Symbol
Level
1 Alert __
2 Important _*
3 Most Urgent **
PI Server Applications User Guide Page 309
Chapter 8 - PI Alarm Subsystem
The three priorities are classified from the most severe (priority level 3) to the least severe
(priority level 1) as Most Urgent, Important, and Alert and their respective symbols which
is denoted in front of the alarm condition are “**”, “_*”, and “__” respectively. Table 8–15
shows the same Alarm Digital State Set with the additional priorities.
Table 8–15. Alarm Digital State Set with Three Priorities
Priority New alarm Acknowledged Unacknowledged
Alarm Alarm Missed
** Lolo << ** Lolo ** Lolo _x
Most ** Low << ** Low ** Low _x
Urgent
** High << ** High ** High _x
** Hihi << ** Hihi ** Hihi _x
** Rate << ** Rate ** Rate _x
** Step << ** Step ** Step _x
** Change << ** Change ** Change _x
** Dig1 << ** Dig1 ** Dig1 _x
** Dig2 << ** Dig2 ** Dig2 _x
_* Lolo << _* Lolo _* Lolo _x
_* Low << _* Low _* Low _x
Important
_* High << _* High _* High _x
_* Hihi << _* Hihi _* Hihi _x
_* Rate << _* Rate _* Rate _x
_* Step << _* Step _* Step _x
_* Change << _* Change _* Change _x
_* Dig1 << _* Dig1 _* Dig1 _x
_* Dig2 << _* Dig2 _* Dig2 _x
__ Lolo << __ Lolo __ Lolo _x
Alert __ Low << __ Low __ Low _x
__ High << __ High __ High _x
__ Hihi << __ Hihi __ Hihi _x
__ Rate << __ Rate __ Rate _x
__ Step << __ Step __ Step _x
__ Change << __ Change __ Change _x
__ Dig1 << __ Dig1 __ Dig1 _x
__ Dig2 << __ Dig2 __ Dig2 _x
Page 310
8.3 - Alarm State Sets
The only default Alarm State Set that is installed is the Pialarm33 State Set. Four sample
Alarm State Sets are also included in a piconfig script (two for use with numeric source tags
and two for digital). These sample Alarm State Sets are provided in Section 8.3, Alarm State
Sets. For each type, one set is simple, only showing alarm condition, and the other complete,
showing priority, condition, and acknowledge status. The sample Alarm State Sets for
numeric source points are displayed in Table 8–13 and Table 8–14. A second set of Alarm
State Sets for digital or string source points are provided in Table 8–16 and Table 8–17.
Table 8–16. Example Digital Alarm State Set with One Priority
New alarm Acknowledged Unacknowledged
Alarm Alarm Missed
Move << Move Move _x
Fail << Fail Fail _x
Off << Off Off _x
Over << Over Over _x
Under << Under << Under <<
Change << Change Change _x
D7 << D7 D7 _x
D8 << D8 D8 _x
Table 8–17. Example Digital Alarm Set with Three Priorities
Priority New alarm Acknowledged Unacknowledged
Alarm Alarm Missed
** Move << ** Move ** Move _x
Most Urgent ** Fail << ** Fail ** Fail _x
** Off << ** Off ** Off _x
** Over << ** Over ** Over _x
** Under << ** Under ** Under _x
** Change << ** Change ** Change _x
** D7 << ** D7 ** D7 _x
** D8 << ** D8 ** D8 _x
_* Move << _* Move _* Move _x
PI Server Applications User Guide Page 311
Chapter 8 - PI Alarm Subsystem
Priority New alarm Acknowledged Unacknowledged
Alarm Alarm Missed
_* Fail << _* Fail _* Fail _x
_* OFF << _* OFF _* OFF _x
_* Over << _* Over _* Over _x
_* Under << _* Under _* Under _x
_* Change << _* Change _* Change _x
_* D7 << _* D7 _* D7 _x
_* D8 << _* D8 _* D8 _x
__ Move << __ Move __ Move _x
Alert __ Fail << __ Fail __ Fail _x
__ OFF << __ OFF __ OFF _x
__ Over << __ Over __ Over _x
__ Under << __ Under __ Under _x
__ Change << __ Change __ Change _x
__ D7 << __ D7 __ D7 _x
__ D8 << __ D8 __ D8 _x
Each site using PI Alarms needs to examine its needs for alarm display sets and establish
local standards. While state sets can be added or changed, some changes will require
significant re-configuration of client programs. This can be minimized by planning.
As with all Digital State Sets, each of the digital state strings in the tables corresponds to a
digital state code. The manner in which the Alarm State Sets mentioned above are changed
into digital states is explained in Section 8.11, Alarm State Set Encoding and Decoding.
8.4 Alarm Groups
An Alarm Group is a collection of alarm points that are grouped together using a common
group name. Furthermore, Alarm Groups may also contain other Alarm Groups, to create an
alarm hierarchy. Each alarm point is assigned to a single Alarm Group. The Alarm Group
organization should match the operational structure of the plant. This hierarchy forms the
basis for alarm system control and reporting functions.
Each Alarm Group is represented in the PI system by one or more points. A single point is
required to provide the name for the group referred to by alarm points within it. The Alarm
Group point can receive values that represent statistics about the alarms in the group.
Additional points allow the alarm subsystem to report group statistics (number of alarms,
number of unacknowledged alarms, etc.). These additional statistical points are optional.
Page 312
8.4 - Alarm Groups
8.4.1 Alarm Group Point Configuration
An Alarm Group is represented by one or more points in the PI System. The default point
source for Alarm Group points is G. The Alarm Group uses the point class base with a
numeric data type. The parameters that configure an Alarm Group are contained in the
ExDesc attribute.
Attribute Parameters
ExDesc GroupName PointFunc Arg
The GroupName parameter defines the name of the group. The PointFunc parameter
contains the options to be set for the group. Statistics of the Alarm Group are described in the
PointFunc table (Table 8–18). The Arg parameter is a modifier to the PointFunc parameter.
Available statistics include the number of alarms at each priority and the highest priority of
the currently active alarms in the group. Groups can be arranged on a hierarchy.
Table 8–18. PointFunc Options
PointFunc Description
GroupID Setting PointFunc to GroupID defines the Alarm Group. The optional Arg
parameter is the name of the group’s parent group in the hierarchy (if it exists)
UnAck Displays total number of unacknowledged alarms within a group or priority.
The Arg parameter defines the priority for the unacknowledged alarms.
InAlarm Displays total number of points in alarm within a group or priority. The Arg
parameter defines the priority of the alarms.
In that case, the statistics at the parent level include the points in the groups below. Groups
can be arranged to any depth. There is nothing preventing both points and groups from being
assigned to the same group. Table 8–19 shows an example Alarm Group hierarchy with two
subgroups.
Table 8–19. Example Alarm Group
TagName ExDesc Description
AlarmTop AlarmTop Name of Alarm Group for the top of alarm hierarchy and
GroupID also total number of alarm points within the hierarchy in
an Alarm State.
Tot_Unack AlarmTop Total number of unacknowledged alarms in AlarmTop
UnAck hierarchy
AlarmGrp1 AlarmGrp1 Name of Alarm Group that belongs to the AlarmTop
GroupID hierarchy and also the total number of alarm points in this
AlarmTop group that is in an Alarm State.
AlarmGrp1_Unack_1 AlarmGrp1 Number of unacknowledged alarms in AlarmGrp1 with
UnAck 1 priority 1
AlarmGrp1_InAlarm_1 AlarmGrp1 Number of alarm points in an Alarm State in AlarmGrp1
InAlarm 1 with priority 1
PI Server Applications User Guide Page 313
Chapter 8 - PI Alarm Subsystem
TagName ExDesc Description
AlarmGrp2 AlarmGrp2 Name of Alarm Group that belongs to the AlarmTop
GroupID hierarchy and also the total number of alarm points in this
AlarmTop group that is in an Alarm State.
AlarmGrp2_InAlarm_0 AlarmGrp2 Number of alarm points in an Alarm State in AlarmGrp2
InAlarm 0 with priority 0
AlarmGrp2_Unack AlarmGrp2 Total number of unacknowledged alarms in AlarmGrp2
UnAck
This example Alarm Group contains the point AlarmTop that defines the top of the alarm
hierarchy. AlarmTop and Tot_Unack give the statistics of the total number of alarms points
that are in alarm and the total number of unacknowledged alarms in the alarm hierarchy that
are in the alarm hierarchy. AlarmGrp1 and AlarmGrp2 are the two Alarm Groups within the
hierarchy.
AlarmGrp1_Unack_1 and AlarmGrp1_InAlarm_1 are the statistics of the number of
unacknowledged alarms in Alarm Group AlarmGrp1 with priority 1 and the number of alarm
points in AlarmGrp1 that are in alarm with priority 1, respectively.
AlarmGrp2_InAlarm_0 and AlarmGrp2_Unack are the number of alarm points in an
Alarm State with priority 0 in AlarmGrp2, and the statistics of the total number of
unacknowledged alarms in AlarmGrp2, respectively. Using the modifier Arg of ‘UnAck’
with the priority 0 will always return 0 because conditions are always considered
acknowledged.
8.5 Build Alarm Points
Alarm points are created in the same manner as other points except that the Alarm must be of
alarm point class, which includes Base attributes. The point type must be digital and the
PointSource must be ‘@’.
To override the PointSource default values, see Override Default PointSource Values for
Alarms, page 316.
8.5.1 PI TagConfigurator
You can easily create alarm points with the PI TagConfigurator tool. See the OSIsoft
Technical Support Web site to download this tool.
Page 314
8.6 - Build Alarm Group Points
Figure 8–4. PI TagConfigurator Creation of Alarm Point
8.5.2 Piconfig
Alternatively, you can use piconfig to create an alarm point:
@table pipoint
@ptclass alarm
@mode create, t
@istru tag, pointsource, sourcetag, exdesc, pointtype, digitalset,
test1, action1
alarmtag1, @, sinusoid, alarmgrp1, digital, pialarm33, lt (20), lolo 2
@ends
8.6 Build Alarm Group Points
Alarm Group points are created in the same manner as other points. The point type must be
numeric and the PointSource must be G.
To override the PointSource default values, see Override Default PointSource Values for
Alarms, page 316.
8.6.1 PI TagConfigurator
Alarm Group points can be created using the PI Tag Configurator utility, which you can
obtain from the OSIsoft support Web site.
PI Server Applications User Guide Page 315
Chapter 8 - PI Alarm Subsystem
Figure 8–5. PI Tag Configurator
8.6.2 Piconfig
Alternatively, you can use the piconfig utility to create the same Alarm Group point.
@table pipoint
@ptclass base
@mode create, t
@istru tag, pointsource, exdesc, pointtype
alarmgrp1, G, “alarmgrp1 GroupID”, Int32
@ends
8.7 Override Default PointSource Values for Alarms
You can override the default PointSource values by setting particular values in the Windows
Registry. Under the Registry key, SYSTEM/CurrentControlSet/Services/pialarm, the
string values AlarmPS, GroupPS, and SqcPS will be present if used.
For example, in Figure 8–6, the RegEdit screen has been reset with the PointSource for
Alarm points set to A, the PointSource for group points to S, and the PointSource for sqc
alarmpoints to C. Changes take effect only when the pialarm service is restarted.
Page 316
8.8 - Build Alarm Digital State Sets
Figure 8–6. Editing Default PointSource Values for Alarms
For UNIX systems, the command line that starts the Alarm Subsystem may contain optional
arguments to override the default point sources. For the same settings as in the Windows
example above, include the following options in the command line: -ps=A, -gps=S, and -
qps=C.
8.8 Build Alarm Digital State Sets
Alarm Digital State Sets are similar to all digital state sets in that each digital state string must
correspond to a digital state code. The Alarm State Set is special because there is a specific
structure that is required for this type of digital state set. The following piconfig script is an
example that shows how to build a simple Alarm Digital State Set with three
acknowledgement statuses, three priorities, and two conditions - low and high.
@table PIDS
@mode create,t
@istyp delim,
@istru set,
@istru oldcode ,state
@istru ...,
pialm33,
1, ----
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<
6, _* Low <<
7, ** Low <<
PI Server Applications User Guide Page 317
Chapter 8 - PI Alarm Subsystem
8, __ Low _x
9, _* Low _x
10, ** Low _x
11, __ High ^^
12, _* High ^^
13, ** High ^^
14, __ High <<
15, _* High <<
16, ** High <<
17, __ High _x
18, _* High _x
19, ** High _x
20, LOW
21, HIGH
22, 3 3
@ends,
In the above script, the Alarm State Set is named pialm33. There are 22 digital states. The
first digital state is the state of no alarm. In this script, the no alarm status is represented by
the symbol “----”.
1, ----
If the desired representation for no alarm is “No Alarm,” this line in the script would be:
1, No Alarm
The last digital state (22nd) corresponds to the number of acknowledgment statuses and the
number of priorities that exist for the Alarm State Set. In this example, it is three for both. For
only one priority, the line would read as follows:
22, 3 1
The Alarm State Set is created in a manner similar to having three nested loops, where the
outer loop is the condition, the middle loop is the acknowledgement status, and the innermost
loop is the priority. So for each condition, the innermost loop sets the priorities from least
severe to most severe, which are represented here by the symbols “__”, “_*”, “**”.
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
The middle loop then sets the acknowledgement statuses in the order of acknowledged alarm
(“ ^^“), new alarm (“<<”) and unacknowledged alarm missed (“_x”).
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<
6, _* Low <<
7, ** Low <<
8, __ Low _x
9, _* Low _x
10, ** Low _x
Page 318
8.9 - Program Operation
The outer loop finally loops around the conditions. Hence each condition has 3
acknowledgement statuses and 3 priorities, and thus 9 digital states each. Since the first
digital state code is the no alarm condition, digital state codes 2 though 19 are used for the
Alarm States. At the end of the Alarm States are the condition names themselves.
20, LOW
21, HIGH
As mentioned earlier, the last digital state code is used to tell the alarm program how many
acknowledgement statuses and priorities are in the Alarm State Set.
22, 3 3
Further details on encoding and decoding Alarm Digital States is provided in Alarm State Set
Encoding and Decoding, page 321.
8.9 Program Operation
8.9.1 Startup
The Alarm Subsystem program is started with the rest of the system. The location of the
program, pialarm.exe for Windows and pialarm for UNIX, is in the pi\bin directory. All rate
calculations are reset when the PI System or the Alarm Subsystem is restarted.
8.9.2 Alarm Notification
Alarm Points are standard digital points. Client programs can request to be alerted when point
values change through the standard Update Manager mechanisms. PI ProcessBook can use
alarm summary tags as the basis for the operator alert process without signing up for every
alarm point in the system. Future versions of the alarm server will allow a client to receive
alarm updates on an Alarm Group basis.
Viewing Alarms in PI ProcessBook
The following figure shows an example of an alarm display in PI ProcessBook.
PI Server Applications User Guide Page 319
Chapter 8 - PI Alarm Subsystem
Figure 8–7. Example PI ProcessBook Display of Alarms
The example above is edited from the Kamyr display, from the PIDemo example included in
PIProcessBook. It shows the alarm point values next to the values of the source tag as well as
a trend display of the statistics of the alarms for the unit (Unit5). The chart on the bottom left
corner displays the statistics of the alarms for the four other units as well as the current unit.
8.9.3 Error Messages
All significant events in the life of an alarm and Alarm Group point are noted in the system
Message Log, including point additions, edits and error conditions. For UNIX, an additional
log file is called pilarm.log. To monitor logged events, use the pigetmsg utility. See the PI
Server System Management Guide for information about using the pigetmsg utility.
Page 320
8.10 - PI for OpenVMS Upgrade Considerations
8.9.4 Demonstration Points
Demonstration points for the PI Alarm Subsystem are available in the pi\adm directory in the
Alarmpts.dif file but are not automatically created when the system is installed. These alarm
demonstration points can be created by redirecting the file to the piconfig utility. See Chapter
11, The Piconfig Utility, in the PI Server System Management Guide for information about
using the piconfig utility.
$ piconfig < alarmpts.dif
8.10 PI for OpenVMS Upgrade Considerations
The PI Server Alarm subsystem is capable of having all the alarms of the PI for OpenVMS
version and more.
The following are known differences:
The method of alarm messaging is not supported on the server side. The Alarm Client
program will allow for the viewing of alarms and Alarm Groups as well as
messaging. This feature will be available in the future.
A log of the alarms is not available. The history of the alarm is contained in the alarm
points themselves.
Acknowledgement of the alarm is accomplished by selecting the auto-
acknowledgement feature or writing an acknowledged digital state to the PI system
through the PI-API.
8.10.1 New Alarm Subsystem Features in PI Server 3.4
The Alarm Subsystem includes new features that are not included in PI for OpenVMS.
The Alarm Subsystem allows you to set Alarm priorities.
Alarm Groups can incorporate other Alarm Groups, to form hierarchies.
The Alarm Subsystem supports testing of string tags.
8.11 Alarm State Set Encoding and Decoding
Due to the manner in which the Alarm State Set is structured, conversion from the digital
state code or offset to the condition, acknowledgement status, and priority is not as
straightforward as it may seem.
There is a distinction between the manner in which Digital State Sets are created and the
digital state code (offset) that is returned from a client program. For example, the following is
part of the piconfig script to create an Alarm Digital State Set as explained in Section 8.8,
Build Alarm Digital State Sets.
@table PIDS,
@mode create,t
@istyp delim,
PI Server Applications User Guide Page 321
Chapter 8 - PI Alarm Subsystem
@istru set,
@istru oldcode ,state
@istru ...,
pialm33,
1, ----
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<
etc…
In the script, the digital states are numbered starting at 1. On the contrary, the offset, which is
returned from a client program returns the digital state offset in which the number begins at 0.
Therefore, for encoding and decoding, the digital state code is the digital state offset. Hence
the offset for the digital state shown for ** Low ^^ in the script is 3 and not 4.
In order for client applications to convert from digital state codes to the condition,
acknowledgement status, and priority, and vice versa, the following algorithms should be
applied. See section 8.8, Build Alarm Digital State Sets for more information.
8.11.1 Conversion to Digital State code
The algorithm for conversion points first needs to change the condition, C,
acknowledgement status, A, and priority, P, to numeric values. In the conversion the value
for the condition is given by where the condition is placed in the Alarm State Set. For
example, in the Alarm State Set given in Table 8–15, the conditions are listed as follows.
Lolo
Low
High
Hihi
Rate
Step
Change
Dig1
Dig2
Therefore, the position for the condition Hihi within the list of conditions is 4, and the
number of conditions, MaxC, is 9. Nack is the number of acknowledgement statuses. This
number can only be 1 or 3. The numeric value for the acknowledgement statuses, A, for the
case when Nack is 1 will be 1. The numeric values for the situation when Nack is 3, is given
as follows.
A = 0 (Acknowledged)
A = 1 (New Alarm)
A = 2 (Unacknowledged Missed)
The priority, P, is level of severity associated with the alarm. This number increases as the
severity of the alarm increases and goes from 0 to the maximum priority, MxP.
For example, an Alarm State Set with MxP equal to 3 is as follows.
P = 0 (Condition Only)
P = 1 (Alert)
Page 322
8.11 - Alarm State Set Encoding and Decoding
P = 2 (Important)
P = 3 (Most Urgent)
P equal to 0 results in the alarm condition. The number of states per condition Pa1 is given
by multiplying the number of acknowledgeable statuses by the max numeric priority level:
Pa1 = Nack * MxP
For example, if the two conditions in the Alarm State Set are high and low, then MaxC is
equal to 2. The number of states in the Alarm State Set is Nsts.
Nsts = Pa1 * MaxC + MaxC
The digital state code, code, is then given by the following equation.
code = Pa1 * ( C - 1 ) + Mxp * A + P
8.11.2 Conversion from Digital State Code
Given the numeric values for the condition, C, acknowledgement status, A, and Priority, P,
the digital state code, code, is obtained using the following equations points.
C = int( ( code-1)/Pa1 ) +1
A = int( ( code-Pa1*(C-1)-1)/MxP )
P = code-Pa1*(C-1) - MxP * A
In the prior equations, the number of states per condition is Pa1 and the maximum number of
priorities is MxP. These are defined in Section 8.8, Build Alarm Digital State Sets.
8.11.3 Sample Alarm Digital State Sets
The following tables list the four Alarm State Sets and their respective digital state numbers,
which are used in a piconfig session points. The only Alarm Digital State Set that is installed
(by default) is pialarm33.
These Alarm State Sets can be created in a piconfig session using the file almstate.dif.
$ piconfig < almstate.dif
One Priority Alarm Set
Table 8–20. One Priority Alarm Set
Offset AlarmSet
0 .
1 Lolo
2 Low
3 High
4 Hihi
5 Rate
6 Change
7 Dig1
PI Server Applications User Guide Page 323
Chapter 8 - PI Alarm Subsystem
Offset AlarmSet
8 Dig2
9 Lolo <<
10 Low <<
11 High <<
12 Hihi <<
13 Rate <<
14 Change <<
15 Dig1 <<
16 Dig2 <<
17 Lolo _x
18 Low _x
19 High _x
20 Hihi _x
21 Rate _x
22 Change _x
23 Dig1 _x
24 Dig2 _x
25 LOLO
26 LOW
27 HIGH
28 HIHI
29 RATE
30 CHANGE
31 DIG1
32 DIG2
33 31
Three Priority Alarm Set
Table 8–21. Three Priority Alarm Set
Offset AlarmSet
0 .
1 __ Lolo
2 _* Lolo
Page 324
8.11 - Alarm State Set Encoding and Decoding
Offset AlarmSet
3 ** Lolo
4 __ Lolo <<
5 _* Lolo <<
6 ** Lolo <<
7 __ Lolo _x
8 _* Lolo _x
9 ** Lolo _x
10 __ Low
11 _* Low
12 ** Low
13 __ Low <<
14 _* Low <<
15 ** Low <<
16 __ Low _x
17 _* Low _x
18 ** Low _x
19 __ High
20 _* High
21 ** High
22 __ High <<
23 _* High <<
24 ** High <<
25 __ High _x
26 _* High _x
27 ** High _x
28 __ Hihi
29 _* Hihi
30 ** Hihi
31 __ Hihi <<
32 _* Hihi <<
33 ** Hihi <<
34 __ Hihi _x
35 _* Hihi _x
PI Server Applications User Guide Page 325
Chapter 8 - PI Alarm Subsystem
Offset AlarmSet
36 ** Hihi _x
37 __ Rate
38 _* Rate
39 ** Rate
40 __ Rate <<
41 _* Rate <<
42 ** Rate <<
43 __ Rate _x
44 _* Rate _x
45 ** Rate _x
46 __ Step
47 _* Step
48 ** Step
49 __ Step <<
50 _* Step <<
51 ** Step <<
52 __ Step _x
53 _* Step _x
54 ** Step _x
55 __ Change
56 _* Change
57 ** Change
58 __ Change <<
59 _* Change <<
60 ** Change <<
61 __ Change _x
62 _* Change _x
63 ** Change _x
64 __ Dig1
65 _* Dig1
66 ** Dig1
67 __ Dig1 <<
68 _* Dig1 <<
Page 326
8.11 - Alarm State Set Encoding and Decoding
Offset AlarmSet
69 ** Dig1 <<
70 __ Dig1 _x
71 _* Dig1 _x
72 ** Dig1 _x
73 __ Dig2
74 _* Dig2
75 ** Dig2
76 __ Dig2 <<
77 _* Dig2 <<
78 ** Dig2 <<
79 __ Dig2 _x
80 _* Dig2 _x
81 ** Dig2 _x
82 LOLO
83 LOW
84 HIHI
85 HIGH
86 RATE
87 STEP
88 CHANGE
89 DIG1
90 DIG2
91 3 36
8.11.4 Digital Base Set
Single Priority Alarm Set
Table 8–22. Single Priority Alarm Set (Digital Base Set)
Offset AlarmSet
0 .
1 Move
2 Fail
3 OFF
4 Over
PI Server Applications User Guide Page 327
Chapter 8 - PI Alarm Subsystem
Offset AlarmSet
5 Under
6 Change
7 Dig6
8 Dig7
9 Move <<
10 Fail <<
11 OFF <<
12 Over <<
13 Under <<
14 Change <<
15 Dig7 <<
16 Dig8 <<
17 Move _x
18 Fail _x
19 OFF _x
20 Over _x
21 Under _x
22 Change _x
23 Dig7 _x
24 Dig8 _x
25 MOVE
26 FAIL
27 OFF
28 OVER
29 UNDER
30 CHANGE
31 DIG7
32 DIG8
33 31
Page 328
8.11 - Alarm State Set Encoding and Decoding
Three Priority Alarm Set
Table 8–23. Three Priority Alarm Set (Digital Base Set)
Offset AlarmSet
0 .
1 __ Move
2 _* Move
3 ** Move
4 __ Move <<
5 _* Move <<
6 ** Move <<
7 __ Move _x
8 _* Move _x
9 ** Move _x
10 __ Fail
11 _* Fail
12 ** Fail
13 __ Fail <<
14 _* Fail <<
15 ** Fail <<
16 __ Fail _x
17 _* Fail _x
18 ** Fail _x
19 __ OFF
20 _* OFF
21 ** OFF
22 __ OFF <<
23 _* OFF <<
24 ** OFF <<
25 __ OFF _x
26 _* OFF _x
27 ** OFF _x
28 __ Over
29 _* Over
30 ** Over
PI Server Applications User Guide Page 329
Chapter 8 - PI Alarm Subsystem
Offset AlarmSet
31 __ Over <<
32 _* Over <<
33 ** Over <<
34 __ Over _x
35 _* Over _x
36 ** Over _x
37 __ Under
38 _* Under
39 ** Under
40 __ Under <<
41 _* Under <<
42 ** Under <<
43 __ Under _x
44 _* Under _x
45 ** Under _x
46 __ Change
47 _* Change
48 ** Change
49 __ Change <<
50 _* Change <<
51 ** Change <<
52 __ Change _x
53 _* Change _x
54 ** Change _x
55 __ Dig7
56 _* Dig7
57 ** Dig7
58 __ Dig7 <<
59 _* Dig7 <<
60 ** Dig7 <<
61 __ Dig7 _x
62 _* Dig7 _x
63 ** Dig7 _x
Page 330
8.11 - Alarm State Set Encoding and Decoding
Offset AlarmSet
64 __ Dig8
65 _* Dig8
66 ** Dig8
67 __ Dig8 <<
68 _* Dig8 <<
69 ** Dig8 <<
70 __ Dig8 _x
71 _* Dig8 _x
72 ** Dig8 _x
73 MOVE
74 FAIL
75 OFF
76 OVER
77 UNDER
78 CHANGE
79 DIG7
80 DIG8
81 33
PI Server Applications User Guide Page 331
Chapter 9. PI REAL-TIME SQC
Statistical Quality Control (SQC) is the use of numerical methods to monitor the
characteristics of a process, making sure they remain within pre-determined boundaries.
The PI Real-Time SQC (PI SQC) component allows you to apply Western Electric Pattern
Tests to all process or laboratory data collected by the PI System. PI SQC continually reviews
any SQC tests in the PI System. It stores test results, and a record of SQC control limits back
into your PI System. The results are available for viewing and analysis via PI ProcessBook
and the PI SQC Add-In.
PI SQC is a part of PI Alarm, which provides continual evaluation of SQC pattern tests and
the management of alarms generated from them. When an unacceptable deviation from test
norm occurs, PI SQC notifies the PI SQC Alarm Manager.
The chapter includes an overview of SQC fundamentals, an understanding of how PI SQC
works, an explanation of how to configure the PI points on which PI SQC functionality
depends, and instructions on how to install PI SQC.
The following topics are included:
Section 9.1, Introduction to Statistical Quality Control , on page 334
Section 9.2, Case Study for PI Real-Time SQC, on page 334
Section 9.3, Real-Time SQC Definitions, on page 335
Section 9.4, Tests for Unnatural Patterns, on page 337
Section 9.5, PI Real-Time SQC, on page 340
Section 9.6, Pattern Tests, on page 341
Section 9.7, SQC Alarm Priority and Precedence, on page 342
Section 9.8, Create a New SQC Alarm, on page 343
Section 9.9, Start and Run the PI Alarm Subsystem, on page 343
Section 9.10, Associated Point Configuration, on page 347
Section 9.11, PI SQC Alarm Point Configuration, on page 351
Section 9.12, PI Real-Time SQC Chart Types, on page 359
Section 9.13, Default SQC Alarm Digital States, on page 360
Section 9.14, Log Messages, on page 363
PI Server Applications User Guide Page 333
Chapter 9 - PI Real-Time SQC
The following books, on the subject of Statistical Quality Control (SQC), were used in
developing this chapter, and may be helpful in developing your implementation of PI SQC.
Wheeler, Donald J., Advanced Topics in Statistical Process Control: The Power of
Shewart's Charts, 1995, SPC Press, Knoxville
Statistical Quality Control Handbook, 2nd Edition, 1958, Western Electric Company
9.1 Introduction to Statistical Quality Control
Whenever a series of observations or measurements of a process parameter are examined the
measurements will not, in general, be identical to each other. Statistical Quality Control is
beased on the core premise that all processes fluctuate. The fluctuations may be natural or
unnatural. Natural fluctuations are generally small, while unnatural fluctuations are larger and
introduced by external (hopefully, definable) causes. SQC provides a set of simple tools to
identify instances of unnatural fluctuation so that causes can be assigned and corrected.
In simple terms:
Everything Varies – People live to different ages; all patterns fluctuate.
Individual things are unpredictable – You cannot predict exactly how long you will
live; individual points are not predictable.
Groups of things from a constant system of causes tend to be predictable – Actuaries
rely on this to predict life expectancy for insurance companies; a series of points
from a constant process tend to follow a pattern.
It is possible to calculate statistical control limits for any given set of data and to evaluate the
data against those limits. When the data fits within the limits its fluctuations are said to have a
natural pattern. If the data falls outside of the limits it is said to have an unnatural pattern. The
limits can either be defined in terms of a firm number, such as "centerline +/- 3 standard
deviations", or in terms of pattern tests like "4 successive points greater than 2.0 standard
deviations from the center line on the same side of the center line".
The primary method for such evaluation of the process is the Control Chart. Methods for
preparation and interpretation of control charts have been developed over the last 40 years.
Control Charts are employed by a wide range of industries and agencies as a means to
monitor and stimulate improvements in many types of processes.
9.2 Case Study for PI Real-Time SQC
The following example illustrates how PI SQC can be used and helpful in a typical setting.
Tip: If you are not familiar with the principals and practices of Real-Time SQC, read
Section 9.1, Introduction to Statistical Quality Control before you read this
application example.
Page 334
9.3 - Real-Time SQC Definitions and Terminology
Assume that we want to set up an SQC Alarm that will evaluate data entered for a lab test.
We’ve already established a PI point for the manual entry of laboratory results, and we have
been entering data for some time.
Recently, we decided to apply SQC to this laboratory measurement. We used PI ProcessBook
and the SQC Add-In for ProcessBook to construct an ad-hoc SQC chart of individuals for the
measurement. By investigating data collected when the process was running within norms,
we established control limits for the chart. We entered those numeric values into the control
parameters tab for that chart. We decided to apply only the 1 of 1, Outside 3 Sigma limit to
this chart.
The ad-hoc chart served us well for a couple of months; it gave us enough information to
make process improvements. After observing the post-process improvement data for some
time, we recalculated control limits for this lab measurement and found that we could tighten
the chart control limits. Since we decided to keep a history of our control limits over time, we
created PI points into which we entered both the old and the newly calculated control limits.
We then set the control parameters for the chart to get limits from the new PI tags.
After using this chart for a while, we decided that we wanted to alert the operator when the
chart showed that a pattern test failure had occurred, so that action could be taken before we
produced off-spec product. It wasn’t practical for the operator to keep the ad-hoc SQC chart
displayed in the monitor all the time, so we decided to implement an SQC Alarm in PI.
We configured an SQC alarm point to use the same lab value as the ad-hoc chart, the same
control limit tags and to evaluate the same pattern test (Individual Measurements). Now the
SQC calculations happen on the PI Server whenever the lab tester enters a new value. The
operator sees an indication on the PI ProcessBook display if the calculation results in an
alarm condition. The operator can take corrective action and acknowledge the alarm. If the
process is in an upset condition, the operator can suspend the evaluation of the alarm by
clicking on a button on the PI ProcessBook display - and later turn the alarm evaluation back
on when the process returns to normal.
If process engineers review the SQC control limits and enter new SQC control limits lab
measurement, the PI SQC Alarm processor senses the change and begins using the new limits
for the SQC Alarm.
9.3 Real-Time SQC Definitions and Terminology
The following SQC terms and phrases are used in this chapter.
Statistical Quality Control – The use of numerical methods to help keep the
characteristics of a process within boundaries.
• Statistical – drawing conclusions from numbers
• Quality – the characteristics or properties of the process
• Control – keeping something within boundaries
Process – A process is a set of conditions or causes that work together to produce a
result. In an industrial setting a process can be a single control loop, a unit operation, a
PI Server Applications User Guide Page 335
Chapter 9 - PI Real-Time SQC
laboratory measurement, a task performed by a single person or a team, or virtually any
combination of ‘actors’ that work together to produce a result.
Fluctuating Measurements – All processes have parameters that can be measured.
Repeated measurement of a process’s parameters will show fluctuations in the
parameter’s value. Fluctuations can be classified into two types:
• Natural Fluctuation – These are small fluctuations due to the precision of
measurement, the normal small random changes in the process that cannot be
assigned to a cause (Non-definable Cause). Natural fluctuation may be due to
minute variability in equipment, measurement imprecision, or other similar
causes.
• Unnatural Fluctuation – These are large, abnormal fluctuations due to some
external cause. The causes of unnatural fluctuations are generally definable to
some outside influence. For example, an unnatural fluctuation could arise from
software malfunction, field instrument failure, putting the wrong material into the
product or similar causes.
Natural Pattern – A pattern of measurements of a process parameter exhibiting natural
variability due to minute fluctuations in raw materials, equipment, measurement
precision, etc. Obviously, natural fluctuations result in natural patterns. A natural pattern
will always have the all of the following characteristics (source: Statistical Quality
Control Handbook, 1956-1984, Western Electric Company.)
• Most of the points are near the centerline.
• A few of the points spread out and approach the control limits.
• None of the points (or at least only a very rare and occasional point) exceeds the
control limits.
Conversely, unnatural patterns will lack one or more of the three characteristics listed
above.
Unnatural Pattern – A pattern of measurements of a process parameter exhibiting large
fluctuations due to a definable cause.
Tests for Unnatural Patterns – There are two basic premises for testing the naturalness
of a pattern:
• Test individual points versus limits.
• Test multiple points for trend – there are several commonly accepted tests for
trend recognition (e.g. eight points in a row on one side of the plot center line.)
Sample Grouping – Breaking a large collection of measurements into subgroups.
Evaluating subgroup averages and ranges provides a more sensitive tool for spotting
process variations with definable causes (unnatural patterns).
Example
The following example illustrates the above definitions.
Page 336
9.4 - Tests for Unnatural Patterns
Over the last couple of decades there has been an active water-sampling program in the San
Francisco Bay. The graph below depicts the salinity data collected since 1989 at a single
monitoring station at a depth of 1 meter:
C h a r t o f S F B a y S a lin it y S t a 3 3
35
30
25
20
S a lin
15
10
6
8
1
6
6
/2
/1
/1
/2
/1
/1
/1
/1
/1
/1
/1
/2
/1
/2
0
3
2
1
D a t e & T im e
Figure 9–1. San Francisco Bay Salinity
In Figure 9–1, the process is a particular locale in San Francisco Bay. Measurements of
salinity were taken over time at that location. It is clear from the plot that the measurements
fluctuate. In order to learn whether the fluctuations are natural or unnatural we need to be
able to test for unnatural patterns and evaluate the data against those tests.
Statistical quality control can be defined as: defining tests and evaluating data (sets of
measurements) against those tests to determine if data exhibit unnatural patterns.
9.4 Tests for Unnatural Patterns
Historically, Shewart's classic Control Chart test involved testing the samples plotted on the
Control Chart against 3 sigma limits. Over time, people applying SQC instituted additional
tests that sought to check the samples for the presence of unnatural patterns. Over the years a
number of such tests have been established. The basic set of pattern tests is known as the
Western Electric set.
9.4.1 Western Electric Unnatural Pattern Tests
Seven classic pattern tests from the Western Electric SQC book are implemented in PI. For
interpretation of patterns, the area between the upper and lower control limits is broken into 3
zones. The zones along with their names as implemented in PI SQC are illustrated below.
PI Server Applications User Guide Page 337
Chapter 9 - PI Real-Time SQC
Upper Control Limit (UCL)
Zone A (OutsideControl)
Zone B (OutsideTwoSigma)
Zone C (OutsideOneSigma)
Value
Lower Control Limit (LCL)
Sample (or time)
Figure 9–2. SQC Chart Zone Definition
9.4.2 Pattern Types and Tests
Instability
There are four tests for instability. These are the most important of the pattern tests:
1. Any single point that falls outside the 3-sigma limit fails this test.
Figure 9–3. One Point Outside 3 Sigma Limit (Instability)
2. Two out of three successive points fall in Zone A or beyond on one side of the center
line.
Page 338
9.4 - Tests for Unnatural Patterns
Figure 9–4. Two of Three Points in Zone A or Beyond (Instability)
3. Four out of five successive points fall into Zone B or beyond on one side of the
center line.
Figure 9–5. Four of Five Points in Zone B or Beyond (Instability)
4. Eight successive points fall on one side of the center line.
Figure 9–6. Eight Successive Points Fall on One Side of the Center Line (Instability)
Stratification
Samples whose up and down variations are very small in relation to the centerline are termed
stratified. Stratification exists when 15 or more consecutive points fall within Zone C on
either side of the centerline.
PI Server Applications User Guide Page 339
Chapter 9 - PI Real-Time SQC
Figure 9–7. Fifteen Consecutive Points in Zone C (Stratification)
Mixtures
The mixture pattern is one in which points fall near the limits and not near the centerline. The
test for mixture is eight consecutive points on both sides of the centerline where no point is
within Zone C. At least one crossing of the center line must occur.
Figure 9–8. Eight Points on Both Sides of Center with None in Zone C (Mixture)
Trends
Trends are indicated by a series of points that are either monotonically increasing or
decreasing.
9.5 PI Real-Time SQC Configuration
SQC Alarm processing is a critical part of implementing Real-Time SQC. The continual
evaluation of SQC pattern tests and the management of alarms generated from them are the
responsibility of the PI Real-Time SQC product.
Creation and maintenance of SQC Alarms is most easily performed using the PI SQC Alarm
Manager application, which includes its own user guide. The PI point that implements PI
SQC Alarm functionality is called an SQC Alarm. See Section 9.11, PI SQC Alarm Point
Configuration for a detailed discussion of configuration options for an SQC Alarm.
Page 340
9.6 - Pattern Tests
9.5.1 Required and Optional Points
An SQC Alarm requires five points in the Data Archive in addition to the alarm point itself.
Required points provide a data source for the alarm, user control over the operation of the
alarm point, and storage of the SQC control limits. Required points can be shared among
SQC Alarms, if appropriate.
There are five optional PI points that you can configure for an SQC Alarm. One of these
optional points provides detailed reporting on the status of all pattern tests when the Alarm is
set. Other optional points are used by client and user-written programs to associate
specification limits and comments with an SQC Alarm and to drive limit changes based on
the value of another PI point (e.g., product-based limits). See section 9.10, Associated Point
Configuration, for point specifications.
9.6 Pattern Tests
Each PI SQC Alarm has one or more pattern tests defined. A pattern test is in Alarm status if
some maximum number ‘X’ out of a total number ‘Y’ of consecutive samples meets the test
condition (for example, if 2 of 3 samples are outside two standard deviations from the
centerline). The standard Western Electric Pattern Tests are supported:
Outside Control – This test counts the number of samples outside the control limit
on one side of the center line.
Outside Two Sigma – This test evaluates the sample against a limit drawn 2/3 of the
way between the center line and the control limit. Do not confuse sigma in this usage
with the standard deviation of the sample (that interpretation would only be true if, as
classically defined, SQC control limits are set to 3 times the standard deviation of
process measurements; but the control limits could be set to other values depending
on process needs).
Outside One Sigma – This test evaluates the sample against a limit drawn 1/3 of the
way between the center line and the control limit. Do not confuse sigma in this usage
with the standard deviation of the sample.
One Side of CL – This test counts how many samples are on one side of the center
line.
Stratification – This test counts the number of samples that fall within the upper and
lower One Sigma limits on both sides of the center line.
Mixture – This test counts the number of samples that fall outside the upper and the
lower One Sigma limits on both sides of the center line.
Trend – This test counts the number of samples which are monotonically increasing
or decreasing.
PI Server Applications User Guide Page 341
Chapter 9 - PI Real-Time SQC
Upper Control Limit (UCL)
Upper TwoSigma Limit
Upper OneSigma Limit
Value
Center Line (CL)
Lower OneSigma Limit
Lower TwoSigma LImit
Lower Control Limit (LCL)
Sample (or time)
Figure 9–9. Limits for Pattern Tests
The following implementation options are supported for tests 1, 2, 3, and 4:
Test evaluated only above the center line
Test evaluated only below the center line
Test evaluated both above and below the center line
9.7 SQC Alarm Priority and Precedence
The SQC Alarm processor uses the concepts of alarm priority and test precedence established
in the PI Alarm Subsystem. A brief explanation appears below.
9.7.1 Priority
SQC Alarms embody the same concept of priority that is described in Chapter 8, PI Alarm
Subsystem. Higher priority indicates a more immediate operator concern. For example,
consider an alarm system designed with four priorities 0, 1, 2, and 3. A priority of 0 might
indicate an alert for which no action is required, while a priority of 3 indicates a severe alarm
requiring an immediate response.
Each SQC Alarm can be configured to have a priority which applies to all of the alarm's
pattern tests. Selecting a priority may prove useful for incorporating SQC Alarms into Alarm
Groups for the general management of alarms. For more information, see Section 8.6, Build
Alarm Group Points.
9.7.2 Precedence
The seven pattern tests that may be executed with PI SQC have a fixed order of precedence,
as listed below.
Page 342
9.8 - Create a New SQC Alarm
Table 9–1. Precedence of SQC Alarm's Pattern Tests
Precedence Pattern Test
7 OutsideControl
6 OutsideOneSigma
5 OutsideTwoSigma
4 OneSideofCL
3 Stratification
2 Mixture
1 Trend
An SQC alarm point can be configured to test for any combination of these patterns. In such a
point, if more than one pattern test is in alarm status, the highest precedence test will be the
one reported in the SQC alarm point.
9.8 Create a New SQC Alarm
Follow these steps to activate a new SQC Alarm:
Caution: If you perform these steps out of order, an SQC Alarm may be placed in
the Error state.
1. Start the PI Alarm Subsystem. The first time the subsystem runs, it creates the new
point class used for SQC Alarms, and the Digital State Tables used for controlling
SQC Alarm execution and reporting.
2. Create the Associated Points on the PI Server. You can use the Excel Workbooks that
are included in the distribution as templates.
3. Enter initial values for control limit points and enter Normal for the ResetTag and
the TestStatusTag (if used).
4. Create the SQC alarm point. You can use the Excel Workbooks included in the
distribution as a template.
9.9 Start and Run the PI Alarm Subsystem
PI Real-Time SQC is handled by an enhanced version of the PI Alarm Subsystem.
To start the PI Alarm Subsystem, use the command:
net start pialarm
To stop the PI Alarm Subsystem, use the command:
net stop pialarm
PI Server Applications User Guide Page 343
Chapter 9 - PI Real-Time SQC
9.9.1 Initial Subsystem Startup
The first time that the Alarm Subsystem with Real-Time SQC capability is run, it creates the
SQC_Alarm Point Class needed to establish Real-Time SQC Alarms. The subsystem also
creates the pisqcalarm digital state set, which contains the Alarm States used by PI SQC.
During the initial and subsequent Alarm Subsystem startups, messages are logged to the PI
System Message Log, which you can review with the pigetmsg utility.
Determine the PointSource
When the Alarm Subsystem starts up, it determines the PointSource used by SQC Alarms.
The default PointSource is Q. The subsystem finds all points on the server that have the
specified PointSource.
On Windows, you can override the default PointSource by editing the pialarm key in the
Registry. To do this, start RegEdit and select the key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\pialarm
Add a value to this key called SQCAlarmPS. Set the value equal to the letter you want for
the PointSource (for example, Q).
Find all SQC Alarms
For each point found with the PointSource specified above, the Scan attribute is checked. If
the Scan attribute is On, an SQC Alarm is initialized.
Initialize each SQC Alarm
After the SQC Alarm is created, its behavior is set by interpreting the configuration
information in the SQC alarm point attributes. If the subsystem cannot interpret the
configuration information, then a value of Error is written to the point and the point is not
processed further. The following sections describe how SQC alarm point attributes are used
during the subsystem startup.
Source Data
This is the process data source to be monitored. The SourceTag attribute is read and the SQC
Alarm signs up for notification of new data events for the source point.
Control Limits
The UCL, CL, and LCL Tag attributes are read, and the SQC Alarm signs up for notification
of data events on those points.
SQC Execution Control
The ResetTag attribute is read and the SQC Alarm signs up for notification of data events on
the reset point.
Page 344
9.9 - Start and Run the PI Alarm Subsystem
TestStatusTag
The TestStatusTag attribute is read, and if it is a valid PI point, the SQC Alarm uses it for
detailed pattern test reporting.
Pattern Tests
Each SQC Alarm contains seven pattern tests. Each pattern test is initialized by reading its
configuration text.
Event Sign Up
The SQC Alarm also signs up for data events on the SQC alarm points so it will know about
attempts to acknowledge alarms. The current value of the ResetTag is read and used to
preserve the execution state of the SQC Alarm.
An SQC Alarm can be set up to clear when the subsystem restarts. If the ClearOnStart
attribute is set to True then the alarm is cleared, and alarm calculations are started anew. If
the ClearOnStart attribute is set to False then data are retrieved from PI to the pattern test
buffer, the prior state of the SQC Alarm is retrieved from PI, and alarm calculations are
restarted.
9.9.2 Subsystem Startup
Control the Evaluation of SQC Alarms
The SQC Alarm ResetTag attribute controls the execution state of the SQC Alarm. The three
default execution states are Normal, Hold, and Clear:
The Normal state allows the SQC Alarm to be evaluated. If Normal is written to the
ResetTag of an SQC Alarm which was in Hold, the System Digital State Alarm-On
(indicating that the SQC Alarm is active and awaiting a new SourceTag event to
process) will be written to the SQC alarm point.
The Hold state suspends evaluation of pattern tests. If Hold is written to the
ResetTag of an SQC Alarm the System Digital State Alarm-Off (indicating that the
SQC Alarm is no longer active) will be written to the SQC alarm point.
The Clear state clears the pattern test buffer, sets the SQC Alarm in a No Alarm
State and places the SQC Alarm in a Hold state, but the SQC Alarm values remains
as Clear.
If you need to clear and restart the SQC Alarm calculations for an SQC alarm point, you must
first set its ResetTag to Clear and then to Normal. You can do this by using the PI API in
VBA code in PI ProcessBook, Microsoft Excel or in a user-written program. An example
illustrating the technique appears in the PI ProcessBook independent display file, which is
included in the PI SQC distribution.
Evaluate New Source Data
When a new value arrives for the SourceTag of an SQC Alarm, the new value is added to the
collection of previous values used by the test evaluator. Each of the pattern tests is evaluated.
Whenever there is a change to the alarm condition of one or more of the pattern tests, the
PI Server Applications User Guide Page 345
Chapter 9 - PI Real-Time SQC
highest precedence test in alarm is written to the SQC alarm point. The timestamp of the SQC
Alarm will be the same as the source data event time.
If the optional TestStatusTag is configured, then a value corresponding to all tests in alarm
will be written to the TestStatusTag with the same timestamp as the SQC Alarm event. The
TestStatusTag also includes an indication of the side of the center line of the most recent
source data event.
SQC Alarm processing is a Real-Time function; alarms are evaluated whenever new data for
source points arrive. If PI Archive data are edited, or data are inserted into the Archive before
the most recent Snapshot event (out of order data), then the SQC Alarm processor ignores
that data.
Change the Control Limits
The control limits for an SQC Alarm can be changed at any time. When control limits are
changed, new test evaluation limits are calculated for each pattern test. If the SQC Alarm’s
ClearOnLimitChange attribute of the SQC alarm point is set to Yes, then the SQC Alarm is
cleared and alarm calculations are started anew.
If more than one limit is changed for an SQC Alarm, then more than one reset of the alarm
calculations will occur. If you need to change more than one control limit, you can avoid the
multiple resets by first setting the SQC Alarm’s ResetTag to Hold, changing the control
limits, and then setting the ResetTag to Normal. You can do this with the PI API in VBA
code in PI ProcessBook, Microsoft Excel, or in a user written program. An example
illustrating the technique is included in the PI ProcessBook independent display file included
in the PI SQC distribution.
Control limits are applied in real-time. Once a new control limit (one that is different in value
from the existing control limit) is entered, regardless of its timestamp, it is applied to the
Alarms calculated from that moment in real-time forward. If a control limit value is inserted
before the most recent snapshot event for the control limit, it will be ignored.
Acknowledge SQC Alarms
SQC Alarms can be configured to either of two acknowledgement options. The point attribute
that controls acknowledgement behavior is AutoAck. The default value of the SQC Alarm’s
AutoAck attribute is Yes. If the default value is used, then SQC Alarms will appear just as if
the SQC chart were drawn manually – each pattern test failure will result in an Alarm event.
This is the typical manner for evaluating Shewart control charts.
If you wish to require personnel to manually acknowledge an SQC Alarm, set AutoAck to
No. An unacknowledged alarm will be written for each alarm calculated by the pattern tests.
The user has the opportunity to acknowledge the alarm by writing the unacknowledged
digital state to the SQC alarm point.
9.9.3 Subsystem Shutdown
If only the Alarm Subsystem is shut down, SQC Alarm evaluation is simply terminated.
If the entire PI System is shut down, SQC Alarm evaluation is also terminated. All points that
were configured to receive shutdown events will receive the shutdown value.
Page 346
9.10 - Associated Point Configuration
9.10 Associated Point Configuration
An SQC Alarm requires the existence or creation of several PI points in addition to the SQC
alarm point. Also, the user has the option to create several additional PI points that could be
used by user-written programs to further enhance SQC Alarm reporting. All of these points
are described in the following topics, along with the requirements for configuring these
points.
9.10.1 Tools to Create and Edit Associated PI Points
The SQC alarm point and its associated PI points can be configured using the PI
TagConfigurator portion of PI SMT (PI System Management Tools). The PI SMT can be
downloaded from the OSIsoft support Web site. A sample Excel workbook for use with PI
TagConfigurator is included in the distribution media.
Note: When defining a new SQC Alarm, it is important that all of the required,
associated PI points are created before the SQC alarm point is created.
In the following section, the function of each of the required PI points is described in detail.
9.10.2 Summary of Associated PI Points for SQC Alarms
In addition to the SQC alarm point itself, five PI points are required to implement an SQC
Alarm. Additionally, five optional tags may also be created if desired.
Table 9–2. Summary of Associated Points
Tag Alias Description
SourceTag The PI point on which the Alarm Calculations will be performed. This point
MUST have compression turned off (compressing = 0).
Note: If compression on the source tag is not turned off, then alarms will be
calculated based on snapshot events that may later be ‘compressed out.' This
may lead to confusion since alarms might be generated that are not associated
with archived source-data events.
TestStatusTag (Optional) The PI point whose value corresponds to all pattern tests currently in
alarm condition.
ResetTag The PI point whose value sets the execution status of the Pattern Test
evaluation.
UCLTag The PI point whose value is the upper control limit for the chart.
CLTag The PI point whose value is the center line for the chart.
LCLTag The PI point whose value is the lower control limit for the chart.
USLTag (Optional) The PI point whose value is the Upper Specification limit for the chart.
LSLTag (Optional) The PI point whose value is the Lower Specification limit for the chart.
ProductTag (Optional) The PI point whose value represents the current product.
CommentTag (Optional) The PI point for storing comments associated with the SQC Alarm.
PI Server Applications User Guide Page 347
Chapter 9 - PI Real-Time SQC
9.10.3 Configure the Associated Points
Each of the following tag reference attributes of the SQC alarm point hold the TagName of
the PI point to be used in the Alarm calculation.
Although a naming convention for the points associated with the SQC alarm point is not
necessary, you may wish to implement one for ease in recognizing the purpose for the
associated points. One possible convention is to base the names of the SQC alarm point and
all of the associated points on the name of the SourceTag. If the source tag is PV1011
associated tags might be named PV1011.alarm, PV1011.status, PV1011.UCL, PV1011.LCL,
etc.
Note: For the associated points it is usually desirable to archive every value that is
input for that point. Thus, exception reporting and compression are typically turned
off for all associated points.
SourceTag
The SourceTag contains the values from which the SQC Alarm pattern tests are evaluated.
This is also the value that would be charted if the user were generating a graphic SQC Chart.
It is possible to use the same SourceTag for multiple SQC Alarms.
The SQC Alarm’s SourceTag can be any PI point. Typically the SourceTag point will be a
manually entered value for a chart of individuals, or a PI Totalizer Point for aggregated
sampled data. For example, the sampled data could be an average of a fixed number of
manually entered values or a time-weighted average of an analog measurement from a DCS.
The pointtype of the SourceTag should be a numeric data type, typically a floating point
number such as a float32 or float64.
To ensure that archive events for alarms and source tag archive events are in sync, the
SourceTag must have compression turned off.
Note: If compression on the source tag is not turned off, then alarms will be
calculated based on Snapshot events that may later be ‘compressed out.' This may
lead to confusion since alarms might be generated that are not associated with
archived source-data events.
TestStatusTag
The TestStatusTag can be used by customer-written programs in situations where
knowledge of all pattern tests in alarm is needed (for example, in the dynamic creation of
operator action guidelines). A TestStatusTag can only apply to one SQC Alarm.
The TestStatusTag is a point with pointtype int32, whose value is set by the Alarm
Subsystem. The value indicates all of the pattern tests currently in alarm by assigning each of
the pattern tests a bit within the 32-bit word. Whenever a pattern test is in alarm, its bit is set.
If a test is not evaluated, its bit is always zero. After the bits are set for all pattern tests in
alarm, the sign of the TestStatusTag is set to indicate whether the corresponding value of the
SourceTag was above or below the center line for the event triggering the alarm. If the value
of the SourceTag was equal to the center line, the TestStatusTag is positive.
Page 348
9.10 - Associated Point Configuration
The Alarm Subsystem assigns the values given in Table 9–3 to the TestStatusTag based on
the individual SQC pattern-test alarms.
Table 9–3. TestStatusTag Bits Indicate SQC Alarm State
Test Value Bit #
OutsideControl 64 6
OutsideTwoSigma 32 5
OutsideOneSigma 16 4
OneSideofCL 8 3
Stratification 4 2
Mixture 2 1
Trend 1 0
A TestStatusTag value of 0 indicates no tests in alarm; a value of 64 indicates the
OutsideControl test is in alarm; a value of 24 indicates that both the OutsideOneSigma and
OneSideofCL tests are in alarm.
For values of the SourceTag below the centerline, the integer generated by the above bit
setting algorithm is then multiplied by -1.
Table 9–4 provides more examples.
Table 9–4. Examples of TestStatusTag values
Tests in Alarm TestStatusTag
OneSideofCL & Stratification 8+4 12
OutsideTwoSigma & Trend 32 + 1 -33
(SourceTag < CL)
OutsideTwoSigma & 32 + 16 48
OutsideOneSigma
For values of the SourceTag below the centerline, the TestStatusTag will be negative;
however, care must be taken when analyzing the individual bits of the TestStatusTag. Before
analyzing the bits of a negative TestStatusTag, the TestStatusTag should first be multiplied
by -1 to remove the sign. Then the individual bits may be readily analyzed. For example, if
the OneSideofCL alarm has been set because the values of the SourceTag are below the
centerline, the TestStatusTag will first be assigned a value of 8 and then multiplied by -1 to
arrive at -8. When viewed as a group of bits that are set, -8 is represented as
11111111111111111111111111111000, not -100.
PI Server Applications User Guide Page 349
Chapter 9 - PI Real-Time SQC
ResetTag
The ResetTag is used by client programs to control the execution of pattern tests on an SQC
Alarm. The PI Alarm Subsystem looks for updates to the value of the ResetTag and
implements the desired actions. The allowed values of the ResetTag are listed in Table 9–5.
Table 9–5. Values of the ResetTag
Value Action Digital State Offset
Normal Pattern Tests are processed 0
Hold Pattern Tests are not processed, but buffer is 1
preserved (no new values are added to it,
however)
Clear SQC alarm point set to the "no alarm" 2
condition, buffer is cleared, and the SQC Alarm
behavior is the same as if it were placed in
Hold. (i.e. Pattern Tests are not processed. No
new values are placed in the buffer.)
After Clearing an alarm it is necessary to set
the ResetTag to Normal to restart the
processing of the SQC Alarm.
The same ResetTag PI point can be used for multiple SQC Alarm calculations if desired.
The PointType of the ResetTag must be Digital and the DigitalSet attribute should be set to
pialarmcontrol, which is the Digital State Set where the reset values are stored. This Digital
State Set is created automatically when the subsystem starts up for the first time.
UCLTag, CLTag and LCLTag
Control limits are stored in the PI points referenced by UCLTag, CLTag, and LCLTag
parameters. These PI points can be performance equations, manually entry points, or points
whose values come from a DCS or a user-written program. The SQC pattern test evaluation
portion of the PI Alarm Subsystem monitors the values of the control limits and senses
changes in their values (e.g., if the user implements limits that change with product or grade).
The same UCL, CL, and LCL points can be shared among multiple SQC Alarms if desired.
The pointtype of the control limit points should be set a numeric data type, such as a float32
or float64.
If a control limit is changed, the pattern tests for the associated SQC Alarm are reset,
depending on the ClearOnLimitChange attribute. If ClearOnLimitChange = Yes, the SQC
Alarm is placed in the Hold state, the TestBuffer is zeroed and the alarm evaluation is then
set to the Normal state.
USLTag and LSLTag
Specification limits are stored in the PI points referenced by the optional USLTag, and
LSLTag attributes. These PI points can be performance equations, manually entry points, or
points whose values come from a DCS or a user-written program.
Page 350
9.11 - PI SQC Alarm Point Configuration
The pointtype of the control limit points should be set to a numeric data type, such as a
float32 or float64.
These tags are used for display and for calculation of the process capability (Cpk) by version
1.1 or greater of the PI SQC Add-In for ProcessBook. If the attributes are blank, then the
specification limits will not be displayed and the Cpk will not be calculated.
While specification limits are not used in SQC Alarm calculations, users may wish to
establish regular PI Alarms based on the values of the SourceTag relative to the specification
points.
ProductTag
ProductTag is an optional PI point used to designate the current product for which the SQC
Alarm is being calculated. User-written programs might use this point's value to
programmatically adjust the control and specification limits based on the product or grade of
material being manufactured.
CommentTag
CommentTag is an optional PI point for storing comments associated with the SQC Alarm.
Information regarding conditions in the plant environment at certain times may be stored in
this tag. User-written programs may be used to enter and retrieve these comments for use in
process improvements based on attributing SQC Alarms to causes such as the technique
known as Pareto analysis.
9.11 PI SQC Alarm Point Configuration
The PI SQC Alarm Point is the central storage point for all the information needed to
implement a PI SQC Alarm. Configuration information of a SQC alarm point includes all of
the attributes needed to define the PI SQC Alarm’s behavior as well as the associated points
that are referenced by the SQC Alarm.
The following topics describe how to manually configure the PI SQC alarm point. OSI
recommends the use of the PI SQC Alarm Manager application for the creation and
maintenance of SQC Alarms.
Later, you will find discussion of how to configure associated points, both required and
optional, that are used to define a SQC Alarm.
9.11.1 Methods for Configuring PI SQC Alarm Points
The order of point creation is important, because if the SQC alarm point is created before the
associated points (including setting their initial values), then the PI Alarm Subsystem will not
process the SQC Alarm; instead, it will place the SQC Alarm in the Error state.
The PI SQC Alarm Manager is a utility included in the distribution media that will enable
you to create and edit alarm points correctly.
Alarm points can also be configured using the PI TagConfigurator portion of PI-SMT (PI
System Management Tools). PI TagConfigurator currently supports creating, editing, and
PI Server Applications User Guide Page 351
Chapter 9 - PI Real-Time SQC
deleting SQC Alarm tags. Sample Excel workbooks for use with PI TagConfigurator are
included in the distribution media. The instructions in the workbooks step through the
creation of associated points, setting initial values for the associated points, creating the
sample aggregation point (for SQC Alarms other than for a chart of Individuals), and the
creation of the SQC alarm point itself.
9.11.2 SQC Alarm Point Class
SQC Alarm Definition
SQC alarm points have their own point class: SQC_Alarm. This SQC_Alarm point class
contains attributes needed to describe an SQC Alarm. The fundamental attributes that are
required to specify an SQC alarm point are given in Table 9–6.
Note: When specifying attribute values ‘Yes’, ‘Y’, ‘True’, ‘T’, ‘On’ and ‘1’ all have
equivalent meaning and may be used interchangeably. The strings are case
insensitive. The same is true of ‘No’, ‘N’, ‘False’, ’F’, ’Off’ and ‘0’.
Table 9–6. SQC_Alarm Point Class Attributes
Default Value or Valid
Point Attribute Options Description
Ptclass SQC_Alarm The SQC Alarm Point Class
PointType Digital All SQC Alarms are Digital points
Digitalset pisqcalarm Contains SQC Alarm States
PointSource Q Identifies SQC alarm points
Scan 1 or 0 (default=1) On (1) or Off (0). SQC Alarms are only
calculated for scan=On
Compressing 1 or 0 (default=1) On or Off. Should be set to OFF
AutoAck Yes (default) or No Automatic acknowledgement of alarms
ChartType 0-8 (0 is default) Describes type of SQC chart the SQC
Alarm is testing (Used only by the PI SQC
Add-In for ProcessBook).
ClearOnStart Yes or No (default) Yes means start alarm calculations afresh
on startup or editing of the alarm point; No
means seed alarm calculations with
archive values of SourceTag and restore
the alarm’s prior state
ClearOnLimitChange Yes (default) or No Yes means start alarm calculations afresh
when any limit tag changes; No means
continue evaluating alarms using new limit
values.
ExDesc Specifies Alarm Group
Page 352
9.11 - PI SQC Alarm Point Configuration
Default Value or Valid
Point Attribute Options Description
SQCAlarmPriority 0-n (0 is default) Integer value specifies the alarm priority
assigned to all alarms generated by this
SQC Alarm definition.
PIProductLimits <reserved for future use>
WaitOnLimitChange <reserved for future use>
Pattern Test Definitions (if left blank, the pattern test will not be performed)
OutsideControl x of y [<blank>, above, Within y number of samples, x are outside
or below] of control limits. Options: specify above or
below to apply test only above or below the
center line.
OutsideTwoSigma x of y [<blank>, above, Within y number of samples, x are outside
or below] the "Two Sigma" limit. Options: specify
above or below to report alarms for this test
only above or below the center line.
OutsideOneSigma x of y [<blank>, above, Within y number of samples, x are outside
or below] the "One Sigma" limit. Options: specify
above or below to report alarms for this test
only above or below the center line.
OneSideofCL x of y [<blank>, above, Within y number of samples, x are on one
or below] side of the center line. Options: specify
above or below to report alarms for this test
only above or below the center line.
Stratification x of y Within y number of samples, x are within
the "One Sigma" limit.
Mixture x of y Within y number of samples, x are not
within the "One Sigma" limit.
Trend x x consecutive values trend either up or
down.
Associated-Point TagName Definitions
SourceTag TagName for PI point on which the Alarm
Calculations will be performed
TestStatusTag (Optional) TagName for PI point to which
SQC Alarm system writes value indicating
which tests are in alarm
UCLTag TagName for Upper Control Limit
CLTag TagName for Center Line
PI Server Applications User Guide Page 353
Chapter 9 - PI Real-Time SQC
Default Value or Valid
Point Attribute Options Description
LCLTag TagName for Lower Control Limit
ResetTag TagName for PI point governing Alarm
Calculation execution and reset
USLTag (Optional) TagName for Upper
Specification Limit
LSLTag (Optional) TagName for Lower
Specification Limit
ProductTag (Optional) TagName for a PI point to store
the name of the current product or grade
being produced.
CommentTag (Optional) TagName for a PI point to store
comments associated with the SQC Alarm.
Ptclass
This must be set to SQC_Alarm.
PointType
This must be set to digital. The SQC alarm point contains a digital state representing the
value of the highest precedence alarm currently set.
Digitalset
This must be set to pisqcalarm, which contains SQC Alarm States. The digital states in the
pisqcalarm Digital State Set are described in "Default SQC Alarm Digital States," page 360.
PointSource
The PointSource identifies points as SQC alarm points. The default PointSource for SQC
Alarms is Q, although this can be configured to a different string as described in the topic,
Determine the PointSource, in section 9.9.1.
Scan
Scan is used to determine when SQC Alarms are calculated. SQC Alarms are not calculated
when Scan = Off. When Scan is changed from Off to On while the SQC Alarms are running,
the ClearOnStart attribute (described below) determines the SQC Alarm's startup behavior.
Compressing
Compression defaults to On (i.e., 1) for all PI points, but Compressing should be set to
OFF (i.e., 0) to ensure archiving of all SQC Alarms.
Page 354
9.11 - PI SQC Alarm Point Configuration
Note: Exception reporting is not used for SQC alarm points.
Behavior Controls
AutoAck
AutoAck is used for automatic acknowledgement of alarms. It defaults to Yes.
If AutoAck = No, the SQCAlarmPriority needs to be set to a nonzero value in order to use
acknowledgements.
ChartType
ChartType is an indicator used by the PI SQC Add-In to PI ProcessBook. The ChartType
attribute indicates the type of SQC chart for which the SQC Alarms are being calculated.
Valid values are listed in Table 9–7.
Note: This attribute is not used by the PI Server in its SQC calculations. The SQC
Alarm Point’s SourceTag will determine whether this is a chart of individuals, an x-
bar chart, etc. The default value is 0. See page 359 for a description of how to set up
SQC Alarms for the various chart types.
Table 9–7. Valid ChartType Values
Value ChartType
0 Chart type is unspecified (default)
1 Individuals
2 X-Bar
3 Moving Average
4 Exponentially-Weighted Moving Average (EWMA)
5 Standard Deviation
6 Moving Standard Deviation
7 Range
8 Moving Range
ClearOnStart
ClearOnStart=Yes is used to clear any active alarm and start alarm calculations afresh on
startup or after a change to the alarm point’s attributes. No means to start the alarm
calculations using retrieved archive values of SourceTag and to restore the SQC Alarm’s
prior state. If not specified on point creation, ClearOnStart defaults to No.
PI Server Applications User Guide Page 355
Chapter 9 - PI Real-Time SQC
ClearOnLimitChange
ClearOnLimitChange=Yes means clear any active alarm and start alarm calculations afresh
when any control limit tag (UCLTag, CLTag, LCLTag) changes. No means continue
evaluating alarms using new limit values. If not specified on point creation, ClearOnStart
defaults to Yes.
Note: If set to Yes, changing more than one limit tag may result in one reset for each
limit that is changed. This can be avoided by first setting the ResetTag to Clear,
changing the control limits, and then setting the ResetTag to Normal.
PIProductLimits
<Included in Point class and reserved for future use>
WaitOnLimitChange
<Included in Point class and reserved for future use>
Alarm Group Identification
ExDesc
ExDesc specifies an Alarm Group that this SQC Alarm belongs to. SQC Alarms may be
added to existing PI Alarm Groups.
Alarm Priority
SQCAlarmPriority
SQCAlarmPriority is an integer value that sets the priority of the SQC Alarm. Defaults to 0.
This affects how the SQC Alarm will be reported with respect to other alarms and SQC
Alarms on your system. For a discussion of alarm priorities and precedence, see page 342.
In addition to setting AutoAck = No, SQCAlarmPriority must be set to a nonzero value in
order to use acknowledgements.
9.11.3 Pattern Test Configuration
Each SQC Alarm can test for up to seven pre-set patterns. Any combination of pattern tests
may be used in a single alarm. Pattern tests that compare values of the source tag to the
control limits use values of the UCLTag, CLTag, and LCLTag. A description of each test
follows below.
The general form for configuring a pattern test is to enter the text "x of y", where x and y are
positive integers. If a pattern test attribute is left blank it will not be evaluated. The
descriptions of each pattern test also list the values for x of y recommended in the Western
Electric Statistical Quality Control Handbook.
In the case of the Trend pattern test only, x is specified because the test looks for x
consecutively increasing or decreasing values.
Page 356
9.11 - PI SQC Alarm Point Configuration
For four of the tests (OutsideControl, OutsideOneSigma, OutsideTwoSigma, and
OneSideofCL), the modifiers above and below can be added after "x of y" to restrict the
alarm reporting to a single side of the center line. Table 9–8 illustrates the pattern test
configuration options.
Table 9–8. Pattern Test Configuration Examples
Attribute Entry Pattern Test Behavior
<Blank> Test will not be performed (default).
4 of 5 Test looks for 4 out of 5 consecutive values of the SourceTag which
meet the test condition. This test will be evaluated for values of the
SourceTag that are both greater than and less than the value of the
CLTag
2 of 3 above Test will look for 2 out of 3 consecutive values of the SourceTag
which meet the test condition. Alarms resulting from this test will
only be reported for values of the SourceTag that are greater than
the value of the CLTag.
8 of 8 below Test will look for 8 consecutive values of the SourceTag which meet
the test condition. Alarms resulting from this test will only be
reported for values of the SourceTag that are less than the value of
the CLTag.
OutsideControl
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside of
control limits. A value of the SourceTag is outside the control limits when
SourceTag > UCL or SourceTag < LCL.
The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 1
of 1 for this pattern test.
OutsideTwoSigma
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside the
"TwoSigma" limit. A value of the SourceTag is outside the "TwoSigma" limit when
SourceTag > (2/3 * (UCL-CL) + CL) or SourceTag < (CL - 2/3 * (CL-LCL)).
The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 2
of 3 for this pattern test.
OutsideOneSigma
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside the
"OneSigma" limit. A value of the SourceTag is outside the "OneSigma" limit when
SourceTag > (1/3 * (UCL-CL) + CL) or SourceTag < (CL - 1/3 * (CL-LCL)).
PI Server Applications User Guide Page 357
Chapter 9 - PI Real-Time SQC
The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 4
of 5 for this pattern test.
OneSideofCL
This pattern test fails (sets an alarm) when x of y values of the SourceTag are on one side of
the center line. The above or below options can be used with this pattern test to restrict
pattern alarm reporting to one side of the center line. The Western Electric SQC Handbook
recommends 8 of 8 for this pattern test.
Stratification
This pattern test fails (sets an alarm) when x of y values of the SourceTag are within the
"OneSigma" limit. A value of the SourceTag is within the "OneSigma" limit when
(CL - 1/3 * (UCL-CL)) > SourceTag > (CL + 1/3 * (CL-LCL)).
The Western Electric SQC Handbook recommends 15 of 15 for this pattern test.
Mixture
This pattern test fails (sets an alarm) when x of y values of the SourceTag are found on both
sides of the centerline and none of these values falls within "OneSigma." Each of the x values
must satisfy one of the following two conditions
SourceTag > (CL + 1/3 * (UCL-CL)) or SourceTag < (CL - 1/3 * (CL-LCL));
and among the x values, both of these conditions must be met at least once.
The Western Electric SQC Handbook recommends 8 of 8 for this pattern test.
Trend
This pattern test fails (sets an alarm) when x consecutive values of the SourceTag trend either
up or down.
The Western Electric SQC Handbook recommends 8 for this pattern test.
9.11.4 Associated-Point Tagnames
There are several required and optional tags associated with each SQC Alarm. The tag names
of these points are stored in the attributes described below.
SourceTag
Tagname for PI point containing the source data on which the SQC Alarm calculations will
be performed.
TestStatusTag
(Optional) Tagname for PI point to which SQC Alarm system writes value indicating which
tests are in alarm. When this attribute is left blank (the default) the TestStatusTag is not used.
When a TestStatusTag is used, the TestStatusTag point must be unique in each SQC Alarm
definition.
Page 358
9.12 - PI Real-Time SQC Chart Types
UCLTag
Tagname for Upper Control Limit. The same UCLTag can be used in more than one SQC
Alarm definition.
CLTag
Tagname for Center Line. The same CLTag can be used in more than one SQC Alarm
definition.
LCLTag
Tagname for Lower Control Limit. The same LCLTag can be used in more than one SQC
Alarm definition.
ResetTag
Tagname for PI point governing the SQC Alarm calculation's execution and reset. The same
ResetTag can be used in more than one SQC Alarm definition.
USLTag and LSLTag
(Optional) Tagnames for the PI points to store the Upper Specification and Lower
Specification Limits. The same USLTag and LSLTag can be used in more than one SQC
Alarm definition. Leave these tag attributes blank (default) if you do not wish to store your
specification limits in PI points.
ProductTag
Reserved for future use
CommentTag
(Optional) Tagname for a PI point to store comments associated with the SQC Alarm. Leave
this tag attribute blank (default) if you do not wish to store comments in a PI point.
9.12 PI Real-Time SQC Chart Types
The type of control chart for which an SQC Alarm is established depends solely on the SQC
Alarm’s SourceTag. The SourceTag can be any PI point type; creating subgroups of
measurements for use in SQC is generally done using a combination of totalizer and
performance equation points.
9.12.1 Charts of Individuals
The SourceTag for the SQC Alarm here is any PI point. Each new measurement is used in the
pattern test evaluation
PI Server Applications User Guide Page 359
Chapter 9 - PI Real-Time SQC
9.12.2 Moving Average, Moving Range and Moving Standard Deviation
The SourceTag for these types of SQC Alarms is a Totalizer point whose source is the raw
measurement point. The Totalizer point should configured to take the moving average, etc. of
the raw data point based either on a number of raw data events or a time period.
9.12.3 X-Bar, Range and Standard Deviation
The SourceTag for these types of SQC Alarms is a Totalizer point whose source is the raw
measurement point. The Totalizer point should configured to take the average, etc. of the raw
data point based either on a number of raw data events (nsampleblock) or a time period.
9.12.4 EWMA
The SourceTag for the EWMA (Exponentially Weighted Moving Average) SQC Alarm is a
Performance Equation which watches for events on the raw data tag and whose equation
syntax is (note that <xxx> indicates that you need to substitute a value or string):
‘<RawDataTag>’ +
if badval (‘<me>’) then
<Lambda> * PrevVal(<’RawDataTag>’) else
<Lambda> * PrevVal(‘<me>’)
Lambda is the weighting factor whose magnitude you must determine. You should substitute
the name of the Performance Equation tag that you are creating for <me> in the example
above.
9.13 Default SQC Alarm Digital States
The default digital state set (pisqcalarm) for SQC Alarms is automatically installed during
the first startup of the PI Alarm Subsystem. Another Digital State Set can be created for
custom use. The Digital State Set must contain the same seven pattern tests in the same order
as below. You may alter the number of acknowledgement states or priorities or change the
text displayed when a pattern test fails in your custom set. See Create a New SQC Alarm for
details on constructing Alarm Digital State Sets.
The zeroeth state contains the No Alarm digital state. The last digital state (71st in this case),
records the number of priorities and acknowledgement states in the digital state set.
Table 9–9. Default DigitalSet for SQC Alarms
Offset AlarmSet
0 .
1 __ Trend
2 _* Trend
3 ** Trend
4 __ Trend <<
5 _* Trend <<
Page 360
9.13 - Default SQC Alarm Digital States
Offset AlarmSet
6 ** Trend <<
7 __ Trend _x
8 _* Trend _x
9 ** Trend _x
10 __ Mixture
11 _* Mixture
12 ** Mixture
13 __ Mixture <<
14 _* Mixture <<
15 ** Mixture <<
16 __ Mixture _x
17 _* Mixture _x
18 ** Mixture _x
19 __ Stratification
20 _* Stratification
21 ** Stratification
22 __ Stratification <<
23 _* Stratification <<
24 ** Stratification <<
25 __ Stratification _x
26 _* Stratification _x
27 ** Stratification _x
28 __ OneSideofCL
29 _* OneSideofCL
30 ** OneSideofCL
31 __ OneSideofCL <<
32 _* OneSideofCL <<
33 ** OneSideofCL <<
34 __ OneSideofCL _x
35 _* OneSideofCL _x
36 ** OneSideofCL _x
37 __ OutsideTwoSigma
38 _* OutsideTwoSigma
PI Server Applications User Guide Page 361
Chapter 9 - PI Real-Time SQC
Offset AlarmSet
39 ** OutsideTwoSigma
40 __ OutsideTwoSigma <<
41 _* OutsideTwoSigma <<
42 ** OutsideTwoSigma <<
43 __ OutsideTwoSigma _x
44 _* OutsideTwoSigma _x
45 ** OutsideTwoSigma _x
46 __ OutsideOneSigma
47 _* OutsideOneSigma
48 ** OutsideOneSigma
49 __ OutsideOneSigma <<
50 _* OutsideOneSigma <<
51 ** OutsideOneSigma <<
52 __ OutsideOneSigma _x
53 _* OutsideOneSigma _x
54 ** OutsideOneSigma _x
55 __ OutsideControl
56 _* OutsideControl
57 ** OutsideControl
58 __ OutsideControl <<
59 _* OutsideControl <<
60 ** OutsideControl <<
61 __ OutsideControl _x
62 _* OutsideControl _x
63 ** OutsideControl _x
64 Trend
65 Mixture
66 Stratification
67 OneSideofCL
68 OutsideTwoSigma
69 OutsideOneSigma
70 OutsideControl
71 33
Page 362
9.14 - Log Messages
9.14 Log Messages
Errors in configuration of SQC alarm points and errors encountered in the operation of the
subsystem are written to the PI System Message Log. The following section explains how to
view those error messages using the PIGetMsg utility. The error messages are listed along
with hints on how to correct the error condition.
9.14.1 View Log Messages
The PIGetMsg utility provides the means to view all SQC-related messages written to the PI
System Message Log. Use the following command to view them:
pigetmsg -st "pitimestring" -et "pitimestring" -pn "pialarm" -msg "mask"
Substitute a valid time string in PI format for the start and end pitimestring and substitute the
string mask you are interested in for mask. The mask could be a tagname.
9.14.2 Log Message Reference
Wherever you see <SQC Alarm Point> in this list, you will see the name of your SQC alarm
point within the braces in the message log.
Table 9–10 lists the messages that occur under normal operating conditions.
Table 9–10. Informational Messages
Message Explanation
Created the state set The subsystem created one of the digital state sets it needs
to function. Only seen if the state set does not exist at the
time of subsystem startup.
SQC alarm point class OK The subsystem created the SQC Alarm pointclass. Only
seen if the pointclass does not exist when the subsystem
starts up. The subsystem successfully created the
pointclass.
Adding SQC Alarm <SQC A new SQC alarm point has been created on the PI Server
Alarm Point> and it is being picked up by the subsystem.
Previously deleted SQC Alarm The SQC Alarm was previously established. PI point was
<SQC Alarm Point> is being deleted and then re-created. Now it is being picked up by
added again. the subsystem.
Editing SQC Alarm <SQC Alarm The SQC alarm point has been edited and the subsystem is
Point> picking up the changes.
An existing PI point is being The PI point's PointSource was edited to the one used by
changed to an SQC Alarm the subsystem for SQC Alarms and is being picked up by
<SQC Alarm Point> the subsystem.
PointSource edit, deleting alarm The PI point's PointSource was edited to one not used by
<SQC Alarm Point> the subsystem, and the subsystem will no longer process
the point.
PI Point Deleted, deleting alarm The PI point was deleted so the subsystem will no longer
<SQC Alarm Point> process it.
PI Server Applications User Guide Page 363
Chapter 9 - PI Real-Time SQC
Message Explanation
<SQC Alarm Point> Scan set to The SQC Alarm's Scan attribute was set to 'OFF', so the
off subsystem will no longer process it.
<SQC Alarm Point> Scan-off at The subsystem tried to establish the SQC Alarm, but the
initialization – not added point's scan attribute is set to 'OFF'. If this is not what you
want, edit the point using PI SMT and change the scan
attribute to 'ON'.
<SQC Alarm Point> Scan-on ... SQC alarm point was edited and the Scan parameter was
re-initializing. changed from 'OFF' to 'ON'. The Alarm is being put back on
line.
Error Messages
Table 9–11 lists messages that indicate that a serious error has occurred at some point in the
running of PI Real-Time SQC or in the initialization of a Real-Time SQC Alarm.
Table 9–11. Error Messages: Serious Errors
Message Explanation
Failed to create SQC alarm The subsystem had trouble creating the pointclass. Possible
point class ... retrying solution to problem: Open a command window and change
directory to the pi\adm directory. Then issue the command
net stop pialarm. After the services are stopped,
enter the command net start pialarm. Now look in the
message log for the message ‘SQC alarm point class
created’.
<SQC Alarm Point> failed to The digital set specified for the SQC Alarm is not valid.
setup digital set Check to see that you have used a valid digital state set and
that it conforms to the requirements as listed in this chapter.
<SQC Alarm Point> being Subsystem can't get attributes for point during an attempt to
edited but unable to retrieve edit the SQC Alarm.
attributes
<SQC Alarm Point> is wrong The SQC Alarm was not created as a digital point. Change
point type for alarm point the SQC alarm point's pointtype to digital.
<SQC Alarm Point> failed to Unable to retrieve the SQC Alarm's SourceTag attribute.
get sourcetag attribute.Status-
<SQC Alarm Point> update For some reason the subsystem was not able to sign up for
signup for <_sourcetag > data events on the tag.
failed
<SQC Alarm Point> sourcetag The SourceTag was not a recognized type, change the
<_sourcetag> pointtype is not SourceTag pointtype.
valid
<SQC Alarm Point> failed to Unable to retrieve the TestStatusTag attribute.
get teststatustag attribute
<SQC Alarm Point> failed to Unable to get the SQCAlarmPriority attribute.
get SQCAlarmPriority attribute
Page 364
9.14 - Log Messages
Message Explanation
<SQC Alarm Point> update Unable to sign up for data events on the SQC alarm point
signup for <SQC Alarm Point>
failed
<SQC Alarm Point> Status of The current value of the ResetTag for the SQC Alarm is not
< ResetTag > is bad at start NORMAL, HOLD or CLEAR. Enter an initial value of
NORMAL for the reset tag.
<SQC Alarm Point> Status of One or more limit points for this SQC Alarm has a bad
one or more Limits is bad at status (includes 'Pt Created', 'Shutdown', etc). Enter initial
start values for all three limit tags.
<SQC Alarm Point> One or One or more of the pattern test attributes was not properly
more pattern tests failed to defined. Check to see that all pattern tests are properly
initialize configured according to this chapter.
PI Server Applications User Guide Page 365
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
PI Server Applications User Guide Page 367
Technical Support and Resources
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a
Page 368
INDEX OF TOPICS
– operator, 52 Alarm Statistics, 313
* operator, 52 for SQC alarms, 356
/ operator, 52 hierarchy, 313
^ operator, 52 Identification, 356
+ operator, 52 Alarm Group Points
< operator, 52 Building with PI
<= operator, 53 TagConfigurator, 315
<> operator, 53 Building with piconfig, 316
= operator, 53 Alarm Notification, 319
> operator, 53 Alarm Points, 292
>= operator, 53 Building with piconfig, 315
Abs Alarm Set
function in PEs, 70 Single Priority, 327
Absolute time expressions, 50 Three Priority, 324, 329
Absolute Timestamp Alarm State Set, 308
Recalculator Subsystem, 20 Encoding and Decoding, 321
Accumulation Alarm States, 292
Interval, Totalizer, 259 Alarm Subsystem
output, 259 Acknowledgement, 292, 293
Totalizer, 259 Acknowledgement Status, 308
Acknowledgement actions, 293
Alarms, 292, 293, 308 Alarm Group, 312
Acos Alarm State Set, 308
function in PEs, 71 AutoAck, 306
Action 1 point attribute Building Alarm Group Points,
313, 315
in Alarms, 304
Building Alarm Points, 314
Actions
Combiner Logic, 293
Alarms, 293
Condition, 292, 308
Activation tag, 242, 253
ControlTag, 307
Alarm Digital State Sets
Conversion to digital state
Building, 317
code, 322
Alarm Group, 292, 312
PI Server Applications User Guide Page 369
Index of Topics
Converstion from digital state Alarms
code, 323 Number of alarms, 313
DeadBand, 307 Number of unacknowledged
Demonstration Points, 321 alarms, 313
Digital state sets, 360 Alias
DigitalSet attribute, 306 Deleting, 249
Error messages, 320, 363 Renaming a batch alias, 249
ExDesc, 306 Alias Table
IsUnack, 304 Batch Subsystem, 248
new features, 321 AllEvents
Notification, 319 Totalizer, 280
Options, 307 AlmAckStat
Overview, 291 function in PEs, 72
Point Configuration, 294 Almconditon
Points, 292 function in PEs, 73
Priority, 292, 309 AlmCondText
Program Operation, 319 function in PEs, 74
ReferenceTag, 306 AlmPriority
Sample Alarm State Sets, 323 function in PEs, 75
shutdown, 346 And operator, 53
sign up for data events, 345 Archive, 101
SourceTag, 295 retrieval, 63, 65
Start, 319 search, 63
startup, 344 Archive and Time Functions
test, 293 Recalculator Subsystem
Test1, 295 Subsystem, 33
Change, 303 Archiving flag
CondEQ, 303 Recalculator Subsystem, 23
CondNE, 304 Arg Alarm Group, 313
EQ, 298 Argument
GT, 297 Data type, 297
Includes, 302 for built-in functions, 61
Is_In, 301 tagnames as, 48
LT, 298 Arithmetic operations
NE, 298 on Times, 54
Not_In, 301 Arithmetic Operators, 52, 53
RateGT, 299 Arma
RateLT, 300 function in PEs, 76
StepGT, 299 Ascii
StepLT, 299 function in PEs, 78
Upgrading from PI for Asin
OpenVMS, 321 function in PEs, 79
Page 370
Associated Points, 348 Recalculator Subsystem
Atn Subsystem, 34
function in PEs, 80 Bod
Atn2 function in PEs, 84
function in PEs, 81 Bom
Attributes, 63 function in PEs, 85
exdesc character limits, 14 Bonm
PE Subsystem, 11 function in PEs, 86
setting for PEs, 11 Calc Failed message, 59
Totalizer, 260 CalcMode, 261
AutoAck, 346, 355 AllEvents, 280
Alarms, 306 ChangeEvents, 281
Average EventWeighted, 279
Totalizer, 275 TimeTrue, 281
Avg TimeWeighted, 277
function in PEs, 82 Totalizer, 277
Badval Calculated expressions
function in PEs, 83 character limits, 13, 14
Basis time Calculated Points, 6
Recalculator Subsystem, 20 about, 6
Batch Subsystem adding scan classes, 10
Alias Table, 248 calculation expressions, 13
Batch Deletes, 253 creating, 7
Batch Edits, 252 exDesc attribute, 13, 14
configuration, 241 finding scan classes, 10
Operation, 253 finding the PointSource, 8
Pibaunit name table, 253 location3 attribute, 12
Batch tags in Data Archive, 250 location4 attribute, 12
BATCHACTIVETYPE, 242 PointSource attribute, 12
BATCHEXPR, 243 scan attribute, 14
BATCHID scan class offset, 9
Defining, 244 scan class period, 9
Defining for Web Processes, scan class, UTC time flag, 9
245 scan classes, 9
definition of, 241 scheduling, 11
Evaluation, 253 scheduling problems, 17
Behavior Controls setting scan classes, 12
PI SQC, 355 shutdown attribute, 14
BID switching calculations on or
Batch Subsystem, 250 off, 14
Blob tips for creating, 16
Data types, 296 Calculated tags
PI Server Applications User Guide Page 371
Index of Topics
inconsistent data types, 18 Compressing, 354
setting attributes, 11 Computer platform
Calculation expressions, 13 Information, 368
about, 13 CompValue, 262
examples, 14 Totalizer, 284
syntax basics, 45 Concat
Calculation intervals function in PEs, 89
PEs, 11 CondEQ
Celsius scale, 189 Alarms, 303
ChangeEvents Condition
Totalizer, 281 Alarms, 292, 308
Char CondNE
function in PEs, 87 Alarms, 304
Character limits on PEs, 13, 14 Configuration
ChartType, 355 Batch, 241
Check a Point's exDesc Parameter, Totalizer, 258
60 Conjunction Operators, 53
Clapeyron equation, 188 Control chart, 334
ClearOnLimitChange, 350, 356 Control limits, 334
ClearOnStart, 345, 355 changing, 346
Clock Scheduling reset of alarm calculations,
for PEs, 11 346
Recalculator Subsystem, 23 initializing on startup, 344
Clock TotalCloseMode Real-Time application, 346
Totalizer, 266 ControlAlg, 308
Clock-scheduled points ControlTag, 307
setting scan class, 12 Alarms, 307
CloseAtEvent Conversion
Totalizer, 285 Totalizer, 283
CLTag, 347, 350 Conversion factor
Coercion, data type, 18 TagTot function, 163
Combination Time, 20 Conversion, data type, 18
Combined time expressions, 49 Cos
Combiner Logic function in PEs, 90
Alarms, 293 Cosh
CommentTag, 347, 351 function in PEs, 91
Comparing Count
Point Values to Strings, 51 Batch Subsystem, 250
Comparisons Counting Functions
Compare Totalizer, 256, 276
function in PEs, 88 Cpk, 351
in PEs, 56, 59 Critical point of steam, 189
Page 372
Curve Dynamic Functions
function in PEs, 92 Recalculator Subsystem
CYCLETIME tag, 245 Subsystem, 33
Data types Dynamic Response, 64
checking, in PEs, 59 Encoding and Decoding
inconsistent, in PEs, 18 Alarm State Set, 321
DataLink, 6 Engineering units, Steam Tables,
185
Day
Enthalpy
function in PEs, 93
as independent variable, 188
DaySec
Entropy
function in PEs, 94
as independent variable, 188
DeadBand
EQ
Alarms, 307
Alarms, 298
Default
Error Messages
point source for alarm group
points, 313 Alarm, 320
Delay PI SQC, 363
function in PEs, 95 Totalizer, 288
Delete Errors
an Alias, 249 Checking, 58
Demonstration Points in PEs, 16, 59
Alarm, 321 EvalDelay
Totalizer, 290 Batch Subsystem, 243, 253
Dependent Point Event
Recalculator Subsystem, 20 Totalizer, 276
Digital Base Set, 327 Event expression
Digital Set, 354 Totalizer, 267
Alarms, 306 Event RateSampleMode
Digital State Set Totalizer, 265
SQC custom, 360 Event Scheduling
SQC default, 360 for PEs, 11
Digital States Recalculator Subsystem, 23
numbers and strings as, 51 EventChange TotalCloseMode
Steam Tables, 186 Totalizer, 267
Digstate EventCount
function in PEs, 96 function in PEs, 98
DigText EventExpression
function in PEs, 97 Totalizer, 284
Disjunction Operators, 53 EventTag, 12
Documentation EventTrue TotalCloseMode
conventions, v Totalizer, 268
for interfaces, vi EventWeighted
PI Server Applications User Guide Page 373
Index of Topics
Totalizer, 279 function in PEs, 106
EventXX Fluctuation
Totalizer, 277 natural, 336
EventXX_XX unnatural, 336
Totalizer, 277 Forever TotalCloseMode
Examples Totalizer, 273
calculation expressions, 14 Format
Exception reporting, 355 function in PEs, 107
ExDesc, 356 of PEs, 45
Alarms, 306 Frac
ExDesc attribute function in PEs, 108
Checking an, 60 Functions
create calculated point, 6 aggregate, 62
for PEs, 13, 14 as PE operands, 47, 51
Execution control, 344 Attributes
Exp Totalizer, 274
function in PEs, 99 Average, 275
Expressions Events, 276
absolute time, 50 EventXX, 277
combined time, 49 EventXX_XX, 277
PE syntax, 45 math, 62, 64
relative time, 49 Maximum, 276
tagnames in, 47 Minimum, 276
time, tips for, 50 Range, 276
Extended descriptor StdDeviation, 276
character limits, 14 tagnames as arguments, 48
Filter Expression Time, 64
Totalizer, 259, 283 Total, 275
FindEq Totalizer, 261
function in PEs, 100 transcendental, 62
FindGE GroupID
function in PEs, 101 Alarm Group, 313
FindGT GroupName
function in PEs, 102 Alarm Group, 313
FindLE GroupTag
function in PEs, 103 alarms, 294
FindLT GT
function in PEs, 104 Alarms, 297
FindNE Handle
function in PEs, 105 Batch Subsystem, 251
Float Hierarchy
Page 374
Alarm Groups, 313 Left
Hour function in PEs, 116
function in PEs, 109 Len
If-then-else expressions, 53 function in PEs, 117
If-then-else operator, 57 Limits
Impulse on characters in PEs, 13, 14
function in PEs, 110 List
in ( ) operator, 53 aliases
in .. operator, 53 Batch Subsystem, 249
InAlarm location1 attribute
Alarm Group, 313 Recalculator Subsystem, 23
Includes location3 attribute
Alarms, 302 for PEs, 12
Inclusion Operators, 53 PEs, 11
Independent Variables, 187, 188 location4 attribute
InFromTotalizer for PEs, 10, 12
Totalizer, 284 Log
Instability tests, 338 function in PEs, 118
InStr Log10
function in PEs, 111 function in PEs, 119
InstrumentTag, 12 Lower Control Limit tag, 359
Int Lower Specification Limit tag, 359
function in PEs, 112 LSLTag, 347, 350
Interfaces LT
downloading documentation Alarms, 298
for, vi LTrim
PE Subsystem, 6 function in PEs, 120
Intervals between PE calculations, Max
11
function in PEs, 121
Inversion
Maximum
Recalculator Subsystem, 21
Totalizer, 276
Is_In
Median
Alarms, 301
function in PEs, 122
IsDST
MedianFilt
function in PEs, 113
function in PEs, 123
IsSet
Mid
function in PEs, 114
function in PEs, 124
IsUnack
Min
Alarms, 304
function in PEs, 125
LCase
Minimum
function in PEs, 115
Totalizer, 276
LCLTag, 347, 350
PI Server Applications User Guide Page 375
Index of Topics
Minute scheduling problems, 17
function in PEs, 126 Totalizer, 282
Mixture pattern, 340 Offset2
test algorithm, 358 Totalizer, 282
Mod operator, 52 OneAtEnd
Month Totalizer, 286
function in PEs, 127 OneAtStart
MovingCount Totalizer, 286
Totalizer, 268, 270 OneSideofCL, 341
Naming convention, 186 test algorithm, 358
Naming tags, 48 Operands
Natural fluctuation, 336 functions, 51
Natural pattern, 334, 336 in PEs, 46
Natural RateSampleMode numbers as, 47
Totalizer, 263 strings, 48
NE tagnames as, 47
Alarms, 298 tagnames as function
NEWUnitName, 242 arguments, 48
NextEvent time expressions, 49
function in PEs, 128 Operation
NextVal Alarm, 319
function in PEs, 129 Totalizer, 288
NoClampZero Operations on times, 54
Totalizer, 285 –operator, 53
Noon Operators
function in PEs, 130 Arithmetic, 53
Not in PEs
operator, 53 priority, 58
Not_In List of, 52
Alarms, 301 Prefix, 56
NsampleBlock TotalCloseMode Option
Totalizer, 270 Alarms, 307
NsampleMovin TotalCloseMode g CloseAtEvent, 285
Totalizer, 268 OneAtEnd, 286
NSampleMoving OneAtStart, 286
Totalizer, 270 Options field
Numbers Totalizer, 284
as digital states, 51 Setable, 273, 285
as PE operands, 46, 47 Or operator, 53
Offset Out-of-order data
scan class, 9 PI SQC, 346
OutsideControl
Page 376
test algorithm, 357 about, 6
OutsideOneSigma executable, 6
test algorithm, 357 overloading, 17
OutsideTwoSigma skipped calculations, 17
test algorithm, 357 starting and stopping, 7
OverIsTop Performance Equations
Totalizer, 286 about calculated points, 6
Overloading PE Subsystem, 17 adding scan classes, 10
Parameters Built-in functions table, 62, 65
tagnames as, 48 calculation expressions, 13
Totalizer, 258 changing the PointSource, 8
Pareto analysis character limits, 13, 14
comment tag, 351 creating, 7
Parsetime errors in, 16
function in PEs, 132 examples, 14
Recalculator Subsystem, 31 exDesc attribute, 13, 14
Pattern finding scan classes, 10
natural, 334, 336 finding the PointSource, 8
unnatural, 334, 336 How they're used, 6
Pattern tests inconsistent data types, 18
additional options for, 342 location3 attribute, 12
as used in PI Real Time SQC location4 attribute, 12
definitions, 341 number operands, 47
configuration of, 356 operands, 46
definition of, 336 Operators, 52
evaluation of, 345 Parentheses, 58
initializing, 345 Pipetest Utility, 59
precedence, 342 PointSource attribute, 12
order of, 342 scan attribute, 14
Western Electric, 337 scan class offset, 9
zones, 337 scan class period, 9
Pattern types, 338 scan class,UTC time flag, 9
instability, 338 scan classes, 9
mixture, 340 Scheduler, 5, 7
stratification, 339 scheduling, 11
trend, 340 scheduling problems, 17
PctGood setting attributes, 11
PEs, 133 setting scan classes, 12
Totalizer, 282 shutdown attribute, 14
PE Operators. See Operators string operands, 48
PE Subsystem switching calculations on or
off, 14
PI Server Applications User Guide Page 377
Index of Topics
syntax, 45 Scan class period, 9
syntax basics, 45 scan class,UTC time flag, 9
tagnames as function scan classes, 9
arguments, 48 adding for PEs, 10
tagnames as operands, 47 configuring for PEs, 9
tagnames in, 48 setting for PEs, 12
tagnames in expressions, 47 Scan classes
time expressions, 49 finding for PEs, 10
time expressions as operands, Scheduler, 7
49
scheduling, 11
time-based or event-based,
scheduling problems, 17
definition, 5
setting attributes, 11
times as strings, 50
Shutdown attribute, 14
tips, 16
string operands, 48
tips for time expressions, 50
switching calculations on or
troubleshooting, 16
off, 14
Period
syntax, 45
MovingCount, 282
syntax basics, 45
scan class, 9
tagnames as function
Totalizer, 281 arguments, 48
Period2 tagnames as operands, 47
Totalizer, 282 tagnames in, 48
PeriodEnd ReportMode tagnames in expressions, 47
Totalizer, 273 time expressions, 49
PEs time expressions as operands,
about calculated points, 6 49
calculation expressions, 13 times as strings, 50
changing the PointSource, 8 Tips for creating, 16
character limits, 14 tips for time expressions, 50
creating, 7 PI
errors in, 16 Performance Equation
examples, 14 Scheduler, 7
exDesc attribute, 13, 14 PI BA for OpenVMS, 245
finding the PointSource, 8 PI DataLink, 6
inconsistent data types, 18 PI Message Log, 363
location3 attribute, 12 PI Message subsystem, 344
location4 attribute, 12 PI PE Steam module
number operands, 47 definition, 185
operands, 46 naming convention, 186
PointSource attribute, 12 supported functions, 186
scan attribute, 14 PI ProcessBook, 6, 319
Scan class offset, 9 PI SDK, 6
Page 378
PI SMT, 347, 351 in Totalizer, 266
PI SQC Subsystem Point Class
Multiple resets SQC, 352
how to avoid, 346 Point Configuration
Running the subsystem, 345 Alarms, 294
Sample Grouping, 336 Recalculator Subsystem, 34
Zones, 337 Totalizer Points, 258
PI System Point restart
shut down event-scheduled points, 288
impact on SQC, 346 PointFunc
PI System Management Tools, 347, Alarm Group, 313
351 Points
PI TagConfigurator, 347, 351 creating PEs, 7
Alarm Group Points, 315 naming, 48
Building Totalizer Points, 287 PointSource, 354
Piconfig alarm group points, 313
Building Totalizer Points, 287 configuring for PEs, 8
PIGetMsg utility, 363 determining, 344
Pilasttotal_T.dat, 288 how to set default, 344
pipeschd file overriding defaults, 316
adding scan classes, 10 PEs, changing, 8
changing the point source, 8 PointSource attribute
finding scan classes, 10 for PEs, 8, 11, 12
PointSource, 8 PointType, 354
scan classes, 9 Poly
pipeschd.bat, 8 function in PEs, 134
pipeschd.exe, 6 Postprocessing, 255
pipeschd.sh, 8 Prefix Operators, 53, 56
Pipetest Utility, 59 Pressure
Pisqcalarm digital set, 354 as independent variable, 187
PItotal, 256 PrevEvent
Program, 288 function in PEs, 135
Point PrevVal
dependent PE points, 21 function in PEs, 136
Point Attributes Priorities
RateSampleMode Alarms, 292, 309
in Totalizer, 263 Priority
ReportMode PI SQC, 342
in Totalizer, 273 Process
SourceTag definition of, 335
in Totalizer, 263 Process capability, 351
TotalCloseMode
PI Server Applications User Guide Page 379
Index of Topics
ProcessBook, 6 Relative Point Relationship, 28
PRODEXPR, 243 Relative Time Point
ProdIDsearch Relationship, 29
Batch Subsystem, 251 Simple Point Relationship, 24
Product Special Event Point
Relationship, 29
Defining Name, 244
Time Range Point
Product Batch Subsystem, 241
Relationship, 30
ProductTag, 347, 351
Time Shift Point Relationship,
Program Operation 28
Alarm, 319 Recalculator Subsystem
Totalizer, 288 Archive and Time Functions,
PStDev 33
function in PEs, 137 Archive retrieval & search
Ptclass, 354 functions, 32
ptClassName Compression exception, 23
for PEs, 11 compression, calculated
values, 26
Quotes
configuration, 35
around strings, 48
Dynamic Functions, 33
Ramping ReportMode
error and information
Totalizer, 274
messages, 44
Range exception reporting, 26
function in PEs, 138 Extract from Timestamp, 32
Totalizer, 276
functionality, 21
RateGT glossary, 20, 241
Alarms, 299 Incomplete Timestamps, 33
RateLT
installation, 35
Alarms, 300 Limitations, 32
RateSampleMode, 260, 267, 269 manual use for one point, 42
Event, 265 multiple instances of, 41
Natural, 263 options, 37
Point attribute in Totalizer, 263
overview, 19
Scan1, 263 Overview, 19
Scan2, 264 point configuration, 34
Recalculation
starting, 37
Absolute Time Reference step attribute, 25
Point Relationship, 31
time functions, 31
Multi-level Dependency Point
Relationship, 27 time range considerations, 22
Multi-level Time Point tuning, 44
Relationship, 30 Reference State
Recursive Point Relationship, Steam Functions, 189
28 ReferenceTag
Page 380
Alarms, 306 definition, 9
Registry offset, 9
Recalculator Subsystem, 40 period, 9
Relational Operators, 52 scheduling problems, 17
Relative time UTC time flag, 9
expressions, 49 Scan Flag
Relative Timestamp Response to, 288
Recalculator Subsystem, 20 Scan1 RateSampleMode
ReportMode, 261 Totalizer, 263
PeriodEnd, 273 Scan2 RateSampleMode
Point Attribute Totalizer, 264
in Totalizer, 273 Scheduling
Ramping, 274 clock, for PEs, 11
RunEst2, 274 event, for PEs, 11
RunEstimate, 274 Totalizer, 259
Running, 274 Scheduling PEs, 11
Totalizer, 273 problems, 17
ResetTag, 347, 350 SDK, 6
digitalset, 350 SearchStart
functions of, 345 Batch Subsystem, 251
initializing, 344 Second
pointtype, 350 function in PEs, 142
Right Sequencing PEs, 17
function in PEs, 139 Server Application
Round PE Syntax and Functions
function in PEs, 140 Reference, 2
RTrim Performance Equations
Calculator, 1
function in PEs, 141
Performance Equations
RunEst2 ReportMode
Scheduler, 1, 5
Totalizer, 274
PI Alarm Subsystem, 3
RunEstimate ReportMode
PI Batch Subsystem, 2
Totalizer, 274
PI Totalizer Subsystem, 2
Running ReportMode
Real-Time SQC, 3
Totalizer, 274
Recalculator, 19, 20
Sample Grouping
Steam Tables, Syntax and
PI SQC, 336 Functions Reference, 2
Scan attribute, 354 Totalizer, 255
checking on subsystem startup, Server Applications
344
Overview, 1
for PEs, 14
Setable
Recalculator Subsystem, 23
Totalizer, 285
Scan class
PI Server Applications User Guide Page 381
Index of Topics
Sgn How to clear and restart alarm
function in PEs, 143 calculations, 345
Shutdown How to control execution of,
345
Alarm subsystem, 346
initialization,clearing on
Shutdown attribute
subsystem startup, 345
for PEs, 14
initialization,control limits,
Sin 344
function in PEs, 144 initialization,execution control,
Single Priority Alarm Set, 327 344
Sinh initialization,pattern tests, 345
function in PEs, 145 initialization,signing up for
SMT, 347, 351 events, 345
about, vi initialization,source data, 344
Source data Initialization,subsystem error
handling, 344
obtaining on startup, 344
initialization,test status
SourcePoint indicator, 345
Recalculator Subsystem, 20
manual acknowledgement of,
SourceStat 346
Totalizer, 286 point class, 352
SourceTag, 347, 348 PointSource,determining, 344
Point attribute PointSource,how to set default,
in Alarms, 295 344
Totalizer, 263 priority of, 342
Specification limits, 350 required and optional points
SQC alarm, 340 for, 341
acknowledgment options, 346 TestStatusTag
associated points values, 349
SourceTag, 358 TestStatusTag,use of, 346
TestStatusTag, 358 SQC Alarm point
UCLTag, 359 attributes, 352
CLTag, 359 configuring, 351
LCLTag, 359 SQC Chart types
ResetTag, 359 exponentially weighted
moving average, 360
USLTag, 359
individuals, 359
LSLTag, 359
moving average, 360
CommentTag, 359
moving standard deviation,
Behavior on control limit 360
change, 346
range, 360
Finding all, 344
standard deviation, 360
How to change control limits,
346 x-bar, 360
SQC_Alarm Point Class
Page 382
creation of, 344 StmEng_HsatT, 195
SQCAlarmPriority, 356 StmEng_PsatT, 194
Sqr StmEng_SPH, 207
function in PEs, 146 StmEng_SPT, 205
SquareRoot, 12 StmEng_SPTL, 206
SStDev StmEng_SPX, 213
function in PEs, 147 StmEng_SsatP, 192
Start StmEng_SsatT, 196
Alarm, 319 StmEng_TPH, 208
Recalculator Subsystem, 36 StmEng_TPS, 209
Totalizer, 288 StmEng_TsatP, 190
Startup StmEng_VPH, 200
of alarm subsystem, 344 StmEng_VPS, 201
StateNo StmEng_VPT, 198
function in PEs, 148 StmEng_VPTL, 199
States StmEng_VsatP, 193
numbers and strings as, 51 StmEng_VsatT, 197
Statistical Quality Control StmEng_XPH, 210
definition of, 335 StmEng_XPS, 211
introduction to, 334 StmSI_HPS, 228
reference sources, 334 StmSI_HPT, 226
StdDeviation StmSI_HPTL, 227
Totalizer, 276 StmSI_HPX, 236
StDev StmSI_HsatP, 215
function in PEs, 149 StmSI_HsatT, 219
Steam Functions StmSI_PsatT, 218
Reference, 2, 190 StmSI_SPH, 231
valid range, 187 StmSI_SPT, 229
Step attribute StmSI_SPTL, 230
Recalculator Subsystem, 23 StmSI_SPX, 237
Recalculator Subsystem:, 25 StmSI_SsatP, 216
STEP tag, 245 StmSI_SsatT, 220
StepGT StmSI_TPH, 232
Alarms, 299 StmSI_TPS, 233
StepLT StmSI_TsatP, 214
Alarms, 299 StmSI_VPH, 224
StmEng_HPS, 204 StmSI_VPS, 225
StmEng_HPT, 202 StmSI_VPT, 222
StmEng_HPTL, 203 StmSI_VPTL, 223
StmEng_HPX, 212 StmSI_VsatP, 217
StmEng_HsatP, 191 StmSI_VsatT, 221
PI Server Applications User Guide Page 383
Index of Topics
StmSI_XPH, 234 Performance Equations, 15
StmSI_XPS, 235 TagMean
Stop function in PEs, 157
Recalculator Subsystem, 43 TagMin
Stratification function in PEs, 158
pattern test, 339 Tagname or time expression?, 48
test algorithm, 358 Tagnames
String Batch Subsystem, renaming,
function in PEs, 150 249
String functions, 64 in arguments, 61
Strings in PEs, 48, 159
as digital states, 51 TAGnames
as PE operands, 47, 48 as function arguments, 48
Comparing Point Values to, 51 as PE operands, 47
times as, 50 in expressions, 47
using quotes with, 48 TagNum
Subgroups, 336 in PEs, 160
Subsystems Tags
PE, about, 6 naming, 48
PE, executable, 6 TagSource
Syntax function in PEs, 161
PEs, 45 TagSpan
System Management Tools, vi function in PEs, 162
Table TagTot
Pibaunit name, 253 Example, Performance
Equations, 15
Tag
function in PEs, 163
Aliases, 245
TagTot function
Tag Configurator, 347, 351
conversion factor, 163
TagAvg
TagType
function in PEs, 151
function in PEs, 165
TagBad
TagTypVal
function in PEs, 152
function in PEs, 166
TagDesc
TagVal
function in PEs, 153
function in PEs, 167
TagEU
TagZero
function in PEs, 154
function in PEs, 168
TagExDesc
Tan
function in PEs, 155
function in PEs, 169
TagMax
Tanh
function in PEs, 156
function in PEs, 170
TagMax vs. Max Example
Technical Support, 367
Page 384
Temperature setting for PEs, 12
as independent variable, 187 TimeTrue
Test1 point attribute Totalizer, 281
in Alarms, 295 TimeWeighted
Testing alarms, 293 Totalizer, 277
TestStatusTag, 347, 348 Timing Functions
initializing, 345 Totalizer, 276
pointtype, 348 Tips for creating PEs, 16
use of, 346 Total
values, 349 function in PEs, 178
Text Totalizer, 275
function in PEs, 171 TotalCloseMode, 260, 266
Three Priority Alarm Set, 324, 329 Clock, 266
Time expression or tagname?, 48 EventChange, 267
Time expressions EventTrue, 268
absolute time, 50 Forever, 273
and strings, 50 NSampleBlock, 270
Arithmetic operations on, 54 NSampleMoving, 268
as PE operands, 49 TimeMoving, 271
combined time, 49 Totalizer, 266
relative time, 49 Totalization of Digital Tag
tips, 50 Example
Time Functions Performance Equations, 14
Extract from Timestamp, 32 Totalizer Subsystem
Recalculator Subsystem, 31 Building Totalizer Points, 286
TimeEq CalcMode, 277
function in PEs, 172 Compatibility with PI for
OpenVMS, 289
TimeGE
CompValue, 284
function in PEs, 173
Configuration, 258
TimeGT
Conversion, 283
function in PEs, 174
Demonstration Points, 290
TimeLE
Error Messages, 288
function in PEs, 175
EventExpression, 284
TimeLT
Filter Expression, 283
function in PEs, 176
InFromTotalizer, 284
TimeMoving TotalCloseMode
MovingCount, 282
Totalizer, 271
new features, 289
TimeNE
Offset, 282
function in PEs, 177
Offset2, 282
Timestamps
Options field, 284
modifying through
Recalculator, 31 OverIsTop, 286
PI Server Applications User Guide Page 385
Index of Topics
Overview, 255 UniInt
PctGood, 282 downloading documentation
Period, 281 for, vi
Period2, 282 Unit Batch Subsystem, 241
Point Class Attributes, 260 UnitName, Batch Subsystem, 242,
248, 250
Points
Universal Coordinate Time, 55
Building, 286
in PEs, 9
RateSampleMode, 263
Universal Interface
ReportMode, 273
downloading documentation
Scheduling, 259
for, vi
SourceStat, 286
Unnatural fluctuation, 336
SourceTag, 263
Unnatural Pattern, 337
TotalCloseMode, 266
tests for, 336
UnderIsZero, 286
Western Electric tests for, 337
upgrading from PI for
Update events, PEs, 11
OpenVMS, 288
Upgrade from PI for OpenVMS
ZeroBias, 281
Alarm, 321
Trend pattern test, 340, 358
Totalizer, 288
algorithm, 358
Upper Control Limit tag, 359
Triggering events, PEs, 11
Upper Specification Limit tag, 359
Trim
UserInt1, 12
function in PEs, 179
UserReal1, 12
Triple point of water, 189
USLTag, 347, 350
Troubleshooting
UTC, 55
PEs, 16
UTC time flag, scan class, 9
Recalculator Subsystem, 44
Utility
Trunc
pipetest, 59
function in PEs, 180
Values of the TestStatusTag, 349
Type
Web processes, 245
checking, in PEs, 59
Weekday
Type coercion
function in PEs, 182
in PEs, 18
Western Electric SQC book, 337
UCase
Wildcards, 249
function in PEs, 181
Year
UCLTag, 347, 350
function in PEs, 183
UnAck
Yearday
Alarm Group, 313
function in PEs, 184
UnderIsBad
ZeroBias, 261
Totalizer, 285
Totalizer, 281
UnderIsZero
Totalizer, 286
Page 386
PINet and PIonPINet User Guide
PI3 Server 3.4.370
PINet and PIonPINet 2.6
© 2005-2006 OSIsoft, Inc. All rights reserved
OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: [email protected]
Worldwide Offices
OSIsoft Australia OSIsoft Japan KK
Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
Sales Outlets and Distributors
Brazil South America / Caribbean
Middle East / North Africa Southeast Asia
Republic of South Africa South Korea
Russia / Central Asia Taiwan
Revised: January 2006
Send documentation requests, comments and corrections to [email protected].
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE
About this Guide
The PINet and PIonPINet User Guide is part of the OSIsoft PI Server Documentation Set. It
explains how to install and use the PINet and PIonPINet packages that provide distributed
process data acquisition for OpenVMS. PINet and PIonPINet allow parts of a PI for
OpenVMS display system to run transparently on a PINet node.
The PI Server Documentation Set
You can download the most recent version of the PI Server Documentation Set from the
OSIsoft Technical Support Web site (http://techsupport.osisoft.com).
The PI Server Documentation Set includes the following user guides.
Title Subject
Introduction to PI System A simple guide explaining everything you need to do to manage a
Management PI Server. This book walks you through all the basic system
management tasks using point-and-click administration tools.
PI Server Installation and A guide to installing and upgrading PI Servers.
Upgrade Guide
PI Server System An in-depth guide to PI Server system management, including the
Management Guide many command-line tools provided with the PI Server, such as
piconfig, pidiag, and piartool.
PI Server Reference Guide A comprehensive reference guide for the PI Server, including
details on databases and data flow, including exception and
compression.
Auditing the PI Server A guide to maintaining a good audit trail of your process data in the
PI Server.
PI Server Applications User A guide to the PI Server applications: Performance Equations,
Guide Totalizer, Recalculator, Batch, Alarm, and Real Time SQC. These
applications are typically licensed separately from the PI Server.
PINet and PIonPINet User A guide to PINet/OpenVMS and PIonPINet packages (PI-PN)
Guide which allow parts of a PI for OpenVMS display system to run
transparently on a PINet node.
PINet and PIonPINet User Guide Page iii
Preface – Using this Guide
The PI2 Server Documentation Set
The following table provides a summary of key PI2 Server publications. You can download
the latest versions of these and other publications from the OSIsoft Technical Support
Website, http://techsupport.osisoft.com, or http://training.osisoft.com.
The PI Guide Contents
Mastering PI2, Volume I - Volume 1 covers core PI2 Server subsystems. It describes PI data
Server Reference flows, the Data Archive, Event Queue, and Event Manager. It
provides instructions for building points and setting up interfaces,
interface nodes, and status monitoring. It describes utilities and
management tools for the system manager, and their use in
troubleshooting.
Mastering PI2, Volume II - Volume 2 covers Customizing PI2. It includes information for
Server Applications systems managers and users who primarily use terminals to
access the PI2 Server. Topics include: the PI2 menu system, user
accounts and permissions, printing, alarm message routing, and
the Event Logger.
PI2 VMS Manual, Volume 1 Volume 1 covers the Data Archive, Data Trending, Graphics
Package, Performance Equations, Event Logger, Manual Input,
Analysis, Real-Time SQC, Alarms, Profile Display, PC Download,
and the Interactive Report Writer.
PI2 VMS Manual, Volume 2 Volume 2 provides an in depth look at the various Toolkit functions
available with PI2.
PI2 VMS Manual, Volume 3 Volume 3 provides an Addendum for Release 2.0 of the PI2
Toolkit.
PI2 Installation & Upgrade PI2 server applications user reference guide. Tutorial for using
Handbook Trends, Unit Summaries, New Graphics package, Performance
Equations and Formula Library.
See section 6.5, PIonPINet/VMS Operation, for additional PI2 documentation references.
Related Documentation
OSIsoft provides a variety of documentation to help you use and understand the PI Server,
interfaces and client tools. Each interface has its own manual, and each client tool has its own
online help and/or user guide.
PI Server System Managers should read the UniInt End User Manual, which describes the
OSIsoft Universal Interface (UniInt). Many PI interfaces are based upon UniInt, and this
guide can provide a deeper understanding of interface design.
Page iv
Preface – Using this Guide
Using PI Server Tools
The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
the System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.
PINet and PIonPINet User Guide Page v
Preface – Using this Guide
Conventions Used in this Guide
This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case PI CLIENT TOOLS Use the client tool, PI ProcessBook, to verify that all
PI SERVER SUBSYSTEMS data has been recovered.
PI SYSTEM ELEMENTS All incoming data is queued in the Event Queue by
the Snapshot subsystem.
Italic text FILES, DIRECTORIES, PATHS The backup script is in the \PI\adm directory.
EMPHASIS See Auditing the PI Server for Message Log
NEW TERMS information.
PLACEHOLDERS Archive files can be either fixed or dynamic. The
archive receiving current data is called the Primary
FIELDS Archive.
Bold Italic text REFERENCES to a publication See the PI Server Reference Guide …
Bold text SYSTEM and APPLICATION The Archive Subsystem, PIArchss, manages data
components: archives. PIArchss must be restarted for changes to
Subsystems take effect.
Tools / Utilities On UNIX, the site-specific startup script is
pisitestart.sh and on Windows it is
Processes / Scripts / Variables pisrvsitestart.bat.
Arguments / Switches / Options Three Point Database attributes affect compression:
Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
Properties / Methods / Events / known as the compression specifications.
Functions
PROCEDURES and KEY On the Tools menu, click Advanced Options.
COMMANDS Press CTRL+ALT+DELETE to reboot
INTERFACE components Click Tools > Tag Search to open the Tag Search
Menus / Menu Items tool.
Icons / Buttons / Tabs Click the Advanced Search tab.
Dialog box titles and options Use the search parameters PImean Value = 1.
Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: CODE examples use the piartool -ss command. For example:
"Consolas" COMMANDS to be typed on the
font command line (optionally with
arguments or switches)
System INPUT or OUTPUT such
as excerpts from log files and other
data displayed in ASCII text
Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses [email protected]
Page vi
QUICK TABLE OF CONTENTS
Chapter 1. Introduction .................................................................................................................1
Chapter 2. Installing or Upgrading PINet/VMS............................................................................7
Chapter 3. Using and Managing PINet/VMS..............................................................................25
Chapter 4. Advanced Management Topics for PINet ...............................................................45
Chapter 5. Installing PIonPINet/VMS .........................................................................................53
Chapter 6. Using and Managing PIonPINet /VMS .....................................................................59
PINet and PIonPINet User Guide Page vii
TABLE OF CONTENTS
Preface – Using this Guide ..............................................................................................................iii
Table of Figures ..............................................................................................................................xiii
Chapter 1. Introduction .................................................................................................................1
1.1 Overview.............................................................................................................................1
1.1.1 General Features of PINet/VMS.............................................................................2
1.1.2 Client/Server Relationship ......................................................................................4
1.1.3 PI3 System Architecture .........................................................................................5
1.1.4 Features of PIonPINet ............................................................................................5
Chapter 2. Installing or Upgrading PINet/VMS............................................................................7
2.1 System Requirements.......................................................................................................7
2.2 PINet Design Changes / Limits.........................................................................................8
2.3 Memory and Disk Estimates for VAX/VMS......................................................................8
2.3.1 PINet Memory and Disk Estimates.........................................................................8
2.3.2 Memory and Disk Estimates for DEC AXP/VMS Systems...................................10
2.4 PINet/VMS Installation.....................................................................................................11
2.4.1 Preparation for Installation or Upgrade ................................................................11
2.4.2 Instructions - Upgrade from PINet 2.x ..................................................................13
2.4.3 Instructions - New Installation PINet 2.x...............................................................16
2.5 Typical PINet Upgrade ....................................................................................................18
2.6 PINet Installation from Savesets on Another Node’s Disk..........................................20
2.7 Post VMSInstal Steps......................................................................................................21
2.7.1 Installation Verification and Configuration ............................................................21
2.7.2 Automatic PINet/VMS Startup and Shutdown ......................................................22
2.7.3 Manual PINet/VMS Startup and Shutdown ..........................................................22
2.7.4 SnapShot Range Checking ..................................................................................22
2.7.5 Putsnapshot Time Check Enhancement ..............................................................22
2.7.6 PINet to PINet.......................................................................................................23
PINet and PIonPINet User Guide Page ix
Table of Contents
Chapter 3. Using and Managing PINet/VMS..............................................................................25
3.1 PINet/VMS Operation.......................................................................................................25
3.1.1 Files Involved in Installation and Upgrade............................................................25
3.1.2 Directories.............................................................................................................25
3.1.3 Startup ..................................................................................................................25
3.1.4 System Message Log ...........................................................................................26
3.1.5 Point-Related ID Numbers in PI2 versus PI3 .......................................................26
3.1.6 PINet – Co-Mingled Tagnames ............................................................................27
3.1.7 PINet/VMS Utilities ...............................................................................................27
3.1.8 I/ORates Program.................................................................................................30
3.1.9 Shutdown..............................................................................................................31
3.1.10 PINet/VMS Processes ..........................................................................................33
3.2 PINet and DST ..................................................................................................................34
3.3 PINet Backup Scripts ......................................................................................................35
3.3.1 Purposes for Backups ..........................................................................................35
3.3.2 Image Backups.....................................................................................................35
3.3.3 Key Users .............................................................................................................35
3.3.4 Preservation of Databases and History................................................................36
3.3.5 Need Analysis.......................................................................................................36
3.3.6 A Proposed Procedure .........................................................................................37
3.3.7 Other Alternatives.................................................................................................38
3.4 Troubleshooting ..............................................................................................................40
3.4.1 Connection to the PI Home Node.........................................................................40
3.4.2 Logical Names Not Correct ..................................................................................41
3.4.3 Incorrect TCP/IP Vendor Libraries .......................................................................42
3.4.4 Rebuilding the Point Database.............................................................................42
Chapter 4. Advanced Management Topics for PINet ...............................................................45
4.1 Renaming Points on PI3 and the PINet Response .......................................................45
4.2 Renaming Tags in PI3 .....................................................................................................45
4.3 PINet – PointID .................................................................................................................46
4.4 PINet – Migration by Upgrade or New Install................................................................47
4.5 PINet to PINet and PINet as a PI Server Node ..............................................................48
4.6 Troubleshooting PINet Connections .............................................................................50
4.7 Starting PINet on OpenVMS 6.1 and Later ....................................................................51
Page x
Table of Contents
Chapter 5. Installing PIonPINet/VMS .........................................................................................53
5.1 System Requirements.....................................................................................................53
5.1.1 PIonPINet Memory and Disk Estimates ...............................................................53
5.1.2 Memory Requirements .........................................................................................53
5.1.3 Disk Requirements ...............................................................................................54
5.1.4 Memory and Disk for DEC AXP/VMS Systems....................................................55
5.1.5 TCP/IP Software...................................................................................................56
5.2 Installing PIonPINet/VMS ................................................................................................56
5.2.1 Preparing for Install of PIonPINet Node ...............................................................56
5.2.2 Upgrading VMS ....................................................................................................57
5.2.3 Startup ..................................................................................................................57
5.2.4 Shutdown..............................................................................................................57
Chapter 6. Using and Managing PIonPINet /VMS .....................................................................59
6.1 How PIonPINet Works .....................................................................................................59
6.1.1 Normal Operation .................................................................................................59
6.1.2 Failure Modes.......................................................................................................60
6.2 Supported Modules .........................................................................................................60
6.3 Unsupported Modules.....................................................................................................61
6.4 PINet Design Changes / Limits.......................................................................................62
6.5 PIonPINet/VMS Operation...............................................................................................62
Appendix A: PINet and PIonPINet Revision History ....................................................................65
Technical Support and Resources ................................................................................................73
Index of Topics ................................................................................................................................77
PINet and PIonPINet User Guide Page xi
TABLE OF FIGURES
Figure 1-1. – PI2 System Architecture .......................................................................................2
Figure 1-2. – PINet Data Flow....................................................................................................3
Figure 1-3. – PI3 Client/Server Architecture ..............................................................................5
Figure 4-1. – PINet Server Installation .....................................................................................50
PINet and PIonPINet User Guide Page xiii
Chapter 1. INTRODUCTION
1.1 Overview
PINet/VMS provides support for distributed applications to the PI System. Such distributed
applications are generally data acquisition instrument interface programs written originally
for the PI2.x System.
PINet/VMS serves two major functions:
It allows users who are currently using the PI2.x System to migrate to a PI 3 Server
System.
It provides users of PI Server with an expanded list of available data acquisition
instrument interface programs.
The PIonPINet package (PI-PN) allows parts of a PI2.x for OpenVMS display and menu
system to run transparently on a PINet node. This allows distribution of computer load
associated with user terminals and X-Window sessions. It allows users familiar with the
display system and certain optional server applications to continue using them when
migrating the PI Home Node from OpenVMS to PI3 Server. Distributing the display system
may also provide more autonomy for management of users and change in a distributed
environment.
PIonPINet displays use a client/server protocol to retrieve snapshot and archive data from the
PI Home Node. Important information such as point attributes are cached on each node to
improve performance.
Note: Unless otherwise noted, in this guide, "PI Server" generally refers to the PI 3
Server.
PINet and PIonPINet User Guide Page 1
Chapter 1 – Introduction
PI Home Node
Snapshot
Archives
Groups
Users
Optional Modules
PINet PI API and PI SDK PIonPINet
Interfaces Interfaces Snapshot
Event Queue PI ProcessBook Display Library
PINEtSync PI DataLink Custom Menus
ExceptServer User-written Users
Applications Optional Modules
DCS / PLC
Figure 1-1. – PI2 System Architecture
1.1.1 General Features of PINet/VMS
Databases
The primary function of a PINet/VMS node is to support data acquisition interface programs.
As such, programs on the PINet/VMS node can read the following data:
Point Attributes (Tag, Descriptor, Zero, Span, etc.)
Long Tagnames
Snapshot
Archive
Engineering Unit Strings
Digital State Strings
Page 2
1.1 – Overview
The node with the PI System is called the PI Home Node. There can be several PINet
satellite nodes connected to a PI Home Node. PINet/VMS keeps its own local version of the
Point Database and Snapshot Subsystem file. However, point creation must still be performed
on the PI Server System (PI Home) Node.
PINet/VMS connects to the PI Home Node to retrieve archive data, engineering unit strings,
and digital state strings. PINet/VMS also connects to the PI Home Node when it processes
snapshot data for storage into the PI Server.
Time Synchronization
The PINet/VMS node may adjust its system time to match that of the PI Home Node. See the
discussion about PINetSync in section 3.1.10, for more information.
Data Buffering
The PINet/VMS node can buffer data for times when PI is not running on the Home Node or
when the network is down. The PINet/VMS node can be restarted even if PI is not running on
the Home Node.
However, some interface programs require that the PINet/VMS node be connected to the PI
Home Node when the interface is started. (Consult the individual documentation sets for each
of your interfaces to PI for more information.)
The following illustration shows the features and infrastructure of a PINet node.
Figure 1-2. – PINet Data Flow
The data source (an interface) sends exception reports to the PINet SnapShot using a
function, PutSnapShot. PutSnapShot places a data set consisting of a Value, Status and
PINet and PIonPINet User Guide Page 3
Chapter 1 – Introduction
Time Stamp into a memory image called SnapShot. Simultaneously the data set is placed into
the event queue for forwarding to the PI Server Home Node and into the PI Event Manager.
The event queue is monitored by a process called ExceptServ, whose job is to send data sets
to the PI Server and receive confirmations of successful transfers. If the network or PI Server
are offline, the ExceptServ process retries until successful. During times when the network
or PI Server are offline, the Event Queue buffers the data sets to protect against loss. A
process called QManager monitors the event queue. The QManager makes the value, Event
Queue, a virtual queue. It makes sure that no data are lost when the PI Home Node is not
available because of backup or maintenance.
1.1.2 Client/Server Relationship
In a non-distributed PI System for OpenVMS implementation, data archives, calculation
processes, and user displays are contained on a single OpenVMS system, referred to as the PI
Home Node (PI Server). Interface programs can run on any OpenVMS system with PINet
software or on any other platform with PI API software.
PIonPINet supports many of the features of the PI for OpenVMS Home Node through several
mechanisms:
A client/server protocol provides remote access to archive data (which resides on the
PI Home Node.)
A synchronization process provides local assess to the Tag configuration. This
process sets the time on the PIonPINet node to match the PI Home Node.
The current Snapshot values of Tags collected locally are stored locally.
Values sent to PI are queued and sent by a separate process so those data are saved
when the PI Home Node is not available.
PI displays all the features mentioned above. It is a complete version of the menu system
formerly available only on the PI for OpenVMS Home Node along with the most important
display types. This menu system is identical in function to the menu system on the PI for
OpenVMS Home Node, but it contains its own list of displays. A separate user database is
defined on each PIonPINet node.
Page 4
1.1 – Overview
1.1.3 PI3 System Architecture
Figure 1-3. – PI3 Client/Server Architecture
PI3 and PI Clients (PI ProcessBook, PI DataLink, PI API) make it easy to have a distributed
PI3 system with many servers concurrently accessed by clients for data retrieval.
PINet only connects to one PI server at a time. The PINet is custom built for the PI3 server it
runs against.
1.1.4 Features of PIonPINet
PIonPINet/VMS is an optional, layered product which may be separately licensed for
installation on a PINet/VMS node. PINet/VMS is a pre-requisite for PIonPINet/VMS.
PIonPINet/VMS is a subset of the programs and subsystems available from a PI for
OpenVMS Home Node, which have been ported to run on a PINet/VMS node.
PIonPINet/VMS is a complete PINet node with PI for OpenVMS server applications and user
services added.
PIonPINet currently runs on an OpenVMS processor and is supported by PI Server Home
Node version 3.1 or later. Communication from PIonPINet to PI Server Home Nodes is
provided by any of the supported TCP/IP implementations for OpenVMS.
PINet and PIonPINet User Guide Page 5
Chapter 2. INSTALLING OR UPGRADING PINET/VMS
2.1 System Requirements
Platforms
PINet/VMS runs only on VAX or ALPHA computers from Digital Equipment Corporation.
Note: Digital Equipment Corporation (DEC) was purchased by Compaq Computer,
and subsequently by Hewlett Packard (HP). References to PINet/VMS on the DEC
platform, may include servers or operating systems identified with the Compaq or HP
brand name.
OpenVMS
The VAX or ALPHA machine must be running the OpenVMS operating system, version 6.1,
6.2, 7.1 or later. You must be running OpenVMS version 6.1, 6.2, 7.1 or greater. OpenVMS
7.0 is not supported.
TCP/IP Software
One of the following TCP/IP software products is required on the VAX or ALPHA.
DEC TCP/IP Services for OpenVMS (commonly called UCX), v 2.0b or higher
Process Software TCPWare version 3.1 or higher
Process Systems (formerly TGV/Cisco) MultiNet, v3.2 or higher for VAX, v3.4 or
higher for ALPHA
Attachmate (formerly Wollongong) PathWay, runtime release 1.1 or higher
PI on Windows and UNIX
The PI Server must be Version 3.1 or later.
PI2.x on OpenVMS
PINet/VMS Systems older than version 2.0.9 must first be upgraded to 2.0.9 before they can
be further upgraded to PINet/VMS 2.12 or later. Note that the PINet software for a node
connecting to a PI Server system is specially compiled for this purpose. The PINet software
which was compiled for connection to PI for OpenVMS servers should not be used with PI
version 3.1 or later servers.
PINet and PIonPINet User Guide Page 7
Chapter 2 – Installing or Upgrading PINet/VMS
2.2 PINet Design Changes / Limits
Point License Increase
PINet has two parameters related to the size of the Point Database, Ultimate Point Count and
Current Point Limit. These parameters are important even when the Home Node is a PI3
Server since they are used to determine the size of the Point Database on the PINet/VMS
node.
Ultimate Point Count size changes increase the physical size of the Point Database. As a
result, the amount of disk and memory required for such a PINet System could increase to
support such an upgrade.
Current Point Limit is the licensed number of points for the PINet System. If it were
necessary to increase the size of Current Point Limit larger than the present setting for
Ultimate Point Count, then both parameters would be changed.
Point License Impacts PINet
The PI System for OpenVMS will reuse the point number of a deleted point. The PI3.x
Server does not. The point number of any new point is higher than all previous point
numbers. In PINet or PIonPINet versions earlier than 2.2, this had an impact on PINet/VMS
since PINet/VMS has a fixed size Point Database that is indexed by point number. This
limitation is addressed in the version 2.2 and later releases of PINet/VMS.
Changing VMS Platforms
Migration from VAX to AXP should only be performed for recent PI versions. (For PINet
version 2.6 "recent" means PINet 2.1.0 or later.) This minimizes compatibility issues and
guarantees the highest possible success.
2.3 Memory and Disk Estimates for VAX/VMS
OSIsoft has developed a spreadsheet model that can assist in planning for PI disk and
memory requirements, including VAX, AXP, for PINet, and PIonPINet. Contact your
OSIsoft Salesperson for a copy or download the spreadsheet from OSIsoft Technical
Support’s web site at:
http://techsupport.osisoft.com/support_smr_systemsizing.aspx
2.3.1 PINet Memory and Disk Estimates
We expect that there will be some give and take in memory requirements for PINet version
2.2 and later. Refer to the release notes and installation instructions for more details. Section
5.1.1, PIonPINet Memory and Disk Estimates discusses memory and disk estimates for AXP-
based VMS systems.
Page 8
2.3 – Memory and Disk Estimates for VAX/VMS
Memory Requirements
Feature Memory Requirements
Point Attributes: 125 bytes/ultimate Tag
Archive tables: 6144 bytes/max. # archive files on PI Home Node
Other PINet tables: ~50000.00 bytes
Allow at least 1.5 megabytes memory for VMS system usage. If your VAX is a member of a
cluster, add an additional 1.5 megabytes for each VAX in the cluster. A minimum of 16
megabytes of memory is required. OSIsoft recommends that 25% spare memory be present.
For some interfaces when data is collected on the PINet Satellite node, add 1.3 megabytes or
more of memory to allow for databases or shareable images, such as:
• Allen Bradley PLC (0.6 MB)
• Fisher CHIP (1.3 MB)
• Foxboro FCG (1.3 MB)
• Foxboro AIS (1.3 MB)
• Honeywell CM50S (7.5 MB)
• Rosemount RMTHost (1.3 MB)
• Taylor MOD 300 (1.3 MB)
• Westinghouse WDPF (1.3 MB)
• Yokogawa Centap (1.3 MB)
Manuals for the DCS vendor-supplied software contain information for planning for your
system's memory and disk requirements.
Disk Requirements
Feature Disk Requirements
Point Database file: 512 bytes/ultimate Tag
Other data files: ~50000 bytes
Other PINet files: 35 to 40 megabytes
VMS disk requirements Swap file: 10 megabytes
consisting of: Pagefile: 40-50 megabytes
Vendor interface files: 10 megabytes maximum
When collecting PI Home Node data, vendor interfaces requiring disk space are:
Allen-Bradley PLC (1.3 MB)
Fisher CHIP (6.5 MB)
Foxboro FCG (2.75 MB)
Honeywell TDC3000 (18 MB)
Rosemount RMTHost (8 MB)
PINet and PIonPINet User Guide Page 9
Chapter 2 – Installing or Upgrading PINet/VMS
Taylor MOD300 (9.5 MB)
Westinghouse WDPF (6 MB)
Yokogawa Centap (5.4 MB)
Manuals for the DCS vendor-supplied software contain information helpful for planning
system memory and disk requirements.
An important PINet feature is its ability to spool or queue process data during times when
communication with PI Home Node is lost. To allow proper disk space for spooling, calculate
800 to 1500 bytes per Tag being collected by this node per day for which you would like to
accumulate backlogged data. Reasonable time spans for accumulations of backlogged data
vary. Typical time spans from one to five days. OSIsoft considers four days to be the
minimum practical time span.
Note: OSIsoft recommends 20% to 90% free disk space.
At runtime, the PI System uses PINetBuild. We require that you leave PINetBuild on your
PINet and PIonPINet nodes. PINetBuild is required for startup as well as any upgrade or
technical support of your system.
VMS Disk Requirements
Note: These are rough estimates. Requirements are very dependent on system
configuration and what other applications (relational databases as an example) are
running.
Our estimate for VMS disk requirements includes VMS, DECNet End-Node, typical TCP/IP,
C, FORTRAN, DECWindows as well as swap and page files for one to four users.
VMS System Disk Requirements
VMS ( 5.x+): 120 megabytes. Includes:
Swap file: 10 megabytes (20000 pages).
Pagefile: 50-100 megabytes (100000-200000 pages).
Feature Disk Requirements
Vendor interface 10 megabytes nominal
files:
For fewer than three users you may be able to reduce pagefiles to 25 megabytes (50000
pages). For three to four users you may find that a 30-megabyte (70000 pages) pagefile is
enough.
2.3.2 Memory and Disk Estimates for DEC AXP/VMS Systems
PI on DEC ALPHA (AXP/VMS) platforms enjoys massive compatibility with VAX/VMS
based systems. The major differences are in the size of programs and some data structures.
Page 10
2.4 – PINet/VMS Installation
The ALPHA is a 64-bit machine, so everything will be 2 or more times as large. Data
structures on ALPHA are forced into 64-bit words and in many cases must be page-aligned.
If you are running PINet on DEC ALPHA platforms running OpenVMS you can estimate
your memory and disk requirements as follows:
Requirements for DEC AXP/VMS
Memory Use the sections above to estimate your memory needs as though your system was
running under VAX/VMS. Multiply the result by 2.5 to get your AXP/VMS PIonPINet
memory requirement.
Disk Multiply the VAX/VMS requirement for program file disk space by 2.5 to get the AXP
PINet disk size. Multiply the data and configuration file requirement from VAX/VMS by
4 to get your AXP/VMS PINet disk requirement.
2.4 PINet/VMS Installation
Before you start, be sure to perform all of the following preparation steps.
Refer to the HP/Compaq Guide To Open VMS Software Installation for complete
information on the VMSinstal command procedure.
2.4.1 Preparation for Installation or Upgrade
Each PINet node takes approximately 1.5 hours to install, while PIonPINet node installations
require about 2 hours. Factors such as CPU speed and licensed database size affect the overall
time required.
PINet/VMS Machine
Back up your VMS system disk.
Windows or UNIX Machine
The PI Server System must be installed and functioning on the Windows or UNIX machine
before installation of PINet/VMS interface node can be performed. The best way to confirm
the required operation of PI Server is to run either PI DataLink or PI ProcessBook and
connect to the PI Server (Home) Node.
Security
A PITrust must be defined for the PINet or PIonPINet node. Refer to the PI Server System
Management Guide for instructions regarding PITrust creation.
Create a PITrust for each of your PINet and PI API/SDK nodes to use. The PITrust permits
those nodes to write data to PI without having to log in.
The PINet or PIonPINet node’s PITrust must be defined prior to installation or upgrade of
PINet or PIonPINet.
PINet and PIonPINet User Guide Page 11
Chapter 2 – Installing or Upgrading PINet/VMS
The Proxy database of PI3.2 has been replaced with a Trust table in PI3.3. During upgrades
from PI3.2 to PI3.3, the PIProxy table is automatically converted to a new PITrust table.
Proxies and Trusts are similar to the model for network security used by PI2.
VAX or ALPHA Machine
Prior to installation of PINet/VMS, TCP/IP software must be running on the VAX or ALPHA
machine. In addition, the VAX/ALPHA needs to be able to recognize, via TCP/IP, the PI
Server machine by name. One way to confirm this name translation is to run the FTP program
on the VAX/ALPHA.
For example, if the machine running PI Server is called PITHREE,
$ ftp PITHREE
If the VAX/ALPHA successfully connects to PITHREE, then it translated the name correctly.
If a name translation error occurred, you should enter the name and address of the PI on
Windows and UNIX machine into the local host table of the VAX/ALPHA.
The following examples describe briefly how to add a machine called PITHREE to the local
host database for the different TCP/IP software products. Consult their documentation for
more information.
UCX
$ ucx set host “PITHREE” /addr=123.145.167.21
TCPWare
Edit the TCPWARE:Hosts. file.
MultiNet
Edit the MultiNet:Hosts.Local file. After editing, run the following commands:
$ multinet host_table compile
$ @multinet:install_databases
PathWay
Edit the TWG$ETC:Hosts. file.
Shutdown and restart.
Check Virtual Memory
Confirm that the virtual memory of VMS is adequate to begin the installation by issuing
the command:
$ show memory/full
Examine the report on your screen. Confirm that the total size of all pagefiles of the
system is:
Page 12
2.4 – PINet/VMS Installation
For this PI Node Type On Platform Minimum Size
PINet Satellite VAX 70000 pages
PIonPINet Satellite VAX 100000 pages
PINet AXP 120000 pages
PIonPINet Satellite AXP 200000 pages
… where a page is 512 bytes for VAX systems. (A page may be known as pagelets on
AXP).
If your system does not have enough pagefile capacity, consult your VMS installation
and upgrade documentation.
2.4.2 Instructions - Upgrade from PINet 2.x
If you currently have a PINet/VMS System running on your VAX or ALPHA talking to a
PI2.x System, some files should be deleted and renamed before installing PINet/VMS to
communicate with PI Server.
1. Log in to the VAX/ALPHA with the SYSTEM account.
2. Shut down PINet/VMS. Make sure all PI shareable images are uninstalled.
$ @pinet:removepishareables
and check to make sure no PI files are open:
$ show device/file pinet
3. Execute @PINet:PINetVerify to confirm that no PI processes are running. For
example:
PI Processes (w/CPU usage):
No PI processes running
4. Log off all other users to ensure that PI processes will not be started.
5. Rename the PINet:EventQ.Dat file (to PINet:EventQ.Save). If this migration
preserves the Point ID, you might want to reload this event queue after the upgrade.
If it is a completely new Point Database, the Event Queue file can be deleted.
6. Change the PINet:PINetNames.com file so that the Home Node symbol points to the
PI Server machine. For example, if your PI Home Node is named PITHREE:
$ HomeNode := PITHREE
7. Execute @PINet:PINetNames.com.
8. Rename the PISysDat:Point.Dat file to PISysDat:Point.Old. This will force
PINet/VMS to retrieve during installation the copy of the Point Database from the PI
Server system rather than use the old PI2.x System Point Database. At the beginning
of the linking stage, you will see:
%PINet-I-RESTORE, Restoring product saveset B
This is a NEW INSTALLATION of PINet:
PINet and PIonPINet User Guide Page 13
Chapter 2 – Installing or Upgrading PINet/VMS
The above message regarding a new installation may be ignored.
9. Put the upgrade CD in the VMS system’s CD drive and issue the following
commands:
$ MOUNT/OVERRIDE=IDENTIFICATION-
_$ MEDIA_FORMAT=CDROM-
_$ UNDEFINED_FAT=FIXED:NONE:9216 cd-device
$ @Sys$Update:VMSInstal PINet026 -
_$ cd-device:[000000]
Note: If your VMS system does not have a CD drive, insert the CD into a PC
running Windows 95 or greater. Copy the PINet installation kit files to a
temporary directory on your VMS system using either FTP or WRQ Reflection 4,
in binary transfer mode.
10. On the VMS system, issue the command:
$ SET FILE/ATTRIBUTE=LRL:9216 PINet026.*
Then, run Sys$Update:VMSInstal, specifying your temporary directory as the
location of the installation kit.
11. Substitute the name of your CD drive for cd-device. PINet026 is the product name for
PINet/VMS, release V 2.6.
Note: The character "0" in PINet026 is zero.
The VMSInstal dialogue will guide you. In the OpenVMS installation procedure,
brackets are used to indicate default answers. For example,
* Do you want to continue? [YES]
12. Press the < RETURN > key to indicate YES.
VMSInstal checks that these SysGen parameters are set greater than or equal to the
following values:
MAXBUF 20480
GBLSECTIONS 256
LNMPHASHTBL 512
LNMSHASHTBL 512
The values for the SysGen parameters GBLPAGES and VIRTUALPAGECNT and
PQL_DPGFLQUOTA are calculated at installation time.
If any of these parameters are inadequate, VMSInstal revises the data file
Sys$System:ModParams.dat. With your consent, VMSInstal runs AUTOGEN with
NOREBOOT NOFEEDBACK. VMSInstal prompts you to reboot your system and
restart the installation procedure.
Page 14
2.4 – PINet/VMS Installation
Note: If you have Honeywell CM50 software installed and plan to load the
TDC3000 interface, the SysGen parameters GBLPAGES, VIRTUALPAGECNT
and the System account quota PAGEFLQUO may need to be substantially
larger than the procedure calculates. If you have more that one computer
gateway (CG), or many lists, add 4,500 pages plus 200 pages for each list to the
GBLPAGES calculation. VIRTUALPAGECNT and PGFLQUO will need to be at
least 100,000. Also, if you plan to use the TDC3000 interface, you should set
your PageFile.Sys file to be within the range of 75000-120000 for VAX, and
100000-200000 for AXP. You may resize the pagefile via the
Sys$Update:Swapfiles.com file.
13. You are asked (i) whether PINet/VMS will communicate to the PI Home Node via
TCP/IP and (ii) whether the PI Home Node runs on Windows or UNIX (versus
running on VMS).
Answer YES to both of these questions. The following file is edited to reflect your
answers:
PINet:PINetNames.com
PINet 2.2 and later permit the size of the PINet node's Point Database size to be
changed easily to match the license limit of the PI Server Home Node. On upgrade,
the PINet node's Point Database size is checked, if there is a change in Point
Database size, a message will be written to the screen.
Point Database size change requires a complete synchronization of the databases
copied to the PINet node. This can take up to 45 minutes or so. In rare cases there is a
problem with this synchronization processing; refer to section 3.4.4, Rebuilding the
Point Database for the procedure to complete the synchronization (to manually
rebuild the Point Database.)
14. If you are using your own option file that specifies PISub/Lib explicitly, you may
want OSIsoft to build PISub.olb during this upgrade.
This is a deprecated feature – installations of PINet 2.3 and later will not present this
question during the VMSInstal dialog.
Note: For PI version 2.0.x, 2.1.x and 2.2, the former PISub library is split into two
libraries: PISubShr.olb and PISubNoShr.olb. If you have not written any PI Toolkit
applications and do not have any third party PI software, this modification is
transparent. If you are using PILink:PITKLib.opt (or any OSIsoft-supplied link option
file) when linking your applications, your applications will link normally. Therefore,
PISub.olb is NOT needed.
PISub.olb requires approximately 20000 blocks in addition to 20000 blocks used for
temporary files.
If there is enough disk space to support a copy of PISub.olb, you will be prompted as
follows:
Do you want PISub.olb built? [NO]
PINet and PIonPINet User Guide Page 15
Chapter 2 – Installing or Upgrading PINet/VMS
If there is insufficient disk space, you will be warned to modify your option files.
You will also be given the option to continue the upgrade as follows:
Do you want to continue? [YES]
If you choose to continue the upgrade, the PI System will upgrade normally.
However, it is likely that any applications linked in the procedure
PINet:SiteSpecificLink.com with special link option files will fail. At some point, you
will need to modify your special link option files.
Replace the line:
PILink:PISub/Lib
with the two lines:
PILink:PISubNoShr/Lib
PILink:PISubShr/Lib
A better option is to change the link command procedures to use PILink:PITkLib.opt.
15. Re-link any programs you have written which use PI subroutines such as interfaces or
other custom programs. VMSInstal will automatically perform the commands in
PINet:SiteSpecificLink.com.
16. Check PINet:SiteStart.com and PINet:SiteStop.com. These command files should
contain the site-specific startup and shutdown commands for your system. These are
mostly interface programs and user-written programs based on the PI Toolkit.
2.4.3 Instructions - New Installation PINet 2.x
1. On the PINet/OpenVMS node, log in to VAX/ALPHA with the SYSTEM account.
2. Insure that all other users are logged off your system. Stop batch jobs and application
programs such as databases. This requirement is due to the disk space calculations
performed during the installation of PINet/OpenVMS, which presuppose that no
other programs are concurrently allocating disk space. Use this command to
determine if they have logged out.
$ show users /full
3. Put the upgrade CD in the VMS system’s CD drive and issue the following
commands:
$ MOUNT/OVERRIDE=IDENTIFICATION-
_$ MEDIA_FORMAT=CDROM-
_$ UNDEFINED_FAT=FIXED:NONE:9216 cd-device
$ @Sys$Update:VMSInstal PINet026 -
_$ cd-device:[000000]
Note: If your VMS system does not have a CD drive, insert the CD into a PC
running Windows 95 or greater. Copy the PINet installation kit files to a
temporary directory on your VMS system using either FTP or WRQ Reflection 4,
in binary transfer mode.
Page 16
2.4 – PINet/VMS Installation
On the VMS system, issue the command:
$ SET FILE/ATTRIBUTE=LRL:9216 PINet026.*
Then, run Sys$Update:VMSInstal, specifying your temporary directory as the
location of the installation kit.
4. Substitute the name of your CD drive for cd-device:. PINet026 is the product name
for PINet, release V 2.6.
Note: The character "0" in "PINet026" is a zero.
The VMSInstal dialogue will guide you.
In the OpenVMS installation procedure, brackets are used to indicate default
answers. For example,
* Do you want to continue? [YES]
Press the < RETURN > key to indicate YES.
5. VMSInstal checks for the VMS Queue Manager. If it is not running, VMSInstal
starts it and includes the invocation of the VMS queue manager in the system startup
file, Sys$Manager:SyStartup_VMS.com (VMS 6.x).
6. As part of a new installation procedure, VMSInstal will create an OSIsoft account on
your system. The UIC is usually [400,400] unless this has already been used. The
account has privileges for remote maintenance, but only TmpMbx and NetMbx by
default. OSIsoft personnel change the password at each site periodically. The account
has the DISUSER flag set initially and must be changed. To activate the OSIsoft
account :
$ Set Default Sys$System:
$ Run Authorize
UAF> Modify OSI/Flag=NoDisuser
UAF> Exit
7. VMSInstal also checks that these SysGen parameters are set greater than or equal to
the following values.
MAXBUF 20480
GBLSECTIONS 256
LNMPHASHTBL 512
LNMSHASHTBL 512
The values for the SysGen parameters GBLPAGES and VIRTUALPAGECNT and
PQL_DPGFLQUOTA are dependent on each particular VAX/ALPHA. Thus, these
values are calculated at installation time.
Special Notes:
If you have Honeywell CM50 software installed and plan to load the TDC3000
PINet and PIonPINet User Guide Page 17
Chapter 2 – Installing or Upgrading PINet/VMS
interface, the SysGen parameters GBLPAGES, VIRTUALPAGECNT and the
System account quota PAGEFLQUO may need to be substantially larger than
the procedure calculates. If you have more that one computer gateway (CG), or
many lists, add 4,500 pages plus 200 pages for each list to the GBLPAGES
calculation. VIRTUALPAGECNT and PGFLQUO will need to be at least
100,000.
Also, if you plan to use the TDC3000 interface, you should set your
PageFile.Sys file to be within the range of 75000-120000 for VAX, and 100000-
200000 for AXP. You may resize the pagefile by executing the VMS command:
@Sys$Update:Swapfiles.com
If any of these SysGen parameters are inadequate, VMSInstal revises the data file
Sys$System:ModParams.dat. With your consent, VMSInstal runs AUTOGEN with
NOREBOOT NOFEEDBACK. The VMSInstal procedure prompts you to reboot
your system and restart the procedure.
8. You are prompted for disk device names for the new PINet/OpenVMS directories.
9. You are also asked (i) whether PINet/OpenVMS will communicate to the PI Home
Node via TCP/IP and (ii) whether the PI Home Node runs on Windows or UNIX
(versus running on VMS).
Answer YES to both of these questions. The PINet:PINetNames.com file is edited to
reflect your answers.
10. With your consent, VMSInstal edits the Sys$Manager: files SyStartup_V5.com
(VMS 5.x) or SyStartup_VMS.com (VMS 6.x) and Sys$Manager:SyShutDwn.com to
automatically start up and shut down PINet/OpenVMS.
11. The installation procedure restores files from CD and links the PINet/OpenVMS
System. Depending on the capabilities of the machine, this may take 60 minutes or
more.
2.5 Typical PINet Upgrade
$ @sys$update:vmsinstal
OpenVMS VAX Software Product Installation Procedure V6.2
It is 23-APR-2005 at 09:45.
Enter a question mark (?) at any time for help.
* Are you satisfied with the backup of your system disk [YES]?
* Where will the distribution volumes be mounted: DKA300:[PISAVESET.LOQUAT26]
Enter the products to be processed from the first distribution volume set.
* Products: pinet026
* Enter installation options you wish to use (none):
The following products will be processed:
Page 18
2.5 – Typical PINet Upgrade
PINET V2.6
Beginning installation of PINET V2.6 at 09:45
%VMSInstal-I-RESTORE, Restoring product save set A ...
%PINET-I-CHKVMSVER, Checking VMS version ...
%PINET-I-VEROSI, Verifying OSIsoft accounts ...
%PINET-I-CHKSYSNUM, Checking that system numbers match...
%PINET-I-CHKGBLINS, Checking that all PINET global sections are deinstalled ...
%PINET-I-SYSGEN, Checking sysgen ...
%PINET-I-DEFMBXBUFQUO, Better PINet performance if defmbxbufquo is 4128.
-PINET-I-DEFMBXBUFQUO, Your current defmbxbufquo is 1056
%PINET-I-VERSYSACT, Verifying quotas for the System account ...
Before this upgrade you should have backed up the
PINET directories to another disk or directory.
* Are you satisfied with the backup of your PINET directories [YES]?
PINet will be communicating to PIHome via TCP/IP. If you
wish to change the protocol to DECNet, please follow the
instructions in PINetBuild:PINetTransport.txt before
continuing with the upgrade.
* Do you wish to continue with the installation [YES]?
%PINET-I-CHECKPOINTSIZE, Checking point database size...
%PINET-I-DELETE, This installation deletes pinetbuild.
* Ok to proceed [YES]?
%PINET-I-DELPINETBUILD, Deleting PINetBuild ...
%PINET-I-MODIFY, Modifying new pinetstart.com for xwindows ...
%PINET-I-MODIFY, Modifying new pinetstop.com for xwindows ...
No more questions for about 1 hour as
the remainder of PINET is restored to disk and
the PINET images are built.
%PINET-I-RESTORE, Restoring product save set B ...
PINet UPGRADE:
>>> This procedure purges the PINet directory as it goes to <<<
>>> save disk space. <<<
Linking shareable images...
Linking PINet Node programs...
Copying files...
Linking Interfaces...
PINetInstall completed
Check PINetBuild:PINetInstall.out for errors
$ copy pinetbuild:pinetinstall.out pisysmgr: !/00108/
$ purge/nolog pisysmgr:pinetinstall.out/keep=3 !/00108/
$ Set NoVerify
%VMSInstal-I-MOVEFILES, Files will now be moved to their target directories...
------------------------------------------------------------------------------
Beginning the PINet Installation Verification Procedure.
IVP successful.
Installation of PINET V2.6 completed at 10:42
PINet and PIonPINet User Guide Page 19
Chapter 2 – Installing or Upgrading PINet/VMS
2.6 PINet Installation from Savesets on Another Node’s Disk
To install products across the network using VMSInstal, there must be a default proxy
account on the serving host so that the destination node can access the installation kits. This is
because the VMSInstal utility cannot accept user name and password in the command
statement.
Set up a default proxy as follows:
LYCHEE::DISK$PIDISK:[PITAPE]>set default sys$system:
LYCHEE::SYS$SYSROOT:[SYSEXE]>run authorize
UAF> sho /proxy
_remote user: *
Default proxies are flagged with (D)
UAF> add /proxy guava::system system/d
%UAF-I-NAFADDMSG, record successfully added to network proxy data base
UAF> exit
%UAF-I-NOMODS, no modifications made to system authorization file
%UAF-I-NAFDONEMSG, network proxy data base modified
%UAF-I-RDBNOMODS, no modifications made to rights data base
From this point, PINet installation can proceed normally as below:
LYCHEE::SYS$SYSROOT:[SYSEXE]>set host guava
Welcome to the PINet System
Username: SYSTEM
Password:
Welcome to VAX/VMS V5.5
Last interactive login on Thursday, 4-AUG-1994 18:41
Last non-interactive login on Thursday, 4-AUG-1994 17:56
$ dir lychee::dkb0:[pitape]
Directory LYCHEE::DKB0:[PITAPE]
PINET020.A;1 PINET020.B;1
Total of 2 files.
$ @sys$update:vmsinstal pinet020 lychee::pi$system:[pitape]
VAX/VMS Software Product Installation Procedure V5.5-2
It is 4-AUG-1994 at 18:45.
Enter a question mark (?) at any time for help.
* Are you satisfied with the backup of your system disk [YES]?
The following products will be processed:
Page 20
2.7 – Post VMSInstal Steps
PINET V2.0
Beginning installation of PINET V2.0 at 18:46
%VMSInstal-I-RESTORE, Restoring product save set A ...
%PINET-I-CHKVMSVER, Checking that VMS version is 5.2 or greater ...
%PINET-I-VEROSI, Verifying OSIsoft accounts ...
At this point, the PINet installation kit is opened by the VMSInstal utility, and the
installation proceeds normally.
2.7 Post VMSInstal Steps
2.7.1 Installation Verification and Configuration
You should always verify a PINet/VMS installation. Follow these steps.
1. Check PIBuild:PINetInstall.out for errors if the IVP failed. Do this by editing and
searching for the following strings: "%", "-f-", "-e-", "-w-", "fatal".
2. If necessary, add PINetStart to the OpenVMS system site-specific startup file. Do
this by following the steps in section, 2.7.2, Automatic PINet/VMS Startup and
Shutdown.
3. If necessary, add PINetStop to the OpenVMS system site specific shutdown file. Do
this by following the steps in section 2.7.2, Automatic PINet/VMS Startup and
Shutdown.
4. Install the interfaces. Setup instructions or an installation checklist is included in the
documentation for each interface.
5. Edit the IORates.Dat file to record the rate at which (1) interfaces are collecting data,
and (2) the PINet/VMS System is processing data. See I/ORates in section 3.1.10,
PINet/VMS Processes for details.
6. Many interfaces support scan performance Tags which can provide information on
how long it takes to scan data. Refer to the documentation for each of your interfaces
for more information and details on configuring these Tags.
7. Edit the ShutdownEvents command line in PINet:ShutdownEvents.com and
PINet:CheckForCrash.com to archive shutdown events for the real time points of
your system. See the PINet/VMS Operation section for details.
8. For PI Home Node, PINet Satellite Node and PIonPINet Nodes, choose your option
for SnapShot range checking. Edit the command file, PINet:SetSnapChkRange.com,
to specify an option to do range checking in PINet's SnapShot for point type "R"
points (Float16, Float32). The default is no range checking (argument set to 0). To
specify range checking, set the argument to 1.
9. Run the following PINet/VMS utility programs and record the results. Compare the
current results with past results to help you detect future changes in the VMS
resource requirements of PINet/VMS.
PINet and PIonPINet User Guide Page 21
Chapter 2 – Installing or Upgrading PINet/VMS
Record the number of global pages required by PINet/VMS.
$ Run PIBuild:PINetGblPages.exe
Record the minimum number of virtual pages for your system with PINet/VMS.
$ Run PIBuild:PINetVirtPageCnt.exe
2.7.2 Automatic PINet/VMS Startup and Shutdown
VMSInstal may have already modified the operating system startup and shutdown files,
provided that you answered [YES] to the request during a new installation.
If not, you can enable automatic startup and shutdown.
Edit the Sys$Manager: file SyStartup_VMS.com (OpenVMS 6.x, and later versions) or
SyStartup_V5.com (VMS 5.x) and add the following lines at the end. Substitute the
appropriate disk drive name for dua0.
$! Start PINet System
$ @dua0:[PINet]PINetstart
If necessary, edit Sys$Manager:SysShutdwn.com and add the following lines at the end:
$! Shut down the PINet System
$ @PINet:PINetStop
2.7.3 Manual PINet/VMS Startup and Shutdown
You can start or stop PINet from DCL. You must log on as SYSTEM. To start PINet, enter
the following:
$ @dua0:[pinet]pinetstart
(Substitute the name of your disk for dua0.)
To stop PINet from DCL:
$ @pinet:pinetstop
2.7.4 SnapShot Range Checking
At PINet nodes, there is an option, SetSnapChkRange, for setting range checking for new
data coming into the snapshot. The default behavior is range checking off. With range
checking off, snapshot values are allowed to exceed the range defined by the point's zero and
span attributes. With range checking on, any new snapshot value that exceeds the point's zero
and span is automatically replaced with a status value of UnderRange or OverRange, as
appropriate.
2.7.5 Putsnapshot Time Check Enhancement
Sometimes, it is necessary for the PINet system time to be different (time zone or DST
setting) than the time of a PI3 server. In this special case, even if the interface provides the
correct timestamps (by applying offset) for the data, it is possible for the PINet putsnapshot
to reject the data because of time in the future check.
Page 22
2.7 – Post VMSInstal Steps
In PINet 2.6 and later, you can use a system wide option to disable the Snapshot future time
check. You can modify this setting in the command file setSkipPITimeChk.com in the PINet
directory. You can modify and run the command file at anytime to change the time check
setting.
2.7.6 PINet to PINet
Instead of connecting a VMS PINet node directly to a PI Server, you can connect a PINet
node to another PINet node connected to the PI Server. This feature is useful for a PI Server
system with many VMS PINet nodes. By grouping the PINet nodes, you can reduce the
number of direct connections on the PI Server and distribute the some of the network load
over several machines.
Note: you can use the PINet to PINet option with PI3.x Server, only.
For new installation of PINet, you will be prompted for the PINet-to-PINet option. You do
not have to do anything for the PINet master, that is, the PINet node directly connected to the
PI Server Home Node. You should enable the PINet-to-PINet option for the PINet slave and
specific the PINet master as the Home Node. The PINetTransport can be either DECNET or
TCP/IP to talk to the PINet master.
For upgrading an existing PINet node, the installation procedure automatically adds the
PINettoPINet logical name to your system andset the logical to 0. If you want to change an
existing PINet node to become a PINet slave, you have to modify manually the
pinetnames.com (or pionpinetnames.com for PIonPINet nodes) to change the HOMENODE
name to point to the PINet master. PIHomePort should be changed to 545 and PINettoPINet
should be changed to 1.
PINet and PIonPINet User Guide Page 23
Chapter 3. USING AND MANAGING PINET/VMS
3.1 PINet/VMS Operation
3.1.1 Files Involved in Installation and Upgrade
Installation and upgrade instructions are described in the previous section. The
PINetStart.com and PINetStop.com files are overwritten by the upgrade procedure. Files
PINetNames.com, SiteStart.com, and SiteStop.com are not touched on an upgrade because
they contain site-specific configuration information.
If you have user-written programs, create a file named PINet:SiteSpecificLink.com that
contains the link commands for these programs. These programs will then be automatically
relinked upon a PINet/VMS upgrade.
3.1.2 Directories
There are two pertinent directories on the PINet/VMS node, PINet and PINetBuild. These are
system logical names that usually translate to global directories, [PINet] and [PINetBuild].
The logical names PISysExe, PISysMgr, and PISysDat are translated into the [PINet]
directory. The PIBuild and PILink logical names are resolved into the [PINetBuild] directory.
3.1.3 Startup
and ShutdownPINet:PINetStart.com and PINet:PINetStop.com are the startup and shutdown
command files. Place these files in the OpenVMS-system specific startup
(Sys$Manager:SyStartup_VMS.com) and shutdown (Sys$Manager:SyShutdwn.com) routine,
respectively. Thus, PINet/VMS is started or stopped whenever the VAX/ALPHA is started or
stopped.
When PINet/VMS is first installed – and first started – the Home Node PI System must be
running. At installation and first startup, the PINetSync subsystem rebuilds the complete
Point Database information stored on the PINet node. Do not interrupt this process.
Subsequently, you can start the PINet/VMS System when the home PI System is not running.
Note that some interface programs require that the PINet/VMS node be connected to the
PIHome Node when the interface is started.
The startup command file executes PINet:PINetNames.com. This command file defines the
logical names for directories and files of the PINet/VMS system. In addition, this file
contains a symbol for the TCP/IP node name of the PI Home Node.
PINet and PIonPINet User Guide Page 25
Chapter 3 – Using and Managing PINet/VMS
The startup command file also installs the PITables, PISubShr, PICRTShare, and PIElShare
shareable images. The startup command file starts the batch job that creates a new version of
the PINet/VMS log file at a specified time every night. The PINet/VMS log file,
PIMessLog.txt, is in the directory PINet.
Other log files (PINet subsystem and interface programs) can be found in the PINet directory
with names like: *.out, *.log, and *.txt.
PINetStart.com and PINetStop.com are generic procedures that should not be edited. Put site
specific instructions such as interface start and stop commands in PINet:SiteStart.com and
PINet:SiteStop.com.
3.1.4 System Message Log
The file PINet:PIMessLog.txt is the PINet/VMS system message log file. It records errors and
other messages for the system manager. You should not view the current version with a text
editor since programs may be trying to write to it. Use the OpenVMS type command to view
the file:
$ type PINet:PIMessLog.txt
You can change the number of message logs that are saved by editing the Purge command in
PINet:PIMessLog1.com. You may create a new current message log file with the following
OpenVMS command:
$ create /FDL=PINetBuild:PIMessLog.fdl PILogFile
3.1.5 Point-Related ID Numbers in PI2 versus PI3
The PI2 system has several different ID numbers for things related to each point. Normally
only one of these ID numbers is useful to an application programmer, namely the
PointNumber. Here is a partial list of ID numbers that are associated with points in PI2:
• PointNumber
• PointID
• MemPt
• ArcPt
The other ID numbers are used in private or internal routines that are not exposed in the PI
ToolKit or PI API libraries. All the PI2 ID numbers are related to or derived from a "key" ID
number, the PointNumber. In the PI2 world, unfortunately we loosely refer to this key
number as the PointID. (The PointID is actually something quite different!)
In the PI3 world there are two significant ID numbers for each point: the PointID and the
RecNo. PointID are heavily used by the Snapshot and Base subsystems. RecNo is used by the
Archive subsystem.
When we converted the points from PI2 to PI3, we preserved the PointNumber from PI2 by
“forcing” the PI3 system to let us define PI3’s points with PointID numbers of our choosing.
This can only be done once, by initially creating the Tags in an empty, new install of PI3, in
PointNumber order.
More details on PI2 and PI3 point-related ID numbers can be found in Appendix A.
Page 26
3.1 – PINet/VMS Operation
3.1.6 PINet – Co-Mingled Tagnames
In PINet, a Tag must have a short name, this short name is stored internally as just 10
characters. If the PI3 Tagname is longer than 10 characters, PINet for PI3 uses the PI3
Tagname in PINet’s local copy of the Point Database as the PI2 Long Tagname. A Short
Tagname (10 characters) is derived from the Long Tagname and PointID number. We call
this derived name the Co-mingled Tagname. Some times we call these mangled Tagnames.
Co-mingled Tagnames might look like the following output from PINet for PI3’s WildL.exe
utility.
PointID Short NAME Long Tagname
192 ACE_OU~192 ACE_OUTPUT1
193 ACE_OU~193 ACE_OUTPUT2
194 ACE_OU~194 ACE_OUTPUT3
242 AMCTEST AMCTEST
106 AT2401 AT2401
107 AT2402 AT2402
21 AT402 AT402
24 AT403 AT403
9 BA:ACTIV~9 BA:ACTIVE.1
112 BA:CHI~112 BA:CHIP1.PROC
113 BA:CHI~113 BA:CHIP1.PROD
32 BA:CHIP~32 BA:CHIP1.PROGRESS
114 BA:CHI~114 BA:CHIP1.TRIG
2 BA:CHIP1~2 BA:CHIP1.UBID
Some PINet applications require the short name (co-mingled name). For example, the PINet
IORates subsystem.
3.1.7 PINet/VMS Utilities
I/OMonitor
The program PINet:IOMonitor.exe displays the value of the counters for every Tag in
PINet:IORates.dat. It then displays the rates in events per second at the user specified update
interval (5 seconds is good interval to use).
$ run PINet:IOMonitor.exe
Scan period (secs): 5
SYTDC001 9889 events
SYSNPPINET 21672 events
SYEVMPINET 168 events
Rates in events/second
(use control-C to stop program):
SYTDC001 SYSNPPINET SYEVMPINET
5.40 29.80 1.81
Snap
The program PINet:Snap runs as a DCL command. Type:
$ set command PINet:Snap
PINet and PIonPINet User Guide Page 27
Chapter 3 – Using and Managing PINet/VMS
to add Snap to your command set. Then type:
$ snap Tagname
where Tagname is the name of the Tag.
This program displays the Snapshot value for the Tag as well as both the Short and Long
Tagnames. If data for the Tag are being collected on the PINet/VMS node, the Snapshot is
retrieved from the local Snapshot file. Otherwise, the Snapshot is retrieved from the Home
Node. For example:
Snapshot Report
Short Tagname = BA:ACTIV~9
Long Tagname = BA:ACTIVE.1
Point Number = 9 Type = Digital
Value = Active Time = 21-Mar-96 09:54:10
Not collected on this node
The Short Tagname and Long Tagname are available for backward compatibility with PI2.x
Servers. PI2.x allows each Tag to have 12 character short Tagnames and 80 character long
Tagnames. PI Server has only a single Tagname, which may be any length. For this case the
Snapshot Report abbreviates the Tagname (as necessary) to make it compatible with the PI2.x
Short Tagname and Long Tagname.
QWatch
The program PINet:QWatch.exe shows the status of the Snapshot Event Queue on the
PINet/VMS node. The Event Queue and its QManager subsystem compose the data
buffering mechanism on a PINet satellite node. For QWatch, a scan period of 5 seconds is
suitable. Use <CTRL-C> to exit the program.
$ run PINet:QWatch.exe
Scan period in secs [0]: 5
Queue Watch program
Qptr = 207 QEnd = 208
OverPtr = 759 OverEnd = 759
OFlag = 0 UseFlag = 0
Events in memory = 1, 0.050 percent full
No values on disk
QPtr, QEnd, OverPtr, and OverEnd are pointers to the beginning and end of the two
memory-resident segments of the Event Queue. OFlag is 0 or 1 if the Event Queue is entirely
in memory. OFlag is 2 if the Event Queue has overflowed to disk. The name of the disk file
is PINet:EventQ.dat.
EVMDump
The program PINet:EVMDump.exe lists the processes that have signed up for exceptions
(events from the Event Manager).
$ run PINet:EVMDump.exe
Page 28
3.1 – PINet/VMS Operation
EVMQPtr = 581 EVMQEnd = 581
List #0: NumbPts = 4 PID = 126 Name = PI TDC
NumbEvents: 0 counted 0 recorded
LastTime = 20-Mar-96 16:04:57
BPFI15 464
SINUSOID 1639
LMTRIG 590
CESO2RA 1241
For each process, EVMDump lists the Tags for which it has signed up, the last time it called
pisn_evmexceptions (or PI2.x Toolkit routine EVMGetExceptions), and the number of events
waiting for it the next time it calls pisn_evmexceptions (or PI2.x routine EVMGetExceptions).
WORLD privilege is required to see the process name of all processes that have established
points.
PINetVerify
The command file PINet:PINetVerify.com shows the overall status of the PINet/VMS node.
Run this utility as a first step in debugging PINet/VMS problems.
$ @pinet:pinetverify
Along with a display of some status information, it displays warnings:
• If some of the necessary PINet/VMS processes are not running
• If the PI Home Node is unavailable
• If the PINet/VMS protocol version of the Home Node is incompatible
Essential PINet Processes
Necessary PINet/VMS processes are EVMCheck, ExceptServ, IORates, PIEVManager,
PINetSync, QManager, and SaveSnapshot.
WildL
The program PINet:WildL.exe searches for Tags based on a Tagname specification. An
asterisk is a wildcard character in the Tagname search.
WildL.exe displays its results in three columns. The first column is the PointID, the second
column is the short Tagname (at most 10 characters), and the third column is a regular
Tagname. The short Tagname is necessary for backward compatibility with PI2.x Systems.
For example, to search for Tags beginning with the letter T:
$ run PINet:wildl.exe
Mask: t*
PointID NAME 5/5 points found/remain
11 TAG NUM~11 TAG NUMBER 1
18 TAG1234~18 TAG1234567890
19 TAG1234~19 TAG1234567891
21 THIS IS~21 THIS IS ANOTHER LONG TAGNAME
20 THIS_IS~20 THIS_IS_A_VERY_LONG_TAGNAME
PINet and PIonPINet User Guide Page 29
Chapter 3 – Using and Managing PINet/VMS
ListAtt
The program, PINet:ListAtt.exe can be used to look at most of the classic point class
attributes for a Tag whose name is known.
The attributes displayed are those commonly used by instrument interfaces which run on
OpenVMS PINet nodes and are useful in troubleshooting and monitoring data collection
operation.
This may also be useful for comparing the configuration as stored on the PINet node with the
configuration of the Tag on the PI Server.
$ run pinet:listatt
Enter Tagname: sinusoidu
Tagname :SINUSOID~2 (UTC 12 Hour Sine Wave )
Ipt : 2 Diskpt : 2
Mem Point : 2 Ordinarc : 2
Res Code : 1 Fprimrec : 0
Longname :
SINUSOIDU
Exdesc :
PointType :R Precision :F
Zero : 0.0000000E+00 Span : 100.0000
Typic.Val : 50.00000 EngUnits : 2
Pt Source :R
Location : 0 -2 0 1 0
Filtr code: 0 SquareRoot: 0
Archiving : 1 Compresing: 1 Scan : 1
Total Code: 0 Conv. fact: 1.000000
Exc. Specs: 1.000000 % 0 0
Comp.Specs: 2.000000 % 0 28800
Creator : 1 Create Date: 20-May-1997 14:45
Changer : 1 Change Date: 26-Jan-1999 19:12
Enter Tagname:
3.1.8 I/ORates Program
The I/ORates program provides 10-minute averages of Tags placed in the file
PINet:IORates.dat. This file is a text file that has one line for each Tag separated by a comma
from an I/O counter number. The Tagnames in PINet:IORates.dat may not contain more than
(10) characters (Short Tagnames).
Interface Programs
I/ORates Tags for interface programs that run on a PINet/VMS node should be entered in the
PINet:IORates.dat file. For example,
* IORate Tags
SYTDC001,1
Page 30
3.1 – PINet/VMS Operation
Interfaces may use I/O counter numbers 1-34 and 51-200. Consult each interface’s specific
documentation on where to place the I/O counter number in the interface’s startup command
line.
In the above example, remember to create the SYTDC001 Tag on the PI Home Node.
PINet/VMS System Programs
To record the local Snapshot rate and the rate at which the Event Manager is sending events
to programs using EVM routines, enter Tags with I/O counters 47 and 46, respectively. That
is, enter in PINet:IORates.dat:
* IORate Tags
SYSNPPINET,47
SYEVMPINET,46
You also need to create the Tags SYSNPPINET and SYEVMPINET on the PI Home Node.
Note: The Tagnames SYSNPPINET and SYEVMPINET are arbitrary. You may
create these Tags and name them anything you wish. In fact, if you have more than
one PINet/VMS node, you will need to create two sets of Tags. These may be
SYSNPNET1 and SYEVMNET1 together with SYSNPNET2 and SYEVMNET2.
Tag Creation
You may use the following piconfig commands to create I/O Rate Tags. The fields in the
second line below represent Tagname, descriptor, engineering units, pointtype, zero, span,
typicalvalue, step, and pointsource.
@input defaultpt.dif
sysnppinet,snapshot rate for
PINet,events/min,float16,0.0,3000.0,500.0,0,L
@exit
An I/O Rate Tagname may not contain more than ten (10) characters (use short Tagname).
Starting and Stopping
Whenever changes are made in the PINet:IORates.dat file, the I/ORates program itself needs
to be stopped and re-started:
$ @PINet:Stop IORates
$ @PINet:IORates
3.1.9 Shutdown
PINet/VMS Node
EventsWhen the PINet/VMS System is shut down, points can be set to a status of Shutdown.
The PINet/VMS node should only add shutdown events for Tags for which it collects data.
Modify PINet:ShutdownEvents.com and PINet:CheckForCrash.com to add shutdown events
for these Tags. At the end of each of these files is a line that executes the program
PINet and PIonPINet User Guide Page 31
Chapter 3 – Using and Managing PINet/VMS
ShutdownEvents. This program takes a list of shutdown specifications in addition to the
shutdown time as an argument. Commas should separate these specifications.
The specifications can be:
Point source characters
Point source characters and location parameter
Name(s) of file(s) each containing a list of Tags
Tagnames
These specifications may be mixed in any combination. The Tags specified in this list receive
shutdown events. If a Tag is specified twice in this list, that Tag receives two shutdown
events.
All PINet/VMS nodes should add shutdown events for the Tags in PINet:IORates.dat. The
file name should be the second parameter on the ShutdownEvents command line. Most
PINet/VMS nodes also add shutdown events for Tags with the point source code for the
distributed interface program. The last non-comment line in each command file should look
something like:
$ ShutdownEvents ‘ShutTime’,PINet:IORates.dat,H
Here, H is the point source character used by the interface program running on the
PINet/VMS node.
If ‘ShutTime’ is the only argument to ShutdownEvents, PINet/VMS will write a Shutdown
event to each Tag for which it has collected data. This situation may not be desirable for Tags
of point source L.
When the PINet/VMS System is started, it checks to make sure that the system was shut
down properly by looking for shutdown events for the Tags in PISysDat:IORates.dat. This
file should always be included in the shutdown specification list.
PI Home Node
On the PI Home Node, modify the Shutdown attribute for Tags that are collected on
PINet/VMS nodes. The PI System on the Home Node can be shut down and restarted without
stopping data collection by distributed interface programs running on the PINet/VMS node.
Thus, the PI Home Node should NOT write shutdown events for Tags whose data are
collected on PINet/VMS nodes.
PI Server uses the PI\dat\shutdown.dat file instead of the PISysDat:IORates.dat file. PI
Server allows individual configuration of shutdown events on a Tag by Tag basis, using the
Shutdown point attribute. Normally the Shutdown attribute should be set to 0 (off) for all
points not collected by interfaces on the PI Home Node.
Chapter 1, Starting and Stopping PI in the PI Server System Management Guide, explains
how to configure shutdown events.
Page 32
3.1 – PINet/VMS Operation
3.1.10 PINet/VMS Processes
Several processes run on the PINet/VMS node to support distributed interface programs.
ExceptServ
Data acquisition interface programs put events into the Event Queue with either
pisn_sendexceptions or pisn_putsnapshot (PI2.x Toolkit routines PISendExceptions or
PutSnapshot). The exception report server process, ExceptServ, retrieves events from the
event queue and sends them to the PI Home Node. The PINetMgr process on the Home
Node puts the events into the Snapshot and Archive.
Because PI Server implements point-by-point security, the pisn_sendexceptions or
pisn_putsnapshot routines may not return an error, yet data are not sent to the archive. Check
PINet:PIMessLog.txt to make sure that the ExceptServ program did not encounter any errors
in sending data to the PI Home Node.
QManager
This process, QManager, maintains the virtual event queue. It saves events to disk when the
memory portion of the event queue fills up. It moves the events from disk to memory when
the memory portion of the queue has enough free space.
SaveSnapshot
The SaveSnapshot process writes the local copy of the Snapshot value for each Tag to a file.
PINetSync
The PINetSync process maintains on the PINet/VMS node an accurate copy of the PI Home
Node’s point database. This process also synchronizes the time with the PI Home Node.
By default, the PINet/VMS node sets its system time to match that of the PI Home Node. It
compares its system time to that of the Home Node every hour. The PINet/VMS node time is
updated if it is different from the Home Node time by more than 10 seconds. The PINetSync
process performs this check and writes a message to PINet:PIMessLog.txt whenever it
changes the VMS time.
If you wish to change the default behavior of PINetSync, refer to the instructions in the
PINet:PINetSync1.com file.
PIEVManager
The PIEVManager process maintains queues of exception reports for programs that sign up
for them. This process retrieves exception reports from the PI Home Node if necessary.
EVMCheck
The EVMcheck process periodically checks that each list of points established with the
PIEVManager has an associated parent process. If not, EVMcheck deletes the orphaned list.
PINet and PIonPINet User Guide Page 33
Chapter 3 – Using and Managing PINet/VMS
IORates
The IORates process periodically checks for updates to counters written by interfaces. The
IORates process provides 10 minute averages which are placed in Tags specified by file
PISysDat:IORates.dat established by the interfaces for reporting their status.
Network Communications
The PINet/VMS System talks to the PI Home System via transparent TCP/IP socket calls.
The format of the messages passed between the nodes is referred to as the PINet/VMS
protocol. According to this protocol, the processes on the PINet/VMS node send commands.
The PINetMgr process on the Home Node replies to these commands.
3.2 PINet and DST
PI3 server nodes have automatically follow the DST / Standard time management rules that
their operating system is configured to follow. However, PINet nodes do not have such a
utility. How should the fall and spring time changes be handled on PINet nodes?
In the USA (and other parts of the world), PINet nodes talking to PI3 Home Nodes should
submit a batch job to run at 01:55:00 AM before the change that does the following:
@PINet:Stop PINetSync
wait 00:05:00 ! wait 5 minutes
set time=01:00:00.0 (for fall change)
- OR -
set time=03:00:00 (for spring change)
set time (set time with no parameters synchronizes the VMS clock
with the CMOS clock on the processor board of the OpenVMS systems)
wait 00:05:00 ! wait 5 minutes
@PINet:PINetSync
Note: use line 3 or 4 only.
The rationale behind this procedure is discussed below:
We could rely on the time synchronization feature of PINetSync to set the time on the PINet
node.
However, since PINetSync only checks the Home Node time at a user-specified frequency
(default once per hour), it is possible to have the time wrong for a period up to the time sync
frequency (e.g. one hour as in the case of the default setting). Hence, we recommend using a
batch job to set time directly to avoid losing data (specially in the case of the PI3 Home
Node. For PI2 Home Node where data may be discarded anyway, it is not as critical though it
will prevent unnecessary error messages from putsnapshot).
Also, we recommend stopping the PINetSync procedure before the time sync so that we will
not run into the case of two separate processes trying to set time and get into each other's
way. For example, if the PINetSync procedure already set the PINet system time back before
the batch job is activated, the batch job may get activated in the wrong time. Or if the user
Page 34
3.3 – PINet Backup Scripts
had specified ramping method for time change in the PINetSync startup parameters, the time
change may take a long time to accomplish.
Note: If you are running any scan-based OSIsoft interfaces on your PINet node, it
would also be wise to stop and restart all your interfaces right after you change the
PINet node's time. Most interfaces keep track of their scan times in terms of PINet
time. If you set the time back, the interfaces will go another whole hour before
running another scan. This is not a problem for interfaces collecting data via
exception instead of during predefined scan times. This problem only appears during
the fall DST change.
If your interface takes an extremely long time to start up, you might be better off to just let it
run without stopping and restarting it, but this should be a very rare case.
3.3 PINet Backup Scripts
3.3.1 Purposes for Backups
PINet backups satisfy these needs:
Enabling quick recovery from disaster such as equipment failure or facility fire
Provision for safety against everyday human mistakes and minor problems
System managers traditionally create and maintain a set of backup procedures
(documentation and command files) to accomplish each of these goals independently and
separately.
3.3.2 Image Backups
With the advent of faster, smaller backup devices of high density and reliability, many system
managers have reduced their backup procedures to a single job, an image backup of all disk
volumes. While this is probably not safe or adequate for a PI Server, a PINet node can be
adequately protected in this manner.
3.3.3 Key Users
One frequent problem with backup procedures is that the people who depend on PI and use it
every day are frequently not participating or aware of the recovery plan that may or may not
be in place for their PI System and related applications. This is like not asking the patient for
their informed consent prior to exploratory surgery. The team of people who support PI,
whether or not their existence is formalized, need to be part of the planning and
implementation of the backup and recovery strategy for PI.
Any quick recovery plan should be able to put basic functionality in the hands of key users in
the minimum amount of time. Some sites choose 4 or 8 hours as their recovery goal. It is
important to realize the cost and steps you take to accomplish your recovery goal will be very
different depending on the minimum and maximum time period you choose.
Murphy’s Law is always lurking in the background, waiting for a chance to remind us of our
human frailty. Ideally we would back up everything all the time on a continuous basis. This is
PINet and PIonPINet User Guide Page 35
Chapter 3 – Using and Managing PINet/VMS
not possible. What we can do is try to identify key files and users - backing up these objects
on a frequent basis such as daily or several times per week.
3.3.4 Preservation of Databases and History
In most implementations, a PINet node's main job is to serve as a platform for and to
facilitate the collection and saving of process data. This data is forwarded to the PI Server
node for permanent archiving as soon as possible. Little process information is retained on
the PINet node.
Unlike the PI Server, PINet has no historical storage to protect. While there are several
databases present on each PINet node, these databases are synchronized with the PI Server
node on a regular basis. So loss of one of these databases may affect operations but can be
recovered easily from the PI Server node.
3.3.5 Need Analysis
Because the PINet node has no history and since the databases are copies of information also
found on the PI Server node, the backup needs of PINet are fairly modest. These needs are
even more modest when we consider the small size (in megabytes) of the PINet software
system as compared to the PI Server. Normally there are few if any user applications and
logins on a PINet node. The PINet node is normally dedicated to data collection. The primary
backup need for a PINet node is disaster recovery.
From a certain point of view, there may be no need to backup the PINet node. There may
only be 6-12 files on the PINet node that are customized to that node. Perhaps the easiest
recovery procedure for a lost disk or other failure is to re-install. This can usually be
accomplished in a few hours or less.
A less drastic backup/recovery plan would see the PINet node backed up on some periodic
basis. Since the databases of PINet are synchronized automatically, it is normally adequate to
backup up PINet on a weekly to monthly basis. Additional backups might be made based on
milestones such as software upgrades and plant outages.
The backup for PINet would utilize several sets of tapes in a rotation. The rotation insures
that we don't overwrite the only known, good backup as the first step in the new backup.
There should be at least 3 to 5 sets of tapes in the rotation to provide for protection against:
A failed backup
A failing tape
A problem that happened in the recent past but was not detected immediately.
To be successful, backups have to be well tested, well documented, and require little operator
intervention. Additionally, backups need to be done regularly - because you never know
when you will need one.
Testing the backup and doing the backup regularly are sort of the same thing. Add a step to
read logs or read back the backup tape and you are accomplishing the testing.
Part of documenting a backup procedure is committing the steps to a pre-programmed
procedure. Not only does this document the procedure, but it removes the human element -
retyping the same commands each day and perhaps getting it wrong.
Page 36
3.3 – PINet Backup Scripts
3.3.6 A Proposed Procedure
Two command files might be utilized - one command file to schedule the backup to occur at
an off-peak hour, another command file to actually do the backup. Files to accomplish this
are shown below. These files may need to be customized to suit your implementation of
PINet. Such things as disk and tape drive device names almost certainly need to be
customized for your PINet machine.
$ ! PINetBack.com
$ ! OSIsoft Software, Inc.
$ ! Chuck Thompson
$ !
$ ! This is the command file for backing up the PI System volatile
$ ! data to tape. This procedure submits a batch job at the time
$ ! specified in the submit command below. The batch job command
$ ! file is: PINet:PINetBackBatch.com. The output goes to
$ ! PINet:PINetBack.log.
$ !
$ ! The submit time can be altered by changing the qualifier:
$ ! /after="02:00:00"
$ ! to an other time of day. Good alternate times might be 7pm,
$ ! 10pm or 4am.
$ !
$SubmitJob:
$ !
$ ! Submit batch job to do backup after desired time
$ !
$ Submit /NoPrint /Name="PINetToTape" /NoNotify -
/After="Tomorrow+02:00:00"/Log=PINet:PINetBack.log -
PINet:PINetBackBatch
$ !
$End:
$ !
$ Exit
$ !
$ ! end of file
$ ! PINetBackBatch.com
$ ! OSIsoft Software, Inc.
$ ! Chuck Thompson
$ !
$ ! Command file to back up PINet System.
$ !
$ ! Several items may need to be customized in this file.
$ ! Check the name of the tape drive device name ("TAPE = ") below.
$ !
$Backup:
$ !
$ ! Backup to tape
$ !
PINet and PIonPINet User Guide Page 37
Chapter 3 – Using and Managing PINet/VMS
$ Tape = "MUA0"
$ Allocate 'Tape'
$ Initialize 'Tape' "Arc1"
$ Mount/Foreign/NoAssist 'Tape'
$ If .not. $Severity then goto ErrBranch
$ !
$ ! We do not want to backup the file "eventq.dat" - this file
$ ! could poison the system if restored in the future.
$ !
$ ! For VMS Version 5.x
$ !
$ Backup /Record /NoVerify /Log /Ignore=(Interlock,Label) -
PI$Disk:[PI*...]*.* /Exclude=EventQ.dat -
'Tape':PINet.bck
$ !
$ ! An alternate backup scheme... Get whole disk where PINet lives.
$ ! Note: It is assumed that the PI$Disk logical name references the
$ ! name of an actual disk device, not a concealled logical name.
$ !
$ ! backup /record /noverify /log /ignore=(interlock,label) /image -
$ ! PI$Disk: /exclude=eventq.dat -
$ ! 'tape':PINet.bck
$ !
$ Dismount/Unload 'Tape'
$ Deallocate 'Tape'
$ !
$End:
$ !
$ ! Write message to PI message log
$ !
$ WriteMessLog :== $PISysExe:WriteMessLog
$ WriteMessLog "PINet directory backed up to tape"
$ Exit
$ !
$ !
$ErrBranch:
$ !
$ Write Sys$Output "Mount error: Severity and Status are"
$ Write Sys$Output $Severity,$Status
$ !
$ ! end of file
3.3.7 Other Alternatives
If there is another OpenVMS system on the network that has sufficient spare disk space, a
backup might be made across the network. The following example is an alternative backup
plan for a PINet node with two disk drives. One disk drive is where PINet is installed. The
other disk drive has the OpenVMS installation. The system manager has set up a proxy
between the two computers (a trusting relationship) so that the PINet computer is permitted to
write to the disk of the other OpenVMS server node.
Page 38
3.3 – PINet Backup Scripts
$ ! PINetBackBatch.com 8/20/87 MDH written
$ !
$ ! Command file to back up PINet directory. This file is submitted
$ ! as a batch job by command file PINetBack.com.
$ !
$Backup:
$ !
$ ! Backup to disk over the network
$ !
$ ! 1 Apr 97 cet make a backup to PI Home node disk (PIHome)
$ !
$ Tape = "ARD1::dkb300:[PINet_Bck]"
$ !
$ ! don't allocate or initialize or mount other computer's disk!
$! Allocate 'Tape'
$! Initialize/Density=1600 'Tape' "Arc1"
$! Mount/Foreign/NoAssist 'Tape'
$! If .not. $Severity then goto ErrBranch
$ !
$ ! use this backup command to copy just the PINet directories
$! Backup /Record /NoVerify /Log /Ignore=Interlock -
$! PINet:*.*.0,PINetBuild:*.*.0 /Exclude=EventQ.dat -
$! 'Tape':PINet.bck/save_set
$ !
$ ! use this set of backup commands to copy both the system disk
$ ! and the PINet disk to tape or other computer.
$ !
$ Backup /Record /NoVerify /Log /Ignore=Interlock /image -
Sys$SysDevice: /Exclude=EventQ.dat -
'Tape'PINetSystem.bck/save_set
$ !
$ Backup /Record /NoVerify /Log /Ignore=Interlock /image -
PI$Disk: /Exclude=EventQ.dat -
'Tape'PINet.bck/save_set
$ !
$! Dismount/Unload 'Tape'
$! Deallocate 'Tape'
$ !
$ ! Write message to PI message log
$ !
$ WriteMessLog :== $PINet:WriteMessLog
$! WriteMessLog "PINet directory backed up to tape"
$ WriteMessLog "ARDPIN System and PI Disks backed up to ARD1"
$ Exit
$ !
$ !
$ErrBranch:
$ !
$ Write Sys$Output "Mount error: Severity and Status are"
$ Write Sys$Output $Severity,$Status
PINet and PIonPINet User Guide Page 39
Chapter 3 – Using and Managing PINet/VMS
3.4 Troubleshooting
3.4.1 Connection to the PI Home Node
If PINet/VMS is experiencing problems with connection to the PI Home Node check the
probable causes below.
Interfaces Can't Find Any Tags to Process
Avoid problems by building your points with the point source character CAPITALIZED.
Applications on the PINet node, which are based on PI Toolkit routines, are frequently
uppercase character strings for parsing and passing to the PI Home Node.
The Point Source character should be a single character for interfaces running on PINet. Edit
the interface startup/configuration files check/change the point source character to be
CAPITALIZED.
In some cases, the Point Database on the PINet node becomes corrupted on first build or first
synchronization. Use the procedure on the following pages to rebuild the PINet node's Point
Database.
At the PI Home Server Node
Use piartool -as to check on status of archive and piartool -ss to check on the status of the
Snapshot and Event Queue. Find a Tag whose data are to be collected by the PINet/VMS
node. Use the pisnap utility to look at its most recent snapshot value, timestamp and status. If
the timestamp of the most recent snapshot value and most recent archived value are close to
current time, then the connection between PINet/VMS node and PI Home Node are probably
functioning correctly. If the snapshot and archive times are not close to current time, then the
link from PINet to the Home Node may not be functioning. Look at the PI System Message
Log using pigetmsg. PI Server may have written messages to the log file.
At the PINet Satellite Node
Probably the quickest way to check the status of the PINet node is to try executing the
PINetVerify.com procedure. If the key processes or shareable images are missing, you will
get a warning. PINetVerify will also check for creation of a link to the Home Node as well as
report what protocol version is being supported by the PI Home Server Node.
Run Qwatch from the PINet directory and look at the pointers and flags giving overflow
status. Is the data buffering up on the satellite node or is the problem somewhere else? If the
Oflag is 0, then check the interface to the DCS.
Use the Snap utility to look at the most recent Snapshot value as well as Timestamp plus the
collected here/there status. Look at the times (Snapshot). If the times and values are close to
what you saw on the Home Node, then things are probably okay here. If not, then the link to
the Home Node may not be functioning well. Check the PI log files on both nodes (PI Home
Server Node and PINet Satellite Node). Do the values and timestamps in PI or PINet seem
close to what the DCS system is reporting?
Page 40
3.4 – Troubleshooting
Take a look at the PINet System Message Log (PINet:PIMessLog.txt and other logs named
like, *.out, *.log, *.txt). The PINet/VMS processes or interfaces may put useful information
in the log files.
3.4.2 Logical Names Not Correct
PINetTransport
The PINetTransport logical name must be TCP/IP.
1. To confirm, run the following from DCL:
$ show logical PINetTransport
"PINETTRANSPORT" = "TCPIP" (LNM$SYSTEM_TABLE)
2. If necessary, edit the appropriate line in PINet:PINetNames.com:
$ Define/System/NoLog PINetTransport TCPIP
3. Execute PINet:PINetNames.com; stop PINet.
4. Re-link the entire PINet system:
$ set default PINetBuild:
$ @pinetinstall.com
5. Restart PINet/VMS.
PIHomeNode
The PIHomeNode logical name must contain the name of the machine running PI Server.
To confirm, run the following from DCL:
$ show logical PIHomeNode
" "PIHOMENODE" = "PI3"PIServer"::"0=PIServer""
The above shows that the PIHomeNode is a machine called “PI3”. If necessary, edit
the appropriate line in PINet:PINetNames.com. In this example, the name should be
changed to “PITHREE”.
$ HomeNode := PITHREE
Execute PINet:PINetNames.com. See Rebuilding the Point Database later in this chapter.
Restart PINet/VMS.
PIHomePort
The PIHomePort logical name must match the PI server port number. By default this number
is 5450.
To confirm, run the following from DCL:
$ show logical PINetTransport
"PIHOMEPORT" = "5450" (LNM$SYSTEM_TABLE)
PINet and PIonPINet User Guide Page 41
Chapter 3 – Using and Managing PINet/VMS
If necessary, edit the appropriate line in PINet:PINetNames.com:
$ Define/System/NoLog PIHomePort 5450
Execute PINet:PINetNames.com. Stop and restart PINet/VMS.
3.4.3 Incorrect TCP/IP Vendor Libraries
During the initial installation of PINet/VMS, the installation program tries to determine
which vendor’s TCP/IP product is running on the VAX/ALPHA.
1. To confirm which vendor’s TCP/IP communications library that PINet/VMS is
linked to, run the PINet:get_pinettransport.exe program:
$ run PINet:get_pinettransport.exe
2. If the TCP/IP product is not correct, then the PINet:PINetName.com file must be
edited manually.
3. After you edit PINet:PINetNames.com to reflect the TCP/IP vendor’s libraries, you
must re-link the entire PINet/VMS System:
$ set default PINetBuild:
$ @pinetinstall.com
UCX - VAX
$ Define/System/Exec/NoLog PIVAXCOMMLib sys$library:ucx$ipc.olb
$ Define/System/Exec/NoLog PIVAXCOMMShr pinet:vaxcommdumlib.exe
UCX - ALPHA
$ Define/System/Exec/NoLog PIVAXCOMMLib pinet:vaxcommdumlib.olb
$ Define/System/Exec/NoLog PIVAXCOMMShr pinet:vaxcommdumlib.exe
Process Software TCPWare - VAX or ALPHA
$ Define/System/Exec/NoLog PIVAXCOMMLib pinet:vaxcommdumlib.olb
$ Define/System/Exec/NoLog PIVAXCOMMShr sys$share:tcpware_socklib_shr
Cisco MultiNet - VAX or ALPHA
$ Define/System/Exec/NoLog PIVAXCOMMLib pinet:vaxcommdumlib.olb
$ Define/System/Exec/NoLog PIVAXCOMMShr
multinet:multinet_socket_library
Attachmate PathWay - VAX or ALPHA
$ Define/System/Exec/NoLog PIVAXCOMMLib pinet:vaxcommdumlib.olb
$ Define/System/Exec/NoLog PIVAXCOMMShr sys$share:twglib
3.4.4 Rebuilding the Point Database
If you need to rebuild the Point Database, follow the steps below. Rebuilding the Point
Database is necessary if you switch PI Home Nodes without re-installing PINet/VMS.
Page 42
3.4 – Troubleshooting
Note: The following is only valid if the network transport doesn’t change.
1. Stop PINet/VMS and change to the PISysExe directory.
$ @pisysmgr:pinetstop.com
$ set default pisysexe:
2. Remove all PI shareable images from memory.
$ @removepishareables.com
3. Delete the long name section file.
$ delete pisysdat:long_names.section
4. Delete the event queue file.
$ delete PINet:EventQ.Dat
5. Install PI shareable images.
$ @loadpishareables.com
6. Rename Point.dat.
$ rename pisysdat:point.dat pisysdat:point.old
7. Retrieve points from the PI Home Node.
$ @pinetbuild:pinetinspointdat.com
8. Remove PI shareable images from memory before starting PINet/VMS.
$ @removepishareables.com
$ @pisysmgr:pinetstart.com
PINet and PIonPINet User Guide Page 43
Chapter 4. ADVANCED MANAGEMENT TOPICS FOR PINET
4.1 Renaming Points on PI3 and the PINet Response
A rename on the PI3 version 3.3 and earlier server does not trigger a ptupdate for processes
signing up for Point Database change. (This has been fixed in PI versions 3.3 SR1 and later.)
Note that if the user is changing any other point attribute, a point update will be triggered.
The problem is only for rename. In the case of pinet, pinetsync on the PINet rely on the
point database signup on the PI3 server to process a point database change. If the PI3 server
does not notify pinet about the rename, PINet will not go get the new point record to process
the point change. PI3 3.3 SR1 addressed this issue.
Another problem can be that updates to other point attributes are missed. PI3 version 3.3
manual says “If a PINet node is connected to the PI Server, the default MaxUpdateQueue
value is too small. It should be increased to at least the point count of the PI3. 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.”
Here is a script that can be used to apply the PITimeout table change suggested by the
manual. Clip the lines below, save as a text file, maxupdatequeue.txt. Alter the setting (10000
shown below) to match your Tag count. (Tip: It is better to increase this to match your
Licensed Tag Count.)
@mode edit,t
@istr name,value
maxupdatequeue,10000
@ends
then use piconfig to apply the change:
piconfig < maxupdatequeue.txt > maxupdatequeue.out
and check the output log to confirm the change.
4.2 Renaming Tags in PI3
A Tag rename operation is not transparent to many applications. Especially those applications
that support PE expressions using embedded Tagnames.
Most applications map Tagnames to PointID numbers at startup, thus the application
continues to run during a name change event. Some applications (like PI ProcessBook)
persist the PointID cache so it can then resolve a Tagname change on the next startup.
PINet and PIonPINet User Guide Page 45
Chapter 4 – Advanced Management Topics for PINet
Unfortunately, PI Batch in 3.2 does not. (Even the data set PI calculation expression part of
ProcessBook does not.)
The Client-Server architecture for any application (WEB, PI, Fileservers…) makes the issue
of concordance and links very difficult. Renaming a Tag is much like renaming a Windows
directory that is shared. OSIsoft module database technology includes an aliasing feature as a
possible centralized solution for issues like name concordance.
In the meantime, it is important as an administrator to carefully implement Tagname changes:
1. Publish a Tagname change log (especially to Excel/Datalink users)
Date, old name, new name, ptid, recno, comment
2. Check for references within the PI Server modules and Tag attributes
Batch PIBAUNIT table: ACTIVETAG, BIDEXPR, PRODEXPR
Interface Tags (including PIPESCHD): EXDESC
Totalizer: FILTERSTR, EVENTSTR
3. Update SMT configuration worksheets
SOURCETAG and SRCPTID are maintained by PI, so rename is
automatically supported but saved SMT worksheets need to be re-
imported.
4.3 PINet – PointID
What PINet for PI3 uses as a PointID is actually the archive system’s RecNo from the PI3
server. (This is true for all PINet for PI3 nodes starting with PINet version 2.2.)
Why the difference? PINet for PI3’s databases and structures are all hard-coded to compiled-
in limits set by OSIsoft. The number of points that a PINet node’s local point database can
“see” is limited to your licensed point count of your PI3 server. On the PI3 server, Point IDs
are assigned in 1,2,3…N order. As points are deleted and new points created, PointID
numbers are never reused. Thus after quite a few point deletion/creation cycles, it’s possible
that your PI3 system will have PointID numbers larger than your licensed point count. If that
happens, your PointID numbers will exceed the range PINet can see. (PointID limitation only
effects PINet versions 2.1.1 and 2.1.2. PINet 2.1.0 and earlier versions did not support PI3
server.)
However the archive subsystem’s RecNo ID number ranges from 1 to N where N is the peak
number of concurrent Tags your system has had. PI3 reuses RecNo’s as points are deleted and
new points are created. RecNo ID numbers should always be within the range of the
databases and structures of your PINet for PI3 node(s).
If you license more points for your PI3 server, you may need to upgrade your PINet for PI3
node(s) at the same time.
Page 46
4.4 – PINet – Migration by Upgrade or New Install
4.4 PINet – Migration by Upgrade or New Install
In any case you will have to upgrade or make a new install of PINet to get a version that has
databases built and structured for PI3. (The database sizes and structures are different for a
PINet node compiled for a PI2 system versus a PI3.)
Note that every PINet is custom compiled for each PI Server. It is improbable that PINet
install kits for any two PI Servers will be identical. Be sure to use the proper install kit for
PINet with your PI Server.
A consequence of upgrading will be that the system manager will have to re-link all their
custom programs that are PI related (linked to PI shareable, or using Tag data, or using PI
subroutine libraries).
With the PI2 to PI3 pre-migration survey came a command file that can “sniff” all the
mounted disks of a VMS system to find files linked to PI. The command file is called Find-
PI-Related.com.
Note: Upgrading a PINet compiled for a PI2 server with an install kit for a PINet
compiled for a PI3 server will result in databases that are inconsistent. You will have
to manually rebuild the databases using the procedure documented in Rebuilding the
Point Database on page 42. If you are changing the network transport, there are
additional changes you will have to manually edit into several files. Therefore it is
strongly advised to do a new installation, as this avoids ALL of these issues.
For the migration, it is often easier and faster to just do a new installation of PINet. The
VMSinstal kit for PI, on a new install, takes care of lots of changes that have to be made to
change things like protocol, PI Home Node, addresses, and ports. On an upgrade, the PI
VMSinstal kit does not check or set these parameters for you.
There are only about six files worth preserving from the old PINet – it is pretty quick to just
edit the new PINet installation files as needed by comparing to listings from the old PINet
installation. The six files are:
sitestart.com
sitestop.com
checkforcrash.com
shutdownevents.com
iorates.dat
and the interface startup file, for example, TDC.com from the Honeywell CM50s
interface.
To do a new install on your PINet node for migration, try these steps as preparation for the
PINet installation:
1. Restart PINet
2. Check to see that all PINet processes and PI related processes are stopped
3. Rename the PINet and PINetBuild directories
PINet and PIonPINet User Guide Page 47
Chapter 4 – Advanced Management Topics for PINet
4. Reboot VMS (clears all PI information from operating system environment)
5. Then continue by performing a standard, new, installation of PINet.
For more information, see section 2.4, PINet/VMS Installation.
4.5 PINet to PINet and PINet as a PI Server Node
PI2 has a feature for PINet called PINet to PINet. This feature was added starting with PINet
version 2.1.2. PINet can also act as a PIServer for PINet and PI-API nodes. PIServer and
PINet to PINet can be good solutions in situations including:
PINet or API nodes are overrunning the PI3 Update Manager. (Use both PINet to
PINet and PIServer features.)
API nodes either have weak buffering capability or cannot support buffering at all,
i.e., Windows 9x or some of the imbedded PI-API platforms. (Use PIServer feature.)
Need to support nodes that can only use DECNet networking with a PI3 Server. (Use
PIServer feature.)
PINet to PINet is not implemented very often. Modern Windows servers and newer PI3
versions have vastly improved performance and capabilities that pretty much reduce or
eliminate the need for PINet to PINet. Settings exposed in the PI3 PITimeout Table and
settings at the PI-API node to fine-tune API-Buffering have combined to solve most needs for
PINet to PINet.
Discussion
PINet to PINet is an option that can be selected during PINet installation. The PINet
VMSinstal kit prompts for this option. PINet to PINet would be selected for the slave nodes
only, not the PINet node that is acting as the PI Server. (See the diagram below – Refer to
nodes 1 and 2 as the PINet slaves.)
PINet to PINet should only be used to create a PINet slave node when the server is PI3 and
there are problems with PI3 Update Manager overruns.
Probably all PINet nodes (2.1.0 or later) can implement PIServer features. (Depends on disk,
memory, and processor capability.) Starting with PINet 2.1.2, the PINet VMSinstal kit places
PIServer programs on the PINet node for any network protocols found. To enable the
PIServer listener and set up PI security, follow instructions in section 4.6, Troubleshooting
PINet Connections and in the pinetbuild:PIServer.txt file. PINet versions 2.1.0, 2.1.1 can
have manually implemented PIServer support by following directions in a Tech Note /
Answerbook.
Here are some benefits to using a PINet node as the server for other PINet nodes and PI-API
nodes.
Overrun of PI3 Update Manager
When we first supported PI3 with PINet, several customers implemented schemes that
used a PINet node as a server for PI-API and PINet nodes. At that time, we had slower
Page 48
4.5 – PINet to PINet and PINet as a PI Server Node
Windows and UNIX machines and poorer performance of PI3. The issue was that the
PINet nodes represented a large demand on the PI3 Update Manager and as a result, the
Update Manager could be overrun or lose updates. The Event Manager for PINet was
more robust in some ways as compared to the Update Manager, so the work-around was
to turn a PINet node in to the “server” for all the interface nodes including PINet, PI-API.
(PINet nodes 1 and 2 in the illustration below are slaves of a PINet node acting as the
PIServer node.)
API Nodes Without Buffering
Some API nodes don’t have the resources or capability to support the PI-API buffering
feature. A PINet node has its very robust Event Queue system that can buffer data during
times when the PI Server or LAN are offline. Because PINet caches databases from the
PI Server, PINet has the advantage of supporting application restarts, upgrades, or even
installations during time periods when the PI Server is unreachable. (The PINet Server
node in the illustration below provides Event Queue buffering for all the connected PINet
and PI-API nodes.)
Need to Support DECNet Networking with a PI3 Server
An older PINet node might not have TCP/IP networking. Some of the embedded PI-API
nodes (such as the Honeywell MAS box) do not have an option for TCP/IP networking,
but only use DECNet. An additional PINet node with both DECNet and TCP/IP
networking can act as the server for nodes capable of only DECNet. (The PINet Server
node in the illustration below can receive connections from TCP/IP and DECNet
sources.)
PINet and PIonPINet User Guide Page 49
Chapter 4 – Advanced Management Topics for PINet
Figure 4-1. – PINet Server Installation
4.6 Troubleshooting PINet Connections
Errors such as -999 and -994 in this case are similar to -10401 and like errors.
File protection problems on the PI Server can be a problem. The TCP/IP software and the
PIServer software are candidates. For PI, check the protections of some files. PISysExe:*.exe
should have all files set for (s:rwe, o:rwe, g:rwe, w:rwe) and PISysExe:*.com files should all
be (s:rwe, o:rwe, g:re, w:re). There are many different file protections for files in the
PISysDat directory. However, PIServer.dat needs to be (s:rwe, o:rwe, g:rwe, w:rwe).
The host file and related TCP/IP parts need world access.
With legacy UCX or DEC TCP/IP, it is possible that the PIServer service is incorrectly
defined or is disabled.
Page 50
4.7 – Starting PINet on OpenVMS 6.1 and Later
Definition problem: Old PI versions used a TCP/IP listener named piserver.com.
Starting with PI2.0.8 the listener is called ucxpiserver. Read more about that in
pinetbuild:piserver.txt.
For security reasons, UCX and DEC TCP/IP disable custom services/listeners with
each stop/restart of TCP/IP. The PI startup file is supposed to re-enable the service
automatically. If there is a problem with PI restart, pinetstart.com might abort and
exit prematurely. Since the PIServer routines are the last thing processed by
pinetstart.com – PI might seem to be okay, but only partially started.
4.7 Starting PINet on OpenVMS 6.1 and Later
The startup of the OpenVMS operating system has several execution threads. The startup of
PINet occurs in a different thread than the X-Window subsystem. PINet has some routines
which depend on X-Windows (Motif or DECWindows).
If PINet doesn’t start up automatically when you reboot OpenVMS, and if you can easily
start PINet from the command line, it’s possible that the OpenVMS startup process is
attempting to start PINet before X-Windows is operational.
A workaround for this problem is to start PINet from the system batch queue processor, after
a delay.
Change the startup command you placed in Sys$Manager:SyStartup_VMS.com from:
$ @dua0:[pinet]pinetstart
To:
$ submit /user=system /after=”+00:05:00” /log=dua0:[PINet] -
dua0:[pinet]pinetstart
Substitute the appropriate disk drive name for dua0.
PINet and PIonPINet User Guide Page 51
Chapter 5. INSTALLING PIONPINET/VMS
5.1 System Requirements
OSIsoft has developed a spreadsheet model that can assist in planning for PI disk and
memory requirements, including VAX, AXP, for PINet, and PIonPINet. Contact your
OSIsoft sales person for a copy.
5.1.1 PIonPINet Memory and Disk Estimates
The specifications found below are based on a VAX system running VMS version 6.1 or
later. These specifications do not take into consideration any layered products or applications
other than VMS, DECNet End-Node, TCP/IP, C, FORTRAN, DECWindows, UCX and the
PI System.
If you are using PINet to PINet PIServer, your PINet PIServer node must be running the same
or later version of PI as is running on your PINet or PIonPINet node. If you are adding a
PINet or PIonPINet to an existing PINet to PINet installation, this will most likely require
that you first upgrade the PINet PIServer node to the latest version of PINet.
Memory and disk estimates for AXP-based OpenVMS systems are provided in section 5.1.4,
Memory and Disk for DEC AXP/VMS Systems.
5.1.2 Memory Requirements
Tag Attributes: 125 bytes * ultimate # Tags
Each Archive file: 6144 bytes * (max. # archive files)
Other PI System tables: ~50000 bytes
PI Runtime programs: ~4.5 megabytes
Each PI Display: 61 bytes/display
User account database: 512 bytes/user
A minimum of 16 megabytes of memory is required for PIonPINet. OSIsoft recommends that
25% spare memory be present.
PI CRTs (concurrently logged in PI users) work best with 2 megabytes of memory available
for each CRT concurrently in use. The CRTs and the PI System will work with less memory,
but response time will be a little slower. Actual CRT memory usage, depending on what
PINet and PIonPINet User Guide Page 53
Chapter 5 – Installing PIonPINet/VMS
function is in progress, is 1.5 to 3 megabytes. Each DEC Window user should have 2 to 4
megabytes of memory to support their server processes.
Allow .25 to .5 megabytes of memory for VMS Only Users (not logged into PI) concurrently
logged into the system (i.e. system users, mail, programmers).
Allow at least 1.5 megabytes memory for VMS system usage. If your VAX is a member of a
cluster, add an additional 1.5 megabytes for each other VAX in the cluster.
When data is collected on the PIonPINet node for some interfaces, add 1.3 megabytes of
memory for databases or shareable images such as:
• Allen Bradley PLC (0.6 MB)
• Fisher CHIP (1.3 MB)
• Foxboro FCG (1.3 MB)
• Honeywell CM50S (7.5 MB)
• Rosemount RMTHOST (1.3 MB)
• Taylor MOD 300 (1.3 MB)
• Westinghouse WDPF (1.3 MB)
• Yokogawa Centap (1.3 MB)
Manuals for the DCS vendor-supplied software contain information for planning your system
memory and disk requirements.
5.1.3 Disk Requirements
Point Database file: 512 bytes * ULTIMATE Tag
Other Data files: ~50000 bytes
Displays: 512 bytes * display
Users and Custom Menus: 512 * (NbrFiles) *
(NbrDisplays) / 40
NbrFiles is the larger of NbrUsers or NbrCustmMenus. Normally these are equal.
Other PI files: 50 megabytes
PI Release files (PINetBuild): 55 megabytes
VMS Disk Requirements
Note: These are rough estimates. Requirements are very dependent on system
configuration and what other applications (relational databases as an example) are
running.
Our estimate for VMS disk requirements includes VMS, DECNet End-Node, typical TCP/IP,
C, FORTRAN, DECWindows as well as swap and pagefiles for 8 to 16 users.
Page 54
5.1 – System Requirements
VMS System Disk Requirements
VMS ( 5.x+): 120 megabytes. Includes:
Swap Files: 10 megabytes (20000 pages).
PageFiles: 50-100 megabytes (100000-200000 pages).
Note: For fewer than 3 users you may be able to reduce pagefiles to 25 megabytes
(50000 pages). For 3 to 4 users you may find that a 30-megabyte (70000 pages)
pagefile is enough.
Feature Disk Requirements
Vendor Interface Files 10 megabytes nominal
When collecting data, vendor interfaces requiring disk space are:
Allen-Bradley PLC (1.3 MB)
Fisher CHIP (6.5 MB)
Foxboro FCG (2.75 MB)
Honeywell TDC3000 (18 MB)
Rosemount RMTHost (8 MB)
Taylor MOD300 (9.5 MB)
Westinghouse WDPF (6 MB)
Yokogawa Centap (5.4 MB)
Manuals for the DCS vendor-supplied software contain information helpful for planning
system memory and disk requirements.
Note: OSIsoft recommends 20% to 90% spare disk space.
At runtime, the PI System uses PINetBuild. We require that you leave PINetBuild on your
PIonPINet system. PINetBuild is required for startup as well as any upgrade or technical
support of your system.
5.1.4 Memory and Disk for DEC AXP/VMS Systems
PI on DEC ALPHA (AXP/VMS) platforms enjoys massive compatibility with VAX/VMS
based systems. The major differences are in the size of programs and some data structures.
The ALPHA is a 64-bit machine, so everything will be 2 or more times as large. Data
structures on ALPHA are forced into 64-bit words and in many cases must be page-aligned.
If you are running PIonPINet on DEC ALPHA platforms running OpenVMS you can
estimate your memory and disk requirements as follows:
PINet and PIonPINet User Guide Page 55
Chapter 5 – Installing PIonPINet/VMS
PIonPINet Memory and Disk Requirements
Memory Use the sections above to estimate your memory needs as though your system was
running under VAX/VMS. Multiply the result by 2.5 to get your AXP/VMS PIonPINet
memory requirement.
Disk The program files on AXP/VMS are 2.5 times larger than on VAX/VMS. The data
and configuration files are 4 times larger on AXP/VMS.
5.1.5 TCP/IP Software
One of the following TCP/IP software products is required on the VAX/ALPHA.
DEC TCP/IP Services for OpenVMS (commonly called UCX), v2.0b or higher
Process Software TCPWare version 3.1 or higher
Process Systems (formerly TGV/Cisco) MultiNet, v3.2 or higher for VAX, v3.4 or
higher for ALPHA
Attachmate (formerly Wollongong) PathWay, runtime release 1.1 or higher
Installation
Security
A PITrust must be defined for the PINet or PIonPINet node. Refer to the PI Server System
Management Guide regarding PITrust creation.
The PINet or PIonPINet node’s PITrust must be defined prior to installation or upgrade of
PINet or PIonPINet.
5.2 Installing PIonPINet/VMS
The installation of PIonPINet/VMS is similar to that of PINet/VMS. If you install
PIonPINet/VMS, there is no need to install PINet/VMS. For full installation information,
follow the PINet Installation section of this manual.
PIonPINet takes approximately 2 hours to install. For PI on OpenVMS, refer to the PI Server
Installation and Upgrade Handbook (version 2.6).
In the section below, only the differences for installing PIonPINet versus PINet are
illustrated.
5.2.1 Preparing for Install of PIonPINet Node
When you install a PIonPINet node, you must first install or upgrade the PI Home Node to
version 3.1 or later.
Installation of PIonPINet/VMS follows the same pre-installation, installation, and post-
installation instructions as PINet/VMS, with minor differences.
1. When executing VMSinstal, you will use PIonPINet’s product name:
@sys$update:vmsinstal pipn026 cd-device:[000000]
Page 56
5.2 – Installing PIonPINet/VMS
Note: Substitute the name of your device for cd-device. You will be prompted to
confirm new installation or upgrade.
2. Memory and disk requirements for PIonPINet are slightly different than those for
PINet. Confirm that the virtual memory of VMS is adequate to begin the installation.
5.2.2 Upgrading VMS
OSIsoft assumes that customers will be upgrading their VMS versions about every 2 years or
so. OSIsoft normally supports the last two major versions of VMS for use with new or
upgraded PI systems. Presently OSIsoft is supporting OpenVMS versions 6.1, 6.2, 7.1 and
7.2 and later. OpenVMS version 7.0 is not supported for use with PI systems.
Normally, when upgrading VMS, it is a good practice to re-link the PI System. If you have
questions on PI compatibility with new VMS releases, contact OSIsoft Technical Support. If
a complete re-linking of PI is necessary, PIBuild:PIInstall.com procedure may be used for
this purpose.
When you re-link the PI System, also re-link custom and site-specific applications that use PI
routines.
5.2.3 Startup
The file PISysMgr:PIonPINetStart.com starts PIonPINet/VMS. You should put the following
in your OpenVMS startup command file, Sys$Manager:SyStartup_VMS.com in order to start
PIonPINet/VMS when OpenVMS starts up:
$ @dka0:[PINet]pionpinetstart.com
Substitute the name of your disk for dka0. Site specific PI startup commands are still placed
in PISysMgr:SiteStart.com. Site-Specific PI startup commands would include the start
commands for optional PI components such as interfaces, reports, custom programs.
5.2.4 Shutdown
The file PISysMgr:PIonPINetStop.com stops PIonPINet/VMS. You may wish to put the
following in your Sys$Manager:SysShutdwn.com command file in order to stop
PIonPINet/VMS when OpenVMS shuts down:
$ @pisysmgr:pionpinetstop.com
Site-specific shutdown commands for interfaces, reports, custom programs are still placed in
PISysMgr:SiteStop.com.
PINet and PIonPINet User Guide Page 57
Chapter 6. USING AND MANAGING PIONPINET /VMS
PIonPINet allows running PI2.x applications on a PINet node. Since PINet TCP/IP can run
against a PI3.x System, applications that cannot be migrated can still be run. PIonPINet also
supports PI Toolkit-based applications. PIonPINet is a separately licensed product – contact
OSIsoft sales for more information.
6.1 How PIonPINet Works
6.1.1 Normal Operation
Displays are configured on each PIonPINet node where they will be viewed. The pidisdiff
utility can be used to copy trends, unit summaries, and graphics to other nodes in the
distributed PI System. Since the display, user, and Tag attributes are local, a user does not
generate significant network traffic in the normal course of viewing displays. Snapshot and
Archive data, and Digital State information are retrieved across the network. Since Archive
retrieval is seldom the bottleneck in display generation, the performance of displays on PINet
is good. Display drawing speed is the major performance factor when viewing PI displays.
File system access is the second major performance factor.
Archive editing and Tag configuration are restricted to the PI Home Node.
The following components from the PI2.x Data Archive base package are supported on a
PIonPINet satellite node:
Menus (along with Build Menu, Custom Menu, Edit User, and Central Print
Resource)
Archive List
Tag Search and Tag Info
Tag Concordance (local displays only)
Other optional components from the PI Home Node are enabled for the PIonPINet Satellite
node if licensed. See Supported Modules, below.
Programs and applications on the PIonPINet node can read the following data:
Point Attributes
Snapshot
Archive
PINet and PIonPINet User Guide Page 59
Chapter 6 – Using and Managing PIonPINet /VMS
Engineering Unit strings
Digital State strings
Point Source PIonPINet
Note: Displays that present Engineering Units, Point Sources and Digital State
strings show data from a local default database that is installed with PIonPINet/VMS.
They are not updated with information from the PI Server Home Node. Digital state
strings used in other displays are translated by the Home Node and should be
correct.
Configuration and editing for these items and all archiving is only performed on the PI Home
Node. A process called PINetSync maintains a local copy of the Point Database and
synchronizes the local VMS system time with that of the PI Home Node.
PINet nodes use the PI3 server Record number attribute (RecNo) rather then the PointID.
This is due to PINet architecture, which is based on a fixed size point database. The RecNo is
always below the point count, whereas the PointID grows monotonically.
6.1.2 Failure Modes
When the PI Home Node is not available, users are not able to see Archive data. Snapshot
data collected locally may be viewed. All other functions continue.
When Tags are deleted on the PI Home Node, the distributed displays will attempt to heal
themselves when they are invoked. The self-healing function may be a little disconcerting.
This is the sequence when a user has a display up and a Tag used on the display is deleted on
the PI Home Node, as shown in the following example:
Display is active and the data updates
Tag is deleted on the PI Home Node
When the display is next refreshed, it will exit abnormally and return to the menu
When the display is invoked again, the deleted Tag will not appear
The builder screen reflects a blank space where the deleted Tag once was
6.2 Supported Modules
Optional components from the PI Home Node are enabled for the PIonPINet Satellite node if
licensed. Specifically, PIonPINet/VMS supports the following PI2.x modules:
PINet/VMS - Includes support for interfaces, PI Toolkit programming, PI API
programming. PIonPINet is a superset of the PINet/VMS product. Thus there is no
need to separately install PINet on a PIonPINet node.
PI TR, Data Trending - Including four types of Trends: Horizontal, Vertical,
Composite, and Overview. Both types of Unit Summaries are supported: short and
long.
Page 60
6.3 – Unsupported Modules
PI GP, Graphics Package - The graphics package generates rather large drawing
files (PIGP*.dat). You may wish to examine your disk requirements before
implementing this package. Display files can range in size from several hundred
kilobytes to several megabytes in size. Also, user quotas will need to be considered,
particularly PGFLQUO.
PI AN, Analysis Package - The analysis package is supported on PIonPINet nodes.
No extra configuration is necessary.
PI IR, Interactive Report Builder - There are no special requirements for this
package.
PI RW, Report Writer - Since additional files are necessary to run the report writer,
you may wish to create a special PIReports directory. This provides a concise
repository for source files (*.rdf), compiled files (*.rpi, *.rpo), and reports (*.txt).
PI DL, PC Download Package - Since additional files are optionally created for this
package, you may wish to create a special PIDownload directory. This provides a
concise repository for source files (*.txt) and output files (*.prn).
PI PD, Profile Displays - There are no special requirements for this package.
Note that client products such as PI ProcessBook, PI DataLink, PI SQCView, and PI Profile
generally replace the functionality of the above modules.
If the PI Home Node is PI for Windows or UNIX, PIonPINet/VMS should only be
considered a migration tool for current PI for OpenVMS users.
If the PI Home Node is PI2.x on Open VMS, then PIonPINet provides support for terminal
based users on a satellite node. This frees up resources and computing power on the PI Home
Node. This can also provide a rich, distributed environment for PI Systems needing to
provide some limited functionality during network or PI Home Node outages. PIonPINet also
can provide a powerful distributed environment give a local system manager autonomous
control over local user accounts, privileges, display library and menu systems.
6.3 Unsupported Modules
The following utilities are not supported when the Home Node is a PI3.x Server:
List Digital States
List Engineering Units
List Point Source
These utilities present data, based on the architecture of PI2.x for OpenVMS. They are
incompatible with the PI3.x Server architecture.
The PI API maintains compatibility (relative to these tables) with all servers. All point editing
operations, including changes to Digital-States, Engineering Units and Point Source must be
performed on the PI Home Node.
PINet and PIonPINet User Guide Page 61
Chapter 6 – Using and Managing PIonPINet /VMS
6.4 PINet Design Changes / Limits
Point License Increase
PIonPINet 2.x has two parameters related to the size of the Point Database: Ultimate Point
Count and Current Point Limit. These parameters are important even when the Home Node is
a PI3.x Server, since they are used to determine the size of the point database on the
PINet/VMS node.
Ultimate Point Count size changes increase the physical size of the Point Database. As a
result, the amount of disk and memory required for such a PIonPINet System could increase
to support such an upgrade.
Current Point Limit is the licensed number of points for the PIonPINet System. If it were
necessary to increase the size of Current Point Limit larger than the present setting for
Ultimate Point Count, then both parameters would be changed.
Point License Impacts PIonPINet
The PI System for OpenVMS will reuse the point number of a deleted point. The PI Server
does not. The point number of any new point is higher than all previous point numbers. In
PINet or PIonPINet versions earlier than 2.2, this had an impact on PIonPINet/VMS since
PIonPINet/VMS has a fixed size point database which is indexed by point number. This
limitation is addressed in the version 2.2 and later release of PIonPINet/VMS.
Changing VMS Platforms
Migration from VAX to AXP should only be performed for recent PI versions. For PIonPINet
version 2.2 and later "recent" means PIonPINet 2.1.0 or later. This minimizes compatibility
issues and guarantees the highest possible success.
Ordering and Licensing Information
PIonPINet license does not include PINet. PINet is required as a prerequisite to PIonPINet.
Both PINet and PIonPINet are purchased and licensed for implementation of a PIonPINet
node. OSIsoft's licensing treats these as separate products. However, there is no need to
separately install PINet on a PIonPINet node. The PIonPINet installation tool will install both
products in the same operation.
6.5 PIonPINet/VMS Operation
Directories
There are three directories on a PIonPINet/VMS system:
• PINet
• PINetBuild
• PISysDat
The command file PIonPINetNames.com maps PI logical names to the above directories.
Page 62
6.5 – PIonPINet/VMS Operation
Running PI Displays
To look at PI for OpenVMS displays, log into the PI menu. Execute the following:
@pisysexe:pi
Consult the PI for OpenVMS documentation set for information on the particular PI2.x
server application programs that interest you.
The following sections of the PI for OpenVMS Manual apply to PIonPINet:
PI TR, Data Trending
PI GP, Graphics Package
PI AN, Analysis Package
PI IR, Interactive Report Builder
PI RW, Report Writer
PI DL, PC Download Package
PI PD, Profile Displays
The PI DA, Data Archive section of the PI for OpenVMS Manual set includes chapters on
Getting Started, Display System, and Appendices. These chapters also apply to PIonPINet
(Logging in, Using Standard Displays, User Accounts, Menu System, Privileges.)
The PI Guide is also a very useful reference for navigating the PI menu, using trends and
graphics. The PI Guide also explains concepts such as PI time (absolute and relative). Refer
to the PI System Manager’s Course Notes book for explanation of PINet operation as a data
acquisition node and for troubleshooting tips.
Registered users of OSIsoft Technical Support may download all referenced documentation
from the OSIsoft Technical Support web site: http://techsupport.osisoft.com.
The PI Programming ToolKit and PI API are documented in their respective manuals.
PINet and PIonPINet User Guide Page 63
APPENDIX A: PINET AND PIONPINET REVISION
HISTORY
PI System Changes for Version 2.6
Full details of the bug fixes and enhancements can be found in the software release notes for
PI for OpenVMS version 2.6. These release notes are available on the OSIsoft Web site and
can also be found in the PINetBuild directory of PINet interface nodes running PI2.6. Look
for a file called V2.6.
PINet Version 2.6 is released with many bug fixes and enhanced features primarily affecting
interfaces and PINet interface nodes. Bug fixes and workarounds through April, 2005 are
included in this release.
Enhancements and Bug Fixes
Enhancements and Bug Fixes for the following PI subsystems are included in this release:
ExceptServ (PINet) works better in high throughput systems
Event Manager on PINet signups managed more frequently
PutSnapShot time checking enhancement for DST
PINetSync works better across DST time changes
PutSnapShot Time Check Enhancement
Sometimes, it is necessary for the PINet system time to be different (time zone or DST
setting) than the time of a PI3 server. In this special case, even if the interface provides the
correct timestamps (by applying offset) for the data, it is possible for the PINet putsnapshot
to reject the data because of time in the future check.
In PINet 2.6, we provide a system wide option to disable the snapshot future time check.
Users can modify this setting in the command file setSkipPITimeChk.com in the PINet
directory. You can run the command file at anytime to change the time check setting.
UniInt-based Interface Enhancements and Bug Fixes
With PI2.6, UniInt version 3.5.16 based interfaces now offer a command line option to
disable time offset change restriction.
/VMSAllowDSTMisMatch
PINet and PIonPINet User Guide Page 65
Appendix A: PINet and PIonPINet Revision History
This VMSAllowDSTMisMatch option should normally be used with the PINet
SetSkipPITimeChk option (described above).
Recently Updated Interfaces
The following interfaces have been updated to receive new features and bug fixes:
PI IN-HW-CM50S Honeywell TDC CM50S Interface.
PI IN-WH-VXI Westinghouse VXI Interface
Updated Product Documentation
Registered users of OSIsoft Technical Support may download updated documentation from
the OSIsoft Technical Support web site: http://techsupport.osisoft.com
PI System Changes for Version 2.5
Full details of the bug fixes and enhancements can be found in the software release notes for
PINet for OpenVMS version 2.5. These release notes are available on the OSIsoft Web site
and can also be found in the PINetBuild directory of servers running PI2.5. Look for a file
called V2.5.
PINet Version 2.5 is released with many bug fixes and enhanced features primarily affecting
interfaces and PINet nodes. Bug fixes and workarounds up to about 17-Feb-04 are included in
this release.
Support for OpenVMS 7.3 on the Alpha
With this release OSIsoft has support for OpenVMS 7.3 on the ALPHA (AXP) processor for
both PI Home Nodes and PINet interface nodes. Previously only PINet was supported for
OpenVMS 7.3 on the ALPHA and these were all special builds. PI support for OpenVMS 7.3
on the ALPHA is now a standard build.
Enhancements and Bug Fixes
Enhancements and Bug Fixes for the following PI subsystems are included in this release:
Point Database
Snapshot
PINet’s ExceptServ
Event Manager
Snapshot Range Checking
System managers should consider enabling Snapshot Range Checking on PINet interface
nodes. It is possible to crash the application doing putsnapshot when the difference between
the current snapshot and the previous snapshot is greater than 1.8e38. (e.g. one value is
positive and other negative.) The workaround is to enable snapshot range checking by
editing the PINet:SnapChkRange.com command file and executing the command file.
Page 66
Appendix A: PINet and PIonPINet Revision History
$! setSnapChkRange.com
$!
$! command file to allow use to specify option to do range check in snapshot
$! for type R points. Default is no range checking.
$! To specify range checking, set the argument to 1.
$!
$ rgch :== $pisysexe:setSnapChkRange
$! set to no range checking in snapshot. Change 0 to 1 to do range check
$ rgch 1
The example shown above enables range checking. Changes made to this command file are
persistent because this command file is executed with each restart of PINet.
UniInt-Based Interface Enhancements and Bug Fixes
With PINet 2.5, all UniInt based interfaces are now built with UniInt version 3.5.9. For more
information on general features and operation of UniInt based interfaces please refer to the
UniInt End User Manual and the interface specific documentation for your interface to PI.
Recently Updated Interfaces
The following interfaces have been updated to receive new features and bug fixes:
PI IN-HW-CM50S Honeywell TDC CM50S Interface.
PI IN-MO-MPLC Modbus/ModbusPlus PLC Interface
PI IN-ABB-300N ABB MOD300 Interface
PI IN-FI-CHIP Fisher-Rosemount CHIP (CHIPtoPI) Interface
PI IN-ES-HABSC Esca Habitat SCADA Interface
PI IN-RM-RMTH Fisher-Rosemount RMTHost Interface
PI System Changes for Version 2.4.1
PINet version 2.4.1 is primarily a release supporting interfaces that have been revised or
newly written. Several infrastructure changes benefiting interfaces are also included in this
release. (e.g. new UniInt version used for linking interfaces.)
New Features and Changes
Refer to release notes for individual interfaces
Recently Completed or Revised Interfaces
Refer to release notes for individual interfaces
PI System Changes for Version 2.4
Full details of the bug fixes and enhancements can be found in the software release notes for
PI for OpenVMS version 2.4. These release notes are available on the OSIsoft web site and
PINet and PIonPINet User Guide Page 67
Appendix A: PINet and PIonPINet Revision History
can also be found in the PINetBuild directory of servers running PI2.4 - look for a file called
"V2.4".
New Features and Changes
In the past, some PINet nodes had very large point databases in order to be compatible with
PI3 servers. PI3 customers with PINet can now request a PINet nodes with smaller size point
database matching their PI3 server better. Eligibility for this feature will depend on the range
of archive record numbers defined in the PI3 system. Contact Technical Support to see if
your system can take advantage of this feature.
Recently Completed or Revised Interfaces
New features and bug fixes have been included for several interfaces:
• PI IN-AA-ADV
• PI IN-GSE-D3
• Batch File Lab
• Bailey SemAPI
• PI RMT Host
• FLIC/ModComp to PI
• RNI
• CHIPtoPI
• Epic Cs
• Hartmann & Braun Contronic P/E-K
• Conlink X
PI System Changes for Version 2.3
Problems with several PI utilities and subsystems have been resolved. Refer to the software
release notes for more details on PINet UNIInt. UNIInt is an interface shell developed by
OSIsoft to standardize behavior of interfaces. Enhancements made to UNIInt will benefit all
interfaces using UNIInt. The version of UNIInt will be output to the log file as the interfaces
start up. The PI release notes for version 2.3 can be found in the file, PINetBuild:V 2.3.
New Features and Changes
Point Database: Many sites have the problem of user programs locking PI shareable images
after PI is shut down. The PI shutdown procedures (pinetstop.com and pionpinetstop.com)
now call a command file stoppiuserprogram.com to determine if any PI shareable images are
locked because there are still active processes linked to PI shareable images. The command
procedure prompts the user for permission to terminate these processes. If the user does not
want these processes terminated automatically, answering with "n" will cause
stoppiuserprogram to list the offending processes but not terminate them. Otherwise,
stoppiuserprogram will scan all active processes and terminate those linked with PI shareable
images.
Page 68
Appendix A: PINet and PIonPINet Revision History
Point Database: A new utility, PINet:Find-PI Related.com can be used to identify custom
and 3rd party PI Related programs which were not automatically relinked by the upgrade to
PI. PI Related programs are linked to PI libraries and shareable images. If not relinked, PI
Related programs will not run properly after PI has been upgraded.
PINet Enhancement: The scheme to create the short Tagnames on PINet talking to a PI3
Home Node was changed in PINet 2.3. Tagnames equal to or shorter than 10 characters on
the PI3 Home Node will now retain their Tagnames on the PINet node instead of having
mangled Tagnames created.
During an upgrade, the PINet VMSinstal procedure will automatically rebuild the local
copies of the Point Database, Event Queue, and Snapshot files. To avoid lost data, system
managers should not upgrade PINet nodes at a time when the PINet node has a backlog of
unprocessed data in the event queue.
PI System Changes for Version 2.2
Problems with several PI utilities and subsystems have been resolved. Refer to the software
release notes for more details on the following items:
EVMCheck has been enhanced to accept a user-specified timeout setting when
checking for inactive processes.
ConvertVAXSnapshot utility, which runs as part of a conversion from VAX to AXP
(ALPHA)processor, no longer has problems for Point Databases larger than 64000
points.
ConvertPIPoint utility, which automatically runs on upgrade to increase the Point
Database size, no longer crashes or corrupts records.
The archive call, ArcInterpValFilter now correctly handles “bad data” in the filter
expression.
PINet and PIonPINet for PI3
For systems with PINet or PIonPINet talking to a PI Server, there was a problem when the
point number of a PI3 Tag was larger than the PtDim (total point dimension) on the PINet or
PIonPINet node. This caused data loss in some cases because the PINet or PIonPINet node
could not “see” or allocate memory for those Tags. In the past, this problem could only be
resolved by installing a PINet node with a larger point count. This has been fixed. PI2.2 and
later versions use a new point number conversion algorithm so that as long as the total
number of Tags on the PI Server is less than the PTDIM on the PINet (or PIonPINet) node,
all Tags will be visible by PINet.
As part of the upgrade, many applications on the PINet or PIonPINet node will have to
generate new database files to support the new algorithm. For example, all displays and
report writer RPI files on the PIonPINet nodes talking to a PI Server will have to be
regenerated. For displays, the easiest way is to use the PIDisDIFF utility to save the
definition of existing displays to ASCII file before the upgrade. After the upgrade, use
PIDisDIFF to modify all the displays with the ASCII data file.
PINet and PIonPINet User Guide Page 69
Appendix A: PINet and PIonPINet Revision History
PI2.2 and later versions provide two command files (SaveAllDisp.com and
RestoreAllDisp.com) to automate the saving and restoring of displays. The upgrade procedure
copies these command procedures to PISysEXE and gives the user a chance to quit the
upgrade procedure to run the SaveAllDisp.com procedure before continuing with the upgrade.
For reports, simply delete the *.rpi files. Next time the report is run (Use
PISysExe:DoReport.com to run the reports), the report writer will recompile the reports
which generates new RPI files.
UCX, TCP/IP Services, and OpenVMS 7.2
In OpenVMS 7.2, Compaq changes the UCX product name to TCP/IP Services for
OpenVMS. The logical name, UCX$Service used by PI’s various command files to detect the
presence of UCX has been replaced by TCPIP$Service. Hence, many PI components
depending on UCX would not link or work properly. The workaround for PI2.1.2 was to
define the logical name UCX$Service to point at TCPIP$Service and re-link the PI System.
For PI2.2 and later versions, all the PI command procedures have been changed to check for
both UCX$Service and TCPIP$Service.
PINet and PIonPINet
The installation now checks for and confirms the changes in Point Database size during the
installation. If the PI Server is on OpenVMS, making the Point Database smaller can cause
the loss of Tags and archive data as well as cause an installation failure that is difficult to
recover from. PI2.2 and later versions prevent this by disallowing the size change.
If the PI Server is a PI3 system, it is possible to increase or decrease the Point Database size
on the PINet or PIonPINet node. If the new database will be smaller, the user is prompted for
permission to delete the Point Database files on the PINet or PIonPINet nodes.
PI System Changes for Version 2.1.2
A number of problems affecting PI Server nodes have been corrected. Excessive reconnection
problems for PINet nodes running UCX have been corrected. PI Event Manager update
problems for points not collected locally have been corrected. The update rates are now more
frequent so that events will not accumulate on the PI Home Node. On VAX, OSIsoft is now
using DECC version 4.0 (previously OSIsoft was using only VAXC).
At the PINet nodes there is a new option, SetSnapChkRange, for setting range checking for
new data coming into the snapshot. The default behavior is range checking off. With range
checking off, snapshot values are allowed to exceed the range defined by the point's zero and
span attributes. With range checking on, any new snapshot value that exceeds the point's zero
and span will automatically be replaced with a status value of UnderRange or OverRange as
appropriate. PIServer support is now placed on all PINet and PIonPINet nodes. This is
primarily to support PI SMT/Health Check.
PI Server has been updated to support System Management Tools (PI SMT). PI SMT
includes Health Check, a Windows-based GUI client for monitoring the PI System operation.
PI SMT also includes Tag Configurator for building/changing points via an Excel97 add-in.
Other tools are planned for the future. After installing or upgrading PINet 2.1.2, PI SMT may
Page 70
Appendix A: PINet and PIonPINet Revision History
be installed from the PI3.x CD, or may be downloaded from the OSIsoft Web site,
http://www.osisoft.com. Refer to PI Server System Management Guide, Chapter 2, “System
Management Tools (PI SMT), ” and the PINet version 2.1.2 software release notes for more
information.
PIBuild:PIserver.txt permits the network service for PI to be defined using a command
procedure instead of just an executable image. Users should change to the new service
definition - this is not automatic. The instructions are also found in a file
PINetBuild:PIServer.txt on the PINet server node. The advantages of the change are lower
usage of system memory, more complete logging of system errors and ability to read the
PINet:MTPPIServer.log file while the process is still running.
PINet to PINet
Instead of connecting a VMS PINet node directly to a PI Server, the PINet node can connect
to another PINet node that is connected to the PI Server. This capability is introduced in
version 2.1.2. This feature is useful for PI Server system with a lot of VMS PINet nodes. By
grouping the PINet nodes, you can reduce the number of direct connections on the PI Server
and distribute the some of the network load over several machines. Note that the PINet to
PINet option is strictly used with PI Server.
For new installation of PINet, you will be prompted for the PINet-to-PINet option. You do
not have to do anything for the PINet master, that is, the PINet node directly connected to the
PI Server Home Node. You should enable the PINet-to-PINet option for the PINet slave and
specific the PINet master as the Home Node. The PINetTransport can be either DECNET or
TCP/IP to talk to the PINet master.
For upgrading an existing PINet node, the installation procedure automatically adds the
PINettoPINet logical name to your system and set the logical to 0. If you want to change an
existing PINet node to become a PINet slave, you have to modify manually the
pinetnames.com (or pionpinetnames.com for PIonPINet Nodes) to change the HOMENODE
name to point at the PINet master. PIHomePort should be changed to 545 and PINettoPINet
should be changed to 1.
Upgrading Hint
If you want to implement PINet-to-PINet for existing PINet nodes, it may be easier to remove
the PINet installation and perform a new installation. The same may also be the case if you
are migrating a PINet node from a PI2.1.x or PI2.2.x Home Node as part of a PI2 to PI 3
Server migration.
Save your interface startup files before removing the old PINet installation. Re-install PINet
per the instructions in this chapter. Restore the interface startup files before restarting PINet.
Check the interface startup file configurations against the latest documentation for your
interface to PI.
PINet and PIonPINet User Guide Page 71
Appendix A: PINet and PIonPINet Revision History
Differences Between PI2.x Systems and PI3.x Server
Digital State Table
PINet/VMS communicating with a PI3.x Server System does not maintain nor use the local
copy of the Digital State Table. The file PINet:DigState.Dat exists, but it is neither used nor
updated by PINet/VMS programs.
Functions that translate digital state codes into digital state strings (and vice-versa) are
resolved with PINet/VMS sending messages across the network to the PI Home Node.
Engineering Unit Table
PINet/VMS communicating with a PI3.x Server System does not maintain or use the local
copy of the Engineering Unit Table. The file PINet:EUCode.Dat exists, but it is neither used
nor updated by PINet/VMS programs.
Functions that translate engineering unit codes into engineering unit strings (and vice-versa)
are resolved via lookup into PINet/VMS’s local point database. For PI Server, engineering
unit translations are done on the server.
Event Manager Retrieval for Integer Tags
For PINet/VMS running on a VAX, the PIEVManager cannot obtain values greater than
32767 for an integer Tag. Instead, a status of -290 (Bad Status) is retrieved.
Programming Issues
See the PI Server Reference Manual, Appendix D for a discussion of PI API and PI Toolkit
functions that behave differently when called against a PI3.x Server versus a PI2.x System for
VMS. In addition, the following functions now connect to the PI Home Node in order to
return the specified parameters.
GetDigState
pipt_digstate
Page 72
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a
week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.
Help Desk and Telephone Support
Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349
Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
[email protected]. Technical Support will respond to your inquiry within 24
hours.
Personalized Online Technical Support
The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls (Online Support). The My Support menu allows you to review
My Products, My Download History, and SRP Terms, which covers Service Reliance
Program (SRP) service agreements.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
PINet and PIonPINet User Guide Page 73
Technical Support and Resources
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Remote Server Access
Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.
On-site Technical Support
OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time
Find Version and Build Numbers
To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion -v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option -v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname -a
Page 74
Technical Support and Resources
Special Considerations for PINet and PIonPINet
PINet and PIonPINet require special consideration for support and upgrades. Please follow
these instructions.
Find the Operating System Version, and Running Applications
Enter the command: Show System
Find the PINet or PIonPINet Version Number
To find the PINet or PIonPINet version number, change to the PINet or PISysEXE
directory and enter the command: @PINet:pinetverify
Find Subsystem, Interface and Application Version Numbers
PINet and PIonPINet are custom compiled and distributed as an integrated system. Most
PINet subsystems, interfaces, and applications don’t have separate build numbers. Some
may have a separate version number, which are reported and logged by the program
during restart. Log files are found in PINet, PISysMgr or PISysEXE directories, named
generally: *.log, *.out, and *.txt:
PINet or PISysMgr – PIMessLog.txt;*
PINet or PISysEXE - *.out, *.log, *.txt files
Find System Parameters
Enter the command: type piparamsc
Upgrades
To request an upgrade, provide PINet and operating system version, and platform
information to Technical Support. Follow PI2 upgrade request instructions on the
Technical Support web site: choose Contact Us > Obtaining Upgrades.
Remote Server Access for PINet or PIonPINet
Technical support engineers can remotely access your PINet or PIonPINet node to
provide diagnostics, hands-on troubleshooting, and assistance. You will need a robust
terminal emulation program, such as WRQ Reflections VT (or R2 or R4). Windows
Telnet or Hyperterm applications are not adequate for remote assistance.
PINet and PIonPINet User Guide Page 75
INDEX OF TOPICS
Alpha, 25 PI2 to PI3
Analysis Package Point ID, 26
VMS, 61 PointNumber, 26
Architecture Data
PI2 System, 2 Trending
Attachmate PathWay, 7, 56 VMS, 60
Attribute Data Archive
Search Data Retrieval by PINet, 3
ListAtt.exe, 30 DECNet, 49
AXP. See Alpha PINet to PINet, 23
Backup Differences
Across the network, 38 PI2.x Systems and PI3 Server,
Image, 35 72
Procedure, 35, 37 Digital State
Purpose, 35 Table, 72
Recovery Plan, 36 Directories
Batch PINet, 25
DST, 34 Disk space
Buffering Requirements
PINet, 3 PINet, 16
PINet Satellite Node, 28 PINet/OpenVMS, 8
Client/Server Distributed data collection
Name concordance, 46 Architecture, 1
Relationship, 4 Documentation
Command-line Tools, v PI Server, iii
Computer platform PINet
Information, 74 Data flow, 3
Configuration Typographic conventions, vi
PINet/OpenVMS, 21 DST
Time PINet, 34
Setting, 34 setSkipPITimeChk.com, 22
Conversion Timecheck, 22
Engineering Unit Table, 72
PINet and PIonPINet User Guide Page 77
Index of Topics
Error Messages Files involved, 25
PINet, 26 From Savesets on Another
Estimates Node, 20
Memory and Disk, 8, 53 On OpenVMS, Instructions, 16
Event PINet Migration, 47
Shutdown PINet or PIonPINet Nodes, 56
PINet, 32 PIonPINet/VMS, 56
Event Manager Preparation for
PINet/OpenVMS install, 11
Exceptions
Upgrade
EVMDump.exe, 29
From PI2.x, 13
PINet limits, 72
PINet/OpenVMS, 18
Event Queue
Verification
PINet Satellite Node, 28
PINet/OpenVMS, 21
EVMCheck
Interactive Report Builder
PINet, 29, 33, 34
VMS, 61
EVMDump.exe, 28
Interface
ExceptServ, 4
PINet node, 31
PINet, 29, 33
IORates, 34
Failure Modes, 60
Key Users, 35
File Protection
License information, 62
PINet Connections, 50
Licensed Point Count, 46
Format
Logical Names
Messages between nodes, 34
Troubleshooting, 41
Get_pinettransport.exe, 42
Long Tagname
Graphics Package
Co-Mingled Tagnames, 27
VMS, 61
Snap Utility, 28
Honeywell CM50 software, 15, 17
Master/Slave
I/ORates
PINet to PINet, 23
I/OMonitor
Memory
PINet, 27
Requirements
Interfaces
PINet/OpenVMS, 8
PINet node, 30
Memory and Disk Estimates
PINet, 29
Alpha/AXP, 11, 55
System Programs, 31
PIonPINet, VAX/VMS, 53
Program
VAX/VMS, 8, 53
PINet, 30
Message Log, 26
Start or stop, 31
Create new, 26
Tag creation, 31
PINet, 26
Image Backups, 35
MultiNet
Installation
TCP/IP software, 7, 12, 42, 56
Checklist, 21
Network
Page 78
Index of Topics
Communications, PINet, 34 Unsupported Utility Modules,
Load, Reducing 61
PINet to PINet, 23 PI-AN, 61
OpenVMS Piartool
Version requirements, 7 Check Snapshot and Event
Queue, 40
Operation
Piconfig, 31
PIonPINet, 62
Pidisdiff, 59
OSI
PI-DL, 61
Account, 17
PIEVManager, 72
Overflow
PINet, 29, 33
Qwatch, 40
Pigetmsg, 40
PageFile, 13, 15
PI-GP, 61
PageFile.sys
PI-HealthCheck
change PageFile size, 18
Home Node logical name
Pagelets, 13
Troubleshooting, 41
PathWay
PIHomePort
TCP/IP software, 12, 42
Troubleshooting, 41
Performance
PI-IR, 61
Across the network, 59
PIMessLog.com, 26
PI Home Node, 3, 25, 32, 40
PIMessLog.txt, 26
PI Processes, 13
PINet
PI Server
Advanced Topics, 45
Build number, 75
DECNet, 49
Documentation Set, iii
Installation
Version, 75
Migration, 47
PI shareable images, 43
vs Upgrade, 47
PI2 System
Master/Slave, 48
Changes
PIServer, 48
version 2.1.2, 70
Benefits, 48
version 2.2, 69
Renaming Points, 45
version 2.3, 68
Starting, 22
version 2.4, 67
Startup
version 2.4.1, 67
OpenVMS 6.1 and up, 51
version 2.5, 66
Stopping, 22, 41
version 2.6, 65
System Message Log, 41
Differences, PI3 Server, 72
PINet Node
Displays, 63
Buffering for API Nodes, 49
Modules supported on
PIonPINet, 60 PINet to PINet, 48
PointID, 26 Grouping PINet Nodes, 23
PointNumber, 26 PINet/OpenVMS, 1
CheckForCrash.com, 31
PINet and PIonPINet User Guide Page 79
Index of Topics
Installation, 11 Point Number
Verification of, 21 PI2 vs. PI3, 26
Nodes PointID, 46
SetSnapChkRange, 22, 70 Point.dat, 13, 43
Operation, 25 PointID
Processes, 29, 33 Licensed Point Count, 46
Purpose, 2 PI2 vs. PI3, 26
ShutdownEvents.com, 31 Point Number, 46
Supported on PIonPINet, 60 RecNo, 46
Pinetmgr, 33 Points
PINetNames.com, 13, 42 Renaming, 45
PINetSync Post VMSInstal Steps, 21
PINet, 29, 33 Profile
PINetTransport Displays
Logical name VMS, 61
Troubleshooting, 41 Programming Issues, 72
PINetVerify, 29, 40 Protocol
PINet installation, 13 DECNet, 49, 50
Protocol, 40 PINet/OpenVMS, 34
PIonPINet, 1 PINetVerify, 40
Features, 5 PIonPINet, 1
Installation, 56 TCP/IP, 49, 50
Operation, 62 Purge command
Stopping, 57 PINet message log, 26
Toolkit PutSnapShot, 3, 65
Applications, 59 Time check enhancement, 65
PI-PD, 61 QManager, 4
PI-RW, 61 PINet, 29, 33
Pisnap, 40 Qwatch, 40
PI-TR, 60 Buffering, 40
PITrust Qwatch.exe
for PINet and API/SDK PINet, 28
Nodes, 11 Recovery Plans, 35
Platforms Report Writer
PINet/OpenVMS, 7 VMS, 61
Point Database Requirements
PINet local version, 3 Disk Space
Rebuilding, 42 AXP/VMS, 11
Troubleshooting, 42 PINet/OpenVMS, 9, 10
Point License Memory
Impact on PINet, 8, 62 AXP/VMS, 11
Increase, 8, 62
Page 80
Index of Topics
Pagefiles System Architecture
PINet/OpenVMS, 10 PI3, 5
PITrust Creation, 11 System Management Tools, v
Savesets System Requirements
For PINet Installation, 20 PINet/OpenVMS, 7
SaveSnapshot PINet, 29, 33 Table
SetSnapChkRange, 22, 70 Digital State, 72
Short Tagname Tag, 31
Co-Mingled Tagnames, 27 Rename, 45
Snap Utility, 28 Search
Shutdown, 21, 22, 32 PINet, 29
Automatic PINet/VMS, 22 Tagname
Events Co-Mingled, 27
PINet, 31 Renaming a Tag, 46
PINet, 25, 31 TCP/IP
PIonPINet, 57 PINet to PINet, 23
Slave/Master Software, 42
PINet to PINet, 23 MultiNet, 12
SMT PathWay, 12
About, v TCPWare, 42
Snap, 27, 40 UCX, 12
PINet, 27 TCPWare
Troubleshooting, 40 TCP/IP software, 7, 42, 56
Snapshot Subsystem TDC3000 interface, 15, 18
Event Queue Technical Support, 73
PINet, 28 Time
PINet local version, 3 Synchronization, 34
Start PINet/OpenVMS node to
PINet, 22 home node, 3, 33
PIonPINet, 57 System
Startup Setting, 34
Automatic PINet/VMS, 22 Timecheck
PINet DST, 22
Process, 25 Troubleshooting
Stop Attributes
PINet, 22 ListAtt.exe, 30
PIonPINet, 57 Network Connection, 40
SysGen parameters, 17 PIHomeNode logical name, 41
PINet installation, 14 PIHomePort, 41
System PINet Connections, 50
Set Time, 34 PINet Startup
PINet and PIonPINet User Guide Page 81
Index of Topics
OpenVMS/X-Windows, PINet/OpenVMS, 7
51 VersionRequirements
PINet/OpenVMS, 29, 40 PINet/OpenVMS, 7
PINetTransport, 41 View
PINetVerify, 40 Error Messages
Point Database, 42 PINet, 26
Snap, 40 Message Log
UCX PINet errors, 26
TCP/IP software, 7, 12, 42, 56 VMS
UniInt, iv, 65, 67 Disk Space
Upgrade Requirements, 10
from PI for OpenVMS, 13 Migration from VAX to AXP,
PINet, 47 8, 62
VMS, 57 Upgrading, 57
Utility VMSInstal
Utilities, PINet/OpenVMS, 27 PINet, 11
Vendor’s TCP/IP communications WildL
library, 42 PINet, 29
Version Requirements X-Windows, 1
PI Server, 7 PINet Startup problem, 51
Page 82
You might also like
- Extreme Privacy What It Takes To Disappear93% (15)Extreme Privacy What It Takes To Disappear514 pages
- How To Download Documents From Scribd For Free - 7 Methods67% (9)How To Download Documents From Scribd For Free - 7 Methods25 pages
- How To Root Any BLU Mobile Device Using Magisk (No TWRP Required)67% (3)How To Root Any BLU Mobile Device Using Magisk (No TWRP Required)14 pages
- GSEC GIAC Security Essentials Certification Exam GuideNo ratings yetGSEC GIAC Security Essentials Certification Exam Guide587 pages
- Extreme Privacy - Linux Devices (Michael Bazzell)100% (1)Extreme Privacy - Linux Devices (Michael Bazzell)90 pages
- Top 800+ Latest Android Secret Codes - Hidden Codes 2019100% (10)Top 800+ Latest Android Secret Codes - Hidden Codes 201912 pages
- Michael Bazzell - Open Source Intelligence Techniques - Resources For Searching and Analyzing Online Information-Createspace Independent Publishing Platform (2021)100% (11)Michael Bazzell - Open Source Intelligence Techniques - Resources For Searching and Analyzing Online Information-Createspace Independent Publishing Platform (2021)669 pages
- Secret Code List For Android and All Samsung - Code Exercise100% (2)Secret Code List For Android and All Samsung - Code Exercise6 pages
- Extreme Privacy What It Takes To Disappear 4nbsped 8431566361 9798431566363No ratings yetExtreme Privacy What It Takes To Disappear 4nbsped 8431566361 9798431566363785 pages
- PI Server Applications User Guide PI3 Server Version 3.4.370100% (1)PI Server Applications User Guide PI3 Server Version 3.4.370406 pages
- Restore Galaxy Null IMEI # and Fix Not Registered On NetworkNo ratings yetRestore Galaxy Null IMEI # and Fix Not Registered On Network36 pages
- PI Data Archive 2018 SP3 Applications Guide ENNo ratings yetPI Data Archive 2018 SP3 Applications Guide EN320 pages
- Hacking University Computer Hacking and Mobile Hacking 2 Manuscript Bundle100% (1)Hacking University Computer Hacking and Mobile Hacking 2 Manuscript Bundle95 pages
- Introduction To PI Server System ManagementNo ratings yetIntroduction To PI Server System Management117 pages
- Historian SE 2.0 PI Server Reference Guide PDFNo ratings yetHistorian SE 2.0 PI Server Reference Guide PDF166 pages
- Historian SE 2.01 Introduction To PI System ManagementNo ratings yetHistorian SE 2.01 Introduction To PI System Management118 pages
- PI Data Archive 2018 System Management Guide100% (2)PI Data Archive 2018 System Management Guide234 pages
- PI Asset Framework 2018 SP3 Patch 2 Client Installation and Upgrade Guide ENNo ratings yetPI Asset Framework 2018 SP3 Patch 2 Client Installation and Upgrade Guide EN22 pages
- PI Data Archive 2015 Reference Guide enNo ratings yetPI Data Archive 2015 Reference Guide en188 pages
- PIWorld 2019 Beginning Administration and Management of The PI System - FinalNo ratings yetPIWorld 2019 Beginning Administration and Management of The PI System - Final80 pages
- Architecture and Best Practices Recommendations: For PI SystemsNo ratings yetArchitecture and Best Practices Recommendations: For PI Systems50 pages
- PI Data Archive 2018 SP3 Patch 1 System Management Guide ENNo ratings yetPI Data Archive 2018 SP3 Patch 1 System Management Guide EN202 pages
- PI System Architecture Planning and Implementation100% (1)PI System Architecture Planning and Implementation225 pages
- PI Interface For Relational Databases (PI RDBMS Via ODBC) 3.21.4 User GuideNo ratings yetPI Interface For Relational Databases (PI RDBMS Via ODBC) 3.21.4 User Guide100 pages
- PI World 2018 Administering and Managing The PI SystemNo ratings yetPI World 2018 Administering and Managing The PI System56 pages
- Switch Network Interface For Eserver Pseries High Performance Switch Guide and ReferenceNo ratings yetSwitch Network Interface For Eserver Pseries High Performance Switch Guide and Reference52 pages
- Aveva Pi Server 2023 Pi Smt User Guide EnNo ratings yetAveva Pi Server 2023 Pi Smt User Guide En483 pages
- PI Interface Configuration Utility (PI ICU) 1.5.1 User GuideNo ratings yetPI Interface Configuration Utility (PI ICU) 1.5.1 User Guide108 pages
- PI Coresight 2015 Installation and Administration GuideNo ratings yetPI Coresight 2015 Installation and Administration Guide84 pages
- KB00884 - PI System Daily Health Check: My Support Contact Us Resources Downloads ProductsNo ratings yetKB00884 - PI System Daily Health Check: My Support Contact Us Resources Downloads Products6 pages
- PISystem Administrator For ITProfessionals WorkbookNo ratings yetPISystem Administrator For ITProfessionals Workbook196 pages
- CSS - Info Sheet 3.2-2 - Installupdate Required Modules Add Ons100% (2)CSS - Info Sheet 3.2-2 - Installupdate Required Modules Add Ons16 pages
- Poison Ivy 2.1.0 Documentation by Shapeless - TutorialNo ratings yetPoison Ivy 2.1.0 Documentation by Shapeless - Tutorial12 pages
- Informix 14.10 Quick Reference Guide: Command UtilitiesNo ratings yetInformix 14.10 Quick Reference Guide: Command Utilities8 pages
- Free Prepper and Survival Manuals PDF SNo ratings yetFree Prepper and Survival Manuals PDF S19 pages
- LINUX Administrator's Quick Reference Card: User Management NFS File Sharing100% (3)LINUX Administrator's Quick Reference Card: User Management NFS File Sharing6 pages
- Download full Tweak Your Mac Terminal: Command Line macOS 1st Edition Daniel Platt ebook all chaptersNo ratings yetDownload full Tweak Your Mac Terminal: Command Line macOS 1st Edition Daniel Platt ebook all chapters62 pages
- Repair Your Computer in Windows 8 and 8.1No ratings yetRepair Your Computer in Windows 8 and 8.127 pages
- 2 unit_MCQ_ Machine to machine coummnunicationNo ratings yet2 unit_MCQ_ Machine to machine coummnunication15 pages
- National Institute of Technology RourkelaNo ratings yetNational Institute of Technology Rourkela2 pages
- CCNA 200-125 171q by PenPineappleApplePen - Protected100% (16)CCNA 200-125 171q by PenPineappleApplePen - Protected66 pages
- Detector Fetal BT-200 - Manual de Serviços PDFNo ratings yetDetector Fetal BT-200 - Manual de Serviços PDF10 pages
- VxRail+7 0 XXX+Installation+-+Downloadable+ContentNo ratings yetVxRail+7 0 XXX+Installation+-+Downloadable+Content29 pages
- Netbackup Device Configuration Guide (Unix, Windows & Linux) 6.5No ratings yetNetbackup Device Configuration Guide (Unix, Windows & Linux) 6.5202 pages
- IT-2205 Lec 01 Introduction To Data CommunicationNo ratings yetIT-2205 Lec 01 Introduction To Data Communication26 pages
