HSEPIS-RM020A-EN-E
8/8/07
10:41 AM
Page 1
Historian SE
PI SERVER REFERENCE GUIDE
PUBLICATION HSEPIS-RM020A-EN-E–September 2007
Contact Rockwell
Customer Support Telephone — 1.440.646.3434
Online Support — http://support.rockwellautomation.com
Copyright Notice
© 2007 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA.
This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc.
Any reproduction and/or distribution without prior written consent from Rockwell Automation Technologies, Inc. is strictly
prohibited. Please refer to the license agreement for details.
Trademark Notices
FactoryTalk, Rockwell Automation, Rockwell Software, the Rockwell Software logo are registered trademarks of Rockwell
Automation, Inc.
The following logos and products are trademarks of Rockwell Automation, Inc.:
FactoryTalk Historian Site Edition (SE), RSView, FactoryTalk View, RSView Studio, FactoryTalk View Studio, RSView
Machine Edition, RSView ME Station, RSLinx Enterprise, FactoryTalk Services Platform, and FactoryTalk Live Data.
The following logos and products are trademarks of OSIsoft, Inc.:
PI System, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK.
Other Trademarks
ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows, Windows ME,
Windows NT, Windows 2000, Windows Server 2003, and Windows XP are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States
and/or other countries.
ControlNet is a registered trademark of ControlNet International.
DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA).
Ethernet is a registered trademark of Digital Equipment Corporation, Intel, and Xerox Corporation.
OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.
Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.
All other trademarks are the property of their respective holders and are hereby acknowledged.
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
Warranty
This product is warranted in accordance with the product license. The product’s performance may be affected by system
configuration, the application being performed, operator control, maintenance, and other related factors. Rockwell Automation
is not responsible for these intervening factors. The instructions in this document do not cover all the details or variations in the
equipment, procedure, or process described, nor do they provide directions for meeting every possible contingency during
installation, operation, or maintenance. This product’s implementation may vary among users.
This document is current as of the time of release of the product; however, the accompanying software may have changed since
the release. Rockwell Automation, Inc. reserves the right to change any information contained in this document or the software
at anytime without prior notice. It is your responsibility to obtain the most current information available from Rockwell when
installing or using this product.
Version: 9.00.05
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. These documents
are included on the FactoryTalk Historian SE installation CD under Redist > Docs
Page iv
Title
Subject Matter
Introduction to PI
System Management
A guide to the PI Server for new users and administrators. It explains PI
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
and Upgrade Guide
A guide for installing, upgrading and removing PI Servers on Windows and
UNIX platforms, including cluster and silent installations.
PI Server System
Management Guide
An in-depth administration guide for the PI Server, including starting and
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
Guide
A comprehensive reference guide for the system administrator and
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 User
Guide
A guide to key add-on PI Server Applications: Performance Equations (PE),
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
User Guide
A systems administration guide, including installation, upgrade and
operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.
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
ƒ PI System Elements
ƒ PI Server Subsystems
ƒ Use the client tool, FactoryTalk Historian
ProcessBook, to verify that all data has been
recovered.
ƒ All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text
ƒ
ƒ
ƒ
ƒ
ƒ
ƒ The backup script is located in the \PI\adm directory.
ƒ Archive files can be either fixed or dynamic. The
archive receiving current data is called the Primary
Archive.
ƒ See Section 4.2, Create a New Primary Archive.
Bold Italic text
ƒ References to a publication
ƒ See the PI Server Reference Guide.
Bold text
ƒ System and Application
components:
ƒ Subsystems
ƒ Tools / Utilities
ƒ Processes / Scripts / Variables
ƒ Arguments / Switches / Options
ƒ Parameters / Attributes / Values
ƒ Properties / Methods / Events /
Functions
ƒ The Archive Subsystem, piarchss, manages data
archives. Piarchss must be restarted for changes to
take effect.
ƒ On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
pisrvsitestart.bat.
ƒ Three Point Database attributes affect compression:
CompDev, CompMin, and CompMax. These are
known as the compression specifications.
ƒ Procedures and Key Commands
ƒ On the Tools menu, click Advanced Options.
ƒ Press CTRL+ALT+DELETE to reboot
ƒ Interface components
ƒ Menus / Menu Items
ƒ Icons / Buttons / Tabs
ƒ Dialog box titles and options
ƒ Click Tools > Tag Search to open the Tag Search
tool.
ƒ Click the Advanced Search tab.
ƒ Use the search parameters PImean Value = 1.
Consolas monospace is used for:
To list current Snapshot information every 5 seconds,
use the piartool -ss command. For example:
Monospace
type:
"Consolas"
font
Files, Directories, Paths
Emphasis
New Terms
Fields
References to a chapter or section
ƒ Code examples
ƒ Commands to be typed on the
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 Underlined
Links to URL / Web sites, and email
addresses
PI Server Reference Guide
http://support.rockwellautomation.com
Page v
Preface - Using this Guide
Related Documentation
Rockwell Automation 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.
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...............................................................................................................11
Chapter 3.
PI Server Databases .................................................................................................21
Chapter 4.
PI Point Classes and Attributes...............................................................................43
Chapter 5.
PI Point Class Edit ....................................................................................................63
Chapter 6.
PI Point Type Edit......................................................................................................89
Chapter 7.
Exception Reporting and Compression Testing ...................................................95
Chapter 8.
Security ....................................................................................................................103
Chapter 9.
PI SQL Subsystem ..................................................................................................105
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.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
Interfaces Installed with the PI Server.............................................................................5
1.3.1
Interfaces to Other Data Sources...........................................................................5
1.4
PI Application Programming Interface (API)...................................................................6
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.
2.1
2.2
PI Data Flow...............................................................................................................11
Data Flow from Data Sources into the PI Archive........................................................11
2.1.1
The Snapshot .......................................................................................................13
2.1.2
The Archive Subsystem........................................................................................13
Data Retrieval from the Archive .....................................................................................15
2.2.1
2.3
The Archive Read Cache .....................................................................................15
PI Data Retrieval with Foreign Data Sources................................................................16
2.3.1
Point Configuration ...............................................................................................17
2.3.2
Retrieval of Snapshot Data...................................................................................18
2.3.3
Retrieval of Archive Data......................................................................................18
2.3.4
Archive Files .........................................................................................................19
PI Server Reference Guide
Page ix
Table of Contents
2.3.5
Exception Reporting .............................................................................................19
2.3.6
Compression ........................................................................................................20
2.3.7
Point Security .......................................................................................................20
Chapter 3.
PI Server Databases .................................................................................................21
3.1
Point Database.................................................................................................................21
3.2
Data Archive.....................................................................................................................21
3.2.1
Archive Size Considerations ................................................................................22
3.3
Snapshot ..........................................................................................................................22
3.4
Annotations......................................................................................................................23
3.4.1
3.5
3.6
Annotation Files....................................................................................................23
Digital State Table ...........................................................................................................25
3.5.1
System State Set for All Points ............................................................................25
3.5.2
Defining a Custom Digital State Set .....................................................................26
Timeout Database............................................................................................................27
3.6.1
Table of Configurable Timeout Database Parameters.........................................27
3.7
Firewall Database ............................................................................................................40
3.8
Proxy Database................................................................................................................40
3.9
Trust Database.................................................................................................................40
3.10 User Database..................................................................................................................40
3.11 Group Database...............................................................................................................41
3.12 Module Database .............................................................................................................41
3.13 Batch Database................................................................................................................41
3.14 List of Database Files......................................................................................................41
Chapter 4.
PI Point Classes and Attributes...............................................................................43
4.1
About Point Classes........................................................................................................43
4.2
Base Class Point Attributes ...........................................................................................44
4.2.1
Tag........................................................................................................................44
4.2.2
PtClassName........................................................................................................45
4.2.3
PointType..............................................................................................................45
4.2.4
NewTag ................................................................................................................47
4.2.5
Descriptor .............................................................................................................47
4.2.6
ExDesc .................................................................................................................47
4.2.7
TypicalValue .........................................................................................................47
4.2.8
DigitalSet ..............................................................................................................47
4.2.9
Zero ......................................................................................................................48
4.2.10 Span .....................................................................................................................48
Page x
Table of Contents
4.2.11 Impact of Changing Zero and Span .....................................................................48
4.2.12 EngUnits ...............................................................................................................49
4.2.13 PointSource ..........................................................................................................49
4.2.14 SourceTag ............................................................................................................50
4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent....................................................50
4.2.16 Scan Flag..............................................................................................................50
4.2.17 Compressing Flag ................................................................................................50
4.2.18 CompDev, CompMin, CompMax and CompDevPercent .....................................51
4.2.19 Archiving ...............................................................................................................52
4.2.20 Step ......................................................................................................................52
4.3
Classic Point Class Attributes .......................................................................................54
4.3.1
Instrument Tag .....................................................................................................54
4.3.2
Location1, Location2, Location3, Location4, and Location5 ................................54
4.3.3
SquareRoot ..........................................................................................................55
4.3.4
UserInt1, UserInt2, UserReal1 and UserReal2 ....................................................55
4.3.5
Filtercode ..............................................................................................................55
4.3.6
Totalcode ..............................................................................................................55
4.3.7
Srcptid...................................................................................................................55
4.3.8
Convers ................................................................................................................56
4.3.9
Ranges of ExcMax and CompMax.......................................................................56
4.4
COM Connector Point Attributes ...................................................................................56
4.5
Default Values for Point Attributes................................................................................57
4.6
System-Assigned Attributes ..........................................................................................62
4.6.1
Creator..................................................................................................................62
4.6.2
CreationDate ........................................................................................................62
4.6.3
Changer ................................................................................................................62
4.6.4
ChangeDate .........................................................................................................62
4.6.5
PointID ..................................................................................................................62
4.6.6
RecNo...................................................................................................................62
Chapter 5.
PI Point Class Edit ....................................................................................................63
5.1
Introduction......................................................................................................................63
5.2
Overview...........................................................................................................................64
5.3
Attribute Sets Database Edit ..........................................................................................66
5.3.1
Attribute Set Creation ...........................................................................................66
5.3.2
Attribute Set Deletion............................................................................................69
5.3.3
Attribute Set Edit...................................................................................................70
PI Server Reference Guide
Page xi
Table of Contents
5.4
5.5
Point Classes Database Edit ..........................................................................................76
5.4.1
Point Class Creation.............................................................................................76
5.4.2
Point Class Deletion .............................................................................................76
5.4.3
Point Class Edit ....................................................................................................77
Editing a Point’s Point Class Attribute..........................................................................82
5.5.1
5.6
Point Database Audit ......................................................................................................83
5.6.1
5.7
Conversion of CC Class to and from a Native PI Class .......................................83
Audit Records .......................................................................................................84
Thread-safety ...................................................................................................................86
Chapter 6.
PI Point Type Edit......................................................................................................89
6.1
Introduction......................................................................................................................89
6.2
Error handling ..................................................................................................................94
Chapter 7.
7.1
7.2
Exception Reporting and Compression Testing ...................................................95
Exception Reporting .......................................................................................................95
7.1.1
ExcDev and ExcDevPercent ................................................................................97
7.1.2
ExcMin ..................................................................................................................97
7.1.3
ExcMax .................................................................................................................97
7.1.4
Turning Off Exception Reporting ..........................................................................98
Compression Testing......................................................................................................98
7.2.1
Chapter 8.
Step Flag ............................................................................................................101
Security ....................................................................................................................103
8.1
User Name and Password ............................................................................................103
8.2
Point Security.................................................................................................................103
8.3
Database Security .........................................................................................................103
8.4
Trust Access ..................................................................................................................104
Chapter 9.
9.1
9.2
9.3
Page xii
PI SQL Subsystem ..................................................................................................105
Architecture....................................................................................................................105
9.1.1
Statement Handles .............................................................................................105
9.1.2
Concurrency .......................................................................................................106
Differences between PI 2.x and PI 3.x .........................................................................106
9.2.1
The PIPoint Table...............................................................................................106
9.2.2
Using Performance Equation Subsystem Built-In Functions..............................107
Configuration .................................................................................................................108
9.3.1
Hierarchy of PI SQL Subsystem Settings...........................................................108
9.3.2
Initialization File Settings ....................................................................................109
Table of Contents
9.3.3
9.4
Command Line Arguments.................................................................................109
Troubleshooting ............................................................................................................112
9.4.1
Using the ipisql Utility .........................................................................................112
9.4.2
Generating a Trace File......................................................................................114
9.4.3
Output from the TRACE Option..........................................................................114
9.4.4
Clearing Expensive Query Problems .................................................................116
9.4.5
Performance Counters .......................................................................................117
9.4.6
Technical Support and Problem Reports ...........................................................117
Appendix A: PI Time Format.........................................................................................................119
9.1
Relative Time .................................................................................................................119
9.2
Absolute Time ................................................................................................................119
9.3
9.2.1
Specifying Standard or Daylight Savings Time ..................................................120
9.2.2
Examples ............................................................................................................121
Combined Formats........................................................................................................122
9.3.1
Examples ............................................................................................................122
Appendix B: PI Time Conversions ...............................................................................................123
9.1
Timestamps on PI 2 Systems .......................................................................................123
9.2
Daylight Savings Time Changes on PI 2 Systems .....................................................123
9.3
Timestamps across Time Zones on PI 2 Servers.......................................................124
9.4
Timestamps on PI Server Systems..............................................................................125
9.5
Translating PI 2 Timestamps to PI Server Systems...................................................125
9.6
Translating PI Server Timestamps to PI 2 Based Timestamps.................................127
9.7
How PI Client Applications Handle DST Changes .....................................................127
9.8
PI in the 21st Century....................................................................................................128
Appendix C: PI API and Toolkit Usage ........................................................................................131
9.1
Overview.........................................................................................................................131
9.1.1
PI API..................................................................................................................131
9.2
PI API Usage on PI Server ............................................................................................131
9.3
PI Toolkit Usage on PI Server.......................................................................................138
Appendix D: Predefined Attribute Sets and Point Classes .......................................................139
9.1
Predefined Attribute Sets .............................................................................................139
9.1.1
alarmparam ........................................................................................................139
9.1.2
base ....................................................................................................................140
9.1.3
classic .................................................................................................................140
9.1.4
sqcalm_parameters ............................................................................................141
PI Server Reference Guide
Page xiii
Table of Contents
9.1.5
9.2
totals ...................................................................................................................142
Predefined Point Classes .............................................................................................142
Technical Support and Resources...............................................................................................143
Index of Topics...............................................................................................................................145
Page xiv
TABLE OF TABLES
Table 2–1. COM Connector Point Attributes............................................................................17
Table 3–1. Typical Digital States..............................................................................................25
Table 3–2. ConfigurableTimeout Parameters ..........................................................................28
Table 4–1. Point Types ............................................................................................................45
Table 4–2. Point Database Default Table ................................................................................58
Table 9–1. Default Attributes in BASE Point Class................................................................106
Table 9–2. Command Line Arguments ..................................................................................109
Table 9–3. Command Line Option Tokens ............................................................................110
Table 9–4. Command Line Arguments Supported by ipisql ..................................................113
Table B-1
PI 2 Standard Time to Daylight Savings Time ...................................................124
Table B-2
PI 2 Daylight Savings Time to Standard Time ...................................................124
Table B-3
PI2 Timestamps across Time Zones .................................................................125
Table B-4
PI Server Standard Time to Daylight Savings Time ..........................................126
Table B-5
PI Server Daylight Savings Time to Standard Time ..........................................126
Table B-6
PI Examples of Timestamp conversions for California-based systems .............127
PI Server Reference Guide
Page xv
TABLE OF FIGURES
Figure 2-1. Processing of New Events.....................................................................................14
Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector ........18
Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector ............19
Figure 5-1. Formation of a point class......................................................................................63
Figure 7-1. Swinging Door Compression ...............................................................................100
Figure 9-1. Windows Control Panel Services Applet .............................................................111
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
comes out of the Snapshot
subsystem. Data consists of multiple
timestamped measurements for each
data point. This includes values such
as on/offs, pressures, flows,
temperatures, setpoints, etc.
Requires the PI
Snapshot Subsystem.
Base
pibasess.exe
Maintains the Point Database, Digital
State Table and configuration
databases for user and group
security. It also hosts the PI Module
Database.
Requires the PI Update
Manager
License
Manager
pilicmgr.exe
Maintains licensing information for
the PI Server and all connected
applications
Message
pimsgss.exe
Records status and error messages
for the PI Server in a control log file.
Network
Manager
pinetmgr.exe
Manages communication between PI
Server subsystems, client
applications and interfaces. Also
validates clients at time of
connection. Clients may be standard
products such as FactoryTalk
Historian ProcessBook, or they may
be user-written PI API or PI SDK
programs.
Snapshot
pisnapss.exe
Stores the most recent event for each
point. Applies compression, sends
data to the Event Queue, and serves
Snapshot events to the client
applications.
Requires the PI Update
Manager.
Update
Manager
piupdmgr.exe
Sends notifications of changes in
values or point attributes to any
interface or client application that is
signed up for notification.
These services are
essential for proper
operation of a PI
Server; it is required by
most of the PI
Subsystems and most
client applications.
Messages are routed to
the Windows Event log
or UNIX standard
output if this subsystem
is not available.
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
Equations*
pipeschd.exe
Performs PI Performance Equation calculations for PI calculated
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, Rockwell Automation 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.
Rockwell Automation 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
Rockwell Automation 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 11
‰ Data Retrieval from the Archive begins on page 15
‰ PI Data Retrieval with Foreign Data Sources begins on page 16
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 FactoryTalk Historian
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
New Event
1
2
3
4
5
Queue(s)
Compress
file(s)
n
Cache
RecNo
0
m
0
n
Primary
Archive
Other
On-Line
Archives
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 FactoryTalk
Historian 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 21 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.
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 43.
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
•
•
3.5
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.
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. Rockwell Automation 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
(Default)
Read
Description
All
<subsysname>_Bac
kupTimeout
30 – 86400
(1800)
Periodically
when in
system
backup
mode
This is the maximum number of seconds
to remain in system backup mode. This
timeout parameter only pertains to the
piartool –systembackup command,
which is used to take the audit databases
offline. The parameter has no effect for
VSS backups or non-VSS backups that
are started with the piartool –backup
command.
All
<subsysname>_Thr
eadCount
1–(4 threads)
startup only
Size of the subsystem message thread
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
(Default)
Read
Description
All
<subsysname>_Ma
xThreadsPerClientQ
uery
depend on
value of
<subsysnam
e>_ThreadC
ount
(0)
startup only
Limits the number of concurrent, identical
queries from a client. The possible value
range depends on the number of RPC
threads for a subsystem. For example, if
the number of threads is 8, then the
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
(128 bytes)
startup only
Threshold for CRT library small block
heap memory allocation
All
<subsysname>_Writ
eModTimesToFileP
eriod
10 – 900
(60 sec)
Startup only
PI internally keeps track of the last
modified date of most of the files that it
needs to back up. The last modified times
for each subsystem are updated every
WriteModTimesToFilePeriod. The
smaller the period, the more accurate the
last modified time will be.
A complete list of backed up files along
with their last modified dates can be listed
with the piartool –backup –identify verbose command. For 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
eFileRoot
(path +
name prefix)
before every
shift
Automatic Archive file creation on shifts. If
present, this parameter defines the path
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
(Default)
Read
Description
Archive
Archive_BackupCut
offDate
01-Jan-70 –
NA
(01-Jan-70)
Before every
backup
Archives that contain data more recent
than the Archive_BackupCutoffDate will
be backed up. For example, if “*-30d” is
specified, then at least 30 days of data will
be backed up.
Archive
Archive_BackupLea
dtime
5 – 86400
(1800 sec)
On backup
startup
Number of seconds before the predicted
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
(1800 sec)
Once a
minute
This timeout parameter is now obsolete.
Archive
Archive_CacheClea
nCycle
1 – Flush
Cycle
(10 sec)
startup only
Frequency at which read-only cache
cleanup operations are performed. Setting
this limit too low may affect the
performance of the Archive Subsystem.
Archive
Archive_CacheHigh
PctLimit
100 – 200
(110
percent)
startup only
High cache cleanup threshold, in
percentage of the
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
PctLimit
20 – 100
(80%)
startup only
Low cache cleanup threshold, in
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
rdPool
2048 –
1048576
(4 x ptcount
records)
startup +
end of each
flush cycle
Maximum number of archive cache
records for read access queries. The
actual size of the read-only cache pool
may lower due to low physical memory
resources.
Archive
Archive_CacheReco
rdsPerPoint
4 – cache
epool / 2
(512
records)
startup +
end of each
flush cycle
Maximum number of archive cache
records per point. In the default
configuration, up to 512 records may be
allocated to a single point.
Archive
Archive_CacheTrim
Percent
1 – 75
(40 %)
startup only
Percentage to trim the read and write
cache when low physical memory
resources are detected.
PI Server Reference Guide
Page 27
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max
(Default)
Read
Description
Archive
Archive_DataCoerci
onPolicy
0–3
(0)
startup only
Error handling policy of archive event
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 89.
Archive
Archive_EventQueu
eThreadCount
1 – 255
(5 threads)
startup only
This parameter is now obsolete in version
3.4.370, a single Event Queue thread now
exists (see Archive_FlushThreadCount
below).
Archive
Archive_FlushThrea
dCount
1 – 255
(4 threads)
startup only
Number of Flush threads responsible for
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
eSize
16 – 8192
(256 flush
tasks)
startup only
Size of the Flush Queue between the
EVQ (Event Queue) thread and the Flush
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
aceMB
(256 MB)
once a
minute with
a dynamic
primary
archive + on
shifts when
Archive_Au
toArchiveFi
leRoot is set
Minimum amount of free disk space to
leave on Archive file volumes. A dynamic
primary archive will stop growing if this
limit is reached and a shift will be
triggered.
Archive
Archive_MaxAnnota
tions
128 –
134217728
(65,535
annotations)
startup only
Maximum number of event annotations
per Archive file (annotations are stored in
the parallel file with the .ann extension).
Archive
Archive_MaxIdleCle
anCycles
1 – 60
(2 flush
cycles)
startup only
Maximum idle time of archive cache
records before being discarded. This
number is expressed in number of flush
cycles
(Archive_SecondsBetweenFlush).
Archive
Archive_MaxWriteC
achePerPoint
0 – 2,048
(256 events)
startup +
end of each
flush cycle
Maximum number of write cache events
per point. Events of a given point will be
flushed to disk when this limit is reached.
Page 28
3.6 - Timeout Database
Subsystem
Name
Min – Max
(Default)
Read
Description
Archive
Archive_MinCacheR
ecordPool
1,024 –
102,400
(2,048
records)
startup only
Minimum size of the record pool when
doing cache trimming due to low-memory
conditions.
Archive
Archive_MinMemAv
ail
0 – 1,024
(10 MB)
startup only
Minimum amount of free physical 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_MinPercentMemAvail
percentage.
Archive
Archive_MinPercent
MemAvail
0 – 50
(0%)
startup only
Minimum percentage of free physical
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
chePerPoint
1 – 1,024
(8 events)
startup only
Minimum number of write cache events
per points when doing cache trimming due
to low-memory conditions.
Archive
Archive_PointLockL
ogging
0 – timeout
(5,000 ms)
startup only
Archive lock delay reporting option. By
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
meout
1000 –
270,000
(120,000
ms)
startup only
Maximum time RPC (query) threads can
wait accessing archive points. Default is 2
minutes (120 seconds).
Archive
Archive_SecondsBe
tweenFlush
1 – 86,400
(900 sec)
startup only
Archive cache flush cycle or maximum
time between consecutive disk flushes for
a given point.
Archive
Archive_ShiftFreeTi
me
0 – 86,400
(1,800 sec)
startup only
Number of seconds to substract from the
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
(Default)
Read
Description
Archive
Archive_ShiftRatio
4 – 2048
(512 ratio)
startup only
Ratio of total records to free records at
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
Count
256 – 16384
(2048
records)
before every
shift
Number of records to process in one
chuck during Archive file initializations.
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
imeout
5000 –
900,000
(270,000
ms)
startup only
Maximum time Flush (writer) threads can
wait accessing archive points. Default is
4.5 minutes (270 seconds).
Archive
ArcInsertRecOnOO
O
0–1
(1 boolean)
startup only
Break the chain and insert new records
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
(15000
events)
startup only
Maximum number of compressed events
that can be retrieved by a single query.
This number does not affect interpolated
event retrieval or archive summary calls.
Archive
BreakCrossRefOnD
elete
0–1
(1 boolean)
startup only
Break reference between UnitBatch and
PIBatch on deletion of UnitBatch.
Archive
Cache_FreelistSize
1000 –
100000
(10000
records)
startup only
Size of the list of reusable cache records
that were discarded from the read-only
record pool. This parameter should only
be changed upon recommendation from a
technical support engineer.
Archive
MarkArchiveGaps
0–1
(1 boolean)
startup only
Return special "Arc Off-line" events when
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
(Default)
Read
Description
Archive
piarchss
1–
10000000
(100000
sec)
startup only
Subsystem wait time after every main loop
iteration.
Archive
BatchDb_MaxSearc
hRecords
-1 –
1,000,000
(-1)
startup only
Maximum size (number of records) of
batch queries returned by the Archive
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
okBackDays
1 – 365
(31 days)
startup only
Controls the batch search look back
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
offDate
01-Jan-70 –
NA
(01-Jan-70)
Before every
backup
If the cutoff date is not explicitly specified
in arguments to the pibackup.bat backup
script, then this timeout parameter defines
the default cutoff date. Archives that
contain any data between
Backup_ArchiveCutoffDate and current
time will be backed up. For example, if “*30d” is specified, then at least 30 days of
data will be backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict the
number of archives for backup. Whichever
timeout parameter is most restrictive takes
precedence.
Backup
Backup_NumArchiv
es
1 – 1000000
(3)
Before every
backup
If the number of archives to be backed up
is not explicitly specified in arguments to
the pibackup.bat backup script, then this
timeout parameter defines the default
number of archives to be backed up.
Backup
Backup_TraceLevel
0 – 1000
(0)
Startup only
This is the default backup trace level.
Non-zero backup trace levels cause
debug messages to be written to the PI
Message Log. The default trace level can
be overridden while the PI Backup
Subsystem is running with the piartool –
backup –trace <level> command.
PI Server Reference Guide
Page 31
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max
(Default)
Read
Description
Base
BatchDbEditLogging
0–1
(0 boolean)
startup only
Logging of Batch Database edits and
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
riodSec
30 – 3600
(300 sec)
startup only
Frequency at which checks for idle
modules are performed. Setting this limit
too low may affect the performance of the
Base Subsystem.
Base
ModuleDb_MaxIdle
CleanSec
0 – 604800
(3600 sec)
startup only
Maximum idle time of MDb modules
before being unloaded from memory.
Checks are performed every
ModuleDb_CleanPeriodSec seconds.
Base
pibasess
1–
10000000
(10000
µsec)
startup only
Subsystem wait time after every main loop
iteration.
Base
PointDb_CleanPerio
dSec
30 – 3600
(300 sec)
startup only
Frequency at which checks for idle points
are performed. Setting this limit too low
may affect the performance of the Base
Subsystem.
Base
PointDb_MaxIdleCle
anSec
0 – 604800
(3600 sec)
startup only
Maximum idle time of PI Points before
being unloaded from memory. Checks are
performed every
PointDb_CleanPeriodSec seconds.
Base
PointEditLogging
0–1
(0 boolean)
startup only
Logging of point edits and deletions to the
message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Base
RecreateServerTrus
t
0–1
(1 boolean)
startup only
Recreate missing trust entries for local
machine access. These trust settings are
used by SDK or API applications or
interfaces running on the server node.
Base
WindowsAuthenticat
ion
0–1
(1 boolean)
startup only
Perform windows user authentication
against a domain controller. This feature
should only be disabled upon
recommendation from a technical support
engineer.
Base,
Snapshot,
Archive
EnableAudit
00xFFFFFFF
F
(0 bitmask)
startup only
Auditing mask, -1 (or 0xFFFFFFFF)
enable the audit of all databases. See
Auditing the PI Server for details on
acceptable values.
Page 32
3.6 - Timeout Database
Subsystem
Name
Min – Max
(Default)
Read
Description
Batch
pibatch
1–
10000000
(12000
µsec)
startup only
Subsystem wait time after every main loop
iteration.
Message
pimsgss
1–
10000000
(12000
µsec)
startup only
Subsystem wait time after every main loop
iteration.
NetManager
backlog
5 – 1000
(5)
startup only
Maximum number of pending TCP/IP
connections.
NetManager
connectionlocktimeo
ut
1 – 1000
(90 sec)
startup only
Amount of time to wait for a connection
locked by another thread.
NetManager
connectionwait
1000 –
1000000
(30000
msec)
startup only
Amount of time for a new TCP/IP
connection to become writable.
NetManager
DefaultUserAccess
0–1
(1 boolean)
startup only
Enable guest (or "world") access to the PI
Server.
NetManager
HealthCheckInterval
60 –
1000000
(1800 sec)
startup only
Frequency at which health checks are
performed between NetManager and the
PI Subsystems. NetManager will close
connections if subsystems don't respond
to health checks.
NetManager
keepalive
-1 – 1
(-1 sec)
startup only
TCP/IP keepalive option. A value of -1 is
the system default, 0 indicates disabled.
NetManager
linger_on
0–1
(0 boolean)
startup only
Socket closure behavior (see
linger_time).
NetManager
linger_time
0 – NA
(0 sec)
startup only
Time in seconds to linger on socket
closure, if linger_on is set
NetManager
MaxConnIdleTime
300 – NA
(see
description)
NetManager
MaxMessageLength
10 – 512
(256 MB)
startup only
Maximum size of messages handled by
NetManager, PI3 Subsystems and PI SDK
applications.
NetManager
maxzerobytereads
0 – 1000
(100 bytes)
startup only
Assume a connection close when
receiving a series of zero-byte messages.
PI Server Reference Guide
By default, NetManager will not close
connections regardless of idle time.
NetManager can be configured to close
inactive connections by setting
MaxConnIdleTime to a value greater than
or equal to 300 seconds. Entries less than
300 seconds or no entry results in the
default behavior of no enforcement of
disconnecting idle connections.
Page 33
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max
(Default)
Read
Description
NetManager
minbufsize
1 – 1000
(8 KB)
startup only
TCP/IP send and receive buffers
NetManager
pinetmgr
1–
10000000
(10000
µsec)
startup only
Subsystem wait time after every main loop
iteration.
NetManager
ReadCompletionTim
eout
120 0xFFFFFFF
F
(300 sec)
startup only
Amount of time to block for read
completion.
NetManager
readretry
1–
10000000
(250)
startup only
Maximum retry attempts on read stream
errors
NetManager
readtimeout
1–
50000000
(50000
µsec)
startup only
Read timeout on network I/Os
NetManager
reversenamelookupf
lag
0–1
(1)
startup only
Translate IP addresses to IP host names
on new connections.
NetManager
ThreadStackSize
0 – 10
(0 MB)
startup only
Stack of Net Manager worker thread. A
value of 0 means the same as
NetManager's main thread.
NetManager
writeretry
1–
10000000
(250)
startup only
Maximum retry attempts on write stream
errors
NetManager
writetimeout
1 – 5000000
(50000µsec)
startup only
Write timeout on network I/Os
PESchedule
r
pipeschd
1–
10000000
(50000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Snapshot
EditDays
0(0)
startup only
Number of past days where events can be
modified in the Snapshot or Archive
databases. A value of zero means no time
check is done.
Snapshot
pisnapss
1–
10000000
(1000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Snapshot
SnapFlushCycle
60 – 3600
(900)
startup only
Snapshot table flush cycle or maximum
time between consecutive flushes for a
given point.
Page 34
3.6 - Timeout Database
Subsystem
Name
Min – Max
(Default)
Read
Description
Snapshot
Snapshot_EventQu
euePageSize
64 – 8192
(1024 KB)
startup only
Size of the memory pages from the
memory mapped Event Queue. This
number must be a multiple of 64.
Snapshot
Snapshot_EventQu
euePath
(path)
startup only
Path where the memory-mapped queues
are created (default is PI\dat). The primary
queue name is always pimapevq.dat and
overflow queues are pimq0000.dat,
pimq0001.dat ... pimqFFFF.dat.
Snapshot
Snapshot_EventQu
eueSize
8 – 131072
(64 MB)
startup only
Size of the primary and overflow Event
Queues on disk. This parameter should
be adjusted according to archive event
rate to avoid the creation of overflow
queues.
Snapshot
Snapshot_LowDisk
SpaceMB
(256 MB)
when
overflow
Event
Queues are
created
Minimum amount of free disk space to
leave when creating overflow Event
Queues (pimqXXXX.dat).
Snapshot,
Archive
ArchiveEditLogging
0–1
(0)
startup only
Logging of event edits and deletions to the
message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Snapshot,
Archive
Snapshot_EventQu
eueFlushPeriod
1 – 3600000
(30000
msec)
startup only
Frequency at which the memory-mapped
queue is flushed to disk by the Snapshot
and Archive Subsystems.
SQL
pisqlss
1–
10000000
(12000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Totalizer
pitotal
1–
10000000
(12000µsec)
startup only
Subsystem wait time after every main loop
iteration.
UpdateMan
ager
MaxUpdateQueue
(4095)
startup only
Maximum number of events per consumer
held in the Update Manager.
UpdateMan
ager
PIUPD_MaxConsTi
meout
0 – 7200
(0 sec)
startup only
Maximum value of client-supplied cleanup
time for inactive consumer signups.
UpdateMan
ager
PIUPD_MinConsTi
meout
0 – 7200
(600 sec)
startup only
Minimum value of client-supplied cleanup
time for inactive consumer signups.
UpdateMan
ager
PIUPD_TimeoutKill
Cons
0–1
(0)
startup only
Remove timed out consumers in addition
to removing all pending events.
UpdateMan
ager
piupdmgr
1–
10000000
(12000
µsec)
startup only
Subsystem wait time after every main loop
iteration.
PI Server Reference Guide
Page 35
Chapter 3 - PI Server Databases
Subsystem
Name
Min – Max
(Default)
Read
Description
UpdateMan
ager
TotalUpdateQueue
(100000
events)
startup only
Maximum number of events in Update
Manager for all consumers.
Utilities
CheckUtilityLogin
0–1
(0)
startup only
Force an interactive login from console
utilities (piconfig, pisetpass).
Utilities
piartool
1–
10000000
(1000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Utilities
piconfig
1 – 1000000
(1000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Utilities
pigetmsg
1 – 1000000
(1000µsec)
startup only
Subsystem wait time after every main loop
iteration.
Utilities
pilistupd
1 – 1000000
(1000µsec)
startup only
Subsystem wait time after every main loop
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
Page 36
3.7 - Firewall Database
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.
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.
PI Server Reference Guide
Page 37
Chapter 3 - PI Server Databases
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
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.
Page 38
3.14 - List of Database Files
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
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
PI Server Reference Guide
Page 39
Chapter 3 - PI Server Databases
PIbasess Databases
PIShutev Databases
shutdown.dat
Shutdown event configuration file
Pisnapss Databases
piarcmem.dat
Snapshot database
pimapevq.dat
Event queue
pilastsnap.dat
Time of newest event
PISqlss Databases
Page 40
pisql.ini
Site specific initialization file
Pisql.res
Parsing resource
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 62.
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 tagnaming 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 casesensitive. 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 FactoryTalk Historian DataLink spreadsheets, might also have to be updated.
FactoryTalk Historian 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
Rockwell Automation 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 FactoryTalk Historian
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 FactoryTalk Historian ProcessBook trend with a
vertical scale of database.
This attribute is not used for non numeric points.
PI Server Reference Guide
Page 45
Chapter 4 - PI Point Classes and Attributes
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
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.
Page 46
4.2 - Base Class Point Attributes
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
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.
PI Server Reference Guide
Page 47
Chapter 4 - PI Point Classes and Attributes
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
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.
Page 48
4.2 - Base Class Point Attributes
For example:
‰ At 12:00:00, the value 101.0 is archived,
‰ At 12:01:00, the value 102.0 is archived,
A request for the value at 12:00:30 would return 101.0.
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
PI Server Reference Guide
Page 49
Chapter 4 - PI Point Classes and Attributes
DisplayDigits
Format
2
23.45
1
23.5
0
23.
-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
Page 50
4.3 - Classic Point Class Attributes
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.
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. Rockwell Automation recommends not altering incoming data by leaving this code at its
default value of 0. The other options are:
4.3.6
Code
Time Constant (Sec.)
1
10
2
60
3
120
4
600
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 16bit integers, which meant that the maximum value of each was 65,535 seconds. This will
PI Server Reference Guide
Page 51
Chapter 4 - PI Point Classes and Attributes
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.
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.
Page 52
4.5 - Default Values for Point Attributes
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.
Table 4–2. Point Database Default Table
Point
Class
Field Name
Default
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
PI Server Reference Guide
Page 53
Chapter 4 - PI Point Classes and Attributes
Page 54
Point
Class
Field Name
Default
Value
Limits
Base
ExcMin
0 (sec)
0 ≤ x ≤ 65535
Base
ExDesc
blank
Classic
Filtercode
0
Classic
InstrumentTag
blank
Classic
Location1
0
Classic
Location2
0
Classic
Location3
0
Classic
Location4
0
Classic
Location5
0
Base
NEWTag
Base
PointID
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
Base
Scan
On
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
System-assigned
System-assigned
On, Off, 1, or 0
This must be specified when the
point is created.
4.6 - System-Assigned Attributes
Point
Class
Field Name
Default
Value
Classic
Totalcode
0
Base
TypicalValue
50
Classic
UserInt1
0
Classic
UserInt2
0
Classic
UserReal1
0
Classic
UserReal2
0
Base
Zero
0
Other
Limits
Zero ≤ x ≤ (zero + span)
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.
PI Server Reference Guide
Page 55
Chapter 4 - PI Point Classes and Attributes
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.
Page 56
Chapter 5.
5.1
PI POINT CLASS EDIT
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 PISDK, 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
Page 62
5.3 - Attribute Sets Database Edit
@istru attrib,type,default
@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.
PI Server Reference Guide
Page 63
Chapter 5 - PI Point Class Edit
PIartool –standalone 1
Then launch piconfig in command window, and type the following.
@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 defaultonly 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
Page 64
5.3 - Attribute Sets Database Edit
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.
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
Excmin
uint16
Excmax
uint16 or uint32
Excdev
float32
shutdown
byte
Archiving
byte
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
Compressing
byte
Step
byte
Compmin
uint16
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 systemassigned 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
Page 66
5.3 - Attribute Sets Database Edit
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
@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.
PI Server Reference Guide
Page 67
Chapter 5 - PI Point Class Edit
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
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.
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
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
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 Rockwell
Automation 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.
PI Server Reference Guide
Page 69
Chapter 5 - PI Point Class Edit
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.
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.
Page 70
5.4 - Point Classes Database Edit
In-use point classes may not be deleted.
Example of Creating a Point Class
In command window
PIartool –standalone 1
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.
PI Server Reference Guide
Page 71
Chapter 5 - PI Point Class Edit
Example of Editing a Point Class
If a point class list in piconfig shows the following
* (Ls - ) PIconfig> @table
* (LS - PIPTCLS) PIconfig>
* (Ls - PIPTCLS) PIconfig>
* (Ls - PIPTCLS) PIconfig>
* (Ls - PIPTCLS) PIconfig>
* (Ls - PIPTCLS) PIconfig>
MyPtClass
base,classic
*----------
piptcls
@mode list
@ostru class
@ostru set,...
@select class=MyPtClass
@ends
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
Page 72
5.4 - Point Classes Database 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
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:
PI Server Reference Guide
Page 73
Chapter 5 - PI Point Class Edit
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
-
filtercode Int16 D: 0 C:
instrumenttag String D: C:
location1 Int32 D: 0 C:
location2 Int32 D: 0 C:
location3 Int32 D: 0 C:
location4 Int32 D: 0 C:
location5 Int32 D: 0 C:
myattribute1 String D: my default string C:
myattribute2 Int32 D: 22 C:
PointID Int32 D: 0 C:
pointsource String D: Lab C:
pointtype String D: Float32 C:
PtAccess String D: o:rw g:r w:r C:
PtClassName String D: MyPtClass C:
PtGroup String D: piadmin C:
PtOwner String D: piadmin C:
Recno Int32 D: 1 C:
scan BYTE D: 1 C:
shutdown BYTE D: 1 C:
SourceTag String D: C:
span Float32 D: 100. C:
squareroot Int16 D: 0 C:
srcptid Int32 D: 0 C:
step BYTE D: 0 C:
totalcode Int16 D: 0 C:
typicalvalue Float32 D: 50. C:
userint1 Int32 D: 0 C:
userint2 Int32 D: 0 C:
userreal1 Float32 D: 0. C:
userreal2 Float32 D: 0. C:
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.
Page 74
5.4 - Point Classes Database Edit
‰ 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.
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
PI Server Reference Guide
Page 75
Chapter 5 - PI Point Class Edit
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.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
5 This scenario is unlikely, but if it ever happens, it can be rectified by editing the class.
Page 76
5.6 - Point Database Audit
@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.
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.
6 Starts from 0.
PI Server Reference Guide
Page 77
Chapter 5 - PI Point Class Edit
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 defaultonly 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.
‰ 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
Page 78
Field
Description
PI UserName
User who made change
Action Time
Time and Date of change
PI Database
PIPointAttributeSets
Audit Action
Add, Remove, Edit
5.6 - Point Database Audit
Audit Record Definition
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.
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
PI Server Reference Guide
Page 79
Chapter 5 - PI Point Class Edit
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
Change Record Definition
5.7
Property
Before
After
New_attrib_name
NULL
Default
Deleted_attrib_name
Old value
NULL
Edited_attrib_name
Old value
New value
Thread-safety
Attribute set and point class edits rely on the locking mechanism at 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
Page 80
5.7 - Thread-safety
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.
PI Server Reference Guide
Page 81
Chapter 6.
6.1
PI POINT TYPE EDIT
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.
To illustrate, suppose a point named int16_typedit had the following archived values and was
of type int16.
PI Server Reference Guide
Page 83
Chapter 6 - PI Point Type Edit
6-Oct-2005
6-Oct-2005
6-Oct-2005
6-Oct-2005
13:51:53,27
14:21:54,32767
14:44:56,4
14:51:51,Pt Created
Then it was edited to type int32, and three new values were added.
6-Oct-2005 14:52:01,-10
6-Oct-2005 14:52:03,2147483647
6-Oct-2005 14:52:05,-16
The last value -16 is still in the Snapshot. 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
7 There are events in this example before Pt Created event because data were back-filled to create the example.
Page 84
6.1 - Introduction
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
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
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 85
Chapter 6 - PI Point Type Edit
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
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.
Page 86
6.1 - Introduction
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.
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
int16
int32
float16
float32
float64
digital
string
blob
timestamp
ok
ok5
ok
ok
ok
ok
N/A
N/A
ok5
ok
ok
ok3
ok
N/A
ok
ok
ok
ok3
ok
N/A
N/A
ok
ok3
ok
N/A
ok
ok3
ok
N/A
ok
ok
N/A
N/A
N/A
ok
int32
ok1
float16
ok1
ok2
float32
ok1
ok2
ok5
float64
ok1
ok2
ok5
ok
digital
ok
ok
ok
ok
ok
string
ok
ok
ok
ok
ok
ok4
blob
N/A
N/A
N/A
N/A
N/A
N/A
N/A
timestamp
N/A
ok
ok
ok
ok
N/A
ok
N/A
N/A
1.
Assuming values in the range of 0 to 32767
2.
Assuming values in the range of -2,147,450,880 to 2,147,483,647
3.
Assuming positive, integer values (lower than number of digital states)
4.
Assuming exact match (case insensitive) with a state string
5.
Assuming the range of the source is compatible with the range of the target
PI Server Reference Guide
Page 87
Chapter 6 - PI Point Type Edit
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)
If coercion fails during off-line archive processing, values will be replaced as dictated by the
above policy.
Page 88
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. Rockwell Automation 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 89
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 90
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 91
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 92
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 93
Chapter 7 - Exception Reporting and Compression Testing
This value will be archived.
Eng
Unit
Value
A compression deviation blanket
drawn to this point would not
include all points since the most
recently archived value, so the
previous value would be
archived.
Most recently
archived value
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 94
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 95
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 97
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 98
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.
Rockwell Automation’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 Rockwell
Automation’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 99
0 - Table of Figures
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
Page 100
PIPoint Column
Default value
Convers
0.0
Filtercode
0
location1, location2,
location3, location4,
location5
0
PointID
Same as base class attribute recno
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).
9.2.2
PI SQL query
Returns PIPoint “base” class attribute…
Select pointid from PIPoint…
Recno
Select pointnumber from PIPoint…
Pointid
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 101
0 - Table of Figures
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 102
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 103
0 - Table of Figures
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 104
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 105
0 - Table of Figures
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 109.
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 106
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 commaseparated 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 casesensitive. For a list of supported options, see the table in the "Configuration"
section on page 108.
-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 107
0 - Table of Figures
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 108
9.4 - Troubleshooting
information generated should be forwarded to Rockwell Automation in the event of a query
processing problem.
In general, the first argument of each RPC is the handle ID. The only exception is the
newstatement function, which is the routine that generates the handle ID. In this case, the
returned handle ID is the second argument.
Function Summary Format
The LOG option generates output that looks like this:
FunctionName(arg1, arg2,…) [ErrorCode]
During query execution, progress messages are written to the log file. Each progress message
is of the form:
(HandleId): Calls: n PctDone: n Etime: n Limit: n
The items reported are:
‰ Number of calls to get PI data from other subsystems,
‰ Percent complete, based on an initial estimate,
‰ Elapsed time since the start of execution, in seconds,
‰ Timeout (Limit) in seconds. If this number is 0, no timeout limit has been set.
For example:
newstatement(8,21) [0]
clear(21,1) [0]
clear(21,0) [0]
Prepare[21]>[0][0.431s] select * from picomp
where tag = "sinusoid" and time > "y"
execute(21,&params) begins...
callback(21): Calls: 1 PctDone: 0 Etime: 1 Limit: 0
fetch(21,*results) [0]
clear(21,1) [0]
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 109
0 - Table of Figures
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 110
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 Rockwell Automation
Technical Support.
PI Server Reference Guide
Page 111
APPENDIX A: PI TIME FORMAT
Many PI System utilities prompt for a date and time. The PI time formats are:
‰ Relative
‰ Absolute
‰ Combined
9.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
9.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 113
0 - Appendix A: PI Time Format
9.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 114
9.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.
9.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
PI Server Reference Guide
00:00:00 on the 2nd of the current month
Page 115
0 - 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.
9.3
8:30.01
Ambiguous, 8 could be minutes or hours
:8:30.01
Ambiguous, 8 could be minutes or hours
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.
9.3.1
Examples
Page 116
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
9.1 - Timestamps on PI 2 Systems
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
9.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.
9.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
Time
Local Time
PI 2 System
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
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 117
0 - Appendix B: PI Time Conversions
Universal Coordinated
Time
Local Time
PI 2 System
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
Time
Local Time
PI 2 System
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.
9.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
Page 118
Time zone
Universal Coordinated Time
Local Time
PI 2 System Time
EST (PINet/VMS
node)
17-Nov-96 10:00:00
17-Nov-96
05:00:00
848206800
PST (PI 2 Server)
17-Nov-96 10:00:00
17-Nov-96
02:00:00
848196000
9.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.
9.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.
9.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
Coordinated Time
Local Time
PI 2 System
Time
Offset
PI Server
Time
7-Apr-96 08:30:00
7-Apr-96 00:30:00 PST
828837000
28800
828865800
PI Server Reference Guide
Page 119
0 - Appendix B: PI Time Conversions
Universal
Coordinated Time
Local Time
PI 2 System
Time
Offset
PI Server
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
Coordinated Time
Local Time
PI 2 System
Time
Offset
PI Server
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.
9.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 120
9.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
of Archive Value
Universal
Coordinated
Time
DT/
ST
Returned PI 2
System Time
Local Time
Offset
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.
9.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. Rockwell Automation 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 FactoryTalk Historian 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 121
0 - 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.
9.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 122
APPENDIX C: PI API AND TOOLKIT USAGE
9.1
Overview
9.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 FactoryTalk Historian 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.
9.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 123
0 - 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 124
9.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 125
0 - 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 126
9.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
Rockwell Automation 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 Rockwell Automation 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 127
0 - 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 128
9.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.
9.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 129
0 - 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 130
APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT
CLASSES
9.1
Predefined Attribute Sets
9.1.1
alarmparam
Attribute
Type
action1
String
action2
String
action3
String
action4
String
action5
String
AutoAck
String
ControlAlg
String
ControlTag
String
Deadband
Float32
Options
String
ReferenceTag
String
Srcptid
Int32
test1
String
test2
String
test3
String
test4
String
test5
String
txt1
String
txt2
String
txt3
String
txt4
String
txt5
String
PI Server Reference Guide
Default
yes
0.
0
Page 131
0 - Appendix D: Predefined Attribute Sets and Point Classes
9.1.2
9.1.3
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
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.
-5
classic
Page 132
Attribute
Type
Default
Convers
Float32
1.
Filtercode
Int16
0
Instrumenttag
String
location1
Int32
0
location2
Int32
0
9.1 - Predefined Attribute Sets
9.1.4
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.
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
ProductTag
String
ReferenceTag
String
ResetTag
String
SQCAlarmPriority
Int32
0
Srcptid
Int32
0
Stratification
String
sqcalm_parameters
PI Server Reference Guide
no
Page 133
0 - Appendix D: Predefined Attribute Sets and Point Classes
9.1.5
9.2
TestStatusTag
String
Trend
String
UCLTag
String
USLTag
String
WaitOnLimitChange
String
false
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.
totals
Predefined Point Classes
Alarm
base
alarmparam
Page 134
Base
base
Classic
base
classic
SQC_Alarm
base
sqcalm_parameters
Totalizer
base
totals
TECHNICAL SUPPORT AND RESOURCES
Technical Support Options
Contact Rockwell Automation Technical Support at the following:
•
•
Customer Support Telephone — 1-440-646-3434
Online Support — http://support.rockwellautomation.com
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
•
•
The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Before You Call or Write for Help
When you contact Rockwell Automation 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.
PI Server Reference Guide
Page 135
Technical Support and Resources
•
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:
•
•
Page 136
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
INDEX OF TOPICS
Absolute Time, 113
Access permissions, 49
attributes, 49
Accumulators
data types for, 43
Adm directory, 6
Annotation, 20
file, 21
Anti-virus software
OSIsoft recommendation, 7
API Node, 10
API, see PI API, 5
Apisnap, 5, 20
Application Programming Interface
see PI API, 5
Applications, point attributes for,
51
Architecture
SQL Subsystem, 99
Archive
archiving flag, 48
Files, 19
foreign data sources, 17
flag, 53
Size
Considerations, 20
write cache, 13
Archiving attribute, 48
Archiving flag, 48
Argument
Token
SQL Subsystem, 102
Attributes
and point classes, 41
archiving, 48
PI Server Reference Guide
base class, 41
changeDate, 55
changer, 55
changing tag names, 42
changing zero/span, 46
compDev, compMin,
compMax, 48
compressing, 47
Compression, 18, 93
convers attribute, 51
creationDate, 55
creator, 55
ctr_lmap, 52
ctr_progid, 52
ctr_strmap, 52
dataAccess, 49
dataGroup, 49
defaults, 53
Descriptor, 44
digitalSet, 45
displayDigits, 49
engUnits, 46
exception reporting, 89
exDesc, 44
for classic points, 50
for COM connectors, 52
for user-written programs, 51
instrument tag attribute, 50
location attributes, 50
newTag, 44
pointID, 55
PointSource, 46
PointType, 43
ptAccess, 49
PtClassName, 42
Page 137
Index of Topics
ptGroup, 49
recNo, 56
scan, 47
shutdown, 50
sourceTag, 47
span, 45
squareRoot attribute, 51
srcptid attribute, 51
step, 48
system-assigned, 55
tag name restrictions, 42
totalcode attribute, 51
typicalValue, 45
userInt and userReal attributes,
51
zero, 45
Bad Input digital state, 23
Bad status, 23
Base class, 41
Base Point Class
Point Attributes, 100
Batch Database, 38
bin directory, 6
Blob point type, 43
Buffering
PI API, 6
Build number, 4
C language, 6
Capitalization
case sensitivity in searches, 42
digital state sets, 25
Case sensitivity
digital state names, 25
for tags, 42
ChangeDate, 53
point attribute, 55
Point attribute, 55
Changer, 53
point attribute, 55
Changing zero/span, 46
Chsrc file
UNIX, 8
Page 138
Classes
PtClassName attribute, 42
Classes, base point class, 41
Classic Point
Definitions, 100
Classic Point class, 50
classicctr point class, 52
classicctr.dif, 52
Client Applications
Security, 97
COM connectors, 14
classicctr.dif file, 52
creating point class for, 52
longword mapping parameter,
52
mapped points, 52
point attributes for, 52
program ID parameter, 52
string mapping parameter, 52
COM objects, 14
Combined Time Format, 116
Command
Ptclass, 41
Command Line Arguments
SQL Subsystem, 102
UNIX, SQL Subsystem, 104
Windows, SQL Subsystem,
104
CompDev, 92, 93
Point attribute, 53
CompDev attribute, 48
CompDevPercent, 53, 93
CompDevPercent attribute, 48
CompMax, 92, 93
Point attribute, 53
CompMax attribute, 48
CompMax Point attribute range of
values, 51
CompMin, 92, 93
Point attribute, 53
CompMin attribute, 48
Compressing attribute, 47
Index of Topics
Compression, 47, 92
Deviation, 93, 94
flag, 47, 53
foreign data sources, 18
Maximum, 93
Minimum, 93
out of order events, 48
Specifications, 53
swinging door, 93
Windows
recommendation against,
7
Computer platform
Information, 136
Concurrency, 100
Configuration
SQL Subsystem, 101
Configuration files
shutdown.dat, 50
Configuration parameters, 25
Constraints on tag names, 42
Conventions, naming tags, 42
Convers point attribute, 51, 53, 100
Conversion
factor, 55
CreationDate, 53
point attribute, 55
Creator, 53
point attribute, 55
ctr_lmap, 15
ctr_lmap attribute, 52
ctr_progid, 15
ctr_progid attribute, 52
ctr_strmap, 15
ctr_strmap attribute, 52
Current snapshot values, 5
dat directory, 6
Data
compression, 47, 92
foreign data sources, 14
retrieval
PI Server Reference Guide
from foreign data sources,
16
Data Archive
Database, 19
Expensive queries, 109
Data Compression
specifications, 48
Data flow
overview, 9
Data output
sourceTag attribute, 47
Data permissions, 49
Data sources
non-PI, 14
Data types
for accumulators, 43
for negative integers, 43
pointType attribute, 43
DataAccess
Point attribute, 49
DataAccess Point Attribute, 53
Database
Batch, 38
Firewall, 37
Group, 38
Module, 38
Point, 19, 20
Proxy, 37
Snapshot, 20
Trust, 37
User, 38
Databases
non-PI, 14
timeout database, 25
DataGroup
Point attribute, 49, 53
DataOwner
Point attribute, 49, 53
Daylight Savings Time, 114, 128
Changes, 117
PI Client Applications,
121
Page 139
Index of Topics
to Standard Time, PI 3
Server, 120
Default
Digital State Set, 23
point attributes, 53
Descriptor
Point attribute, 53
Descriptor attribute, 44
Deviation
Compression, 94
Differences
in PI Systems
SQL Subsystem, 100
Digcode, 24
Digital code value, 24
Digital point type, 43
Digital State
Decoding, 128
Retrieving from PI Server, 128
Retrieving from PI2, 128
Sending to PI Server, 127
Sending to PI2, 127
strings, 23
Table, 23
Editing, 24
Digital State Set, 23
defining, 24
deleting, 24
Digital state sets, 45
case sensitivity, 25
Digital states
digitalSet attribute, 45
Digital tag, 24, 94
DigitalSet, 53
DigitalSet attribute, 45
DIGSET_nn, 24
Digstartcode, 127
Directories
PI file system, 6
structure, 6
UNIX, 8
DisplayDigits
Page 140
Point attribute, 53
DisplayDigits attribute, 49, 50
Documentation
conventions, v
for interfaces, vi
Engineering units, 46
EngUnitCode, 130
EngUnits
Point attribute, 53
EngUnits attribute
about, 46
single quotes in, 46
EngUnitStr, 130
Environment variable, 8, 25
Event
Out of order, 93
processing, 11
Event Queue, 11, 12
Events
definition of, 9
shutdown events, 50
significant event, 10
ExcDev, 89, 91
Point attribute, 53
ExcDev attribute, 91
ExcDevPercent, 53
ExcDevPercent attribute, 91
Exception Deviation, 91
Exception Maximum, 91
Exception reporting
about, 89
foreign data sources, 17
minimum, 94
specifications, 47
turning off, 92
ExcMax, 89
Point attribute, 53, 91
ExcMax Point attribute range of
values, 51
ExcMin, 89
Point attribute, 54, 91
ExDesc, 47
Index of Topics
Point attribute, 54
ExDesc attribute, 44
Executables for the PI System, 8
Expensive Queries
clearing, 109
UNIX, 110
Extended descriptor
Point attribute, 54
File System Compression
recommendation against, 7
Files
archive, 19
PI file system, 6
Filtercode, 54
Point Attribute, 100
Filtercode point attribute, 51
Filtering
turning off exception
reporting, 92
Filtering data
Exception reporting, 89
Filtering, zero/span, 46
Firewall, 7, 97
Database, 37
float16
changing zero/span, 46
out of range data, 46
span attribute, 45
zero attribute, 45
float16 point type, 43
float32
Point type, 54
float32 point type, 43
float64 point type, 43
formatting values
displayDigits attribute, 49
getCompSpecs ( ), 129
getCompSpecsEng ( ), 129
getDigCode ( ), 129
getDigPointers( ), 129
getEngCode( ), 129
getEngUnits( ), 130
PI Server Reference Guide
getEngUnString, 130
getExcSpecsEng( ), 130
Group
assigning users to, 38
Database, 38
file, UNIX, 8
Security, 97
Handle. See Statement Handle
I/O
Timeout, 23
Initialization
SQL Subsystem, 102
Installation
PI-SQL Checklist, 102
Instrument tag
point attribute, 50
Instrument Tag
Point attribute, 54
int16 point type, 43
int32 point type, 43
Integer point type, 43
Interface
definition of, 5
PerfMon, 5
Ping, 5
Random and ramp soak, 1
sending digital states, 127
Sending to PI Server, 127
Simulators, 5
SNMP, 5
Interfaces
downloading documentation
for, vi
exception reporting, 89
PointSource attribute, 46
Interpolation, 126
of numeric values, 48
IP Address, 37
ipisql Utility, 105
options for, 106
Istat, 128
Korn Shell, 8
Page 141
Index of Topics
Lab point source, 46
LibC.ansi.sl
UNIX, 8
Libraries, 8
Localtime, 117, 128, 129
Location Codes
Point attribute, 50, 54, 100
location1 point attribute, 50
location2, 54
location2 point attribute, 50
location3 point attribute, 50
location4 point attribute, 50
location5 point attribute, 50
log directory, 6
Log files
location, 8
LOG option
SQL Subsystem, 108
Login, remote
command-line tools, 4
Longword mapping parameter, 52
Mapped point, 15, 52
Maximum
Compression, 93
Messages
Timeout, 37
Microsoft Common Object Model
(COM) technology, 14
Minimum
Compression, 93
Module Database, 38
Naming tags, restrictions, 42
Negative integers
data types for, 43
New Event Processing, 11
NewTag, 54
NewTag attribute, 44
No Data digital state, 23
NT Services
pisqlss, 104
ODBC Driver, 99
Offset
Page 142
Calculation for timestamp, 119
OSIsoft
Error codes, 127
Out of order events
compression, 48
Out of range
for float16, 46
Output to other systems
sourceTag attribute, 47
Over Range, 45, 46
digital state, 23
Parameters
COM program ID, 52
longword mapping, 52
server configuration, 25
string mapping, 52
Password, 38, 97
file, UNIX, 8
Performance
impact of file system
compression, 7
Performance Equations
use in SQL Subsystem, 101
Performance tuning
configuration parameters, 25
Permissions
point and data, 49
PI 2
Daylight Savings Time
Changes, 117
timestamps, 117
PI API, 123
Buffering, 6
Timestamp Translation to
Windows and UNIX PI
Systems, 119
Timestamps, 117
PI point number, 51
PI Server
databases, 19
Daylight Savings Time to
Standard Time, 120
Index of Topics
Standard Time to Daylight
Savings Time, 119
Time Format, 113
Timestamps, 119
Toolkit Usage, 129
PI System
API Time, 117
piadmin, 54
piapi32.dll, 8
piar_replacevalue, 124
piartool
remote login, 4
piconfig, 20
piel_addevnt ( ), 124
piel_evntactn ( ), 124
pigetmsg
remote login, 4
pigrp, 8
pilistupd
remote login, 4
PINet/OpenVMS
Nodes
Time conversions, 119
PI-ODBC Driver
Minimum version, 99
piparams.default
UNIX, 8
PIPoint
Table, 100
PIproxy records, 38
pipt_compspecs, 124
pipt_compspecseng, 124
pipt_dates ( ), 124
pipt_descriptor ( ), 123, 124
pipt_digcode ( ), 124
pipt_digcodefortag ( ), 125
pipt_engunitstring ( ), 125
pipt_engunstring( ), 125
pipt_excspecseng, 125
pipt_exdesc ( ), 125
pipt_findpoint ( ), 125
pipt_nextptwsource ( ), 125
PI Server Reference Guide
pipt_pointid ( ), 126
pipt_pointsource ( ), 126
pipt_recordtype ( ), 126
pipt_rescode ( ), 126
pipt_tag ( ), 126
pipt_taglong ( ), 126
pipt_tagpreferred, 126
pipt_totalspecs ( ), 126
pipt_updates ( ), 127
pipt_wildcardsearch ( ), 127
PI-SDK, 99
pisetpass utility, 97
pisn_getsnapshot ( ), 127
pisn_getsnapshots, 127
pisn_putsnapshot ( ), 127
pisn_putsnapshotq ( ), 127
pisn_putsnapshots ( ), 127
pisn_sendexceptionq ( ), 127
pisn_sendexceptions ( ), 127
pisnap, 5
pisnap.bat, 20
pisnap.sh, 20
pisnapss, 20
pisqlss, 99, 102
configuring, 101
continue command, 110
NT services, 101
pause command, 110
performance tuning, 102
pisql.ini, 102
starting as an NT service, 104
PISysDat
pisql.ini, 102
PITimeout Table, 36, 37
pitm_systime ( ), 128
Point
deleting, 20
security, 18, 97
Source data attribute, 54
Point Attributes
archiving, 48
Page 143
Index of Topics
base class, 41
changeDate, 55
changer, 55
changing tag names, 42
changing zero/span, 46
classic, 50
compressing, 47
Convers, 100
convers attribute, 51
creationDate, 55
creator, 55
ctr_lmap, 52
ctr_progid, 52
ctr_strmap, 52
dataAccess, 49
dataGroup, 49
defaults, 53
Descriptor, 44
digitalSet, 45
displayDigits, 49
engUnits, 46
exDesc, 44
Filtercode, 100
filtercode attribute, 51
for classic points, 50
for COM connectors, 52
instrument tag attribute, 50
location attributes, 50
Location Code, 100
newTag, 44
pointID, 55
Pointid, 100
PointSource, 46
pointType, 43
ptAccess, 49
PtClassName, 42
ptGroup, 49
recNo, 56
Recordtype, 101
Res, 101
scan, 47
Page 144
shutdown, 50
sourceTag, 47
span, 45
Squareroot, 101
squareRoot attribute, 51
srcptid attribute, 51
step, 48
system assigned, 55
tag name restrictions, 42
tag, case sensitivity, 42
Totalcode, 101
totalcode attribute, 51
typicalValue, 45
userInt and userReal attributes,
51
zero, 45
Point Class, 15
Point classes
base class, 41
classic, 50
classicctr point class, 52
for COM connectors, 52
PtClassName attribute, 42
Point Configuration, 15
Point Database, 19
default attribute values, 53
Point types
for accumulators, 43
for negative integers, 43
PointID, 54
point attribute, 55
Point attribute, 55, 100
Points
about, 41
access permissions, 49
archiving attribute, 48
attribute defaults, 53
base class, 41
case sensitivity, 42
changing tag names, 42
changing zero/span, 46
classic point class, 50
Index of Topics
compDev, compMin,
compMax, 48
compressing attribute, 47
compression on/off, 47
convers attribute, 51
data types, 43
dataAccess, 49
dataGroup, 49
Descriptor attribute, 44
digitalSet attribute, 45
displayDigits attribute, 49
engUnits attribute, 46
exDesc attribute, 44
filtercode attribute, 51
instrument tag attribute, 50
interpolation of values, 48
location attributes, 50
mapped, 52
naming restrictions, 42
newTag attribute, 44
PointSource attribute, 46
ptAccess, 49
PtClassName attribute, 42
ptGroup, 49
scan attribute, 47
shutdown attribute, 50
sourceTag attribute, 47
span attribute, 45
squareRoot attribute, 51
srcptid attribute, 51
step attribute, 48
totalcode attribute, 51
turn off data collection, 47
typicalValue attribute, 45
userInt and userReal attributes,
51
viewing snapshot value, 5
zero attribute, 45
PointSource attribute, 46
PointType, 54
PointType attribute, 43
Precision, 11
PI Server Reference Guide
Priorities
in SQL configuration methods,
102
Profile
File
Unix, 8
Program ID parameter, 52
Programs, point attributes for, 51
Proxy Access
Security, 98
Proxy Database, 37
pt Created digital state, 23
ptAccess
Point attribute, 49, 54
ptclass command, 41
ptClassName attribute, 42
ptGroup
Point attribute, 49, 54
ptOwner
Point attribute, 49, 54
Queries
SQL Subsystem, 106
Range
the span attribute, 45
the zero attribute, 45
Real point type, 43
RecNo, 54
point attribute, 56
Point attribute, 56
Records
record number attribute, 56
Recordtype point attribute, 101
Redirector, 14
Relative Time, 113
Remote adminstration, 4
Res point attribute, 101
Rescode, 126
Restrictions on tag names, 42
Scan attribute, 47
Scan Flag, 54
Scan time
slow, 94
Page 145
Index of Topics
Script files
classicctr.dif, 52
Security, 97
access permissions, 49
Firewall, 37
foreign data sources, 18
Servers
Time Conversions among, 117
Shutdown
digital state, 23
flag, 50
Point attribute, 54
Shutdown attribute, 50
Shutdown Events, 23
Shutdown.dat file, 50
Significant events, 10
Simulator interfaces, 5
Slow scan time, 94
SMT
about, vi, 24
Snapshot
definition of, 11
from foreign data sources, 16
viewing current values, 5
Snapshot Subsystem
database, 20
definition of, 11
Source tag, point number, 51
Source, point source, 46
SourceTag, 54
SourceTag attribute, 47
Span
Point attribute, 54
Span attribute, changing, 46
SQL Subsystem, 99
architecture, 99
argument, 102
Command line arguments, 102
configuration, 101
methods, conflicts in, 102
Generating a Trace, 108
Page 146
Initialization file, 102
LOG option, 108
NT services, 101
statement handles, 99
Submitting Queries, 106
TRACE Option, 108
Troubleshooting, 105
tuning, 101
Square root code
Point attribute, 54, 101
SquareRoot
point attribute, 50, 51
srcptid attribute
and sourceTag attribute, 47
srcptid point attribute, 54
srcptid point attribute, 51
Standard Time, 117
to Daylight Savings Time, PI 3
Server, 119
State 16383, 24
State sets, 45
Statement Handle, 99
Handle ID
PI-SQL, 109
Step
flag, 95
Point attribute, 54
Step attribute, 48
Step flag, 48
String
Data Types, 123
String mapping parameter, 52
String point type, 43
Subsecond timestamps, 123
Subsystem
PI-SQL, 99
Snapshot, 11
Subsystems
dependencies among, 1
Swinging door compression, 93
System
state set, 45
Index of Topics
State Set, 24
Time, 121
System Management Tools, vi, 24
System-assigned attributes, 55
Table
Digital State, 23, 24
PIPoint, 100
Tables
timeout, 25
Tag
Digital, 94
system digital state set, 23
Tag attribute, changing, 42
Tag names
capitalization, 42
Tagname
Point attribute, 54
Tagnames
constraints, 42
in external systems, 50
Tags. See points
archiving attribute, 48
changing names, 42
changing zero/span, 46
compDev, compMin,
compMax, 48
compressing attribute, 47
compression on/off, 47
constraints, 42
dataAccess, 49
dataGroup, 49
Descriptor attribute, 44
digitalSet attribute, 45
displayDigits attribute, 49
engUnits attribute, 46
exDesc attribute, 44
in external systems, 50
interpolation of values, 48
mapped, 52
newTag attribute, 44
PointSource attribute, 46
ptAccess, 49
PI Server Reference Guide
ptGroup, 49
scan attribute, 47
shutdown attribute, 50
sourceTag attribute, 47
span attribute, 45
step attribute, 48
turn off data collection, 47
typicalValue attribute, 45
viewing snapshot value, 5
zero attribute, 45
Time
API Time, 117
between events, 93
Changes
Daylight Savings to
Standard, 120
PI 2 Systems, 117
PI Client Applications,
121
conversions, 117
Format, 113
Local time, 117
System Time, 121
transitions
from Open VMS and PI
API to Windows and
UNIX, 119
PI 2 Systems, 117
PI Server Systems, 119
translations
PINet nodes, 119
Zone, 117, 128
Timeout database, 25
Timeout table, 25
Timestamp
across time zones on PI 2
System, 118
Conversions
algorithm, 119
PI 3 & PI 2, 117
PI Server, 119
Subsecond, 123
Page 147
Index of Topics
year 2000, 122
Timestamp point type, 43
Timing parameters, 25
UNIX, 36
Toolkit Usage, 129
Totalcode point attribute, 51
Totalcode Point Attribute, 101
TRACE Option
SQL Subsystem, 108
Trend
seasonal time changes, 122
Trends
formatting numbers, 49
Troubleshooting
SQL Subsystem, 105
Tuning the PI Server
configuration parameters, 25
Turning off exception reporting, 92
Types
about point types, 43
for accumulators, 43
for negative integers, 43
TypicalValue
Point attribute, 55
TypicalValue attribute, 45
TZ environment variable, 128
UCT, 119
Under Range, 45, 46
Under Range digital state, 23
UniInt
downloading documentation
for, vi
Units, engineering, 46
Universal Coordinated Time, 117,
119, 128
Page 148
Universal Interface
downloading documentation
for, vi
UNIX
directory and file structure, 8
UNIX directory structure, 8
User
Database, 38
User programs, point attributes for,
51
UserInt1 point attribute, 51
UserInt2, 55
UserInt2 point attribute, 51
UserReal1, 55
UserReal1 point attribute, 51
UserReal2, 55
UserReal2 point attribute, 51
UTC, 128
Utility
ipisql, 105
piconfig, 20
pisetpass, 38
pisnap.bat, 20
pisnap.sh, 20
Version
PI Server, 4
Visual Basic, 6
Windows
Directory and file structure, 8
Year 2000
Timestamps, 122
Zero
Point attribute, 55
Zero attribute, 45
Zero attribute, changing, 46