Вы находитесь на странице: 1из 164

PI Server Reference Guide

PI3 Server
Version 3.4.370

© 1998-2006 OSIsoft, Inc. All rights reserved


OSIsoft, Inc. North American Offices
777 Davis St., Suite 250 Houston, TX
San Leandro, CA 94577 USA Johnson City, TN
Telephone Mayfield Heights, OH
(01) 510-297-5800 (main phone) Phoenix, AZ
(01) 510-357-8136 (fax) Savannah, GA
(01) 510-297-5828 (support phone) Seattle, WA
Yardley, PA
WWW.OSISOFT.COM Email: support@osisoft.com

Worldwide Offices

OSIsoft Australia OSIsoft Japan KK


Perth, Australia Tokyo, Japan
Auckland, New Zealand OSIsoft Mexico S. De R.L. De C.V.
OSI Software GmbH Mexico City, Mexico
Altenstadt, Germany OSI Software Asia Pte Ltd.
OSIsoft Canada ULC Singapore
Montreal, Canada OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China

Sales Outlets and Distributors


ƒ Brazil ƒ South America / Caribbean
ƒ Middle East / North Africa ƒ Southeast Asia
ƒ Republic of South Africa ƒ South Korea
ƒ Russia / Central Asia ƒ Taiwan

Revised: January 2006


Send documentation requests, comments and corrections to customerfeedback@osisoft.com.

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook,
Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be
trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that
is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement,
recommendation, or warranty of such party's products or any affiliation with such party of any kind.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Copyright Notice
Unpublished -- rights reserved under the copyright laws of the United States
PREFACE – USING THIS GUIDE

About this Guide

The PI Server Reference Guide provides comprehensive information and instructions that
System Administrators need to understand, plan, administer and troubleshoot the PI Server,
PI subsystems, and PI System interfaces.
This guide includes the following topics:
‰ Overview of all PI Databases
‰ Data flow in the PI System
‰ PI Point Classes and Attributes
‰ Class Edit and Type Edit
‰ Exception Reporting
‰ Compression Testing
‰ Security
‰ SQL Subsystem
‰ PI Time Format and Conversions
‰ Overview of the PI Application Programming Interface (PI API)
This guide assumes that the System Administrator has a working understanding of PI Server
tools and utilities such as PIConfig, PIDiag and PIArtool. For additional information about
these command-line tools and other PI System setup and configuration procedures, see the PI
Server System Management Guide.
For a broader overview of the PI System architecture and system administration, see
Introduction to PI System Management.

PI Server Reference Guide Page iii


Preface - Using this Guide

The PI Server Documentation Set

The PI Server Documentation Set provides complete PI Server information and system
management procedures. It includes seven user guides, described below.

Tip: Updated user guides with the most up-to-date information may be available for
download from the OSIsoft Technical Support Web site:
(http://techsupport.osisoft.com).

Title Subject Matter

Introduction to PI A guide to the PI Server for new users and administrators. It explains PI
System Management system components, architecture, data flow, utilities and tools. It provides
instruction for managing points, archives, backups, interfaces, security and
trusts, and performance. It includes a glossary and resource guide.

PI Server Installation A guide for installing, upgrading and removing PI Servers on Windows and
and Upgrade Guide UNIX platforms, including cluster and silent installations.

PI Server System An in-depth administration guide for the PI Server, including starting and
Management Guide stopping systems, managing the Snapshot, Event Queue and Data Archive,
monitoring system health, managing backups, interfaces, security, and
moving and merging servers. Includes comprehensive instructions for using
command-line tools: PIConfig, PIDiag, and PIArtool, and in-depth
troubleshooting and repair information.

PI Server Reference A comprehensive reference guide for the system administrator and
Guide advanced management tasks, including: databases; data flow; PI Point
classes and attributes, class edit and type edit; exception reporting;
compression testing; security; SQL subsystem; PI time format; and
overviews of the PI API, and PI-SDK System Management Tool (SMT).

Auditing the PI An administration guide that explains the Audit Database, which provides a
Server secure audit trail of changes to PI System configuration, security settings,
and Archive Data. It includes administration procedures to enable auditing, to
set subsystem auditing mode, to create and archive database files, and to
export audit records.

PI Server A guide to key add-on PI Server Applications: Performance Equations (PE),


Applications User Totalizer, Recalculator, Batch, Alarm, and Real-Time SQC (Statistical Quality
Guide Control). Includes a reference guide for Performance Equations, and Steam
calculation functions.

PINet and PIonPINet A systems administration guide, including installation, upgrade and
User Guide operations, for PINet for OpenVMS and PIonPINet, which support migration
and interoperability between PI2 and PI3 Systems.

Page iv
Preface - Using this Guide

Conventions Used in this Guide


This guide uses the following formatting and typographic conventions.
Format Use Examples
Title Case ƒ PI Client Tools ƒ Use the client tool, PI ProcessBook, to verify that all
ƒ PI System Elements data has been recovered.
ƒ PI Server Subsystems ƒ All incoming data is queued in the Event Queue by
the Snapshot Subsystem.
Italic text ƒ Files, Directories, Paths ƒ The backup script is located in the \PI\adm directory.
ƒ Emphasis ƒ Archive files can be either fixed or dynamic. The
ƒ New Terms archive receiving current data is called the Primary
Archive.
ƒ Fields
ƒ See Section 4.2, Create a New Primary Archive.
ƒ References to a chapter or section
Bold Italic text ƒ References to a publication ƒ See the PI Server Reference Guide.
Bold text ƒ System and Application ƒ The Archive Subsystem, piarchss, manages data
components: archives. Piarchss must be restarted for changes to
ƒ Subsystems take effect.
ƒ Tools / Utilities ƒ On UNIX, invoke site-specific startup script,
pisitestart.sh, and on Windows, invoke
ƒ Processes / Scripts / Variables pisrvsitestart.bat.
ƒ Arguments / Switches / Options ƒ Three Point Database attributes affect compression:
ƒ Parameters / Attributes / Values CompDev, CompMin, and CompMax. These are
ƒ Properties / Methods / Events / known as the compression specifications.
Functions
ƒ Procedures and Key Commands ƒ On the Tools menu, click Advanced Options.
ƒ Press CTRL+ALT+DELETE to reboot
ƒ Interface components ƒ Click Tools > Tag Search to open the Tag Search
ƒ Menus / Menu Items tool.
ƒ Icons / Buttons / Tabs ƒ Click the Advanced Search tab.
ƒ Dialog box titles and options ƒ Use the search parameters PImean Value = 1.

Monospace Consolas monospace is used for: To list current Snapshot information every 5 seconds,
type: ƒ Code examples use the piartool -ss command. For example:
"Consolas" ƒ Commands to be typed on the
font command line (optionally with
arguments or switches)
ƒ System input or output such as
excerpts from log files and other
data displayed in ASCII text
ƒ Bold consolas is used in the
context of a paragraph
Light Blue - Links to URL / Web sites, and email http://www.osisoft.com/procedures.aspx
Underlined addresses support@osisoft.com

PI Server Reference Guide Page v


Preface - Using this Guide

Related Documentation

OSIsoft provides a full range of documentation to help you understand and use the PI Server,
PI Server Interfaces, and PI Client Tools. Each Interface has its own manual, and each Client
application has its own online help and/or user guide.
The UniInt End User Manual describes the OSIsoft Universal Interface (UniInt), which is
recommended reading for PI Server system managers. Many PI Interfaces are based upon
UniInt, and this guide provides a deeper understanding of principals of Interface design.

Using PI Server Tools

The PI Server provides two sets of powerful tools that allow system administrators and users
to perform system administration tasks and data queries.
‰ The PI Server includes many command-line tools, such as pidiag and piartool. The
PI Server Documentation Set provides extensive instruction for performing PI Server
administrative tasks using command-line tools.
‰ The PI System Management Tools (SMT) is an easy-to-use application that hosts a
variety of different plug-ins, which provide all the basic tools you need to manage a
PI System. You access this set of tools through a single host application. This host
application is sometimes referred to as the SMT Host, but it is more commonly called
System Management Tools or SMT.
You can download the latest version of SMT from the Technical Support Web site:
http://techsupport.osisoft.com
In addition to extensive online help that explains how to use all of the features in the SMT,
the SMT includes the Introduction to PI System Management user guide.

Page vi
QUICK TABLE OF CONTENTS

Chapter 1. The PI Server ...............................................................................................................1

Chapter 2. PI Data Flow.................................................................................................................9

Chapter 3. PI Server Databases .................................................................................................19

Chapter 4. PI Point Classes and Attributes...............................................................................41

Chapter 5. PI Point Class Edit ....................................................................................................57

Chapter 6. PI Point Type Edit......................................................................................................81

Chapter 7. Exception Reporting and Compression Testing ...................................................87

Chapter 8. Security ......................................................................................................................95

Chapter 9. PI SQL Subsystem ....................................................................................................97

Appendix A: PI Time Format.........................................................................................................111

Appendix B: PI Time Conversions ...............................................................................................115

Appendix C: PI API and Toolkit Usage ........................................................................................121

Appendix D: Predefined Attribute Sets and Point Classes .......................................................129

PI Server Reference Guide Page vii


TABLE OF CONTENTS

Preface – Using this Guide ..............................................................................................................iii

Table of Tables.................................................................................................................................xv

Table of Figures .............................................................................................................................xvii

Chapter 1. The PI Server ...............................................................................................................1


1.1 PI Server Subsystems.......................................................................................................1
1.2 Configuration and Administrative Utilities .....................................................................3
1.2.1 Using Command-Line Tools Remotely...................................................................4
1.2.2 Displaying the PI Version Number .........................................................................4
1.2.3 Checking Snapshot Values (apisnap and pisnap) .................................................5
1.3 Interfaces Installed with the PI Server.............................................................................5
1.3.1 Interfaces to Other Data Sources...........................................................................5
1.4 PI Application Programming Interface (API)...................................................................5
1.5 PI Directory Structure .......................................................................................................6
1.5.1 Windows Directory Structure ..................................................................................6
1.5.2 Windows File System Concerns.............................................................................7
1.5.3 UNIX Directory Structure ........................................................................................8

Chapter 2. PI Data Flow.................................................................................................................9


2.1 Data Flow from Data Sources into the PI Archive..........................................................9
2.1.1 The Snapshot .......................................................................................................11
2.1.2 The Archive Subsystem........................................................................................11
2.2 Data Retrieval from the Archive .....................................................................................13
2.2.1 The Archive Read Cache .....................................................................................13
2.3 PI Data Retrieval with Foreign Data Sources................................................................14
2.3.1 Point Configuration ...............................................................................................15
2.3.2 Retrieval of Snapshot Data...................................................................................16
2.3.3 Retrieval of Archive Data......................................................................................16
2.3.4 Archive Files .........................................................................................................17

PI Server Reference Guide Page ix


Table of Contents

2.3.5 Exception Reporting .............................................................................................17


2.3.6 Compression ........................................................................................................18
2.3.7 Point Security .......................................................................................................18

Chapter 3. PI Server Databases .................................................................................................19


3.1 Point Database.................................................................................................................19
3.2 Data Archive.....................................................................................................................19
3.2.1 Archive Size Considerations ................................................................................20
3.3 Snapshot ..........................................................................................................................20
3.4 Annotations......................................................................................................................20
3.4.1 Annotation Files....................................................................................................21
3.5 Digital State Table ...........................................................................................................23
3.5.1 System State Set for All Points ............................................................................23
3.5.2 Defining a Custom Digital State Set .....................................................................24
3.6 Timeout Database............................................................................................................25
3.6.1 Table of Configurable Timeout Database Parameters.........................................25
3.7 Firewall Database ............................................................................................................37
3.8 Proxy Database................................................................................................................37
3.9 Trust Database.................................................................................................................37
3.10 User Database..................................................................................................................38
3.11 Group Database...............................................................................................................38
3.12 Module Database .............................................................................................................38
3.13 Batch Database................................................................................................................38
3.14 List of Database Files......................................................................................................38

Chapter 4. PI Point Classes and Attributes...............................................................................41


4.1 About Point Classes........................................................................................................41
4.2 Base Class Point Attributes ...........................................................................................41
4.2.1 Tag........................................................................................................................42
4.2.2 PtClassName........................................................................................................42
4.2.3 PointType..............................................................................................................43
4.2.4 NewTag ................................................................................................................44
4.2.5 Descriptor .............................................................................................................44
4.2.6 ExDesc .................................................................................................................44
4.2.7 TypicalValue .........................................................................................................45
4.2.8 DigitalSet ..............................................................................................................45
4.2.9 Zero ......................................................................................................................45
4.2.10 Span .....................................................................................................................45

Page x
Table of Contents

4.2.11 Impact of Changing Zero and Span .....................................................................45


4.2.12 EngUnits ...............................................................................................................46
4.2.13 PointSource ..........................................................................................................46
4.2.14 SourceTag ............................................................................................................46
4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent....................................................47
4.2.16 Scan Flag..............................................................................................................47
4.2.17 Compressing Flag ................................................................................................47
4.2.18 CompDev, CompMin, CompMax and CompDevPercent .....................................47
4.2.19 Archiving ...............................................................................................................48
4.2.20 Step ......................................................................................................................48
4.3 Classic Point Class Attributes .......................................................................................50
4.3.1 Instrument Tag .....................................................................................................50
4.3.2 Location1, Location2, Location3, Location4, and Location5 ................................50
4.3.3 SquareRoot ..........................................................................................................50
4.3.4 UserInt1, UserInt2, UserReal1 and UserReal2 ....................................................51
4.3.5 Filtercode ..............................................................................................................51
4.3.6 Totalcode ..............................................................................................................51
4.3.7 Srcptid...................................................................................................................51
4.3.8 Convers ................................................................................................................51
4.3.9 Ranges of ExcMax and CompMax.......................................................................51
4.4 COM Connector Point Attributes ...................................................................................52
4.5 Default Values for Point Attributes................................................................................52
4.6 System-Assigned Attributes ..........................................................................................55
4.6.1 Creator..................................................................................................................55
4.6.2 CreationDate ........................................................................................................55
4.6.3 Changer ................................................................................................................55
4.6.4 ChangeDate .........................................................................................................55
4.6.5 PointID ..................................................................................................................55
4.6.6 RecNo...................................................................................................................55

Chapter 5. PI Point Class Edit ....................................................................................................57


5.1 Introduction......................................................................................................................57
5.2 Overview...........................................................................................................................58
5.3 Attribute Sets Database Edit ..........................................................................................60
5.3.1 Attribute Set Creation ...........................................................................................60
5.3.2 Attribute Set Deletion............................................................................................63
5.3.3 Attribute Set Edit...................................................................................................64

PI Server Reference Guide Page xi


Table of Contents

5.4 Point Classes Database Edit ..........................................................................................70


5.4.1 Point Class Creation.............................................................................................70
5.4.2 Point Class Deletion .............................................................................................70
5.4.3 Point Class Edit ....................................................................................................71
5.5 Editing a Point’s Point Class Attribute..........................................................................76
5.5.1 Conversion of CC Class to and from a Native PI Class .......................................77
5.6 Point Database Audit ......................................................................................................77
5.6.1 Audit Records .......................................................................................................78
5.7 Thread-safety ...................................................................................................................80

Chapter 6. PI Point Type Edit......................................................................................................81


6.1 Introduction......................................................................................................................81
6.2 Error handling ..................................................................................................................85

Chapter 7. Exception Reporting and Compression Testing ...................................................87


7.1 Exception Reporting .......................................................................................................87
7.1.1 ExcDev and ExcDevPercent ................................................................................89
7.1.2 ExcMin ..................................................................................................................89
7.1.3 ExcMax .................................................................................................................89
7.1.4 Turning Off Exception Reporting ..........................................................................90
7.2 Compression Testing......................................................................................................90
7.2.1 Step Flag ..............................................................................................................93

Chapter 8. Security ......................................................................................................................95


8.1 User Name and Password ..............................................................................................95
8.2 Point Security...................................................................................................................95
8.3 Database Security ...........................................................................................................95
8.4 Trust Access ....................................................................................................................96

Chapter 9. PI SQL Subsystem ....................................................................................................97


9.1 Architecture......................................................................................................................97
9.1.1 Statement Handles ...............................................................................................97
9.1.2 Concurrency .........................................................................................................98
9.2 Differences between PI 2.x and PI 3.x ...........................................................................98
9.2.1 The PIPoint Table.................................................................................................98
9.2.2 Using Performance Equation Subsystem Built-In Functions................................99
9.3 Configuration ...................................................................................................................99
9.3.1 Hierarchy of PI SQL Subsystem Settings...........................................................100
9.3.2 Initialization File Settings ....................................................................................100

Page xii
Table of Contents

9.3.3 Command Line Arguments.................................................................................100


9.4 Troubleshooting ............................................................................................................103
9.4.1 Using the ipisql Utility .........................................................................................103
9.4.2 Generating a Trace File......................................................................................106
9.4.3 Output from the TRACE Option..........................................................................106
9.4.4 Clearing Expensive Query Problems .................................................................107
9.4.5 Performance Counters .......................................................................................108
9.4.6 Technical Support and Problem Reports ...........................................................109

Appendix A: PI Time Format.........................................................................................................111


A.1 Relative Time .................................................................................................................111
A.2 Absolute Time ................................................................................................................111
A.2.1 Specifying Standard or Daylight Savings Time ..................................................112
A.2.2 Examples ............................................................................................................113
A.3 Combined Formats........................................................................................................114
A.3.1 Examples ............................................................................................................114

Appendix B: PI Time Conversions ...............................................................................................115


B.1 Timestamps on PI 2 Systems .......................................................................................115
B.2 Daylight Savings Time Changes on PI 2 Systems .....................................................115
B.3 Timestamps across Time Zones on PI 2 Servers.......................................................116
B.4 Timestamps on PI Server Systems..............................................................................117
B.5 Translating PI 2 Timestamps to PI Server Systems...................................................117
B.6 Translating PI Server Timestamps to PI 2 Based Timestamps.................................118
B.7 How PI Client Applications Handle DST Changes .....................................................119
B.8 PI in the 21st Century....................................................................................................120

Appendix C: PI API and Toolkit Usage ........................................................................................121


C.1 Overview.........................................................................................................................121
B.1.1 PI API..................................................................................................................121
C.2 PI API Usage on PI Server ............................................................................................121
C.3 PI Toolkit Usage on PI Server.......................................................................................127

Appendix D: Predefined Attribute Sets and Point Classes .......................................................129


D.1 Predefined Attribute Sets .............................................................................................129
D.1.1 alarmparam ........................................................................................................129
D.1.2 base ....................................................................................................................130
D.1.3 classic .................................................................................................................130
D.1.4 sqcalm_parameters ............................................................................................131

PI Server Reference Guide Page xiii


Table of Contents

D.1.5 totals ...................................................................................................................132


D.2 Predefined Point Classes .............................................................................................132

Technical Support and Resources...............................................................................................133

Index of Topics...............................................................................................................................135

Page xiv
TABLE OF TABLES

Table 2–1. COM Connector Point Attributes............................................................................15


Table 3–1. Typical Digital States..............................................................................................23
Table 3–2. ConfigurableTimeout Parameters ..........................................................................25
Table 4–1. Point Types ............................................................................................................43
Table 4–2. Point Database Default Table ................................................................................53
Table 9–1. Default Attributes in BASE Point Class..................................................................98
Table 9–2. Command Line Arguments ..................................................................................101
Table 9–3. Command Line Option Tokens ............................................................................101
Table 9–4. Command Line Arguments Supported by ipisql ..................................................105
Table B-1 PI 2 Standard Time to Daylight Savings Time ...................................................115
Table B-2 PI 2 Daylight Savings Time to Standard Time ...................................................116
Table B-3 PI2 Timestamps across Time Zones .................................................................116
Table B-4 PI Server Standard Time to Daylight Savings Time ..........................................117
Table B-5 PI Server Daylight Savings Time to Standard Time ..........................................118
Table B-6 PI Examples of Timestamp conversions for California-based systems .............119

PI Server Reference Guide Page xv


TABLE OF FIGURES

Figure 2-1. Processing of New Events.....................................................................................12


Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector ........16
Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector ............17
Figure 5-1. Formation of a point class......................................................................................57
Figure 7-1. Swinging Door Compression .................................................................................92
Figure 9-1. Windows Control Panel Services Applet .............................................................103

PI Server Reference Guide Page xvii


Chapter 1. THE PI SERVER

The PI System is a set of software modules for plant-wide monitoring and analysis. It acts as
a data server for Microsoft Windows-based client applications. Operators, engineers,
managers, and other plant personnel use a variety of client applications to connect to the PI
Server to view plant data stored in the PI Archive or in external data storage systems.
The PI Server typically runs on one computer, while PI interfaces and client applications run
on a variety of other computers on the network. Such a distributed data collection architecture
offers several advantages over a monolithic architecture, including scalability, robustness,
and flexibility.
A PI Server includes:
‰ PI Server Subsystems: The processes, called subsystems, that comprise the PI Server.
‰ Configuration and administrative utilities.
‰ Interfaces, including Random and Ramp Soak for simulated data, and PerfMon,
SNMP and Ping for monitoring purposes.
‰ PI API and PI-SDK. This software is included with the PI Server for internal use by
the applications on the PI Server.
This chapter provides an introduction to these elements of the PI Server, and explains the
structure of the PI Server File system.

1.1 PI Server Subsystems

The PI Server consists of several interlocking processes, which this book refers to as
subsystems. The executable for each of the PI subsystems is installed in the PI\bin directory.
Six PI subsystems make up the core PI Server. Generally, the system cannot function to a
minimum level without these subsystems. Some subsystems depend on other subsystems for
proper behavior. All subsystems will wait for any dependent subsystems. The core PI
subsystems are listed in the following table.

PI Server Reference Guide Page 1


Chapter 1 - The PI Server

Subsystem Executable What It Does Dependency Issues

Archive piarchss.exe Stores and serves the data after it Requires the PI
comes out of the Snapshot Snapshot Subsystem.
subsystem. Data consists of multiple
timestamped measurements for each
data point. This includes values such
as on/offs, pressures, flows,
temperatures, setpoints, etc.

Base pibasess.exe Maintains the Point Database, Digital Requires the PI Update
State Table and configuration Manager
databases for user and group
security. It also hosts the PI Module
Database.

License pilicmgr.exe Maintains licensing information for


Manager the PI Server and all connected
applications

Message pimsgss.exe Records status and error messages Messages are routed to
for the PI Server in a control log file. the Windows Event log
or UNIX standard
output if this subsystem
is not available.

Network pinetmgr.exe Manages communication between PI


Manager Server subsystems, client
applications and interfaces. Also
validates clients at time of
connection. Clients may be standard
products such as PI ProcessBook, or
they may be user-written PI API or PI
SDK programs.

Snapshot pisnapss.exe Stores the most recent event for each Requires the PI Update
point. Applies compression, sends Manager.
data to the Event Queue, and serves
Snapshot events to the client
applications.

Update piupdmgr.exe Sends notifications of changes in These services are


Manager values or point attributes to any essential for proper
interface or client application that is operation of a PI
signed up for notification. Server; it is required by
most of the PI
Subsystems and most
client applications.

In addition to the core PI Subsystems, the PI Server includes additional subsystems such as
Batch and Performance Equation Scheduler. These subsystems do not need to be running in
order for PI to be running. Some of these subsystems are licensed separately and might not be
installed on your PI Server.

Page 2
1.2 - Configuration and Administrative Utilities

Other Subsystems

Subsystem Executable What It Does

Alarm* pialarm.exe Provides alarm capabilities for PI points.

Backup pibackup.exe Manages backups of PI.

Batch* pibatch.exe Detects and records batch activity.

Performance pipeschd.exe Performs PI Performance Equation calculations for PI calculated


Equations* points.

Recalculator pirecalc.exe Automatically adjusts values of Performance Equation (PE)


points.

Redirector piudsrdr.exe The Base, Archive, and Snapshot Subsystems use the
Redirector to obtain data from the external systems.

Shutdown pishutev.exe Determines when the PI system was stopped and writes
shutdown events to points configured to receive these events
(runs only at startup and then stops)

SQL pisqlss.exe Prepares and executes SQL statements directed at the PI


Server. The primary users of this subsystem are the PI ODBC
Driver and the PI SDK.

Totalizer* pitotal.exe Performs postprocessing calculations on a point in the


snapshot, storing the results in a PI “Totalizer” point.

* indicates a separately licensed subsystem

1.2 Configuration and Administrative Utilities

The PI Server for Windows and UNIX includes several utilities that are used to configure
points, monitor the data flow, manage the archives, and configure the security settings.
The PI Server comes with a wide variety of configuration and administrative utilities:

Utility Location Description

apisnap PI\adm A tool for checking snapshot values.

piarchss PI\bin PI Offline Archive Utility. This is actually the archive subsystem
executable—which you can run with command-line options, as a utility.

piarcreate PI\adm Archive creation utility. Once created, Archive files can be mounted
using piartool.

piartool PI\adm PI Archive Tool. This utility includes many commands to monitor,
inspect or modify the state of a running PI Server.

piconfig PI\adm A tool for configuring PI Server databases, such as the Point database
and the Digital State table.

PI Server Reference Guide Page 3


Chapter 1 - The PI Server

Utility Location Description

pidiag PI\adm A tool for PI diagnostics and repair.

pigetmsg PI\adm A tool for viewing PI Server messages.

pilistupd PI\adm A tool for monitoring the Update Manager, specifically for looking at
Event Queues.

pipetest PI\adm Performance equation test utility.

pisetpass PI\adm A tool for changing user passwords

pisnap PI\adm Starts apisnap against the local PI Server

pisqlss PI\bin Pisqlss is actually the SQL Subsystem—which you can run with
command-line options, as a utility.

piversion PI\adm Use piversion –v to get the version and build numbers of the PI Server.

To view usage information for any of these utilities, use the -? argument. For example:
pilistupd -?

1.2.1 Using Command-Line Tools Remotely


It is useful to be able to run the PI administration tools remotely. A piconfig session may be
run remotely by issuing the Login command.
The piartool, pigetmsg and pilistupd utilities can be run remotely by specifying four
parameters:
‰ PI Server home node host name or IP address
‰ PI user account name
‰ PI user account password
‰ Port ID (defaults to 5450)
For example:
pilistupd -remote
This requires PI-SDK installation on the client.

1.2.2 Displaying the PI Version Number


Get PI Server version and build numbers by typing:
piversion –v
From the PI\adm directory.
If you have applied a patch to your PI Server, the version numbers of the executable modules
affected will be different from that shown by piversion -v.
When a module is executed using the -v option, the module is not actually started; only the
version number is displayed.

Page 4
1.3 - Interfaces Installed with the PI Server

1.2.3 Checking Snapshot Values (apisnap and pisnap)


On both Windows and UNIX platforms, there is a utility in the PI\adm directory called
apisnap that shows the current value (Snapshot) for a specified point.
When you run the apisnap utility on the PI Server, it prompts you for a point name. (To quit
the utility, press <Enter> instead of entering a point name).
The apisnap utility accepts as a parameter the network name (and optionally, a TCP/IP port
number) of a computer running a PI Server. For example, to connect to a PI Server running
on the same computer, you would enter:
apisnap localhost:5450
There is also a script in the PI\adm directory called pisnap.bat on Windows and pisnap.sh on
UNIX. This script runs the apisnap utility and connects to PI on the same computer.

1.3 Interfaces Installed with the PI Server

Each PI Server includes several interfaces. Two of these, Random and Ramp Soak, are
simulator interfaces. They can be configured to simulate random, sinusoidal, and batch data.
These are installed on the PI Home Node, but may be run remotely.
Three additional interfaces are useful for monitoring the health of your system and network.
Each is limited to a maximum of 512 performance points in the Point Database and can only
be run on the PI Home node.
‰ PerfMon reads Performance Counters on Windows systems and stores the values in
PI points,
‰ SNMP collects performance data from computer systems and network routers using
the Simple Network Management Protocol, and stores the values in PI points.
‰ Ping monitors the network availability of computer systems by pinging them and
stores the response times in PI points.
A version of the interface without the 512-point limit may be purchased separately.

1.3.1 Interfaces to Other Data Sources


Interfaces are software modules for collecting data from any computing device with
measurements that change over time. Typical data sources are Distributed Control Systems
(DCSs), Programmable Logic Controllers (PLCs), lab systems, and process models. Most
interfaces can also send data in the reverse direction, from PI to the foreign system.

1.4 PI Application Programming Interface (API)

The PI Application Programming Interface (PI API) is a library of functions that allow
programmatic access to the PI System, both for data archiving and for retrieval. OSIsoft uses
the API internally to create interfaces that run on a variety of platforms. Users may also use
the API for their own applications.

PI Server Reference Guide Page 5


Chapter 1 - The PI Server

The PI API is a library of functions that may be called from C, Visual Basic, or other
languages. These functions let you read and write values from the PI Server. They also let
you retrieve point configuration information.
The PI API also provides the ability to buffer data that is being sent to PI. This allows PI to
be taken offline for software or hardware upgrades without compromising data collection.
When PI becomes available again, the buffered data are then forwarded to PI.
API nodes are UNIX or Windows workstations that run programs such as interfaces that are
based on the PI API.

1.5 PI Directory Structure

The PI Server file organization is a little different for Windows and UNIX platforms. Refer to
the section for the appropriate operating system.

1.5.1 Windows Directory Structure


By default, PI installs its files in a folder called PI on the disk with the most available space,
but you can choose a different location for PI during installation. Within the PI directory, PI
installs a few subdirectories.

Directory Contents

PI\adm Contains administrative tools.

PI\bin Contains subsystem or PI service executables.

PI\dat Contains databases such as points and digital states. This is also the
default directory for Archive files and the Event Queue.

PI\interfaces Contains interfaces that were installed with previous versions of PI. Is
not present on new PI Server installations, but might be present on
Servers that are running upgrades.

PI\log Contains log files.

PI\setup Contains files for install and uninstall.

The PI directory structure for Windows systems differs depending on whether the system is a
new installation or an upgrade.

PI Interfaces Directory on Windows


PI installs interfaces in a directory called PIPC. The PIPC directory tree, if it does not exist,
is created during the installation of the PI-SDK. Refer to the PI-SDK documentation for more
information about the PI-SDK installation.
Previous versions of PI installed interfaces in a directory called interfaces under the main PI
directory. If your PI Server is based on an upgrade, rather than a new install, then older
interfaces might be located in the PI/interfaces directory. For upgrades, interfaces that have
been installed in the PI directory tree will remain in the PI directory tree. All other interfaces
are installed in the PIPC directory tree.

Page 6
1.5 - PI Directory Structure

1.5.2 Windows File System Concerns


When running PI on Windows, OSIsoft recommends the following:
‰ Disable virus scanning on the archive and database folder. Virus scanning may
corrupt active files (e.g. the primary archive). The problem with virus scanning is
that, because the data is random, it might have a bit pattern that matches a known
virus signature. The virus scanning software then locks and quarantines the PI Server
file.
‰ Don't use the Windows File System Compression feature on the PI Server. When
you use compressed files, you slow down PI's access to Archive files. The
compression might save disk space, but it requires more CPU resources.
The following sections explain these recommendations in more detail.

Windows File Compression


Using compressed files can slow down the access to the Archive files, and thus degrade the
performance of the whole system. This is especially true on files that are constantly changing,
such as the primary archive, the Event Queue or the current message log file.
OSIsoft recommends that you do not use the File System Compression feature of Windows.
If you use this compression, while it may save disk space, it will require more CPU resources
each time data arrives at the Archive or database files or is accessed by clients.

Using Anti-Virus Software


OSI Software recommends against using anti-virus software to scan the directories containing
PI Server database and Archive files on systems collecting production data.
To be effective, anti-virus software must be configured to immediately scan files whose
contents change. The contents of the PI Server Archive files change constantly as archive
cache records are regularly flushed from memory to disk. Archive files tend to be large,
which means that the time required to scan can be quite long. In addition, if any random bit
pattern in an Archive file happens to match a known virus signature, the anti-virus software
can lock or otherwise quarantine the Archive file. This corruption of the Archive file system
has happened at several sites, resulting in the unrecoverable loss of production data. The
same situation can occur for other PI Server database files, although these files change less
often.
Anti-virus software should be configured to exclude scanning the PI\dat directory and any
directory containing Archive files. The PI\dat directory does not contain any executable
programs or scripts.
Another effective technique for protecting a production PI Server from Internet hackers is to
install a firewall between the Internet and the server. For maximum protection, the firewall
can be configured so that it stops all incoming Internet traffic except for those packets which
(1) originate from safe, user-specified IP addresses, and (2) are destined for TCP/IP port 5450
on the PI Server computer. Downloaded files, or files from an unverifiable source could be
scanned for viruses on a separate "quarantine" computer before moving them to the PI Serve

PI Server Reference Guide Page 7


Chapter 1 - The PI Server

Other Files on Windows Systems


On Windows systems, the PI System may use the file, WINNT\system32\pdh.dll – this is the
Microsoft Performance Data Helper library, which is used by the PI Performance Monitor
interface. This file is loaded or upgraded on your system during the normal installation
procedure.
Additionally, the PI-SDK places some Windows files during installation. The files placed by
the PI-SDK are listed in the PI-SDK Release Notes, which are installed in the SDK
subdirectory of the directory indicated by the pihome entry of the pipc.ini file.

1.5.3 UNIX Directory Structure


The PI directory structure for UNIX systems:

Directory Contents

PI/adm Contains administrative tools.

PI/bin Contains the PI System executables.

PI/dat Contains data files such as the Point Database

PI/interfaces Contains subdirectories with executables for each of the interfaces.

PI/lib Contains libraries used by PI.

PI/log Contains all PI log files. Log files for the interfaces may also be found in the
PI\interfaces subdirectories.

PI/patches Contains miscellaneous files that may be needed for some installations.

Other Files on UNIX Systems


There are a few files used by the PI System that are not located under the PI directory. On
UNIX systems, the following files may be used by the PI System:
/etc/piparams.default - This file is created during PI installation.
/etc/passwd - This file is modified to create the piadmin and OSI login accounts.
/etc/group - This file is modified to create the pigrp group.
/usr/lib/libC.ansi.sl - This file is needed only on some platforms. The file name may vary.
/usr/piadmin/.profile - This file is modified by the System Administrator to define the
shared library path environment variable if using the Korn shell. It is needed only on
some platforms. The path may vary, depending on the installation The environment
variable varies depending on the platform.
/usr/piadmin/.chsrc - This file is modified by the System Administrator to define the
shared library path environment variable if using the Korn shell. It is needed only on
some platforms. The path may vary, depending on the installation. The environment
variable varies depending on the platform.

Page 8
Chapter 2. PI DATA FLOW

This chapter describes the flow of data through a PI Server and interfaces. PI typically stores
data in the PI Data Archive, which is managed by the PI Archive Subsystem. However,
Windows-based PI Servers can also retrieve data from foreign data-storage systems. Foreign
data-storage systems are, for the purposes of this book, any data systems other than the PI
Data Archive.
This chapter begins by explaining the flow of data from data sources to the PI Data Archive.
Later sections discuss data retrieval, both from the PI Data Archive and from foreign data
storage systems. This chapter contains the following sections:
‰ Data Flow from Data Sources into the PI Archive begins on page 9
‰ Data Retrieval from the Archive begins on page 13
‰ PI Data Retrieval with Foreign Data Sources begins on page 14

Note: In the PI Server for UNIX, there is no COM Connector capability. All data must
be stored in the PI Data Archive.

2.1 Data Flow from Data Sources into the PI Archive

The fundamental unit of data storage in the PI System is called an event. An event consists of
a timestamp, a value, and a status. In the simplest terms, interfaces collect data from data
sources, then send these data to the PI Server in the form of events. The PI Server then stores
these events in the PI Archive. This simple view of PI data flow is shown in the following
illustration.

PI Server Reference Guide Page 9


Chapter 2 - PI Data Flow

In reality, the data flow is more complex than the preceding illustration indicates. The most
important thing to understand about PI data flow is that PI does not save every single event
that an interface collects. Instead, PI stores only significant events. A significant event is one
that is essential for recreating the original data. PI discards events that are not significant.
This section provides a more detailed description of the data path that an event follows from
the data source to the PI Data Archive and describes the places in the data path where PI
evaluates a point to see whether it is significant. The basic steps along the path are as follows:
1. The interface collects the data from the data source. The data sources can be almost
anything, including Distributed Control Systems (DCSs), Programmable Logic
Controllers (PLCs), lab systems, Supervisory Control and Data Acquisition systems
(SCADA), process models, and other business information systems. PI Performance
Equations, ACE, and Totalizer are also all data sources.
2. Each different data source needs a PI interface that can interpret it. Most PI interfaces
run on a separate computer, called an Interface Node. (The Interface Node is
sometimes also called the API Node.)
3. The PI interface uses exception reporting to determine which events to pass on the PI
Server and which are not needed. Exception reporting is a simple linear test that
determines whether the incoming value is significantly different from the existing
value. You set the specifications for exception reporting in the tag attributes for each
point. By tuning these exception specifications, you can ensure that the interface
passes on only values that are of interest to you.
4. The interface sends significant events to the buffering service, if the buffering service
is configured for that interface.
5. The buffering service sends the events on to the PI Server or, if the Interface Node
cannot connect to the PI Server, the buffering service holds the data until the Server
connection is restored. This is an important mechanism for safeguarding your data, so
it’s important to configure buffering for your interfaces, where possible.

Page 10
2.1 - Data Flow from Data Sources into the PI Archive

6. When an interface sends an event to the PI Server, it goes first into the Snapshot
Subsystem. The Snapshot Subsystem holds a “snapshot” of each point in the point
configuration database. This snapshot includes: the current value of the point, the last
archived value, compression specifications, and security attributes.
7. The Snapshot uses the information about each point to decide what to do with
incoming events for that point. If an event is out of order, the Snapshot sends it
straight to the archive. If the event is not out of order, the Snapshot Subsystem
applies the compression test.
8. PI uses the compression test to decide whether an event is significant. As in
exception reporting, you set the specifications for compression in the tag attributes
for each point. Unlike exception reporting though, compression testing is not linear.
PI uses a very sophisticated compression algorithm to determine whether it needs a
particular value in order to accurately reconstruct the data curve for a particular point.
9. If the event passes the compression test, the Snapshot sends it to the PI Event Queue.
10. The Archive Subsystem retrieves events from the Event Queue. Since the Event
Queue is a memory-mapped file, the events in it are persistent. This means that they
are recoverable in cases of unexpected crashes or delays.

2.1.1 The Snapshot


A new event entering the PI System from an interface or manual input program is sent to the
Snapshot Subsystem. The Snapshot is the most recent event for a point. It can be viewed as a
buffer that is only one element deep. When a new event comes in, it becomes the new
Snapshot. The previous Snapshot is evaluated according to the compression specifications
and is either sent to the Event Queue or discarded.
Any event that has a timestamp older than the Snapshot will not become the Snapshot.
Instead, it is sent to the Archive Subsystem through the Event Queue.
Event values are always stored in full precision in the Snapshot. Scaling, if applicable, is
applied when the event is stored into the Archive. For more information on scaling, see the
section on point types in Chapter 3, PI System Databases.
When the archive events for a point are listed or trended by PI ProcessBook and other tools,
the Snapshot is automatically included in the list.
The Snapshot Table resides in memory. It is flushed to disk (piarcmem.dat) by the Snapshot
Subsystem at least every 15 minutes.

2.1.2 The Archive Subsystem


The PI Snapshot sends events that pass compression to the Archive Subsystem. When events
enter the Archive Subsystem, they do not go directly to Archive files for storage. Instead,
they go first to the Archive Event Queue, which sends them to the Archive Write Cache.
Finally the Archive Write Cache sends the events to the Archive Files themselves for storage.

PI Server Reference Guide Page 11


Chapter 2 - PI Data Flow

SnapShot
1
2 Queue(s)
3
4 Compress
5
New Event
file(s)

Cache
0 m
RecNo 0

Other
On-Line
Archives
n Primary
Archive

Figure 2-1. Processing of New Events

The Event Queue


Events that have passed the compression filter are placed in the Event Queue. This includes
events that are out of order, events for points whose status has changed, and events for points
with the Compression attribute set to OFF.
The Event Queue has the job of buffering the incoming process data on the way to the
Archive. The operation of the queue protects the data against loss should any of the following
system upsets occur:
‰ Loss or failure of the Archive Subsystem
‰ Surge of process data from process or other upset
‰ Temporary CPU loading of the computer running PI
The memory-resident Event Queue is always backed up on disk (pimapevq.dat). If the queue
becomes full due to long delays in the Archive Subsystem, up to 65,535 additional queues
may be created. When the Archive is able to recover from the cause of the upset, all the
queues are processed in the order created.
The default size of the Event Queue is 64 megabytes but it may be configured from 8
megabytes to 128 gigabytes. The amount of free space on the disk is generally the only
limitation on the size and number of queues.
The Event Queue is located in the PI\dat directory, but can be on a different volume. The
System Manager should ensure that adequate free disk is maintained on that volume. When
the Archive Subsystem is unavailable, you may need an average of 5 kilobytes of free space
per point per day. This assumes 250 events per point per day for a floating-point tag.

The Write Cache


When the Event Queue sends an event to the Archive Subsystem, the Archive keeps it first in
the Write Cache, which is a memory array that stores events for each point. The Write Cache

Page 12
2.2 - Data Retrieval from the Archive

stores events for a point in memory until the data reaches certain configurable limits on size
and/or time since the last write to disk. Then the Write Cache data for that point is written to
the Archive files. By holding events for each point up to the specified limits, PI reduces the
frequency of disk access, improving overall performance.
Specifically, write cache events are flushed to disk at the following times:
‰ When the Write Cache for a particular point reaches the maximum size, the data for
that point (and just for that point) is flushed to disk. The maximum number of events
in the Write Cache for each point is 256, but this is configurable by the
Archive_MaxWriteCachePerPoint setting in the timeout table.
‰ Every record in the Write Cache is flushed at least once every Flush Cycle. The
default cycle is 900 Seconds (15 minutes) and can be configured using the timeout
parameter Archive_SecondsBetweenFlush.

2.2 Data Retrieval from the Archive

Many applications request data from the PI Server system, for example, trends or PI
DataLink. Every such request translates into a low level call to the archive that retrieves the
raw data, values and timestamps. This raw data is always exactly what was put into the
archive by the interface. However, there are two exceptions where the data-retrieval functions
generate an extra event.
When the request spans a time period with no mounted Archive files, a digital state of Arc
OffLine is inserted one second after the end of the last scanned Archive file. This prevents
the interpolation of data over an unknown period, for example when an archive is offline for
maintenance.
This option is active by default but can be disabled by setting the timeout parameter:
MarkArchiveGaps, 0
Similarly, when requests for data go into the future, a NoData digital state is inserted one
second after the current time. If the Snapshot is in the future, then the NoData digital state is
inserted one second after the Snapshot, in order to prevent data extrapolation into the future.
The PI server rejects Snapshots more than 10 minutes into the future.
Requests for data before the oldest registered archive also return NoData.
Since these two digital states are used within the PI Server, we recommend not inserting them
into the archive as this can lead to misinterpretation of data-retrieval results.

2.2.1 The Archive Read Cache


The read cache is a piece of memory that contains a linked list or records for each point. The
read cache has a one-to-one relationship with records in the Archive. When a client asks for
data from the Archive, the Archive translates that data to Record Number, and then figures
out if the data being requested is in the Read Cache already. If not, it determines in which
Archive to go look for the data.

PI Server Reference Guide Page 13


Chapter 2 - PI Data Flow

The size of the Read Cache is configurable and, by default, a single point can use as many as
512 records from the pool. This number is configurable with the
Archive_CacheRecordsPerPoint parameter (the maximum value is half the cache pool).
Assuming enough memory resources, the limit on the total number of records in the Read
Cache is set to 4 times the point count, but can be manually overwritten by the
Archive_CacheRecordPool parameter.
You can use piartool -cas (cache statistics) to view cache information for a point, and
piartool -cad (cache diagnostics) to dump the information in both the read and write caches.

2.3 PI Data Retrieval with Foreign Data Sources

Data are sometimes not stored in the Archive or Snapshot Subsystem. They may be stored in
an external or ‘foreign’ data source. The Base, Archive, and Snapshot Subsystems can
request data from foreign data storage systems through modules called COM Connectors.
Each COM Connector is coded to interact with a specific foreign data system. A separate
COM Connector must be installed to communicate with each specific foreign data system.
A PI Server system may have any number of COM Connectors installed. Since the identity of
the COM Connector to use is determined on a point-by-point basis, a single PI Server system
can access any number of foreign data systems. It is not necessary to dedicate an installation
of PI Server strictly to communication with external systems.
The core Subsystems of the PI Server do not communicate directly with COM Connectors.
Instead, the Subsystems send requests to the PI Server Redirector, which acts as a request
broker. The Redirector loads one or more COM Connectors and forwards the requests to
them.

Note: The Redirector is a module in PI Server for Windows only. PI Server for UNIX
does not support the use of COM Connectors or the Redirector.

The Redirector and the COM Connectors are COM objects, implemented using Microsoft
Component Object Model (COM) technology. The Redirector is installed as part of the PI
Server. COM Connectors are installed separately.
COM Connectors are installed on the PI Server, but are not loaded into the Server’s memory
until needed. When PI shuts down, the Redirector and all COM connectors are automatically
unloaded from memory.
COM Connectors may be in-process or out-of-process COM objects. In-process COM objects
are .dll files, while out-of-process COM objects are .exe files. OSIsoft has developed some
COM Connectors to specific data systems. Others may be available from vendors or
integrators. In general, the decision to build an in-process vs. an out-of-process COM object
is made by the COM Connector developer.
The PI Server Redirector is an out-of-process COM object. It does not run as a service, which
means it will not be found in the Services control panel applet. When the Redirector is
running, system managers will be able to see a process called piudsrdr.exe in the Processes
tab of the Windows Task Manager.

Page 14
2.3 - PI Data Retrieval with Foreign Data Sources

Client applications are not aware of the difference between data retrieval from the PI Data
Archive and data retrieval from a foreign data storage system using a COM Connector. In all
cases, the application connects to the PI Network Manager. Each point from which data are
retrieved is identified by a tag, and has attributes stored in the PI Point Database, regardless
of the source of the data. The differences in data flow are implemented by the Snapshot and
Archive Subsystems. Details are in the sections Retrieval of Snapshot Data and Retrieval of
Archive Data, below.
The PI Server sends data to client applications in exactly the same way, regardless of whether
the data is stored in the Archive Subsystem or in a foreign data source. The same is true of
data requests from PI Server Subsystems such as the Totalizer, the Alarm Subsystem, and the
Performance Equation Scheduler.
The PI Server can put new data into a foreign data system if it is supported by the COM
Connector for the foreign data system.

2.3.1 Point Configuration


In order to interact with a point on a foreign system, a corresponding point, called a mapped
point or COM Connector point, must be created in the PI Server Point Database.
A mapped point in the Point Database is simply one that links to data in a foreign-system.
To build a mapped point, you must select a point class that includes three specific attributes,
as well as the normal attributes of a point class. These three point attributes are shown in the
following table:

Table 2–1. COM Connector Point Attributes

Attribute Name Description

ctr_progid COM program ID, as stored in the Windows registry. This name is used to
invoke the COM Connector object when needed.

ctr_lmap Longword mapping parameter. ctr_lmap and ctr_strmap are passed to the
COM Connector so that it can locate the appropriate foreign system point.

ctr_strmap String mapping parameter. ctr_lmap and ctr_strmap are passed to the
COM Connector so that it can locate the appropriate foreign system point.

PI Server ships with a point class called classicctr that contains these three point attributes as
well as the base and classic attribute sets. You can create this point class by executing the
script PI\adm\classicctr.dif using the piconfig utility. You may also use the contents of this
script as a basis for your own point class definition.
You construct points according to the specifications of the point class. A complete list of
point attributes is listed in PI Server Databases on page 19 in the Point Database section.
Point creation and maintenance are done using the PI TagConfigurator, a Microsoft Excel
spreadsheet-based tool, or piconfig, a script-based tool.
Whenever the point information indicates that the requested point is a mapped point, the
Redirector will obtain data values from the corresponding foreign system point.

PI Server Reference Guide Page 15


Chapter 2 - PI Data Flow

2.3.2 Retrieval of Snapshot Data


When the PI Server Snapshot Subsystem starts, it is notified of the presence of mapped points
by the Base Subsystem. When a client application requests a Snapshot value, the Network
Manager routes the request to the Snapshot Subsystem.
If the point’s data are normally stored in the PI Data Archive, the Snapshot value would be
retrieved from the Snapshot Subsystem and then returned to the Network Manager.
If a Snapshot value for a mapped point is requested, the data path is different. In this case, the
Snapshot Subsystem requests the value from the Redirector, which in turn requests the value
from the appropriate COM Connector. The COM Connector obtains the value from the
foreign data storage system and returns it to the Redirector, which sends it to the Snapshot
Subsystem. Then it is routed to the Network Manager for transmission to the client.

Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector

2.3.3 Retrieval of Archive Data


The retrieval of Archive data from the COM Connector by the PI Server Archive Subsystem
is similar to Snapshot retrieval by the Snapshot Subsystem. When the PI Server Archive
Subsystem starts, it is notified of the presence of mapped points by the Base Subsystem.
When a client application requests archive values, the request is routed to the Archive
Subsystem by the Network Manager as before. The archive values are retrieved from the
subsystem and returned to the Network Manager for transmission to the client.

Page 16
2.3 - PI Data Retrieval with Foreign Data Sources

If archive values for a mapped point are requested, the data path is different. In this case, the
Archive Subsystem requests the value from the Redirector, which in turn obtains the value
from the appropriate COM Connector

Figure 2-3. DataFlow through Archive Subsystem, Redirector, and COM Connector

2.3.4 Archive Files


Even though Archive files are not used if data are retrieved using COM Connectors, the files
must exist and must be sized as if all points on the PI Server were PI Data Archive points.
Normal maintenance and backup procedures apply to the Archive files, with one exception: if
a PI Server installation consists entirely of mapped points, it will not be necessary to back up
the Archive files.

2.3.5 Exception Reporting


The COM Connection mechanism includes support for exception reporting. There is a ‘sign
up’ method that the PI Server Snapshot Subsystem will call in the COM Connector if a client
signs up for exceptions on a mapped point. The Snapshot Subsystem will obtain exception
values from the COM Connector by way of the Redirector.
If the foreign system does not support exception handling, it may be coded to return a
standard COM error code indicating that the method is not implemented.

PI Server Reference Guide Page 17


Chapter 2 - PI Data Flow

2.3.6 Compression
PI Server does apply the PI Data Archive’s data compression algorithm to mapped foreign
points. If the COM Connector supports putting new data values into the foreign system, then
that system is responsible for their storage. The foreign system may or may not support
compression.

2.3.7 Point Security


Data retrieved from foreign data system is subject to the same security as data values
retrieved from storage within the PI Data Archive. Every PI point, whether mapped or not,
carries a security descriptor that defines the access PI users may have to data.

Page 18
Chapter 3. PI SERVER DATABASES

The PI Server includes several databases that store PI configuration information and process
data. The two main databases are the Point Database and the Data Archive. Other parts of the
system, including the Snapshot Subsystem, the Digital State Table, and Module Database,
support the main databases.
System Management Tools as well as a set of command line utilities are used to configure
and manage the PI Server.
See also PI Server System Management, and documentation about free System Management
tools posted on the OSIsoft Web site.

3.1 Point Database

The most important configuration database is the Point Database. This contains the list of
points that are either recorded in the PI Data Archive or mapped to points in foreign data
systems when COM Connectors are used. The points whose data are stored in PI Data
Archive are sometimes called native PI points. The points whose data are stored in foreign
data systems are interchangeably referred to mapped points or COM Connector points. The
Point Database stores configuration information for each point as a list of point attributes.
Attributes are grouped into attribute sets, which in turn are grouped into point classes. The
Base class, Totalizer class and Classic class are some of the point classes commonly used in
PI. When a point is created, it is assigned a point class, which restricts the point to a specific
set of attributes.
For a complete explanation of the PI point classes and point attributes, refer to PI Point
Classes and Attributes on page 41.

3.2 Data Archive

The most important process information database is the Data archive. The archive is a
historical record of values for each point in the Point Database.
The Data Archive contains the time-stamped values for all the points in the Point Database.
The time-stamped values are stored in a set of disk files. Each file covers a different,
non-overlapping time period. Three archive files are created during installation. Additional
archives can be created when needed, using the utilities provided. The archive files may vary
in size.

PI Server Reference Guide Page 19


Chapter 3 - PI Server Databases

3.2.1 Archive Size Considerations


When an archive value is replaced, the new value is flagged in the archive as modified. This
results in additional storage being allocated for the replaced value. For numeric values the
size approximately doubles.

Caution: When you delete a point, the records for that point in the current archive
are made available for reuse. A consequence of this is that all history is irrecoverably
lost for the deleted point. Records in old Archive files that contain data for the
deleted point are not directly accessible. However, the data can be recovered using
the Offline Archive Utility using an ID-conversion table.

3.3 Snapshot

The Snapshot Database contains the most recent value, status, and time stamp for each point
in the Point Database.
The Snapshot database piarcmem.dat contains mostly frequently updated data. If this file is
damaged it can be rebuild using pibasess –snapfix. Snap fix rebuilds this file based on the
point database and sets all values to a Shutdown status; normal data collection quickly
replaces Shutdown statuses with new values. Many PI Systems have a few points that update
very infrequently; in this case these values will remain at Shutdown until a new Snapshot
value is received.
The PI Snapshot Subsystem actually maintains several databases. The pimapevq.dat
maintains the Event Queue. If pimapevq.dat (or pimq####.dat, where #### is a hexadecimal
number between 0000h and FFFFh) is corrupted, pisnapss may not be able to start. In this
case the file can be renamed and pisnapss will create a new one. Offline archive recovery
tools can be used to recover data from this file. The file pilastsnap.dat maintains the Snapshot
time of the newest event. This is used to determine the PI Server shutdown time. This file is
overwritten every 10 minutes and during PI Server shutdown.

File name Description

piarcmem.dat Snapshot database

pimapevq.dat Event queue (could also be pimq0000.dat, pimq0001.dat…)

pilastsnap.dat Time of newest event

Two utilities provide access to the Snapshot Database. The pisnap.sh (UNIX) or pisnap.bat
(NT) utility can be used to view the contents of the Snapshot. The piconfig utility can be used
to both view and modify the contents of the Snapshot.

3.4 Annotations

Every value in the Snapshot or the Archive may be annotated. An annotation can be of any
data type.

Page 20
3.4 - Annotations

Annotations can be accessed via the PI-SDK. Text annotations can be added and edited using
piconfig. This option should only be used for testing and verification.
Applications using the PI-SDK can add/edit annotations for a specified Archive event.
The Batch Database uses annotations to store the following object types:
‰ PIBatches
‰ PIUnitBatches
‰ PITransferRecords

3.4.1 Annotation Files


Annotations are store in an Annotation file. Each Archive file has a single associated
Annotation file. An annotation is a variant associated with a PI Event.

Note: The PI SDK supplies a programmatic interface for creating, accessing and
editing annotations. The PI SDK User Guide and online help are the best source for
details on valid variants for annotations.

Annotations are best understood with a simplified description of creating and accessing them.
For example:
1. A PI-SDK based application creates a variant. Variants can be of many types, such as
strings, an array of strings, various numeric types, etc. For this example, the variant is
an array of strings. The first string may be a lab technician’s name, the second string
may be a comment.
2. This same application creates a timed value, for example, a value and timestamp that
represent a manual measurement made on a piece of lab equipment. The variant
created above is associated with the timed value—the value is now annotated. The
PI-SDK is used to make this association. In this example, the annotation contains the
technician making the measurement and an associated comment.
3. The annotated value is then sent to the PI Snapshot. This is sent just as any other
event. The difference is that the event also contains the annotation.
4. Annotated events will always bypass compression. Upon reaching the Snapshot, the
annotated event is sent to the Archive via the Event Queue.
5. From the queue, the annotated event is written to the cache. Then, a few special steps
are taken writing the annotated event to the Archive.
First the target Archive and the Archive’s Annotation file is found. The variant that
represents the annotation is written to the Annotation file. On writing to the file, the
annotation is assigned a handle. The handle represents where in the Annotation file
the annotation was written.
Finally, the annotation handle is written to the event and the event is written to the
Archive. The event contains the timestamp, value and handle to the associated
annotation.

PI Server Reference Guide Page 21


Chapter 3 - PI Server Databases

6. Annotation retrieval starts by accessing the event. The event is accessed by normal
PI-SDK data access, such as get plot values or get archive value. Annotations may be
quite large, so annotations are never returned by normal Archive access. The PI-SDK
represents events as timed values.
7. The PI-SDK timed value, if annotated, supports retrieving the annotation. Annotation
retrieval requires a call the PI Server, where the annotation handle is used to read the
annotation from the Annotation file and return it to the caller.
8. Annotations may be edited and posted back to the PI Server to replace an existing
annotation. This works like any Archive event edit, except the event is annotated.
Filling an archive will cause a shift of both the Archive and Annotation file; filling an
Annotation file will cause a shift of both the Archive and Annotation file.
Annotation files grow as annotations are added; they generally use significantly less
space than the Archive. On most systems the Archive fills before the Annotation file.
The annotation size is limited by the Event Queue page size, which has a default size of 1MB
and a maximum size of 8MB. You set Event Queue page size using the timeout parameter,
Snapshot_EventqueuePageSize.
Annotation file statistics are shown with the archive listing utility piartool –al. The following
is output from an archive listing:
Archive[0]: D:\PI\dat\piarch.033 (Used: 1.8%)
PIarcfilehead[$Workfile: piarfile.cxx $ $Revision: $]::
Version: 7 Path: D:\PI\dat\piarch.001
State: 4 Type: 0 Write Flag: 1 Shift Flag: 1
Record Size: 1024 Count: 131072 Add Rate/Hour: 1.7
Offsets: Primary: 20/65536 Overflow: 128673/131072
Annotations: 10826/65535 Annotation File Size: 434144
Start Time: 19-Oct-05 12:39:10
End Time: Current Time
Backup Time: Never
Last Modified: 19-Dec-05 13:10:32
In the above listing, the Archive file is d:PI\arc\piarch.033. The corresponding Annotation
file is d:PI\arc\piarch.033.ann. There are 10,826 annotations; with room for a total of 65,535.
This number is configurable with the parameter Archive_MaxAnnotations, which only
controls the number of annotations in the primary archive. Note however that Annotation
files are limited to 2GB in size. In the above example, the Annotation file is 434,144 bytes (or
424KB).
The Annotation file always is identical path and name to the archive with the .ann suffix. As
archives are loaded, Annotation files are loaded, using this naming convention. The
Annotation file is created if it does not exist. It is important the Archive and Annotation files
remain together—most importantly when a backed up archive is restored.
‰ System management needs for Annotation files are simple—keep the Archive file
and corresponding Annotation file together:
• Archive backups should copy the Annotation file to the same backup location.

Page 22
3.5 - Digital State Table

• When an Archive is moved to a new location, move the corresponding


Annotation file to the same location.
• When an Archive file is deleted, delete the corresponding Annotation file to
avoid future name collisions.

3.5 Digital State Table

The Digital State Table contains the digital state sets. A digital state set has a name and
consists of a list of states, sometimes called digital state strings. For example, we can define
the digital state set Valve-state-set as containing the two states OPEN and CLOSE.
When retrieving digital state strings using the PI API, note that the state strings will be
truncated to 79 characters.

3.5.1 System State Set for All Points


The default set is called the System Digital State Set and contains over 300 digital states that
may apply to any tag. The following table describes some of these pre-defined digital states:

Table 3–1. Typical Digital States

State Use

I/O Timeout Interfaces use this state to indicate that communication with a remote device has
failed.

No Data Data-retrieval functions use this state for time periods where no archive values
for a tag can exist. 10 minutes into the future or before the oldest mounted
archive.

Under Range For float16 point types, this state indicates a value that is less than the zero for
the tag.

Over Range For float16 point types, this state indicates a value that is greater than the top of
range (zero+span) for that tag.

Pt Created A tag is given this state when it is created. This is the value of a tag before any
values have been put into the system for that tag.

Shutdown All tags that are configured to receive shutdown events get set to this state on
system shutdown.

Arc Off-line Used by data-retrieval functions to indicate a period of time not covered by any
mounted archive.

Bad Input Interfaces use this state to indicate that a device is reporting bad status.

The System Digital State Set also contains all of the digital state strings found in the PI 2.x
Digital State Table. See the PI Server System Management Guide for details on how to get a
list of these.

PI Server Reference Guide Page 23


Chapter 3 - PI Server Databases

Note: The last possible state in the System Digital State Set (number 16383) is
reserved for the PI System’s internal usage. OSIsoft recommends minimizing
changes to the System Digital State Set. At most, you can translate the states into
another language without changing their meaning. Digital points should use a user-
defined digital set. Not the System Digital State Set.

3.5.2 Defining a Custom Digital State Set


For a digital tag, there are typically only a small number of valid states. Before defining the
tag, a custom digital state set containing just those valid states is defined. When the tag is
defined, it is assigned the custom digital state set.
There is no need to include System states in custom sets because the System states contained
in the System state set will be used where needed by the PI Server. You may define up to
16383 state sets with up to 16383 states in each set.
For example, suppose a valve position is reported by an instrument system as having a digital
code value of 0 or 1. The value 0 means that the valve is closed, while the value 1 means the
valve is open.
Before configuring this tag, it is necessary to establish a digital state set with two strings,
CLOSED and OPEN. You might name it Valve Position. Other tags that also have states of
CLOSED and OPEN could be defined to use the same digital state set, Valve Position. Tags
that have states of ON and OFF would use a different digital state set, which you might have
called Switch Position.
The digital code value (0 or 1) is determined by the PI Server according to the position of the
state (digital state string) in the Digital State Table. The first value is 0 (zero), the second one
is 1, the third is 2, etc. This is termed digcode in PI API.
When retrieving state strings, PI API returns a maximum of 79 characters.

Editing the Digital State Table


The Digital State Table may be viewed and edited using the piconfig utility or the PI System
Management Tools (SMT), which are discussed in PI Server System Management Guide.
Changing a state string affects the retrieval of values already in the archive. If you change the
first state string in the example above from CLOSED to SHUT, all values in the archive are
reported with the new state string instead of the old one.
If you wish to affect only new values being received by the archive, you can define a new
state set and change the point attribute to use this new state set. In this example, values of 0
recorded before you change the DigitalSet point attribute have a value of CLOSED. Values
of 0 recorded after the point attribute edit will have a value of SHUT.

Deleting a Digital State Set


Once a set has been defined, it cannot be deleted. Attempting to delete a complete set will
result in a set named DIGSET_nn, where nn is the set number. This is to ensure that old
archive events can always refer to a valid set.

Page 24
3.6 - Timeout Database

Capitalization of Digital State Names


Like tags, digital state names are not case-sensitive. If you define a state with all capital
letters (for example OFF) then any later references to that state are not case sensitive (so off
or Off are valid references to your state set called OFF). for display purposes. Leading and
trailing blanks are removed from state names. Blank states are not allowed.

3.6 Timeout Database

The PI Timeout database, also called the Timeout Table contains a variety of PI Server
configuration parameters. Originally the PI Timeout database contained only timing
parameters, but other PI Server settings are now included in the Timeout database. In most
cases, the default values for these parameters are best, however in some situations you might
want to adjust one or more parameters to tune the PI Server performance.

3.6.1 Table of Configurable Timeout Database Parameters


The following table lists the Timeout Table Parameters that are configurable. To edit Timeout
database parameters, use piconfig or the Timeout Table editor in the PI System Management
Tools (SMT). Modifications to the Timeout Database will only be recognized upon restarting
PI.

Table 3–2. ConfigurableTimeout Parameters

Subsystem Name Min – Max Read Description


(Default)
All <subsysname>_Bac 30 – 86400 Periodically This is the maximum number of seconds
kupTimeout (1800) when in to remain in system backup mode. This
system timeout parameter only pertains to the
backup piartool –systembackup command,
mode which is used to take the audit databases
offline. The parameter has no effect for
VSS backups or non-VSS backups that
are started with the piartool –backup
command.
All <subsysname>_Thr 1–- startup only Size of the subsystem message thread
eadCount (4 threads) pool. Message threads are dedicated to
RPC request processing. Depending on
the number of processors on the machine,
this value may be increased so more RPC
requests can be handled simultaneously.
If all the threads are busy, RPCs are
queued up and processed in chronological
order. Note: the default for the Archive
Subsystem (piarchss_ThreadCount) is 8
worker threads instead of 4 for all other
subsystems.

PI Server Reference Guide Page 25


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
All <subsysname>_Ma depend on startup only Limits the number of concurrent, identical
xThreadsPerClientQ value of queries from a client. The possible value
uery <subsysnam range depends on the number of RPC
e>_ThreadC threads for a subsystem. For example, if
ount the number of threads is 8, then the
(0) possible values range from -7 to 7.
A negative value means that the same
request from the same client can
consume all but that number of threads
concurrently.
A positive value means that the same
request from the same client can
consume a maximum of that number of
threads concurrently.
A value of 0 implies no limits.
When exceeding the number of
concurrent threads allowed, the client gets
the following error message:
“[-10767] Client exceeded maximum
concurrent queries in RPC thread pool.”
All SBHThreshold 0 – 1920 startup only Threshold for CRT library small block
(128 bytes) heap memory allocation

All <subsysname>_Writ 10 – 900 Startup only PI internally keeps track of the last
eModTimesToFileP (60 sec) modified date of most of the files that it
eriod needs to back up. The last modified times
for each subsystem are updated every
WriteModTimesToFilePeriod. The
smaller the period, the more accurate the
last modified time will be.
A complete list of backed up files along
with their last modified dates can be listed
with the piartool –backup –identify -
verbose command. For archives, the last
modified date can also be viewed with
piartool –al.
Note for Archive files:
When a value is written to a PI point, the
value is not actually written to the archive
until the archive cache is flushed. The
maximum period between archive flushes
is set with the
Archive_SecondsBetweenFlush timeout
parameter. After the cache is flushed, the
last modified time will be updated within
WriteModTimesToFilePeriod seconds.
Archive Archive_AutoArchiv - before every Automatic Archive file creation on shifts. If
eFileRoot (path + shift present, this parameter defines the path
name prefix) and file name prefix to be used for new
archives. Example: "C:\PI\arc\auto_"

Page 26
3.6 - Timeout Database

Subsystem Name Min – Max Read Description


(Default)
Archive Archive_BackupCut 01-Jan-70 – Before every Archives that contain data more recent
offDate NA backup than the Archive_BackupCutoffDate will
(01-Jan-70) be backed up. For example, if “*-30d” is
specified, then at least 30 days of data will
be backed up.
Archive Archive_BackupLea 5 – 86400 On backup Number of seconds before the predicted
dtime (1800 sec) startup archive shift that a non-VSS archive
backup may start. The PI Backup
Subsystem will wait up to 30 minutes for
the archive shift to complete. This timeout
parameter has no effect on VSS backups.
Archive Archive_BSTimeout 1 – 86400 Once a This timeout parameter is now obsolete.
(1800 sec) minute

Archive Archive_CacheClea 1 – Flush startup only Frequency at which read-only cache


nCycle Cycle cleanup operations are performed. Setting
(10 sec) this limit too low may affect the
performance of the Archive Subsystem.
Archive Archive_CacheHigh 100 – 200 startup only High cache cleanup threshold, in
PctLimit (110 percentage of the
percent) Archive_CacheRecordPool value.
Oldest cache records are deleted when
the read-only cache pool is above this
limit, regardless of
Archive_MaxIdleCleanCycles.
Archive Archive_CacheLow 20 – 100 startup only Low cache cleanup threshold, in
PctLimit (80%) percentage of the
Archive_CacheRecordPool value.
Oldest cache records stop being deleted
when the read-only cache pool is below
this limit.
Archive Archive_CacheReco 2048 – startup + Maximum number of archive cache
rdPool 1048576 end of each records for read access queries. The
(4 x ptcount flush cycle actual size of the read-only cache pool
records) may lower due to low physical memory
resources.
Archive Archive_CacheReco 4 – cache startup + Maximum number of archive cache
rdsPerPoint epool / 2 end of each records per point. In the default
(512 flush cycle configuration, up to 512 records may be
records) allocated to a single point.

Archive Archive_CacheTrim 1 – 75 startup only Percentage to trim the read and write
Percent (40 %) cache when low physical memory
resources are detected.

PI Server Reference Guide Page 27


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
Archive Archive_DataCoerci 0–3 startup only Error handling policy of archive event
onPolicy (0) coercion after point type changes. Archive
events are preserved (i.e. not modified)
when the type of a point is modified after
its creation. When clients request these
events, automatic data coercion is
performed. This parameter decides what
the Archive Subsystem should do when
this coercion fails. For more details,
please refer to the chapter “PI Point Type
Edit” on page 81.
Archive Archive_EventQueu 1 – 255 startup only This parameter is now obsolete in version
eThreadCount (5 threads) 3.4.370, a single Event Queue thread now
exists (see Archive_FlushThreadCount
below).
Archive Archive_FlushThrea 1 – 255 startup only Number of Flush threads responsible for
dCount (4 threads) saving write cache events to disk. These
threads communicate with the Event
Queue thread via a Flush Queue (see
also Archive_FlushQueueSize).
Archive Archive_FlushQueu 16 – 8192 startup only Size of the Flush Queue between the
eSize (256 flush EVQ (Event Queue) thread and the Flush
tasks) threads. A flush task is created when a
point’s write cache events must be saved
to disk. Increasing this parameter may
improve the archive write throughput in
some cases.
Archive Archive_LowDiskSp - once a Minimum amount of free disk space to
aceMB (256 MB) minute with leave on Archive file volumes. A dynamic
a dynamic primary archive will stop growing if this
primary limit is reached and a shift will be
archive + on triggered.
shifts when
Archive_Au
toArchiveFi
leRoot is set
Archive Archive_MaxAnnota 128 – startup only Maximum number of event annotations
tions 134217728 per Archive file (annotations are stored in
(65,535 the parallel file with the .ann extension).
annotations)
Archive Archive_MaxIdleCle 1 – 60 startup only Maximum idle time of archive cache
anCycles (2 flush records before being discarded. This
cycles) number is expressed in number of flush
cycles
(Archive_SecondsBetweenFlush).
Archive Archive_MaxWriteC 0 – 2,048 startup + Maximum number of write cache events
achePerPoint (256 events) end of each per point. Events of a given point will be
flush cycle flushed to disk when this limit is reached.

Page 28
3.6 - Timeout Database

Subsystem Name Min – Max Read Description


(Default)
Archive Archive_MinCacheR 1,024 – startup only Minimum size of the record pool when
ecordPool 102,400 doing cache trimming due to low-memory
(2,048 conditions.
records)
Archive Archive_MinMemAv 0 – 1,024 startup only Minimum amount of free physical memory
ail (10 MB) to leave for OS and other subsystems.
The Archive Subsystem will start trimming
its cache when physical memory
resources go below this or the
Archive_MinPercentMemAvail
percentage.
Archive Archive_MinPercent 0 – 50 startup only Minimum percentage of free physical
MemAvail (0%) memory to leave for OS and other
subsystems. The Archive Subsystem will
start trimming its cache when physical
memory resources go below this or the
Archive_MinMemAvail value.
Archive Archive_MinWriteCa 1 – 1,024 startup only Minimum number of write cache events
chePerPoint (8 events) per points when doing cache trimming due
to low-memory conditions.
Archive Archive_PointLockL 0 – timeout startup only Archive lock delay reporting option. By
ogging (5,000 ms) default, threads taking longer than 5
seconds to acquire a lock will report in the
message log. A value of 0 disables lock
time reporting.
Archive Archive_PointLockTi 1000 – startup only Maximum time RPC (query) threads can
meout 270,000 wait accessing archive points. Default is 2
(120,000 minutes (120 seconds).
ms)
Archive Archive_SecondsBe 1 – 86,400 startup only Archive cache flush cycle or maximum
tweenFlush (900 sec) time between consecutive disk flushes for
a given point.
Archive Archive_ShiftFreeTi 0 – 86,400 startup only Number of seconds to substract from the
me (1,800 sec) predicted time to determine the actual
shift time. Setting this parameter to
something greater than zero will leave the
corresponding free archive space (default
is 30 minutes). This parameter and/or the
Archive_ShiftRatio are useful on
systems where backfilling or out-of-order
events are expected.

PI Server Reference Guide Page 29


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
Archive Archive_ShiftRatio 4 – 2048 startup only Ratio of total records to free records at
(512 ratio) which archive shifts are triggered. The
inverse of this parameter defines the
percentage of free records to leave in
Archive files (default is 1/512 = 0.2%).
This parameter and/or the
Archive_ShiftFreeTime are useful on
systems where backfilling or out-of-order
events are expected.
Archive Archive_ShiftRecord 256 – 16384 before every Number of records to process in one
Count (2048 shift chuck during Archive file initializations.
records) When shifting or initializing new archives,
this parameter partly defines the speed of
archive initializations. However, setting
this parameter higher than the default may
impact system performance as more
memory will be consumed.
Archive Archive_WriteLockT 5000 – startup only Maximum time Flush (writer) threads can
imeout 900,000 wait accessing archive points. Default is
(270,000 4.5 minutes (270 seconds).
ms)
Archive ArcInsertRecOnOO 0–1 startup only Break the chain and insert new records
O (1 boolean) when out-of-order events need to be
inserted into full overflow records. When
set to 0 (false), this parameter makes the
Archive Subsystem to revert back to the
event cascading algorithm of PI 3.3 and
earlier versions.
Archive ArcMaxCollect - startup only Maximum number of compressed events
(15000 that can be retrieved by a single query.
events) This number does not affect interpolated
event retrieval or archive summary calls.
Archive BreakCrossRefOnD 0–1 startup only Break reference between UnitBatch and
elete (1 boolean) PIBatch on deletion of UnitBatch.

Archive Cache_FreelistSize 1000 – startup only Size of the list of reusable cache records
100000 that were discarded from the read-only
(10000 record pool. This parameter should only
records) be changed upon recommendation from a
technical support engineer.
Archive MarkArchiveGaps 0–1 startup only Return special "Arc Off-line" events when
(1 boolean) Archive files are taken offline or when time
gaps are detected in mounted archives.
The archive offline markers are primarily
useful to prevent any mis-interpolation of
data across missing archives.

Page 30
3.6 - Timeout Database

Subsystem Name Min – Max Read Description


(Default)
Archive piarchss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(100000
sec)
Archive BatchDb_MaxSearc -1 – startup only Maximum size (number of records) of
hRecords 1,000,000 batch queries returned by the Archive
(-1) Subsystem. Very large batch searches
can lead to performances problems with
the PI Archive Subsystem. This applies to
PIUnitBatches, PIBatches and
PICampaigns.
If set, exceeding the limit causes the
search to be terminated, no records
returned and the following error:
[-16029] Batch database search exceeded
maximum allowed records.
Archive BatchDb_SearchLo 1 – 365 startup only Controls the batch search look back
okBackDays (31 days) period. Batch searches are performed
internally this many days in the past from
the start time provided. This can be set
from 1 to 365 (days). The default value is
31 days (one month).
Backup Backup_ArchiveCut 01-Jan-70 – Before every If the cutoff date is not explicitly specified
offDate NA backup in arguments to the pibackup.bat backup
(01-Jan-70) script, then this timeout parameter defines
the default cutoff date. Archives that
contain any data between
Backup_ArchiveCutoffDate and current
time will be backed up. For example, if “*-
30d” is specified, then at least 30 days of
data will be backed up.
Both Backup_NumArchives and
Backup_ArchiveCutoffDate restrict the
number of archives for backup. Whichever
timeout parameter is most restrictive takes
precedence.
Backup Backup_NumArchiv 1 – 1000000 Before every If the number of archives to be backed up
es (3) backup is not explicitly specified in arguments to
the pibackup.bat backup script, then this
timeout parameter defines the default
number of archives to be backed up.
Backup Backup_TraceLevel 0 – 1000 Startup only This is the default backup trace level.
(0) Non-zero backup trace levels cause
debug messages to be written to the PI
Message Log. The default trace level can
be overridden while the PI Backup
Subsystem is running with the piartool –
backup –trace <level> command.

PI Server Reference Guide Page 31


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
Base BatchDbEditLogging 0–1 startup only Logging of Batch Database edits and
(0 boolean) deletions to the message log. This
parameter does not apply to PIBatch
Subsystem and is superceded by the
Audit feature (EnableAudit) of the PI
Server.
Base ModuleDb_CleanPe 30 – 3600 startup only Frequency at which checks for idle
riodSec (300 sec) modules are performed. Setting this limit
too low may affect the performance of the
Base Subsystem.
Base ModuleDb_MaxIdle 0 – 604800 startup only Maximum idle time of MDb modules
CleanSec (3600 sec) before being unloaded from memory.
Checks are performed every
ModuleDb_CleanPeriodSec seconds.
Base pibasess 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(10000
µsec)
Base PointDb_CleanPerio 30 – 3600 startup only Frequency at which checks for idle points
dSec (300 sec) are performed. Setting this limit too low
may affect the performance of the Base
Subsystem.
Base PointDb_MaxIdleCle 0 – 604800 startup only Maximum idle time of PI Points before
anSec (3600 sec) being unloaded from memory. Checks are
performed every
PointDb_CleanPeriodSec seconds.
Base PointEditLogging 0–1 startup only Logging of point edits and deletions to the
(0 boolean) message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Base RecreateServerTrus 0–1 startup only Recreate missing trust entries for local
t (1 boolean) machine access. These trust settings are
used by SDK or API applications or
interfaces running on the server node.
Base WindowsAuthenticat 0–1 startup only Perform windows user authentication
ion (1 boolean) against a domain controller. This feature
should only be disabled upon
recommendation from a technical support
engineer.
Base, EnableAudit 0- startup only Auditing mask, -1 (or 0xFFFFFFFF)
Snapshot, 0xFFFFFFF enable the audit of all databases. See
Archive F Auditing the PI Server for details on
(0 bitmask) acceptable values.

Page 32
3.6 - Timeout Database

Subsystem Name Min – Max Read Description


(Default)
Batch pibatch 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000
µsec)
Message pimsgss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000
µsec)
NetManager backlog 5 – 1000 startup only Maximum number of pending TCP/IP
(5) connections.

NetManager connectionlocktimeo 1 – 1000 startup only Amount of time to wait for a connection
ut (90 sec) locked by another thread.

NetManager connectionwait 1000 – startup only Amount of time for a new TCP/IP
1000000 connection to become writable.
(30000
msec)
NetManager DefaultUserAccess 0–1 startup only Enable guest (or "world") access to the PI
(1 boolean) Server.

NetManager HealthCheckInterval 60 – 1000 startup only Frequency at which health checks are
(1800 sec) performed between NetManager and the
PI Subsystems. NetManager will close
connections if subsystems don't respond
to health checks.
NetManager keepalive -1 – 1 startup only TCP/IP keepalive option. A value of -1 is
(-1 sec) the system default, 0 indicates disabled.

NetManager linger_on 0–1 startup only Socket closure behavior (see


(0 boolean) linger_time).

NetManager linger_time 0 – NA startup only Time in seconds to linger on socket


(0 sec) closure, if linger_on is set

NetManager MaxMessageLength 10 – 512 startup only Maximum size of messages handled by


(256 MB) NetManager, PI3 Subsystems and PI SDK
applications.
NetManager maxzerobytereads 0 – 1000 startup only Assume a connection close when
(100 bytes) receiving a series of zero-byte messages.

NetManager minbufsize 1 – 1000 startup only TCP/IP send and receive buffers
(8 KB)
NetManager pinetmgr 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(10000
µsec)

PI Server Reference Guide Page 33


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
NetManager ReadCompletionTim 120 - startup only Amount of time to block for read
eout 0xFFFFFFF completion.
F
(300 sec)
NetManager readretry 1– startup only Maximum retry attempts on read stream
10000000 errors
(250)
NetManager readtimeout 1– startup only Read timeout on network I/Os
50000000
(50000
µsec)
NetManager reversenamelookupf 0–1 startup only Translate IP addresses to IP host names
lag (1) on new connections.

NetManager ThreadStackSize 0 – 10 startup only Stack of Net Manager worker thread. A


(0 MB) value of 0 means the same as
NetManager's main thread.
NetManager writeretry 1– startup only Maximum retry attempts on write stream
10000000 errors
(250)
NetManager writetimeout 1 – 5000000 startup only Write timeout on network I/Os
(50000µsec)
PESchedule pipeschd 1– startup only Subsystem wait time after every main loop
r 10000000 iteration.
(50000µsec)
Snapshot EditDays 0- startup only Number of past days where events can be
(0) modified in the Snapshot or Archive
databases. A value of zero means no time
check is done.
Snapshot pisnapss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(1000µsec)
Snapshot SnapFlushCycle 60 – 3600 startup only Snapshot table flush cycle or maximum
(900) time between consecutive flushes for a
given point.
Snapshot Snapshot_EventQu 64 – 8192 startup only Size of the memory pages from the
euePageSize (1024 KB) memory mapped Event Queue. This
number must be a multiple of 64.
Snapshot Snapshot_EventQu - startup only Path where the memory-mapped queues
euePath (path) are created (default is PI\dat). The primary
queue name is always pimapevq.dat and
overflow queues are pimq0000.dat,
pimq0001.dat ... pimqFFFF.dat.

Page 34
3.6 - Timeout Database

Subsystem Name Min – Max Read Description


(Default)
Snapshot Snapshot_EventQu 8 – 131072 startup only Size of the primary and overflow Event
eueSize (64 MB) Queues on disk. This parameter should
be adjusted according to archive event
rate to avoid the creation of overflow
queues.
Snapshot Snapshot_LowDisk - when Minimum amount of free disk space to
SpaceMB (256 MB) overflow leave when creating overflow Event
Event Queues (pimqXXXX.dat).
Queues are
created
Snapshot, ArchiveEditLogging 0–1 startup only Logging of event edits and deletions to the
Archive (0) message log. This parameter is
superceded by the Audit feature
(EnableAudit) of the PI Server.
Snapshot, Snapshot_EventQu 1 – 3600000 startup only Frequency at which the memory-mapped
Archive eueFlushPeriod (30000 queue is flushed to disk by the Snapshot
msec) and Archive Subsystems.

SQL pisqlss 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000µsec)
Totalizer pitotal 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(12000µsec)
UpdateMan MaxUpdateQueue - startup only Maximum number of events per consumer
ager (4095) held in the Update Manager.

UpdateMan PIUPD_MaxConsTi 0 – 7200 startup only Maximum value of client-supplied cleanup


ager meout (0 sec) time for inactive consumer signups.

UpdateMan PIUPD_MinConsTi 0 – 7200 startup only Minimum value of client-supplied cleanup


ager meout (600 sec) time for inactive consumer signups.

UpdateMan PIUPD_TimeoutKill 0–1 startup only Remove timed out consumers in addition
ager Cons (0) to removing all pending events.

UpdateMan piupdmgr 1– startup only Subsystem wait time after every main loop
ager 10000000 iteration.
(12000
µsec)
UpdateMan TotalUpdateQueue - startup only Maximum number of events in Update
ager (100000 Manager for all consumers.
events)
Utilities CheckUtilityLogin 0–1 startup only Force an interactive login from console
(0) utilities (piconfig, pisetpass).

PI Server Reference Guide Page 35


Chapter 3 - PI Server Databases

Subsystem Name Min – Max Read Description


(Default)
Utilities piartool 1– startup only Subsystem wait time after every main loop
10000000 iteration.
(1000µsec)
Utilities piconfig 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.

Utilities pigetmsg 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.

Utilities pilistupd 1 – 1000000 startup only Subsystem wait time after every main loop
(1000µsec) iteration.

Timeout Database Parameters for UNIX-based Systems


On UNIX-based PI Systems, the low-level I/O routines use several PI Timeout table
parameters. You might change the values of some of these parameters to get better
performance for the specific version of UNIX you are running, the size of the PI System and
so on.
The Timeout table parameters are stored in PI/dat/pitimeout.tbl. You can use piconfig to edit
the values of Timeout Table parameters. Modifications to the PITimeout Table do not go into
effect until PI is restarted.
The timeout table contains the entries shown below, where the time values are specified in
microseconds:
$ piconfig
* (Ls - ) piconfig> @table pi_gen, pitimeout
* (Ls - PI_GEN) piconfig> @ostructure name, value
* (Ls - PI_GEN) piconfig> @select name=*
(Ls - PI_GEN) piconfig> @endsection
piarchss,10000
piartool,1
pibasess,10000
pimsgss,12000
pinetmgr,3000
pipeschd,50000
pisnapss,1000
piupdmgr,12000
readtimeout,50000
readretry,250
writetimeout,50000
writeretry,250
piconfig,1
pigetmsg,1
pilistupd,1
Most of the entries define a messaging timeout for the PI subsystems and utilities.
The other entries in the PItimeout Table are used as follows.

Page 36
3.7 - Firewall Database

Readtimeout Time in microseconds to block in select call while reading and assembling a
message

Readretry Number of retries to attempt while reading and assembling a message. Retries
are attempted only on fatal errors, which are: EAGAIN, EWOULDBLOCK,
ENOBUFS, and EIO.

Writetimeout Same as readtimeout, except acts on send call

Writeretry Same as readretry but acts on send call

The following message in pinetmgr.log (PI 3.1 build 2.74 and later) indicates that the
READTIMEOUT or WRITETIMEOUT timing parameter reached the set limit.
PIstream::recv(SOCK_Stream *, int): select failed1 0
The following message in the application standard out indicates that the READRETRY or
WRITERETRY timing parameter reached the set limit.
PIstream::recv(SOCK_Stream *, int): max retries exceeded

3.7 Firewall Database

The PI Firewall is a security feature that allows the PI Server Manager to control access to the
PI Data Archive at the IP network address level. System administrators can allow or deny
access by specific computers this way. More information is available in PI Server System
Management Guide, Chapter 1, PI System Management.

3.8 Proxy Database

As of release 3.3, the Proxy Database is no longer in use. The Trust Database replaces it.
During upgrade, existing proxy entries are converted to trust entries.

3.9 Trust Database

The Trust Database is used to grant PI client application access to the PI Server
automatically. This is necessary for PI API and PI-SDK applications that run unattended,
such as interfaces. It also allows for PI-SDK applications to support single user logons. The
process authorizes the use of the access rights of a specific PI Server user.
The PI System Administrator creates records in the Trust Database, mapping credential
attributes such as Domain name, IP host name, IP address, Application name, and Operating
System Username to a PI user.
Trusts can be specified exactly or by allowing entry, for example, to a group of users from a
given domain.
The connecting application and PI Server obtain information about the client’s credentials.
During client connection, the Trust Database is scanned for a match with the client’s

PI Server Reference Guide Page 37


Chapter 3 - PI Server Databases

credentials. If a match is found, the application is granted the access rights of the specified PI
user.
It is possible that more than one trust record matches the incoming entry specifications. In
such cases, the entry that matches the entry most closely will be granted access.
See PI Server System Management Guide, Chapter 1, PI System Management, for more
details on configuring trust database records.
The Trust Database includes all the previously defined PIproxy records.

3.10 User Database

The PI User Database is where all PI users are defined. They may be assigned to groups.
Groups must already be defined in the PI Group Database. Passwords are also stored here.
Users maintain their passwords using the pisetpass utility.

3.11 Group Database

The PI Group Database is where all PI groups are defined. Members of each group may be
viewed here. Membership is assigned only in the PI User Database.

3.12 Module Database

The PI Module Database stores and maintains all the data objects associated with the Module
Database. This includes PIModules, PIHeadingSets, and PIHeadings. PIBasess maintains
this database. All access to the PI Module Database is provided by the PI-SDK.

3.13 Batch Database

The PI Batch Database is the database for the PI Batch objects supported by the PI-SDK. This
database is independent of the PI Batch Subsystem and the databases it maintains. The PI
Batch Database is actually part of the PI Archive and is therefore, maintained by the PI
Archive Subsystem. All access to the PI Batch Database is provided by the PI-SDK.

3.14 List of Database Files

The following table provides a list of database files for your reference. The files are
organized by the subsystem to which they belong.

PIbasess Databases

File name Description

pipoints.dat Point Database

Page 38
3.14 - List of Database Files

PIbasess Databases

piptattr.dat Attribute Set Database

piptclss.dat Point Class Database

pidigst.dat Digital Set Database

pidignam.dat Digital State Name Database

piusr.dat User Database

piusrgrp.dat Group Database

PIModuleDb.dat Pi Module Database

piusrctx.dat User Context Database

pitrstrl.dat Trust Database

piptunit.dat Database reserved for future use.

piptalia.dat Database reserved for future use.

piptsrcind.dat Point Source index file. This is an index that allows for quick lookup by
pointsource. This file is rebuilt automatically if it does not exist.

PIModuleUnitDb.dat Batch process unit index--an index of all modules with the IsPIUnit flag set
to true. Automatically rebuilt if it does not exist.

piptcomind.dat Index of com connector points. Automatically rebuilt if it does not exist.

PIMsgss Databases

pimsgtxt.dat Message text resource

pimsg_yymmdd.dat Message logs where “yymmdd” represents date covered by file

PINetmgr Databases

pifirewall.tbl Firewall database

pitimeout.tbl Timeout database

pisubsys.cfg Inter-process communication info file

pisysid.dat Identifier data file

PIShutev Databases

shutdown.dat Shutdown event configuration file

Pisnapss Databases

piarcmem.dat Snapshot database

pimapevq.dat Event queue

PI Server Reference Guide Page 39


Chapter 3 - PI Server Databases

PIbasess Databases

pilastsnap.dat Time of newest event

PISqlss Databases

pisql.ini Site specific initialization file

Pisql.res Parsing resource

Page 40
Chapter 4. PI POINT CLASSES AND ATTRIBUTES

A point is any measurement or calculation that is stored in the data archive. Points can
represent transmitter readings, manual inputs, status control limits, and so on.

Note: The terms point and tag are sometimes used interchangeably, but the tag is
actually the name of the point.

The configuration information for each point is stored as a list of attributes in the Point
Database.

4.1 About Point Classes

The Point Database has several different point classes, such as Base and Classic.
Point class is assigned when the point is created. Each point class has a different set of
attributes which define the parameters that describe a point. Default is Base point class.
The Base point class contains 39 attributes. Other point classes, such as Totalizer and Classic,
include more attributes, in addition to the 39 attributes from the Base point class. The
Totalizer Point Class is discussed in the PI Server Applications Guide.
Use the piconfig ptclass command to access the attributes belonging to a particular point
class. For example, to display the attributes of the Classic point class, you would type:
@table pipoint
@ptclass classic
@?atr
As a shortcut, you can specify the point class name while setting the pipoint table with a
single piconfig command:
@table pipoint,classic
The piconfig command ptclass is not to be confused with the attribute ptclassname.

4.2 Base Class Point Attributes

The Base class is a common set of attributes that all other point classes include. This section
describes the user-assigned base class point attributes. The Base class also includes a set of
system-assigned attributes that users cannot edit. See System-Assigned Attributes on page 55.

PI Server Reference Guide Page 41


Chapter 4 - PI Point Classes and Attributes

4.2.1 Tag
The Tag attribute is the name of the point. Each Tag must be unique to a PI System. Since the
tag is the name that identifies the point to users, it’s a good idea to use a consistent tag-
naming convention that is meaningful to people in your organization. For example, you could
reserve the first two characters of a tag to indicate a unit name or an area of the plant. You
could reserve another 6 characters to match the standard instrument tag, and so on.
Tags may be any length and can include letters, numbers, and spaces. Tags are subject to the
following constraints:
‰ The first character must be alphanumeric, ‘_’, or ‘%’
‰ No control characters are allowed; such as linefeeds or tabs
‰ The following characters are not allowed:
* ’ ? ; { } [ ] | \ ` ‘ “
(However, these characters are allowed in other tag attributes, such as the descriptor.)
Any tags that follow the above rules are, technically, allowed. However, be aware some legal
characters, such as the ‘_’, are used by other applications in special ways. For example, SQL
uses ‘_’ as a wild card. Using these in tags, may cause problems with these applications.

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

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

Changing Tag Names


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

4.2.2 PtClassName
The PtClassName attribute needs to be defined at point creation time. PtClassName defines
what attributes a point is to have. Prior to PI 3.4.370 the point class of a point could not be
changed once the point was created. In versions 3.4.370.x or greater it can be edited. See
Point Class Edit.

Page 42
4.2 - Base Class Point Attributes

4.2.3 PointType
There are many point types in the PI Server. PointType is assigned when the point is created.
Prior to PI 3.4.370.x this attribute could not be changed, but in versions 3.4.370 or later it can
be edited. See Point Type Edit.

Table 4–1. Point Types

Point Type How It Is Used

Digital Used for points whose value can only be one of several discrete states, such as
ON/OFF or Red/Green/Yellow. Nearest equivalent to the PI 2.x Digital type.

Int16 Used for points whose values are 15-bit unsigned integers (0 to 32767). Nearest
equivalent to the PI 2.x Integer type.

Int32 Used for points whose values are 32-bit signed integers (-2147450880 to
2147483647). PI reserves the lowest 32K values of the 32bit range for digital states.

Float16 Used for floating point values, scaled. The accuracy is one part in 32767. Nearest
equivalent to the PI 2.x Real type.

Float32 Used for single-precision floating-point values, not scaled.

Float64 Used for double-precision floating-point values, not scaled.

String Used to store string data of up to 976 characters.

Blob Binary large object – Used to store any type of binary data up to 976 bytes.

Timestamp Used to store values of type Timestamp. Any Time/Date in the Range 1-jan-1970 to
1-Jan-2038

Choosing Point Type


For points collected automatically, use the point type that most closely matches the point type
in the source system. For example, if the point originates from a transmitter that supplies an
analog measurement with 14 bits of accuracy, use the float16 point type. This point type
provides 15 bits of precision.
For accumulators and other high precision values, use the higher precision point types:either
float32 or float64.
The higher precision point types require more disk space for each stored value. Float16 points
use 16 bits or 2 bytes per value. Float32 and float64 use 4 and 8 bytes per value, respectively.
Int16 and int32 values use 2 and 4 bytes, respectively. Int16 is similar to a PI 2 integer type; it
supports only 15-bit unsigned integers.
If you want to store negative integers, select the int32 point type. Note that PI reserves some
values in the negative range of a 32-bit integer. The smallest value that can be stored is
shown in the table above.
Interface manuals sometimes refer to point types R (real), I (integer), and D (digital).
‰ Use float16 or float32 for type R. If the data are coming from an analog-to-digital
converter (ADC); float16 is sufficient.

PI Server Reference Guide Page 43


Chapter 4 - PI Point Classes and Attributes

‰ Use int16 or int32 for type I or integer values.


‰ Use digital for type D or discrete values.

Float16 vs. Float32


OSIsoft recommends using float32 as the default type for floating point data. Only tags with
very large amounts of data (more than 1000 values per day) that is frequently retrieved should
be configured as float16, and their configuration should match the input device.
The space saving of float16 can reduce the amount of I/O. This is significant only on very
large data retrievals, for example yearly average calculations or long term trends. There is no
impact on the initial storage of incoming data.

Attributes that Depend on Point Type


Some point attributes are not relevant for some point types:
‰ Only Digital type tags use the DigitalSet attribute. It is irrelevant for other type tags
and can be ignored.
‰ For Digital, string and Blob type tags, the values of CompDev, CompDevPercent,
ExcDev and ExcDevPercent are not applicable. The value of these attributes is
automatically returned to applications as zero.
‰ For Digital, string and Blob type tags, the Span and Zero attributes are not
applicable. For digital tags, Zero and Span will be automatically set to the digital set
number and the number of states minus 1 in the set, respectively.

4.2.4 NewTag
The NewTag attribute is used for renaming tags.

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

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

Page 44
4.2 - Base Class Point Attributes

4.2.7 TypicalValue
The Typical Value is used only to document an example of a reasonable value for this point.
For a numeric tag, it must be greater than or equal to the zero, and less than or equal to the
zero plus the span.

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

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

4.2.10 Span
The Span is the difference between the top of the range and the bottom of the range. It is
required for all numeric data type points.
For float16 point types, the span is used with the zero for scaling values in the archive. The
span must be a positive value. If the value for a point type float16 point is greater than the top
of range, it is recorded in the archive as “Over Range.” For other point types, zero and span
do not affect the values recorded in the archive.
The span is also used when defining a PI ProcessBook trend with a vertical scale of database.
This attribute is not used for non numeric points.

4.2.11 Impact of Changing Zero and Span


The Zero and Span for a tag can be changed without affecting data already in the archive.
For points of type Float16, the old zero and span are used for retrieving the archive data

PI Server Reference Guide Page 45


Chapter 4 - PI Point Classes and Attributes

collected before the edit. The new zero and span are used for data collected after the edit.
When span is changed, the exception and compression deviation percents are preserved. This
means that the excdev and compdev fields, which are expressed in engineering units, are
modified internally. If any of the deviation fields is specified in the editing operation they
take precedence.

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

4.2.12 EngUnits
The engineering unit string describes the units of the measurement. You may use any string,
and the string may be of any length. However, the PI API will retrieve only the first
12 characters. The PI-SDK does not truncate the string.
Examples include:
DEGF
Degrees Centigrade
Gal/Min
Gallons Per Minute
‘“Hg
Engineering unit strings are case preserving and case-insensitive. The system trims leading
and trailing blanks are trimmed during input.
A single quote (‘) in a string must be preceded by a double quote (“). Similarly, a double
quote in a string must be preceded by a single quote. Long strings can be used for more
readable engineering units.

4.2.13 PointSource
The PointSource attribute is a string that associates a tag with an interface or PI module. In
order for an interface to read or write to a point, the PointSource attribute must match the
point source setting for that interface.
The default point source is “Lab.” Use this for points that are not associated with any
interface to specify lab-input points.
The ‘%’ (percent) character has also special meaning for SQL and other applications. Using it
as a point source can lead to confusion. Similarly, it is advisable to avoid using ‘?’ or ‘*’ as
point source character.

4.2.14 SourceTag
For data output to other systems, the SourceTag is the PI tag of the data source. For example,
you can define a tag ABC to receive data using point source A, then define another tag DEF

Page 46
4.2 - Base Class Point Attributes

to send this information to another instrument system using point source B. The source tag
for tag DEF would be ABC. This attribute is used by some interfaces, while other interfaces
use the extended descriptor (ExDesc) for this information.
The SourceTag attribute is not stored in the Point Database. It is only a more readable
representation of the srcptid attribute which holds the source point ID. srcptid does not exist
in all point classes. For example, it is part of the classic point class but not of base. If you try
to edit SourceTag for points of point-classes that do not have the attribute, you get an error.

4.2.15 ExcDev, ExcMin, ExcMax and ExcDevPercent


Most interface programs use exception-reporting specifications to determine when to send
data to the Snapshot. The exception reporting specifications consist of a deviation (ExcDev),
a minimum time (ExcMin), and a maximum time (ExcMax). ExcDevPercent is similar to
CompDev, but it specifies the compression deviation in percent of Span rather than in
engineering units. If one is changed by user, the other is automatically changed to be
compatible. If both are changed at once ExcDevPercent takes precedence.
For digital, string and Blob tags, ExcDev and ExcDevPercent are ignored. They are
displayed by applications as zero.

4.2.16 Scan Flag


Some interface programs use a Scan flag. Interfaces that honor this attribute will not update
points whose scan flag is set to OFF. Refer to the documentation to see if your interface
program uses it.

4.2.17 Compressing Flag


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

4.2.18 CompDev, CompMin, CompMax and CompDevPercent


When a new Snapshot arrives, the previous one is evaluated according to the compression
specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is
discarded. The result is that only significant data are written to the archive. This process is
called compression.
The compression specifications consist of a deviation (CompDev), a minimum time
(CompMin), and a maximum time (CompMax):
‰ CompMin: An event is archived if the elapsed time since the previous event is
greater than or equal to the minimum time and the value has changed by more than

PI Server Reference Guide Page 47


Chapter 4 - PI Point Classes and Attributes

the deviation. For points associated with interfaces that send exception reports, the
CompMin should be 0.
‰ CompMax: Events are also archived if the elapsed time is greater than the maximum
time. The recommended maximum time specification is one work shift (e.g., 8
hours). Duplicate values will be archived if the elapsed time exceeds CompMax.
Under no circumstances does this cause PI to generate events; it only filters events
that are externally generated.
‰ CompDev: The most important compression specification is the deviation,
CompDev. Setting this value too low causes too little data compression and wastes
space in the archive. Setting this value too high causes loss of useful data. For most
flows, pressures, and levels, use a deviation specification of 1 or 2 percent of span.
For temperatures, the deviation should usually be 1 or 2 degrees.
‰ CompDevPercent: This is similar to CompDev, but it specifies the compression
deviation in percent of Span rather than in engineering units. If one is changed by
user, the other is automatically changed to be compatible. If both are changed at once
CompDevPercent takes precedence.
For non numeric tags, CompDev and CompDevPercent are ignored. They will be displayed
by applications as zero.

Out of Order Events


Events that are sent to the PI Server out of time order bypass the compression calculation and
are sent to the archive.

Turning off Compression


To turn off compression (that is, to archive every event), set the Compressing attribute to
OFF (0).

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

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

Page 48
4.2 - Base Class Point Attributes

A request for the value at 12:00:30 would return 101.0.


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

PtOwner , PtGroup, PtAccess, DataOwner, DataGroup, DataAccess


The access permission specifications allow restricted access to be configured independently
for both point attributes and point data. Users are defined in the PI User Database. Groups are
defined in the PI Group Database.
A PtOwner is assigned to own the point attributes. A DataOwner is assigned to own the data.
PtOwner and DataOwner can be the same. The default for both attributes is the creator of the
point.
A group is assigned to be the group for the point and for the data (PtGroup and DataGroup).
Read/write access permissions for owner, group, and world (default) are set using the
PtAccess and DataAccess attributes. Some examples of access permissions are:
o:rw g:rw w:rw (everyone can read and write)
o:rw g:r w:r (owner write; everyone read)
o:rw g:r w: (owner write; owner and group read)
See the Security section in PI Server System Management Guide for a full discussion on
security.

DisplayDigits
The DisplayDigits attribute controls the format of numeric values on screens and in reports.
Zero or a positive number indicates the number of digits to display to the right of the decimal
point. A negative number indicates the number of significant digits to display. In this case,
the absolute value of DisplayDigits is the number of significant digits.
The following table shows how a value of 23.45 would appear on the screen for different
values of DisplayDigits:

DisplayDigits Format

3 23.450

2 23.45

1 23.5

0 23.

PI Server Reference Guide Page 49


Chapter 4 - PI Point Classes and Attributes

DisplayDigits Format

-1 2E+001

-2 23.

-4 23.45

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

4.3 Classic Point Class Attributes

Standard OSI interfaces rely on classic attributes. Use the Classic point class for all points
using a PI interface that uses the InstrumentTag or location code attributes.

4.3.1 Instrument Tag


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

4.3.2 Location1, Location2, Location3, Location4, and Location5


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

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

Page 50
4.3 - Classic Point Class Attributes

4.3.4 UserInt1, UserInt2, UserReal1 and UserReal2


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

4.3.5 Filtercode
The Filtercode indicates the time constant of a first-order filter used to smooth incoming
data. OSIsoft recommends not altering incoming data by leaving this code at its default value
of 0. The other options are:

Code Time Constant (Sec.)

1 10

2 60

3 120

4 600

4.3.6 Totalcode
The Totalcode was used by the PI System for OpenVMS to control Totalizer processing. PI
for Windows and UNIX do not use Totalcode. See Totalizer Subsystem in the PI Server
Applications Guide for instructions on configuring the Totalizer for PI for Windows and
UNIX.

4.3.7 Srcptid
This is the PI point number corresponding to the tag specified in the SourceTag attribute. If
this attribute is edited, PI will change SourceTag to the corresponding tag. This attribute
should not be altered directly; change SourceTag instead.

4.3.8 Convers
The Convers attribute was used by the PI System for OpenVMS to control Totalizer
processing. PI for Windows and UNIX does not use Convers. See Totalizer Subsystem in the
PI Server Applications Guide for instructions on configuring the Totalizer for PI for
Windows and UNIX.

4.3.9 Ranges of ExcMax and CompMax


In early releases of PI 3, the values of these two point attributes were stored as unsigned 16-
bit integers, which meant that the maximum value of each was 65,535 seconds. This will
continue to be true for existing systems upgraded to PI 3.3 or greater, but from PI 3.4.370.x
or greater these attributes can be edited to uint32 type. See Attribute Sets Database Edit.
In new installations of PI 3.3 or greater releases, the values of these two point attributes are
stored as unsigned 32-bit integers, and the maximum value of each is 4,294,967,295 seconds.

PI Server Reference Guide Page 51


Chapter 4 - PI Point Classes and Attributes

The PI API protocol defines the ExcMax and CompMax attributes as a signed 16-bit integer.
If the PI Server stores a value that is larger than 32,767, the value returned by the PI API will
be 32,767.
PI-SDK applications will obtain from the PI Server a signed 32-bit integer values for
ExcMax and CompMax.

4.4 COM Connector Point Attributes

COM Connectors allow the PI Server to obtain data from foreign data systems. To do this,
you must create a special PI Server point whose attributes identify the location of the data in
the foreign system.
The term map is used throughout this manual to mean making a relationship between a point
on the foreign system and a point on the PI Server. During PI Server operation, clients make
requests for data by using PI Server point information. The PI Server will then obtain data
from the foreign system point to which the PI Server point is mapped.
The PI Server does not use a specific value of the PointSource attribute to identify mapped
points. A specific point class name is not needed either. Instead, you must define a point class
that includes the following attributes:

Attribute Name Description

ctr_progid COM Program ID, as stored in the Windows registry. This


name is used to instantiate the COM Connector object.

ctr_lmap Longword mapping parameter.

ctr_strmap String mapping parameter.

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


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

4.5 Default Values for Point Attributes

When you create a point, at a minimum you must specify the tag attribute. For all other
attributes, if you don’t assign a value to that attribute, then PI uses the default value. The
default values for PI point attributes are listed in the following table.

Page 52
4.5 - Default Values for Point Attributes

Table 4–2. Point Database Default Table

Point Default
Class Field Name Value Limits

Base Archiving On On, Off, 1, or 0

Base ChangeDate System-assigned

Base Changer System-assigned

Base CompDev 2 (eng units)

Base CompDevPercent Comes from CompDev 0 ≤ x ≤ 100

Base CompMax 28800 (sec) see next subsection

Base CompMin 0 (sec) 0 ≤ x ≤ 65535

Base Compressing On On, Off, 1, or 0

Classic Convers 1

Base Creationdate System-assigned

Base Creator System-assigned

Base DataAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)

Base DataGroup Piadmin In PI Group Database

Base DataOwner Piadmin In PI User Database

Base Descriptor blank

Base DigitalSet no default Used only for digital tags This must
be specified when the point is
created.

Base DisplayDigits -5 -20 ≤ x ≤ 10

Base EngUnits blank

Base ExcDev 1 (eng units)

Base ExcDevPercent Comes from ExcDev 0 ≤ x ≤ 100

Base ExcMax 600 (sec) see next subsection

Base ExcMin 0 (sec) 0 ≤ x ≤ 65535

Base ExDesc blank

Classic Filtercode 0

Classic InstrumentTag blank

PI Server Reference Guide Page 53


Chapter 4 - PI Point Classes and Attributes

Point Default
Class Field Name Value Limits

Classic Location1 0

Classic Location2 0

Classic Location3 0

Classic Location4 0

Classic Location5 0

Base NEWTag

Base PointID System-assigned

Base PointSource Lab

Base PointType Float32

Base PtAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)

Base PtClassName Base Base, classic, Totalizer, alarm

Base PtGroup Piadmin In PI Group Database

Base ptOwner Piadmin In PI User Database

Base RecNo System-assigned

Base Scan On On, Off, 1, or 0

Base Shutdown True

Classic SourceTag blank

Base Span 100 x≥0

Classic SquareRoot 0 On, Off, or 0 <= x <= 10

Classic Srcptid 0

Base Step Off

Base Tag no default This must be specified when the


point is created.

Classic Totalcode 0

Base TypicalValue 50 Zero ≤ x ≤ (zero + span)

Classic UserInt1 0

Classic UserInt2 0

Page 54
4.6 - System-Assigned Attributes

Point Default
Class Field Name Value Limits

Classic UserReal1 0

Classic UserReal2 0

Base Zero 0

Other The Totalizer Point class includes


other attributes, which are discussed
in the PI Server Applications Guide,
Chapter 6, "Totalizer Subsystem."

Note: Programmatic access to some of the attributes may be limited or unavailable


from the PI API.

4.6 System-Assigned Attributes

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

4.6.1 Creator
The user who created the point.

4.6.2 CreationDate
The date and time when the point was created.

4.6.3 Changer
The last user to edit the attributes for this point.

4.6.4 ChangeDate
The date and time when the attributes for this point were last edited.

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

4.6.6 RecNo
The record number is a read-only point attribute that contains the point's primary record
number in the archive. This is useful when using tools such as piartool -aw to examine the
archives. RecNo is not to be confused with the PointID attribute.

PI Server Reference Guide Page 55


Chapter 5. PI POINT CLASS EDIT

5.1 Introduction

A PI point consists of a set of attributes. What attributes a point has is uniquely determined
by its point class. A PI point class consists of a group of PI point attribute sets, each of which
consists of some attributes. The attributes of a point is therefore built by grouping attributes
into attribute sets, and then grouping the attribute sets into a point class and assigning the
point to this point class. A PI point class cannot consist of attribute sets that have overlapping
attributes.

Figure 5-1. Formation of a point class

Point class is assigned to a point when it is created. Prior to PI 3.4.370 it was not possible to
change the attributes of a point once it is created and assigned to a point class. In PI 3.4.370.x
or greater users can edit and delete attribute sets and point classes.

PI Server Reference Guide Page 57


Chapter 5 - PI Point Class Edit

1. Attributes ExcMax and CompMax in base attribute set may now be edited from
uint16 to uint32.
2. It is now also possible to switch a point from one class to another, new or existing, so
that the same point can continue to collect data seamlessly even though its collection
mechanism has changed. For example, one can convert a Totalizer point to a PE
point, which belongs to classic point class, or vice versa, while keeping the same tag.
3. The user can also change the attributes of a point by adding or removing or changing
the types of attributes in the point class of the point. This affects all points that belong
to that point class.
4. By allowing addition, removal and edit of the attributes of point classes, we can
allow the same points to retain their history and continue to collect new data even
when the attribute requirements of the data collecting applications change.

5.2 Overview

Changing the attributes of a point can be accomplished as follows:


1. Edit the PtClassName attribute of the point to the point class that contains the
desired attributes.
2. Edit the point class directly so that it contains the desired attributes. A point class can
be edited by changing the attribute sets that make up the point class. That is, attribute
sets can be added to or deleted from it.
3. Edit the point class implicitly by editing one or more attribute sets that form the point
class. Editing an attribute set triggers edits of all point classes that use the set.
4. Editing a point class, implicitly or directly, triggers edits of all points in that point
class. Therefore a point’s attributes can be modified by editing one or more attribute
sets via implicit edits of point classes and points.
This chapter discusses in detail each of theses processes:
‰ Editing an Attribute Set
‰ Editing a Point Class
‰ Editing the PtClassName Attribute of the Point
Only piadmin is allowed to delete and/or edit attribute sets and point classes. This restriction
was imposed to prevent cases where implicit point class and point edits might fail due to
varying ownerships and permissions.
Attribute sets and point classes may be edited or deleted only in stand alone mode in which
PINetmgr will close the TCP/IP listener and disallow any client connections. Existing PI-
SDK, PI API and PI Server Application connections will be closed, and reconnection
attempts refused for the duration of the stand alone mode. Subsystems and locally run utilities
such as piconfig and piartool can connect. Default-only attribute edits are supported in
Normal mode.

Page 58
5.2 - Overview

The command PIartool –standalone 1 puts the system in stand alone mode (no clients
can connect), and PIartool –standalone 0 sets it in normal operating mode. PIartool –
standalone 2 queries what mode the system is in.
There are some restrictions on which attribute sets and point classes may be edited or deleted.
Below is a summary of the restrictions:
‰ Allow adding attribute(s) to any set except for the Base attribute set.

Note: Any attribute added to a predefined set cannot be removed due to rules
2b, 7a and 9a below: the predefined attribute sets are required by predefined
point classes and predefined point classes may not be deleted. So, they are
always in-use. It is recommended that the user create a new attribute set with
new attributes when expanding a point class rather than adding new attributes to
a predefined set. For the list of predefined attribute sets and point classes see
Appendix.

‰ Allow deleting attributes from a set except from predefined sets (those created by
OSI) if they are required attributes
‰ In-use attribute sets
‰ Disallow renaming attributes
‰ Allow renaming attribute sets except
• Predefined attribute sets
‰ Allow deleting attribute sets except
• Predefined attribute sets
• In-use attribute sets
‰ Allow adding attribute sets to any point class
‰ Allow deleting attribute sets from a point class except from
• Predefined classes (created by OSI) if they are required attribute sets1
• In-use point classes
‰ Allow renaming point classes except
• Predefined point classes
‰ Allow deleting point classes except
• Predefined point classes
‰ In-use point classes
These restrictions were imposed to protect the attribute sets and point classes that PI system
itself uses as building blocks. These restrictions can limit the user’s ability to easily undo

1 Predefined point classes and their required attribute sets are listed in the Appendix.

PI Server Reference Guide Page 59


Chapter 5 - PI Point Class Edit

some actions. To demonstrate how involved undoing some actions can be, suppose that a user
added an attribute set to a point class by mistake. In order to restore the original point class,
all the tags in this class need to be edited to belong to another class so that the class is no
longer in-use. Then the undesired attribute set can be removed from the point class. Finally,
the points can be edited back to the original point class.
It is CRUCIAL to make a backup of the point database before attempting to edit attribute sets
or point classes. One can delete attribute sets from predefined point class as long as the class
is not in use and the set to be deleted is not a required set for that point class. Remember that
any attribute added to a predefined attribute set cannot EVER be removed.
piconfig utility can be used to perform these edits and deletes after placing PI server in stand
alone mode using PIartool utility as discussed above. Examples are shown in the following
sections as appropriate.

5.3 Attribute Sets Database Edit

The following sub-sections discuss three operations that modify the PI Attribute Set database:
‰ Attribute Set Create
‰ Attribute Set Delete
‰ Attribute Set Edit

5.3.1 Attribute Set Creation


An attribute set can be created by specifying the set name and the attribute names, types and
default values. If the type is not specified float32 is assigned. If default value is not specified,
it is set by PI. Allowed types and defaults (in parentheses) are listed below. Types not listed
below are not supported, and will either be rejected outright at attribute set creation time or
have unexpected behavior.

Supported Attribute Types and Defaults


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

Page 60
5.3 - Attribute Sets Database Edit

‰ Float32 (0)
‰ Bool (0)2

Disallowed Attribute Names


The following attribute names are not allowed in any user-defined attribute set:
Built-in attribute names:
‰ PointID
‰ PtClassName
‰ Recno
‰ PtOwner
‰ PtGroup
‰ PtAccess
‰ DataOwner
‰ DataGroup
‰ DataAccess
‰ DigitalSet
‰ Excdevpercent
‰ Compdevpercent
‰ SourceTag
‰ NEWtag
Reserved names:
‰ NEWCLASS
‰ NEWSET
‰ Set
‰ Class
Base attribute names
‰ Tag
‰ Descriptor
‰ exdesc

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

PI Server Reference Guide Page 61


Chapter 5 - PI Point Class Edit

‰ typicalvalue
‰ engunits
‰ zero
‰ span
‰ pointtype
‰ pointsource
‰ scan
‰ excmin
‰ excmax
‰ excdev
‰ shutdown
‰ archiving
‰ compressing
‰ step
‰ compmin
‰ compmax
‰ compdev
‰ creationdate
‰ creator
‰ changedate
‰ changer
‰ displaydigits
The built-in attributes are added to all points. Their types and defaults cannot be modified by
user. However, the values of non system-assigned attributes such as PtOwner, PtGroup,
PtAccess, DataOwner, DataGroup, DataAccess, DigitalSet, ExcDevPercent,
CompDevPercent, SourceTag and NEWTag can be modified by user.
Base attribute set is created by OSI and its edit is severely restricted. See Attribute Set Edit
for further details. Attribute name checks are case-insensitive.

Example of Creating an Attribute Set


Below is an example of how to create an attribute set in piconfig utility. Stand alone mode is
not required for creating an attribute set.
@table piatrset
@mode create
@istru set
@istru attrib,type,default

Page 62
5.3 - Attribute Sets Database Edit

@istru ...
MyAttributeSet
MyAttribute1,BYTE,
MyAttribute2,int32,2
MyAttribute3,string,”Default string”
MyAttribute4,,
@ends
MyAttribute4 will be assigned the type float32, and default of 0.0. The
following lists the attribute set just created.
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttributeSet
@ends
The output will look like
MyAttributeSet
MyAttribute1,BYTE,0
MyAttribute2,Int32,2
MyAttribute3,String,Default string
MyAttribute4,Float32,0.
* End Repeat...
*----------

5.3.2 Attribute Set Deletion


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

Example of Deleting an Attribute Set


An example of how to remove an attribute set is given below.
First place the system in standalone mode using PIartool in command window.
PIartool –standalone 1
Then launch piconfig in command window, and type the following.

PI Server Reference Guide Page 63


Chapter 5 - PI Point Class Edit

@table piatrset
@mode delete
@istru set
MyAttributeSet
@ends
When finished place the system back in normal mode.
PIartool –standalone 0

5.3.3 Attribute Set Edit


An attribute set can be edited by adding, removing attributes and/or changing attribute types
and default values.
Edits other than default-only edits require that the system be put in Stand Alone mode by
running piartool utility as follows.
PIartool –StandAlone 1
PIartool –StandAlone 0 puts the system back in Normal mode. Default-only edits do not
require stand alone mode.
Internally, an attribute set edit (except for default-only edits) is actually done in 4 steps:
‰ Rename the original set to a temporary name, “OriginalName~someGUID”.
‰ Create a new set with desired attributes under the original name.
‰ Trigger implicit point class edits, which in turn will trigger implicit point edits.
‰ Remove the original set from the database after successful implicit edits.
These steps are transparent to the user, but each of these steps is audited if auditing is enabled
for the base subsystem.
Default-only edits modify the existing sets directly instead of following the above steps.
Default edit triggers implicit point class edits but point edits. This is because the new defaults
will only be applied to new points. In the rest of this document an edit implies non default-
only edits unless explicitly stated otherwise.

Implicit Point Class and Point Edits


When an attribute set is edited, all dependent point classes and points are edited without user
intervention. These edits are referred to as implicit edits.
Implicit point edits keep the existing attribute values if they are still in the edited attribute set
that triggered the implicit point edit and are compatible with the new types. If the new
attribute type is not compatible with the old one, the new default takes precedence over the
existing attribute’s value. This situation can arise if the old attribute’s type changed, for
example, from string to int32. If the original string value of the attribute cannot be converted
to an int32, the new default for this attribute type will prevail. Another example is the case
the existing value no longer fits in the new type. For example, if the type changed from
float32 to BYTE, and the existing value was 128.0, then the value will be set to 0.

Page 64
5.3 - Attribute Sets Database Edit

Note that implicit point edit does not validate the point configuration. That is, if a point with
improper configuration (e.g. a Totalizer point with no sourcetag) is implicitly edited, the
implicit edit will succeed although direct edit of the point would have failed validation.
In implicit point edits, additional, if any, attributes are assigned default values until the user
explicitly edits them later. That is, consider a point belonging to a class with base attribute set
and another attribute set called MyAttributeSet. Suppose that MyAttributeSet originally
contained MyAttribute1, MyAttribute2, and MyAttribute3, but was edited to include another
attribute called MyAttribute4. The point will be implicitly edited and will now have the
additional attribute MyAttribute4. This attribute will be set to the default by the implicit edit
process.

Base Attributes and Allowed Types


Base attribute set edit is disallowed except to convert the types of CompMax and ExcMax
attributes from uint163 to uint32 and to change the default values of any attributes in this set.

Name Allowed type

Descriptor String

Exdesc String

Typicalvalue float32

Engunits string

Zero float32

Span float32

Pointtype ubyte

Pointsource string

Scan uint16

Excmax uint16 or uint32

Excdev float32

shutdown byte

Archiving byte

Compressing byte

Step byte

Compmin uint16

3 PI versions earlier than 3.3 were shipped with uint16 type for excmax and compmax.

PI Server Reference Guide Page 65


Chapter 5 - PI Point Class Edit

Name Allowed type

Compmax uint16 or uint32

Compdev float32

Creationdate timestamp

Creator uint16

Changedate timestamp

Changer uint16

Displaydigits byte

Built-in Attributes
Built-in attributes are part of every PI point, but do not belong to any particular attribute set.
The types and defaults of built-in attributes, which are frequently mistaken as belonging to
the base attribute set, do not belong to any attribute set explicitly and cannot be edited. This is
not to say that individual point’s built-in attribute values cannot be edited. Non system-
assigned attribute values may be edited.

Example of Editing an Attribute Set


If an attribute set is edited, its dependent point classes and, subsequently, dependent points
are edited internally by the PI Base Subsystem. No explicit editing of the PI point classes
database by a user is necessary. Such indirect edits are henceforth referred to as implicit edits.
To illustrate, suppose a user wishes to change a set called MyAttributeSet. First place the
system in stand alone mode using piartool utility.
PIartool –standalone 1
List the existing attributes in piconfig utility:
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttribSet
@ends
Suppose the attributes and their types and defaults of this attribute set show as follows.
MyAttribSet
MyAttrib1,Int32,22
MyAttrib2,BYTE,0
MyAttrib3,Float32,5.
To change the attribute MyAttrib2 to type String and add another attribute, MyAttrib4 of type
uint16 in PIConfig:
@table piatrset

Page 66
5.3 - Attribute Sets Database Edit

@mode edit
@istru set
@istru attrib,type,default
@istru ...
MyAttribSet
MyAttrib1,int32,22
MyAttrib2,String,default string
MyAttrib3,float32,
MyAttrib4,uint16,1
@ends
Now list the resulting set:
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttribSet
@ends
MyAttribSet
MyAttrib1,Int32,22
MyAttrib2,String,default string
MyAttrib3,Float32,0.
MyAttrib4,Uint16,1
Editing an attribute set works just like PI digital set edit. Attribute name, type and default
should all be explicitly redefined. If a pre-existing attribute is not specified in the new
definition, it will be permanently removed from the set. If the user had not wanted to edit the
existing attributes, but only wanted to add a new attribute MyAttrib4, he still would have had
to specify all attributes in his definition. That is, doing the following
@table piatrset
@mode edit
@istru set
@istru attrib,type,default
@istru …
MyAttribSet
MyAttrib4,uint16,1
@ends
would have produced MyAttribSet containing only one attribute, namely MyAttrib4.
If an attribute set is edited, and its pre-existing attribute name is specified, but not the type
and default, float32 and value 0.0 will be assigned overwriting the original type and default.
If only the type is specified by the user, a new default will be assigned even if the type is
identical to the previous one. The default of MyAttrib3 attribute was changed to 0.0 from the
original 5.0 because it was not explicitly specified in the edit.
When done with the edit, place the system back in normal mode so that applications can
connect.
PIartool –standalone 0

PI Server Reference Guide Page 67


Chapter 5 - PI Point Class Edit

Renaming an attribute set does not trigger any implicit edits of point classes or points and
does not require standalone mode either.

Restrictions on Attribute Set Edit


All restrictions are delineated in the beginning of this chapter. To repeat a few, attributes may
be added to any attribute set, including the predefined sets, except for the base attribute set;
Removing attributes in an attribute set that is in use is not allowed; Removing attributes in a
predefined attribute set is not allowed; Renaming a predefined attribute set is not allowed.

Informational Messages
Messages such as will not be directly returned to the edit initiating application (e.g. piconfig)
are sent to the PI Message subsystem. Examples of these messages are information regarding
the status (success or failure) of 4 steps involved in edit (rename the old set, add a new set,
implicitly edit dependent point classes and points, and remove the old set) and the number of
dependent point classes found, etc. These messages are useful in verifying that the steps are
carried out correctly during the edit.

Rollback
Attribute set edit triggered point class edits, and their dependent point edits are all committed
to disk as they occur. If an error occurs during implicit edits the remaining edits are aborted.
Those edits that already succeeded are rolled back, and the original set is restored. Then the
user can resolve the cause of the edit failure and re-edit.

Note: In rollback all implicitly edited point classes and points are reconstructed from
the original attribute set which is still in the database under a temporary name. Since
no attribute may be removed from its set if the set is in use, the original attributes
should have remained in the set and retained their values in implicit point edits
unless the new type and original type were incompatible and the values had to be
set to the new defaults. In such a case, the original attribute values of the affected
points cannot be recovered.

Successful rollbacks are audited if the base subsystem is enabled for auditing4. Like any other
types of edits, unsuccessful rollbacks are not audited.
Regardless of success of the rollback the error for the failed edit will be returned to the user.
Additional messages may be found in PI message log.
If the rollback fails an error is logged in PI Message log, and the rollback is aborted. PI points
database may end up with some points belonging to the original point class (under a
temporary name) and others to the new point class (under the original class name) containing
the new attribute set. The cause of the rollback failure needs to be resolved and then the

4 Any action that changes an attribute set, a point class or a point in the database will be audited if auditing is
enabled and the edit was successfully completed.

Page 68
5.3 - Attribute Sets Database Edit

system needs to be restored manually. This can be done by using a good system backup or by
following the procedure outlined in the next section. Once the system is restored, the user can
resolve the cause of the actual edit failure and then re-edit.

System Restore Procedure after Rollback Failure


In general, these steps can be taken to restore the system to the original state. Note that
whether it is implicit edit or direct edit, the original set or class would have the temporary
name (original name~GUID) and the new set or class the original name and the edited
attributes.
1. Fix the cause of the rollback failure first (e.g. PI Snap Subsystem down, global lock
re-acquisition failure, etc.). More on lock re-acquisition failure later in thread-safety
section.
2. If some implicit edits (of point classes and points) already completed successfully,
start with points. Then fix the point classes, and lastly the attribute set.
3. Edit the ptclassname attribute of the implicitly edited points to the original point
class with the temporary name. When done with this step, there should be no points
belonging to the new point class.
4. Remove the new point class.
5. Rename the original class from the temporary name to the original name.
6. Remove the new attribute set.
7. Rename the original set from the temporary name to the original name.
8. Internally the points refer to their point classes by their unique IDs, and the point
classes refer to the attribute sets by their IDs. After renaming point classes their
dependent points should correctly refer to the new names.
9. Once the system is in its original state, determine the cause of the edit failure and fix
it. Then re-edit the attribute set. This procedure should cover most failure cases. If
this procedure doesn’t seem to cover your particular situation please call OSI
Technical Support.
As mentioned earlier if a predefined set gets stuck with undesirable attributes they can not be
deleted. This is because each predefined set is one of the required attribute sets in at least one
predefined point class which cannot be removed. Since the set is required, it cannot be
removed from the point class, and therefore is always in use. Attributes may not be removed
from in-use attribute set. In order to add more attributes to a point class, it is better to create a
new attribute set and add that attribute set to the target point class rather than adding the
attributes to one of the existing member attribute sets of the point class, especially if that set
is predefined.
To remove undesired attributes from a non-predefined attribute set:
1. Create a new set with the desired attributes.
2. Create new point classes that include this attribute set, and edit the dependent points
to belong to these new classes so that the set and classes to be fixed are not in use.

PI Server Reference Guide Page 69


Chapter 5 - PI Point Class Edit

If keeping the original attribute set name or point classes is not important user can stop here
and just delete the original point classes and the attribute set. If it is necessary to keep the
original set and the point classes, continue.
1. Edit the original dependent point classes to exclude the set that contains undesired
attributes.
2. Edit the original attribute set removing the undesirable attributes.
3. Add this set back to the original point classes.
4. Edit the points back to the original classes.
Once the dependent points are all converted back to the original classes in the previous step,
the interim point classes and the set created in step 1 and 2 can now be deleted.

5.4 Point Classes Database Edit

Indirect (i.e. implicit) edit of PI point class database was discussed in the Attribute Set Edit
section. Point class database can also be directly modified by a user via one of the following
three operations: creation, deletion and edit.

5.4.1 Point Class Creation


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

Example of Creating a Point Class


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

5.4.2 Point Class Deletion


Predefined point classes (see Appendix) may not be deleted.
In-use point classes may not be deleted.

Example of Creating a Point Class


In command window
PIartool –standalone 1

Page 70
5.4 - Point Classes Database Edit

In piconfig
@table piptcls
@mode delete
@istru class
MyPtClass
@ends
Back to normal mode.
PIartool –standalone 0

5.4.3 Point Class Edit


A point class can be explicitly edited by adding/removing attribute sets that form the point
class.
piconfig version 3.4.370.x or higher can display which attribute sets form a point class:
@table piptcls
@ostru class
@ostru set,...
@select class=MyPtClass
@ends
This feature makes it easier to see what attribute sets are currently being used to form the
point class.
If there are problems with getting the set names, this operation will return an error but it will
also return as many set names as it can get with the failing set’s name replaced with “???”
(without the quotes). This allows for editing the class to remove the problematic set as a
means to fix a corrupted database.
Internally a point class edit is carried out in four steps:
1. Rename the original point class to a temporary name. It is constructed by
concatenating the original name with a GUID e.g. OriginalName~GUID.
2. Create a new point class with desired attribute sets under the original name.
3. Edit the points that belong to the point class to belong to the new class.
4. Remove the original point class from the database after successful implicit point
edits.
These steps should be transparent to the user if all steps complete successfully.

Example of Editing a Point Class


If a point class list in piconfig shows the following
* (Ls - ) PIconfig> @table piptcls
* (LS - PIPTCLS) PIconfig> @mode list
* (Ls - PIPTCLS) PIconfig> @ostru class
* (Ls - PIPTCLS) PIconfig> @ostru set,...
* (Ls - PIPTCLS) PIconfig> @select class=MyPtClass
* (Ls - PIPTCLS) PIconfig> @ends

PI Server Reference Guide Page 71


Chapter 5 - PI Point Class Edit

MyPtClass
base,classic
*----------
Let’s add attributes MyAttribute1 (string) and MyAttribute2 (int32) to this point class. In
order to do this, create an attribute set, say MyAttributeSet, as follows.
@table piatrset
@mode create
@istru set
@istru attrib,type,default
@istru ...
MyAttributeSet
MyAttribute1,string,my default string
MyAttribute2,int32,22
Then check it was correctly created.
@table piatrset
@mode list
@ostru set
@ostru attrib,type,default
@ostru ...
@select set=MyAttributeSet
@ends
You should see
MyAttributeSet
MyAttribute1,String,my default string
MyAttribute2,Int32,22
* End Repeat...
*----------
Edit MyPtClass to include this attribute set. The system needs to be in standalone mode. Type
the following in command window.
PIartool –standalone 1
In piconfig define the attribute sets that should belong to the point class.
@table piptcls
@mode edit
@istru class
@istru set,...
MyPtClass
base,classic,MyAttributeSet
Check that these attributes now form MyPtClass. You should see
* (Ed - PIPTCLS) PIconfig> @mode list
* (Ls - PIPTCLS) PIconfig> @ostru class
* (Ls - PIPTCLS) PIconfig> @ostru set,...
* (Ls - PIPTCLS) PIconfig> @select class=MyPtClass
* (Ls - PIPTCLS) PIconfig> @ends
MyPtClass

Page 72
5.4 - Point Classes Database Edit

base,classic,MyAttributeSet
*----------
To see all attributes that are in this point class type the following.
@table pipoint
@ptclass MyPtClass
@?atr
The following list will appear
1 - Tag String D: !#!#!# C:
2 - NEWTag String D: C:
3 - archiving BYTE D: 1 C:
4 - changedate TimeSta D: 31-Dec-69 16:00:00 C:
5 - changer Uint16 D: 0 C:
6 - compdev Float32 D: 2. C:
7 - Compdevpercent Float32 D: 2 C:
8 - compmax Uint32 D: 28800 C:
9 - compmin Uint16 D: 0 C:
10 - compressing BYTE D: 1 C:
11 - convers Float32 D: 1. C:
12 - creationdate TimeSta D: 31-Dec-69 16:00:00 C:
13 - creator Uint16 D: 0 C:
14 - DataAccess String D: o:rw g:r w:r C:
15 - DataGroup String D: piadmin C:
16 - DataOwner String D: piadmin C:
17 - descriptor String D: C:
18 - DigitalSet String D: system C:
19 - displaydigits BYTE D: -5 C:
20 - engunits String D: C:
21 - excdev Float32 D: 1. C:
22 - Excdevpercent Float32 D: 1 C:
23 - excmax Uint32 D: 600 C:
24 - excmin Uint16 D: 0 C:
25 - exdesc String D: C:
26 - filtercode Int16 D: 0 C:
27 - instrumenttag String D: C:
28 - location1 Int32 D: 0 C:
29 - location2 Int32 D: 0 C:
30 - location3 Int32 D: 0 C:
31 - location4 Int32 D: 0 C:
32 - location5 Int32 D: 0 C:
33 - myattribute1 String D: my default string C:
34 - myattribute2 Int32 D: 22 C:
35 - PointID Int32 D: 0 C:
36 - pointsource String D: Lab C:
37 - pointtype String D: Float32 C:
38 - PtAccess String D: o:rw g:r w:r C:
39 - PtClassName String D: MyPtClass C:
40 - PtGroup String D: piadmin C:
41 - PtOwner String D: piadmin C:
42 - Recno Int32 D: 1 C:

PI Server Reference Guide Page 73


Chapter 5 - PI Point Class Edit

43 - scan BYTE D: 1 C:
44 - shutdown BYTE D: 1 C:
45 - SourceTag String D: C:
46 - span Float32 D: 100. C:
47 - squareroot Int16 D: 0 C:
48 - srcptid Int32 D: 0 C:
49 - step BYTE D: 0 C:
50 - totalcode Int16 D: 0 C:
51 - typicalvalue Float32 D: 50. C:
52 - userint1 Int32 D: 0 C:
53 - userint2 Int32 D: 0 C:
54 - userreal1 Float32 D: 0. C:
55 - userreal2 Float32 D: 0. C:
56 - zero Float32 D: 0. C:
Place the system back in normal mode.
PIartool –standalone 0

Restrictions on Attribute Set Edit


Some restrictions on point class edits are:
‰ Edited point class should still contain the base attribute set.
‰ Any attribute set may be added to a point class.
‰ Attribute sets may not be deleted from in-use point classes.
‰ Required attribute sets may not be deleted from predefined point classes even if they
are not in use.
‰ Predefined classes may not be renamed.
‰ If the sets in the point class edit definition are not different from the existing ones,
then no further action is taken and success status is returned. If the attributes of one
or more attribute sets have changed, the attribute set edit itself should have taken care
of implicit point class - and point edits.
‰ Renaming a point class does not trigger any implicit edits of points.

Informational Messages
Messages such as will not be directly returned to the user are sent to the PI Message
subsystem. Examples of these messages are information regarding the status of four steps
involved in point class edit (rename the original class, add a new class, implicitly edit
dependent points, remove the original class) and the number of dependent points found, etc.

Rollback
As in the case of an attribute set edits point class edit triggers implicit point edits. If an
implicit point edit fails, all previously successful implicit point edits are rolled back. New
class is deleted, and the original class’s name is restored.

Page 74
5.4 - Point Classes Database Edit

System Restore Procedure after Rollback Failure


If an implicit point edit fails the rest of the edits are aborted. The old class is left in the
database under the temporary name, and the new class will remain also. The edit will return
failure status. Where possible, the failing point name and error description will be returned as
well.
Restoring the system to its original state requires similar procedure as outlined in Attribute
Edit rollback section.
1. First, fix the cause of the rollback failure. For example, if it failed because of
Snapshot Subsystem being off-line, the following repair procedure cannot be carried
out anyway.
2. It may be possible after this step to just edit the remaining points manually to the new
point class. If that is not possible, all dependent points should then be edited to
belong to the original class under the temporary name. Remove the new point class.
3. Rename the original class from the temporary name to the original name. If this is
impossible, restore from backup.
4. Identify the cause of the edit failure and fix it. Then re-edit the point class.
In PI 3.4.370 or greater PIConfig can display the attribute sets that form a point class.
Previously, it had only been possible to display the individual attributes in a point class. The
sets are listed by name. Note that the operation edit in piconfig actually makes two calls, one
for a listing the current set IDs and a second call to do the edit. As long as there are no errors
returned for edit itself, messages like below just means this point class’ original set IDs
contained a set ID (110 in this case) that refers to a set that does not exist anymore5, but the
edit succeeded.
* (Ls - PIPTCLS) PIconfig> @mode edit
* (Ed - PIPTCLS) piconfig> @istru class
* (Ed - PIPTCLS) piconfig> @istru set,...
* (Ed - PIPTCLS) piconfig> Totalizer2
*> Totalizer2
* (Ed - PIPTCLS) piconfig> testatrset,base,totals
*> testatrset,base,totals
Warning: error getting point class' set name list:
*** Start of PIvariant dump ***
setid 110 [-12002] Code Not Found in PInt
*** End of PIvariant dump ***

5 This scenario is unlikely, but if it ever happens, it can be rectified by editing the class.

PI Server Reference Guide Page 75


Chapter 5 - PI Point Class Edit

5.5 Editing a Point’s Point Class Attribute

In some cases, it is more desirable to modify the value of point’s ptclassname attribute (of
type string) to another point class rather then editing the point class it belongs to. A PI point’s
ptclassname attribute edit is supported just as any other point edit.
As in the case of implicitly edited point, the attributes of the point are rebuilt. The important
difference is that unlike in an implicit point edit, some existing attributes may get removed.
The reason is that a point class edit disallows removing any attributes if there are any
dependent points. This effectively prevents points losing existing attributes inadvertently.
However, if the user deliberately moves a point from one class to another and the new point
class does not contain some of this point’s current attributes, they are deleted without
prompting.
When a point’s ptclassname attribute is changed, the new point class’ attributes will be
compared against the existing ones. New attributes will be added and set to default values.
Existing ones will be copied if they are in the new point class. Compatible types retain their
values and incompatible types are set to new defaults value. Attributes that do not belong to
the new point class are removed.
When editing a point via piconfig new attributes can be modified simultaneously. That is, it
is ok to edit the ptclassname attribute and include new attributes that only belong to the new
point class and did not previously belong to the point’s old class. However, the target class
needs to be set before such an edit is attempted.
To illustrate, try editing a point that belongs to Totalizer point class to Classic point class in
piconfig as follows.
@table pinpoint
@ptclass Totalizer
@mode edit
@istru tag,ptclassname,location4,pointsource
The following error will be returned.
*piconfig Err> Unknown parameter <location4> in structure
*@istru tag,ptclassname,location4,pointsource
*piconfig Err> Complete Structure line removed
*@istru tag,ptclassname,location4,pointsource
This is because @ptclass Totalizer sets the environment for this edit to Totalizer point class,
which does not have location4 attribute. Set the environment to the target point class, Classic,
by using @ptclass Classic first if you want to edit the ptclassname attribute and new
attributes unique to the target point class at the same time.
@ptclass classic
@istru tag,ptclassname,location4,pointsource
tagname,classic,1,C
If it is not necessary to edit the ptclassname attribute and new attributes at the same time,
issuing
@ptclass classic
is not necessary since ptclassname is a built-in attribute and every point has this attribute.

Page 76
5.6 - Point Database Audit

Point class of a point can be edited using piconfig in PI 3.4.370 or higher.

5.5.1 Conversion of CC Class to and from a Native PI Class


A special handling is required in case of a native PI point’s ptclassname edit to a COM
Connector point class or vice versa. The difficulty arises from the fact that in order to allow
transparent retrieval of data for a point that has some data in a foreign database and some in
PI Archive, PI needs to be aware of the cutoff times and go to the correct source. The
possibility that the conversion may occur multiple times adds to the complexity.
As of PI3.4.370.xx, history of the conversions is ignored and data request will be directed to
the current data source.

5.6 Point Database Audit

Both Attribute Sets and Point Classes have been added to the Audit database. EnableAudit
parameter in PITimeout Table bit6 will be used for Attribute Sets audit database and bit 4 for
Point Classes audit database. Note that audit records will cascade if dependent point classes
and points are implicitly edited.

Database Bit Value to Enable


(decimal)

Point DB 0 1

Attribute Sets DB 2 4

Point Classes DB 4 16

See Auditing chapter for more details.


‰ A new attribute set create generates an audit record.
‰ An attribute set delete generates an audit record.
‰ Each step involved in editing an attribute set will be audited. That is, renaming the
original set to a temporary name, adding a new one under the original name, implicit
point class and point edits, removing the original set will all be audited. In default-
only audit, however, only the set edit, and implicit point class edits are audited as the
original set and classes are not renamed and no implicit point edits are triggered.
A failed operation does not produce an audit record since the DB is not changed. This
means that if there is an error at any stage in the 4 steps involved in an edit, the audit
trail will stop at the audit of the previous successful step. Any changes to the
database during the rollback, however, will be audited.
‰ A new point class create generates an audit record.

6 Starts from 0.

PI Server Reference Guide Page 77


Chapter 5 - PI Point Class Edit

‰ A point class delete generates an audit record.


‰ Each step involved in editing a point class (renaming the original to a temporary
name, adding new one with the desired attribute sets, implicitly editing dependent
point, and then removing the old one) will be audited.
‰ Just as in the attribute set edit a failed operation does not produce an audit record
since the DB is not changed.

5.6.1 Audit Records


The following are Audit Record and Change Record Definitions for attribute sets database
edit.

PI Point Attribute Sets DB


Audit Record Definition

Field Description

PI UserName User who made change

Action Time Time and Date of change

PI Database PIPointAttributeSets

Audit Action Add, Remove, Edit

AuditRecordID Unique ID assigned to audit record

DB RecordName Name of affected attribute set

DB RecordID Affected record ID in database (set ID)

Changes Table of specific changes

Change Record Definition

Property Before After

New_attribute NULL New default

Deleted_attribute Old default NULL

Modified_attrib Old default New default

The name of the attribute set is treated as if it was an attribute and is shown as Name item.
The audit DB exported in XML format also indicates what type the attribute’s value is.
The following are Audit Record and Change Record Definitions for point classes database
edit.

Page 78
5.6 - Point Database Audit

PI Point Classes DB
Audit Record Definition

Field Description

PI UserName User who made change

Action Time Time and Date of change

PI Database PIPointClasses

Audit Action Add, Remove, Edit

AuditRecordID Unique ID assigned to audit record

DB RecordName Name of affected point class

DB RecordID Affected record ID in database (point class ID)

Changes Table of specific changes

Change Record Definition

Property Before After

New_attribute NULL New default

Deleted_attribute Old default NULL

Modified_attrib Old default New default

The name of the point class is treated as if it was an attribute and is shown as Name item.

PI Points DB
Audit Record Definition

Field Description

PI UserName User who made change

Action Time Time and Date of change

PI Database PIPoint database

Audit Action Change action: Add, Remove, Edit

AuditRecordID Unique ID assigned to audit record

DB RecordName Name of affected point

DB RecordID Affected record ID in database (PI point ID)

Changes Table of specific changes

PI Server Reference Guide Page 79


Chapter 5 - PI Point Class Edit

Change Record Definition

Property Before After

New_attrib_name NULL Default

Deleted_attrib_name Old value NULL

Edited_attrib_name Old value New value

5.7 Thread-safety

Attribute set and point class edits rely on the locking mechanism at the global level for thread
safety. Both of these edits lock the entire points database, and it will not be accessible to the
user. That is, two users cannot simultaneously initiate attribute sets and or point classes.
Point edits, however, get the lock (same global lock as attribute set edits and point class edits)
per point basis. To be more specific, a point edit thread releases the global lock while it
updates the Snapshot, and re-acquires it when the snap update is completed. While the thread
is waiting for the synchronous RPC to PI Snap subsystem to return, the point’s edit status flag
is set, and no other thread can edit the point. If another thread has acquired the lock in that
time, the point edit thread cannot re-acquire the lock and the point edit fails.
This temporary lock release mechanism during point edit was implemented to optimize PI
Base Subsystem’s performance and ensure other requests can still be serviced should the
synchronous RPC to update PI Snap take a long time.
Because of this mechanism, it is possible that while an implicit point edit is in progress it
releases the lock, another (but explicit) point edit acquires the lock, and the implicit point edit
as well as all remaining implicit edits fail or vice versa. The scenario described above is
rarely anticipated, but the users should be aware of it, and should NOT attempt to initiate
both attribute set or point class edits and explicit edits simultaneously. Since client
applications ore remote piconfig sessions cannot connect while the system is in stand alone
mode, this situation can be easily avoided if the administrator does not simultaneously launch
multiple point edits and point class edits simultaneously in parallel (local) piconfig sessions.

Page 80
Chapter 6. PI POINT TYPE EDIT

6.1 Introduction

In PI 3.4.370.x or greater a point’s type can be edited just like other attributes. That is, if
listing the point's type as shown below shows the point type as int32,
@mode list
@ostru tag,pointtype
@istru tag
MyTag
only the following operation is needed in piconfig to change its point type to float32.
@mode edit
@istru tag,pointtype
MyTag,float32
@ends
Under the hood, changing a point’s point type causes the Archive Subsystem to close the
current archive record and start a new one with the new type info in the header.
When a point’s pointtype attribute is changed, already archived history of the point will not
change unless the archive is processed off-line. Off-line archive processing will actually
convert the old type events to events of the new type. This allows the user a choice between
keeping the old data type events and converting them all to the new type.
Upon archive record activation, the old type event will be coerced to the new point type if
possible.
If the value does not fit in the new point type, Coercion Failed digital state will be returned
by default. If Archive_DataCoercionPolicy parameter (see below) is defined in PI timeout
table, an appropriately translated digital state will be returned. PI Server does not log a
warning in PI Message subsystem upon point type edit.
Also if the current Snapshot value cannot be coerced to the new type at the time of the point
type edit, the edit will fail even though the value will actually be archived in the record of the
old type. The point will remain the previous type, and the archived data will look as before.
However, piartool –aw will show two new records since the last archived event’s record.
One will be for the attempted new type, and another for the previous (i.e. current type). The
first of these (the record created for the attempted new type) will remain un-filled thereafter.

PI Server Reference Guide Page 81


Chapter 6 - PI Point Type Edit

To illustrate, suppose a point named int16_typedit had the following archived values and was
of type int16.
6-Oct-2005 13:51:53,27
6-Oct-2005 14:21:54,32767
6-Oct-2005 14:44:56,4
6-Oct-2005 14:51:51,Pt Created
Then it was edited to type int32, and three new values were added.
6-Oct-2005 14:52:01,-10
6-Oct-2005 14:52:03,2147483647
6-Oct-2005 14:52:05,-16
The last value -16 is still in the Snapshot. Try editing the point back to int16 type again by
typing the following in piconfig.
@table pinpoint
@ptclass classic
@mode edit
@istru tag,pointtype
int16_typedit,int16
@ends
The edit will fail and the following error will be returned to piconfig since int16 type doesn’t
allow negative values.
[-10005] Subscript Under Range
Note that this is an error status. An error status like this returned by a point type edit
operation should be distinguished from Coercion Failed which is a System Digital State
which acts as a place holder for an event that failed to coerce.
To see what happens to the archive records when a user tries to edit a point’s type and the
operation fails, launch archive walk by typing
piartool –aw
Something like the following will be shown:
Enter Archive Number: 0
Enter Record Number: 130
Point ID: 1219 Record Number: 130
Chain Record Number - Next: 0 Prev: 0 Index: 0
Record Version: 3 Data type: 8
Flags - Index:1 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 29
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:

7 There are events in this example before Pt Created event because data were back-filled to create the example.

Page 82
6.1 - Introduction

Type “e” (without the quotes) and press Enter to view the events for the point.
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 130
Chain Record Number - Next: 0 Prev: 0 Index: 0
Record Version: 3 Data type: 8
Flags - Index:1 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 29
4 Event(s):
0: 29-Sep-05 14:00:03, S,O,A,S,Q [0,0,0,0,0]: 96688
1: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: 96730
2: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96687
3: 6-Oct-05 14:58:57, S,O,A,S,Q [0,0,0,0,0]: 96686
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Then type 96688 and press Enter to open this Index record:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96688
Chain Record Number - Next: 96730 Prev: 0 Index: 130
Record Version: 3 Data type: 6
Flags - Index:0 Step:0 Del:0 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 4
Storage (bytes) - Available: 998 Used: 22
4 Event(s):
0: 6-Oct-05 13:51:53, S,O,A,S,Q [0,0,0,0,0]: 2
1: 6-Oct-05 14:21:54, S,O,A,S,Q [0,0,0,0,0]: 32767
2: 6-Oct-05 14:44:56, S,O,A,S,Q [0,0,0,0,0]: 4
3: 6-Oct-05 14:51:51, S,O,A,S,Q [0,253,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter to see the next record. Notice the Data type for the following record is “8”, which
is Int328:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96730
Chain Record Number - Next: 96687 Prev: 96688 Index: 130
Record Version: 3 Data type: 8
PI Server 3.4.370
Installation and New Feature Guide Page 89
Flags - Index:0 Step:0 Del:0 Dirty:0

8 Point type enumeration:


int16 = 6, int32 = 8, float16 = 11, float32 =12, float64 = 13, digital = 101, Blob = 102, timestamp = 104, string =
105

PI Server Reference Guide Page 83


Chapter 6 - PI Point Type Edit

Flags - Index:0 Step:0 Del:0 Dirty:0


Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 2
Storage (bytes) - Available: 998 Used: 14
2 Event(s):
0: 6-Oct-05 14:52:01, S,O,A,S,Q [0,0,0,0,0]: -10
1: 6-Oct-05 14:52:03, S,O,A,S,Q [0,0,0,0,0]: 2147483647
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Then press Enter to see the next record. Notice the Data type is now “6”, which is Int16:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96687
Chain Record Number - Next: 96686 Prev: 96730 Index: 130
Record Version: 3 Data type: 6
Flags - Index:0 Step:0 Del:1 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 1
Storage (bytes) - Available: 998 Used: 8
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
Press Enter again to see the next record. The Data type is now “8” again:
PIarcrecord[$Workfile: piarrec.cxx $ $Revision: 71 $]::
Point ID: 1219 Record Number: 96686
Chain Record Number - Next: 0 Prev: 96687 Index: 130
Record Version: 3 Data type: 8
Flags - Index:0 Step:0 Del:1 Dirty:0
Sizes - Record 1024 Data: 998
Parent Archive 00000000 Data Head: 26
Event Count: 1
Storage (bytes) - Available: 998 Used: 10
1 Event(s):
0: 6-Oct-05 14:58:57, S,O,A,S,Q [0,16382,0,0,0]: 0
Enter Record #, <CR> next rec (p)rev (e)vents (a)rchive # (q)uit:
At this time, the point is of type int32. The offset 16382 is a special marker that acts as a
placeholder in the new overflow record created when a point’s type is edited. The first valid
new data for the new type should replace this marker but in record 96687 this marker will
remain there and the record will never be filled since the edit failed.
A tricky situation arises if a value stays in a Snapshot for a long time before a new Snapshot
arrives and the point undergoes several point type conversions meanwhile. This is very
important: the Snapshot undergoes a coercion process every time the tag’s type is
successfully edited. When a new value finally arrives at the Snapshot, the old Snapshot is
coerced back to the type it was originally sent as before being sent to the appropriate record
in the archive. Therefore if the Snapshot event went through several point type conversions
and it cannot be coerced from its latest type to the original type, the value will be rejected by
the archive and lost.

Page 84
6.2 - Error handling

An example of the situation mentioned in the preceding paragraph would be a point going
from an integer type to a digital type and then to a string and then back to integer. If the last
Snapshot for this tag was of type int16 and value 1, the integer would have been coerced to a
digital and the appropriate digital state during the subsequent type edit. This digital state
would have been coerced to a string after that. By the time the point is edited back to integer
type, we have a string (whatever the digital state representation was, say, “Closed”) that
needs to be coerced to int16 and can’t. It would only be coercible if it were a digital because
the coercion process would use the offset.
Out of order events that are sent to the archive after the point type change will go into the
archive as the point type that was in effect at the time of the event’s timestamp.
Below is the matrix of allowed type coercions.
int16 int32 float16 float32 float64 digital string blob timestamp
int16 ok ok5 ok ok ok ok N/A N/A

int32 ok1 ok5 ok ok ok3 ok N/A ok

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

float32 ok1 ok2 ok5 ok ok3 ok N/A ok

float64 ok1 ok2 ok5 ok ok3 ok N/A ok

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


string ok ok ok ok ok ok4 N/A ok

blob N/A N/A N/A N/A N/A N/A N/A N/A


timestamp N/A ok ok ok ok N/A ok N/A

1. Assuming values in the range of 0 to 32767


2. Assuming values in the range of -2,147,450,880 to 2,147,483,647
3. Assuming positive, integer values (lower than number of digital states)
4. Assuming exact match (case insensitive) with a state string
5. Assuming the range of the source is compatible with the range of the target

6.2 Error handling

If coercion is impossible from the stored type to the current point type, what is returned or
whether a value will be returned, is determined by Archive_DataCoercionPolicy. This PI
timeout parameter can have one of the following values:

0 DTC_MarkBad Failed events are returned as DS -315 (“Coercion Failed”)

1 DTC_Leave Original events are returned (mixed types)

2 DTC_Zero Returned as 0 or blank depending on the type

3 DTC_Hide Hidden (skip that event)

PI Server Reference Guide Page 85


Chapter 6 - PI Point Type Edit

If coercion fails during off-line archive processing, values will be replaced as dictated by the
above policy.

Page 86
Chapter 7. EXCEPTION REPORTING AND COMPRESSION
TESTING

Exception reporting and compression testing offer you the opportunity to tune your PI points
for maximum efficiency. Each PI point has attributes that you can set to specify compression
and exception reporting specifications for that point. How you set those specifications will
impact the flow of data from the Interface Node to the Server for that point (exception
reporting) and the efficiency of data storage in the Archive for that point (compression
testing). Exception reporting and compression testing are sometimes confused, but it’s
important to understand the distinctions:
‰ Exception Reporting: Exception reporting takes place on the Interface Node. The
point of Exception reporting is to reduce the communication (I/O) burden between
the PI Server and the Interface Node by filtering out “noise”. As networks have
improved and I/O capacity has become less of an issue, some PI System Managers
have essentially turned exception reporting off, by setting the exception deviation to
zero. OSIsoft recommends that you set the exception deviation to slightly smaller
than the precision of the instrument.
‰ Compression Testing: Compression testing takes place on the Server. The Snapshot
Subsystem performs the compression test. The point of compression testing is to
store data efficiently in the PI Data Archive. More efficient data storage allows for
longer periods of on-line data on the same disk-space. The idea here is not to store an
event that PI can essentially “recreate” by extrapolating from surrounding events.
Unlike exception reporting, which is a simple linear test, the compression test uses a
sophisticated algorithm, called the swinging door compression algorithm, to
determine whether an event is significant.

7.1 Exception Reporting

The exception reporting process is the process that interfaces use to evaluate new events to
determine whether they are significant. The interface sends the significant events to the PI
Server and discards the events that are not significant. The purpose of exception reporting is
to avoid sending random changes—changes that are smaller than the instrument can actually
measure—from the interface to the PI Server.
The interface compares each new value to the previously sent value. The interface sends the
new value to the PI Server only if it is different from the previous value by an amount larger
than the value in the ExcDev attribute.

PI Server Reference Guide Page 87


Chapter 7 - Exception Reporting and Compression Testing

Exception reporting uses a simple dead band algorithm to determine whether to send events
to PI. For each point, you set exception reporting specifications (the ExcDev, ExcMin and
ExcMax attributes) to create the dead band. The interface ignores values that fall inside the
dead band.
Interface programs that do exception reporting apply the following algorithm whenever a new
value is received. A new value is compared to the last value reported. If the new value does
not fall within the dead band, an exception occurs. When an exception occurs, the interface
sends the event (both timestamp and value) that caused the exception and the previous event
to the Snapshot.
The new value is not reported unless:
The difference between the new value and the last value is greater than the exception
deviation specification
and
The difference between the times of the new and last values is greater than or equal to the
exception minimum time specification
or
The difference between the timestamp of the new value and the timestamp of the last
reported value is greater than or equal to the exception maximum time specification.
Note that the time between exception reports might be greater than the exception maximum
time if no new values are received by the interface for a point. Neither the PI Server nor the
interface will ‘create’ data.
Some interfaces do not support exception reporting. See the documentation for your interface
to determine whether it supports this capability. Manually entered data are not normally
reported by exception so that every value can be retained.
Most OSIsoft interfaces report new events on exception. The exception algorithm relies on
the following parameters:
‰ Exception Maximum: Maximum time span between exceptions, expressed in
seconds. This value is configured for each point in the attribute "ExcMax".
‰ Exception Minimum: Minimum time span between exceptions, expressed in
seconds. This value is configured for each point in the attribute "ExcMin".
‰ ExcDev: Dead band when exceeded causes an exception. This is configured for each
PI Point in either the ExcDev or ExcDevPercent attribute.
‰ OldEvent: Value/status/timestamp of last event sent to the Snapshot--this is the last
event that passed exception report.
‰ PrevEvent: Value/status/timestamp of last event compared to determine whether or
not to send to the Snapshot.
‰ NewEvent: Value/status/timestamp of event to test for exception.
Exception reporting works by comparing the new event to the old event as follows.

Page 88
7.1 - Exception Reporting

‰ If the time new event timestamp and old event timestamp is greater than or equal the
excmax, the new event is sent to the Snapshot.
‰ For digital points, if the new value differs from the old value, the new event is sent to
the Snapshot regardless of excmin time.
‰ For numeric points, if the status changes from good to bad, or bad to good, the new
event is sent to the Snapshot.
‰ For numeric points, if the time between the old event and the new event is greater
than or equal to excmin and the absolute value of the difference between the new
value and the old value is greater than excdev, the value is sent to the Snapshot.
‰ If the new event was sent to the Snapshot, the old event is replaced by the new event.
The last step is a test to see if the PrevEvent should also be sent the Snapshot. If the
PrevEvent was not equivalent to the original OldEvent, the PrevEvent is sent to the
Snapshot. The only time the PrevEvent is not sent to the Snapshot is when two consecutive
exception reports send the new event to the Snapshot. The PrevEvent is used to accurately
indicate what really happened to the value; without it, a step change would look like a ramp
change. Basically, if a measurement holds steady for hours, then makes a step change, just
sending the new value to the Snapshot results in interpolating between the old value and the
new value. By also sending the PrevEvent, the step change is stored.

7.1.1 ExcDev and ExcDevPercent


The ExcDev attribute (Exception Deviation) specifies in engineering units how much a value
may differ from the previous value before it is considered to be a significant value. The
ExcDevPercent attribute specifies the same thing as a percentage of the Span attribute. A
typical value is 1% of Span. The exception deviation should be less than the compression
deviation by at least a factor of 2.
You can set either the ExcDev or the ExcDevPercent attribute. If you change one, the other
is automatically changed to be compatible. If you try to change both at once, ExcDevPercent
takes precedence.

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

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

PI Server Reference Guide Page 89


Chapter 7 - Exception Reporting and Compression Testing

7.1.4 Turning Off Exception Reporting


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

7.2 Compression Testing

The Snapshot Subsystem uses compression testing to determine which events it should pass
to the Archive for storage. The point of compression testing is to store just enough data to
accurately reproduce the original signal.
For example, in the following illustration, all the events fall on the same straight line. In a
simple case like this, you don’t actually need to store all the points on the line. If you store
just two points, you can exactly recreate the point value for any other time.

This line can be reconstructed from any two of these events. So the most efficient storage
would be to store only the first and last events (A and B) rather than storing all the events.
Further, no accuracy is sacrificed. If a user wants to retrieve the value at any point along the
line, it can be interpolated from the values that have been stored.
This simple example illustrates how PI applies data compression. In practice, the curves are
more complex than straight lines, and the compression specifications for each tag must be
tuned properly to achieve a balance between storage efficiency and accuracy.
The same principle applies to compressing real-world data. PI uses a sophisticated
compression algorithm to determine which events it needs to keep in order to provide an
accurate data history. The CompDev, CompMin and CompMax attributes allow you to
control the “granularity” of the compression algorithm.
When a new Snapshot arrives, the previous one is evaluated according to the compression
specifications to see if it is a significant event. If so, it is sent to the Event Queue. If not, it is
discarded. This process is called compression.
There are three instances where an event will bypass the compression process and be put in
the Event Queue:
‰ If the Compressing attribute for the point is set to OFF.
‰ If the timestamp is older than the timestamp of the current snapshot. Such an event is
considered out of order.

Page 90
7.2 - Compression Testing

‰ If the Status attribute of the Point has changed.


The compression method used by PI allows PI to keep orders of magnitude more data online
than conventional scanned systems. The data are also much more detailed than in an
archiving system based on averages or periodic samples.
The compression method is called ‘swinging door compression.’ Swinging door compression
discards values that fall on a line connecting values that are recorded in the Archive. When a
new value is received by the Snapshot Subsystem, the previous value is recorded only if any
of the values since the last recorded value do not fall within the compression deviation
blanket. The deviation blanket is a parallelogram extending between the last recorded value
and the new value with a width equal to twice the compression deviation specification.
Each point has three attributes that comprise the compression specifications: CompDev
(compression deviation), CompMin (compression minimum time), and CompMax
(compression maximum time). CompDev is the half-width of the deviation blanket (as shown
in the illustration). CompDevPercent is similar to CompDev, but it specifies the
compression deviation in percent of Span rather than in engineering units.
The compression specifications work in a similar way to the exception specifications. Just
like exception reporting, compression is a filter. The difference is that the exception
specifications determine which events should be sent to PI, whereas the compression
specifications determine which of the events sent to PI should go into the Archive.
CompMin and CompMax are limits that refer to the time between events in the Archive. A
new event is not recorded if the time since the last recorded event is less than the compression
minimum time for the point. A new event is always recorded if the time since the last
recorded event is greater than or equal to the compression maximum time.

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

PI Server Reference Guide Page 91


Chapter 7 - Exception Reporting and Compression Testing

This value will be archived.

Eng
Unit
A compression deviation blanket
Value drawn to this point would not
include all points since the most
recently archived value, so the
Most recently previous value would be
archived value archived.
Compression
Deviation
Specification

Compression Deviation Blanket

Time

Figure 7-1. Swinging Door Compression

You can adjust the compression parameters to produce efficient archive storage without
losing significant data. The compression maximum time is usually set to one value for all
points in the system. It should be large enough that a point that does not change at all uses
very little archive space. A compression maximum time of one work shift (for example, 8
hours) is often a good choice.
Use the compression minimum time (CompMin) to prevent an extremely noisy point from
using a large amount of archive space. This parameter should be set to zero for any point
coming from an interface that does exception reporting. In this case, the exception minimum
time should be used to control particularly noisy points. For a data acquisition system with a
slow scan time, this parameter is not important. There are few cases where you want to use a
non-zero compression minimum time.
The most significant compression parameter is the deviation specification, CompDev. This
parameter is often adjusted after the point is defined. A reasonable starting point is one or two
percent of span for transmitters and 0.5 to 1.0 degrees for thermocouples. Look at trend
displays to find points for which the reproduction of the data is not acceptable. The goal is to
filter out instrument and process noise and still record significant process changes. The effect
of changing the compression deviation is not predictable.
For digital points, any change is a significant change. Only the compression maximum and
minimum time are important. The compression deviation specification is ignored for digital
points.

Page 92
7.2 - Compression Testing

7.2.1 Step Flag


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

PI Server Reference Guide Page 93


Chapter 8. SECURITY

The PI Server is typically used in production systems in which correct and reliable operation
is important. For this reason, a number of security mechanisms are available to protect
against both willful and accidental tampering with the system. These include operating
system security, physical security, network security, and several levels of PI System security.
See the PI Server System Management Guide for details on managing the PI Server security.

8.1 User Name and Password

The PI Firewall provides a first level of access control, based on the network address of the
client. If a connection request successfully passes the PI Firewall, the user ID and password
provide another level of PI access security.
The PI Server has its own user identification and password security.
Client applications are responsible for prompting the user for the login name and password,
and passing this information to the PI Server for authentication.
Users control their own passwords. Use the pisetpass utility to change user passwords. A null
password is allowed but is not generally recommended.

8.2 Point Security

Security applies to point data and point attributes. The archive data for a point is assigned an
owner and a group. The attributes of the point (such as zero, span, compression
specifications, etc.) may be assigned to a different owner and different group, with
independently assigned access permissions.
Users may be assigned to multiple groups, but they don’t have to be assigned to any groups.
There is not necessarily any relationship between the owner and the group.

8.3 Database Security

Security applies to databases owned by the PI Server. Access can be controlled to the Batch,
Campaign, Digital State, Heading Sets, Modules, Point, Transfer Records, User, and
Individual Subsystem Thread and Auditing Table. Each table can be assigned to a different
owner and different group. Access permissions can be different for the owner and the group.

PI Server Reference Guide Page 95


Chapter 8 - Security

8.4 Trust Access

A mechanism for proxy access is provided, primarily to allow interfaces to access the PI
Server for Windows without modifications such as adding login code. The mechanism is
called PI Trust Logins.

Page 96
Chapter 9. PI SQL SUBSYSTEM

The PI SQL Subsystem (pisqlss) prepares and executes SQL statements directed at the PI
Server. The primary users of this subsystem are the PI ODBC Driver and the PI-SDK. This
driver conforms to the ODBC API standards and makes PI data appear to be organized into
data tables. PI ODBC 1.1.2 or later is required to connect to PI Server.
OSIsoft’s implementation of SQL gives applications access to the PI Point Database,
Snapshot, and Archive.
This chapter begins with a discussion of the architecture of the PI SQL Subsystem. It then
outlines the available configuration methods for the PI SQL Subsystem and discusses testing
and troubleshooting techniques. Supporting information, such as details of OSIsoft’s
implementation of SQL, can be found in the PI ODBC Driver Manual.
SQL processing capability is also implemented in the PI System for OpenVMS. Differences
between the two are discussed in this chapter.

9.1 Architecture

This subsection outlines the operation of the PI SQL Subsystem and its interaction with the PI
API.
This discussion is provided as background material. You do not need to understand the details
of the subsystem’s operation in order to use it.

9.1.1 Statement Handles


Most interactions between PI clients and the PI Server do not require the Server to maintain
any context, that is, any record of the client’s operation. Any request for point information or
archive data can be serviced using only the information provided by the client in the request
itself.
The processing of SQL statements is different. When an SQL statement is processed, the
Server must maintain a record of the statement’s status in order to be able to perform
subsequent operations.
This is done by having the PI SQL Subsystem allocate a statement handle when a client
wishes to start processing an SQL statement. The client retains the handle’s identifier and
provides it to the server with every request.
The details of handle allocation and de-allocation are managed internally by a PI API based
client application, such as the PI ODBC Driver.

PI Server Reference Guide Page 97


Chapter 9 - PI SQL Subsystem

If connection between the client and Server is lost, the PI SQL Subsystem retains any
statement handles allocated by the client. These handles become orphaned and cannot be
accessed again. The handles will be de-allocated when the PI SQL Subsystem shuts down.
During shutdown, pisqlss will report the total number of handles allocated during its run, and
how many orphaned handles were aborted.

9.1.2 Concurrency
The PI SQL Subsystem handles SQL processing for all client connections to the PI Server for
Windows and UNIX.
Operations such as parsing an SQL statement and fetching results are relatively inexpensive.
Execution, however, can potentially take time and system resources as data are obtained from
other subsystems.

9.2 Differences between PI 2.x and PI 3.x

There are some differences in SQL processing between the PI Server for Windows and UNIX
and the PI System for OpenVMS. This section outlines these differences.

9.2.1 The PIPoint Table


This subsection outlines the differences between the implementation of the PIPoint Table
between the two styles of PI System.

Classic vs. Base Point Attributes


The columns of the PIPoint Table are exactly the same as the point attributes of a Classic
point. In the PI System for OpenVMS, all points have a design that closely resembles the
Classic point. The PI Server for Windows and UNIX has a few extra attributes relating to
point ownership and access permissions.
In the PI Server for Windows and UNIX, the lowest common set of point attributes is called
the Base point class. When querying attributes of base class points, the PIPoint columns that
represent attributes of classic points will appear to have default values.
This table lists the point attributes that will have default values when querying base class
points:

Table 9–1. Default Attributes in BASE Point Class

PIPoint Column Default value

Convers 0.0

Filtercode 0

location1, location2, 0
location3, location4,
location5

PointID Same as base class attribute recno

Page 98
9.3 - Configuration

PIPoint Column Default value


See next subsection.

Recordtype If base class attribute step is 1, then 0,


otherwise 1.

Res If base class attribute step is 1, then 4,


otherwise 1.

Squareroot 0

Totalcode 0

The keyword pointnumber originally came from the pidiff utility in PI for OpenVMS. This
name is also used in the PI API User Guide. Most PI API calls require a 32-bit integer
PointIdentifier (pt or ptnum - referenced in the PI API User Guide as PI point number).

PI SQL query Returns PIPoint “base” class attribute…

Select pointid from PIPoint… Recno

Select pointnumber from PIPoint… Pointid

9.2.2 Using Performance Equation Subsystem Built-In Functions


Built-in functions in the Performance Equations Subsystem can be called in the SQL select
list, or in the WHERE clause. In most cases, the function syntax is the same as in
Performance Equations.
The exception is calling functions that take a tag argument according to PI Server
Applications Guide, Chapter 2, Performance Equations Subsystem. In performance
equations, the syntax for a tag argument is:
'tag'
When calling these functions in PI SQL, the syntax must be:
TagNum("tag")
The TagNum function explicitly converts a character string argument to a PI PE tag type,
just as the Date function explicitly converts a character string to a time type.
For example, to call PrevEvent in PI SQL in order to obtain the value of point sinusoid
before noon, you must write:
PrevEvent(TagNum("sinusoid"), Date("12:00"))

9.3 Configuration

No advance configuration is necessary to start pisqlss. It is started and stopped exactly the
same way as other subsystems. On Windows, pisqlss can be run as a service.

PI Server Reference Guide Page 99


Chapter 9 - PI SQL Subsystem

Some tuning of pisqlss performance is possible. Settings can be changed using an


initialization file, pisqlss command line parameters, and through settings on a client product,
such as the PI ODBC Driver.

Note: The use of an initialization file may change in a later release to an alternate
method. At that time, any site-specific settings found in the initialization file will be
migrated.

This section outlines configuration using the initialization file and command line arguments.
Refer to client product documentation for instructions on changing SQL processing settings
from the client application.

9.3.1 Hierarchy of PI SQL Subsystem Settings


Since it is possible to set parameters using more than one technique, some of the settings may
be in conflict. The actual value of the settings employed follows this priority scheme:
‰ Initialization file settings
‰ pisqlss command line arguments
‰ Client product settings
Settings made lower in the list override settings higher up. For example, if the SQL query
timeout is set to 45 seconds in the initialization file and to 60 seconds on the pisqlss
command line, the value used will be 60 seconds.

9.3.2 Initialization File Settings


The initialization file is called pisql.ini and can be found in the PI\dat\ directory of your PI
Server. The file contains defaults for all settings. You may change the settings by editing the
file.
The initialization file settings are read when a new statement is allocated. Any change to this
file will be reflected in the next new statement.

Note: On a PI System for OpenVMS, the initialization file is PISysDat:pisql.ini. The


interpretation of the file settings is exactly the same for both PI Servers.

Details of the settings can be found in Appendix B of the PI ODBC Driver Manual.

9.3.3 Command Line Arguments


This section outlines the pisqlss settings that can be altered using command line arguments.
The mechanism for specifying command line arguments differs between supported platforms.
This subsection outlines the techniques.

Arguments Supported by Pisqlss


In general, an argument is specified by an argument token, one or more spaces, and then the
argument value. The argument token always begins with a leading dash ( - ). For example,

Page 100
9.3 - Configuration

pisqlss -t 60 -ts 7200 -o trace,aggrtimestart


In this example, SQL query timeout is set to 60 seconds, the default timestep (for queries
against the piinterp table) is set to 7200 seconds (that is, 2 hours) and the trace and
aggrtimestart options have been set.
The PI SQL Subsystem supports the following command line arguments:

Table 9–2. Command Line Arguments

Command Line
Argument Description

-o (Letter “o”, not zero). Options. The options are specified in a comma-separated
list of tokens. The interpretation of the tokens is not case-sensitive. See the
following table for the list of supported options.

-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the query
to return either a timeout error, or a subset of the actual results, if the
“SUBSET” option is set. See the table of options below.

-ts Default value of the timestep column in the PIINTERP table. This value can be
overridden for any query by specifying a timestep constraint in your SELECT
statement.

The -o argument is followed by a comma-separated list of option tokens with no space


between the tokens. The supported options are as follows:

Table 9–3. Command Line Option Tokens

Option Token Description

AGGRTIMESTART Causes all queries of the aggregate tables to use the time at which the
interval starts to identify the aggregate; the default is to use the time at
which the aggregate period ends.

EXECSAFE If set, the query will not execute if the PI SQL determines that a query is
too unspecific and would take too long to execute.

LOG Writes a summary of every operation by pisqlss on a statement handle to


the file sqltrace.log in your \pi\log\ directory. See also the Trace option
below. (See Note 1, below.)

QEP Causes the gateway to dump a query execution plan to a file called
pisql_n.qep in the \pi\log\ directory on the PI Server. “n” in the file name
represents the handle number.

SUBSET If a query times out while this option is in effect, pisqlss will return a subset
of the actual results with no error. (See Note 2, below.)

TRACE Writes a summary of every Prepare (that is, query parsing) and Execute
operation by pisqlss to the file sqltrace.log in your \pi\log\ directory. See
also the “LOG” option above.

PI Server Reference Guide Page 101


Chapter 9 - PI SQL Subsystem

Note 1: This file is generated in all PI Server configurations, except while not running
as a service on Windows. In this case, output is directed to standard output, which is
the command window.

Note 2: If this option is in effect, it is important to note that the results returned do not
represent the actual final results of the query. When query development is complete,
this option should be removed.

Refer to the Troubleshooting section in this chapter for details of the information generated in
the sqltrace.log file by the LOG and TRACE options.

Specifying Command Line Arguments on UNIX


Command line arguments can be added to the pisqlss startup by editing the PI Server startup
file pistart.sh. Add any desired arguments to the end of the line that starts pisqlss.

Note: pistart.sh is overwritten at every PI Server upgrade.

Specifying Command Line Arguments on Windows


There are two different methods for providing command line arguments on Windows,
depending on how the PI Server is started.

Starting pisqlss in a Command Window


Command line arguments can be provided to a Windows program by listing them after the
program name. You can edit the file pistart.bat to include command line arguments when
starting subsystems.
Starting the PI Server this way results in a command window for every subsystem. You
cannot log off Windows in this configuration and leave the system running.
Use caution in editing pistart.bat. This file is overwritten at every PI Server upgrade.

Starting pisqlss as a Windows Service


Subsystems can be started using the Services applet in the Control Panel, or by using the
pisrvstart.bat file in your PI\adm directory.
The only way to pass command line arguments to pisqlss running as a Windows service is to
use the Services applet in the Control Panel. Open the Services applet, select the PI SQL
Subsystem, right click and choose properties. Stop the service, and enter the arguments into
the Start parameters window. Click the start button to restart the pisqlss.

Page 102
9.4 - Troubleshooting

Figure 9-1. Windows Control Panel Services Applet

This examples shows a system manager about to restart the PI SQL Subsystem while setting
the default timestep to 7200 seconds and turning on TRACE mode.

Note: This works one time only. If you close the Services applet, then reopen and
reselect your service, you will not see your command line arguments from the last
run. This method cannot be used to provide command line parameters to services
started automatically when your Windows system boots.

9.4 Troubleshooting

Unexpected errors may be generated when using an ODBC application to communicate with
the PI Server for Windows and UNIX.
This section outlines techniques to help you validate the operation of the PI SQL Subsystem
and to log its processing steps.

9.4.1 Using the ipisql Utility


This utility is an interactive program that executes SQL statements directed at the PI Server.
It uses the PI API to connect to the PI Server.
The ipisql utility can be found in the PI\adm\ directory. Start the utility by typing its name at
a command prompt. The utility will connect to the default PI Server, write version
information to the screen, and then prompt for input:
D:\pi\adm\ipisql

PI Server Reference Guide Page 103


Chapter 9 - PI SQL Subsystem

Connecting to default PI System...Done


iPISQL Copyright (c) 1993-2000, OSI Software, Inc. All rights reserved.
PI API Version 1.3.4 PINet Protocol Version 00011101
Connected to PI 3.3 Build 361.43 on node "figaro"
PISQL>

To exit ipisql, type the command exit followed by a semi-colon. The error code from the
processing of the last SQL statement is the return code of the ipisql utility. This allows error
detection if ipisql is used in a script.

Submitting Queries
SQL statements can be typed at the prompt and terminated with a semi-colon ( ; ). This
causes the query to be sent to PI. The query can span multiple lines. The prompt for
subsequent lines looks like:
_PISQL>
You can use as many lines as you like.
You can also process queries stored in a text file using the FILE command:
PISQL>file myquery.txt;
A query in a file need not be terminated with a semi-colon; the query will be processed when
the end of the file is reached.
A query file may contain more than one query. If this is the case, a semi-colon must be used
to separate the queries.
Query files may contain the FILE command.

ipisql Options
The ipisql utility supports several options that can be specified on the command line.
Most of the options are exactly the same as the command line options for the PI SQL
Subsystem itself, specifically timeout (-t), timestep (-ts) and options (-o). For more
information, see Command Line Arguments on page 100.
The options argument supports the same option tokens as pisqlss, except LOG and TRACE.
In addition, ipisql supports the option token ANSISQLVAL, which is not supported as a
command-line option for pisqlss.
The full list of command line arguments are supported by ipisql is as follows:

Page 104
9.4 - Troubleshooting

Table 9–4. Command Line Arguments Supported by ipisql

Command Line
Argument Description

-csv Write results to standard output in comma-separated variable format


suitable for importing into a spreadsheet. The query text, column headings,
row count and error information are written to standard error, also in comma-
separated variable format. No command prompts are displayed.

-f Identifies a query file. If this argument is used, ipisql executes the query in
the specified file and exits. A command prompt will not be displayed.

-node Identifies the PI Server node to which to connect. The name to use is the PI
Server computer’s network name. When connecting to a PI Server for
Windows and UNIX, you must either suffix “:5450” to this name, or specify “-
port 5450”.

-o Options. The options are specified in a comma-separated list of tokens with


no space between tokens. The interpretation of the tokens is not case-
sensitive. For a list of supported options, see the table in the "Configuration"
section on page 99.

-p0...-pn SQL parameter values. The first parameter is –p0 (i.e. zero), the second is –
p1, and so on. You may specify as many SQL parameters as you like, and
need not specify all of them; ipisql will prompt for any additional parameter
values needed. The SQL parameter values are in effect throughout the entire
ipisql session.

- password Password. This argument is interpreted only if the “-username” argument is


supplied. If “-username” is provided, but “-password” is not, ipisql will prompt
you for a password.

-port TCP\IP port number. Default value is 545. You may choose to add “:portnum”
to the end of the node name when providing the “node” argument.

-t SQL query timeout, in seconds. If this time expires, pisqlss will cause the
query to return either a timeout error, or a subset of the actual results,
depending on the “SUBSET” option in effect for pisqlss.

-ts Default value of the timestep column in the piinterp table. This value can be
overridden for any query by specifying a timestep constraint in your SELECT
statement.

-username Username. If this argument is not present, ipisql will not attempt to validate
your identity; default access rights will apply.

For example, to execute query in the file myquery.txt against the PI 3.2 System larry using a
default timestep of 2 minutes, issue the command:
ipisql –ts 120 –f myquery.txt –node larry:5450
If the file myquery.txt contains the statement:
select * from picomp where tag = ? and time >= ?
you might avoid the prompt for SQL parameter values by issuing the command:
ipisql –f myquery.txt –p0 sinusoid –p1 "today"

PI Server Reference Guide Page 105


Chapter 9 - PI SQL Subsystem

9.4.2 Generating a Trace File


A trace file can be generated by starting the PI SQL Subsystem with the LOG or TRACE
options. Instructions on how to do this are in the Configuration section.
The options LOG and TRACE are similar. Both generate information in the sqltrace.log file
in the PI\log\ directory. The LOG option provides more detail.
The options can be used together. Output from the two is interspersed.

9.4.3 Output from the TRACE Option


Invoking the TRACE option shows a summary of SQL statement preparation and execution
only.

Statement Preparation Output


Output lines are of the form:
Prepare[HandleNum]>[ErrorCode][ElapsedTime] query string
Elapsed time is given in seconds. For example,
Prepare[1]>[0][0.012s] select * from picomp
where tag = "sinusoid" and time > ?
This statement contains one parameter, identified by a question mark ( ? ), whose value will
be provided at run time. Run-time parameters are discussed in detail in the PI ODBC Driver
Manual.

Statement Execution Output


Output lines are of the form:
Execute[HandleNum]>[ErrorCode][ElapsedTime] Parameters: NParams Columns:
Ncols Rows: Nrows
If the number of run-time parameters is non-zero, this message is followed by one line for
every provided parameter:
Pnn [DataType Length] parameter value
where “nn” is the run-time parameter number, starting with 0.
For example, the Execution message following the above Prepare message might read:
Execute[1]>[0][0.041s] Parameters: 1 Columns: 4 Rows: 16
P00 [time32 ] 21-Jul-97 00:00:00
The query in this example returned 16 rows of 4 columns. The query was provided with one
run-time parameter: a timestamp.

Output from the LOG Option


Output from the LOG option is more detailed. It reflects directly the argument list of the
Remote Procedure Calls (RPCs) implemented by the PI SQL Subsystem. Most of the

Page 106
9.4 - Troubleshooting

information generated should be forwarded to OSIsoft in the event of a query processing


problem.
In general, the first argument of each RPC is the handle ID. The only exception is the
newstatement function, which is the routine that generates the handle ID. In this case, the
returned handle ID is the second argument.

Function Summary Format


The LOG option generates output that looks like this:
FunctionName(arg1, arg2,…) [ErrorCode]
During query execution, progress messages are written to the log file. Each progress message
is of the form:
(HandleId): Calls: n PctDone: n Etime: n Limit: n
The items reported are:
‰ Number of calls to get PI data from other subsystems,
‰ Percent complete, based on an initial estimate,
‰ Elapsed time since the start of execution, in seconds,
‰ Timeout (Limit) in seconds. If this number is 0, no timeout limit has been set.
For example:
newstatement(8,21) [0]
clear(21,1) [0]
clear(21,0) [0]
Prepare[21]>[0][0.431s] select * from picomp
where tag = "sinusoid" and time > "y"
execute(21,&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 107


Chapter 9 - PI SQL Subsystem

Windows
When running as a service on Windows, the PI SQL Subsystem can be directed to abort
processing the current statement and to release the virtual memory it has acquired without
shutting down.
To do this, you must send a pause command to the pisqlss. Three techniques are available for
doing this:
‰ Start the Services control panel applet. Select the PI SQL Subsystem from the list and
click the “Pause” button.
‰ From a command line prompt, issue the command:
net pause pisqlss
‰ From a command line prompt, issue the command:
\pi\bin\pisqlss –pause
A message will be written to the message log indicating that the pisqlss has been paused. The
query in progress when this command is issued will return immediately with an error –10743
(i.e., RPC resolver temporarily off-line). Attempting execution of any new query when the
subsystem is in this state will also return this error.
To resume normal operation, you must send a continue command to the pisqlss. There are
three techniques available for doing this:
‰ Start the Services control panel applet. Select the PI SQL Subsystem from the list and
click the Continue button.
‰ From a command line prompt, issue the command:
net continue pisqlss
‰ From a command line prompt, issue the command:
\pi\bin\pisqlss –continue
A message will be written to the message log indicating that the pisqlss has been continued.
Shutting down and restarting the subsystem can be done at any time and is equally effective.
This is the only option available when running the PI SQL Subsystem on Windows
interactively.

UNIX
Shutting down and restarting the PI SQL Subsystem is the only technique currently available
for aborting expensive queries on UNIX. Use the kill –2 command to stop the pisqlss.

9.4.5 Performance Counters


In PI Server for Windows, several aspects of PI SQL Subsystem processing can be monitored
continuously using the Performance Monitor application. A summary of these counters
appears in the PI Performance Counters section of PI Server System Management Guide,
Chapter 1, PI System Management.

Page 108
9.4 - Troubleshooting

9.4.6 Technical Support and Problem Reports


If the PI SQL Subsystem consistently returns an error when processing SQL statements, or
appears to generate incorrect results, you should stop pisqlss and then restart with the
TRACE and LOG options enabled. Send the resulting sqltrace.log to OSIsoft Technical
Support.

PI Server Reference Guide Page 109


APPENDIX A: PI TIME FORMAT

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

A.1 Relative Time

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

A.2 Absolute Time

Absolute times have one of the following formats:


‰ DD-MMM-YY hh:mm:ss.ssss - day-month-year hour:minute:second
‰ * - current time.
‰ T - 00:00:00 on the current day (TODAY)
‰ Y - 00:00:00on the previous day (YESTERDAY)
‰ Monday - 00:00:00 on the most recent Monday
‰ Sun,Mon,Tue,Wed,Thu,Fri,Sat - 00:00:00 on the most recent Sunday, Monday, ...,
Saturday
‰ For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out,
they default to the current date. Time fields default to 00.

PI Server Reference Guide Page 111


Appendix A: PI Time Format

A.2.1 Specifying Standard or Daylight Savings Time


In almost all cases, PI can accurately determine whether or not daylight savings time is in
effect. If you wish to be specific, you may suffix the DD-MMM-YY hh:mm:ss.ssss absolute
time format with S for standard time, D for daylight time, or the appropriate time zone name.
Examples of time zone names include PST for Pacific Standard Time and MET for Middle
European Time.
You can find the names of your time zones by using pidiag –tz. This sample output was
generated on Windows NT:
c:\pi\adm>pidiag -tz
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
The PI System on Windows supports both long time zone names (such as Pacific Standard
Time) and short time zone names (such as PST). You may specify either name. Comparisons
are not case sensitive. The following time strings are equivalent:
25-Oct-98 01:30 Pacific Daylight Time
25-Oct-98 01:30 pdt
25-Oct-98 01:30 D
UNIX platforms support only the short names. PIdiag –tz shows you the names to use.
For time zones that observe daylight savings time, there is one hour per year in which an
unqualified absolute time string is ambiguous. This always occurs during the last hour of
daylight savings time before the beginning of standard time. In the Northern Hemisphere, this
occurs in the fall. In the Southern Hemisphere, this occurs in the spring. The above time
string of 25-Oct-98 01:30 in North America is an example. PI cannot determine from this
time string alone whether standard time or daylight savings time is intended.
If the unqualified time is passed, PI uses the current time to resolve the ambiguity. This
means that 25-Oct-98 01:30 will be considered daylight savings if the translation takes place
before 25-Oct-98 02:00:00 Pacific Daylight Time, and will be considered standard time
otherwise. If this is not your intent, suffix your time string with the appropriate time zone
name.
To determine if a specific time string is considered ambiguous, you can use pidiag –tz:
c:\pi\adm>pidiag -tz "25-oct-98 1:30:00"
TZ environment variable: <not set>
Standard Time Name: Pacific Standard Time (PST)
Daylight Time Name: Pacific Daylight Time (PDT)
StartYear, EndYear, Month, Week, Day, Time, Offset
1970, 2038, 4, 1, 1, 7200, -3600
1970, 2038, 10, 5, 1, 7200, 0
Passed Time: 25-Oct-98 01:30:00* PST Local: 909279000 UTC: 909307800

Page 112
A.2 - Absolute Time

The last line of the output reflects the passed time. It is marked with an asterisk (*) which
means that the time string would be ambiguous if specified without the time zone name.
Other features of the pidiag –tz command are outlined in PI Server System Management
Guide, Chapter 12, Finding and Fixing Problems: the pidiag Utility.
For the DD-MMM-YY hh:mm:ss.ssss format, if any of the date fields are left out, they
default to the current date. Time fields default to 00.

A.2.2 Examples

25 00:00:00 on the 25th of the current month

25-Aug-86 00:00:00 on that date

8: 08:00:00 on the current date

25 8 08:00:00 on the 25th of the current month

21:30:01.02 9:30:01.0200 PM on the current date

Caution should be used with the default settings. Here are some examples of timestamps that
may be confusing.

8: 08:00:00 on the current date

:8 08:00:00 on the current date

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

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

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

The confusion comes from the ambiguity in the first two examples above. Following this
theme, when minutes are added to the next examples, the time stamps are still similar.

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

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

The difference in the two notations is evident when a date is added to the time. When a date
is added to the front of the time the default notation is hh:mm:ss.ssss not :hh:mm:ss.ssss.

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

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

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

If extra colons and times are added that is greater than the given DD-MMM-YY
hh:mm:ss.ssss format the last part of the time will be disregarded.

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

PI Server Reference Guide Page 113


Appendix A: PI Time Format

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

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

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

A value for the seconds must be used if sub-seconds are used. Hence caution should also be
used when considering timestamps containing sub-seconds.

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

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

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

Here are examples of timestamps that do not work.

8:30.01 Ambiguous, 8 could be minutes or hours

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

A.3 Combined Formats

Combined time scales use both an absolute and a relative time. The absolute part of the time
can be *, T, Y, or a day of the week.

A.3.1 Examples

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

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

Mon + 14.5h 02:30:00 PM on the most recent Monday

* - 1h One hour ago

Page 114
APPENDIX B: PI TIME CONVERSIONS

This section describes how timestamps are converted between Windows and UNIX PI
Servers (PI Servers) and OpenVMS (PI 2.x). The PI API is based on PI 2.x timestamps; all
references to PI 2 System time also apply to PI API time.9

B.1 Timestamps on PI 2 Systems

PI 2 Systems timestamp is based on number of seconds since January 1, 1970 00:00:00 local
time. It is important to emphasize local time. There are at least two limitations to this
convention: daylight savings time changes and PI data access from time zones outside of the
PI System Server time zone.

B.2 Daylight Savings Time Changes on PI 2 Systems

Daylight Savings Time transitions on PI 2 Systems cause one hour of duplicate timestamps
during the transition from daylight saving time (DT) to standard time (ST) and a one-hour
discontinuity during the ST-DT transition. The ST-DT transition only causes data display
problems. The DT-ST transition, unless special procedures are followed, overwrites one hour
of data, resulting in data loss. The following two tables show actual timestamps during these
two transitions for an PI 2 Server in California, USA.

Table B-1 PI 2 Standard Time to Daylight Savings Time

Universal Coordinated PI 2 System


Time Local Time Time

7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000

7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800

7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600

7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400

7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000

9 The extended PI API introduces a time object consisting of time zone information. The discussion applies to
non-extended PI API. See the PI Application Programming Interface manual for detail.

PI Server Reference Guide Page 115


Appendix B: PI Time Conversions

Universal Coordinated PI 2 System


Time Local Time Time

7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400

7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000

7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800

7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600

7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400

Table B-2 PI 2 Daylight Savings Time to Standard Time

Universal Coordinated PI 2 System


Time Local Time Time

27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200

27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000

27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800

27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600

27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000

27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800

27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600

27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400

The first table shows two identical moments in time represented by two different times in the
PI 2 Server. The second table shows two unique one-hour spans sharing the same times in the
PI 2 Server.

B.3 Timestamps across Time Zones on PI 2 Servers

The following table compares a timestamp generated on a PINet/VMS node to a timestamp


on a PI 2 Server in a different time zone.

Table B-3 PI2 Timestamps across Time Zones

Time zone Universal Coordinated Time Local Time PI 2 System Time

EST (PINet/VMS 17-Nov-96 10:00:00 17-Nov-96 848206800


node) 05:00:00

PST (PI 2 Server) 17-Nov-96 10:00:00 17-Nov-96 848196000


02:00:00

Page 116
B.4 - Timestamps on PI Server Systems

Both timestamps represent the same moment in time, but have different values. An interface
running on the PINet/VMS node would write values that the Server treats as three hours in
the future.

B.4 Timestamps on PI Server Systems

The PI Servers solve this problem by internally storing time based on Coordinated Universal
Time (or UTC:Universal Time, Coordinated). A given moment in time is represented by the
same timestamp regardless of PI Server location. Feeding data from multiple PI Server
satellite nodes scattered around the world into one PI Server poses no time problems.

B.5 Translating PI 2 Timestamps to PI Server Systems

Data sources based on the PI API or data from PI 2 Net nodes pose a conversion problem.
The timestamps arrive at the Server in PI 2 Server format and must be converted to PI Server
format.
PI 2 Server timestamps are converted to PI Server format on the PI Server. Therefore all
conversions assume the local time and ST/DT state of the PI Server. Conversions are applied
to incoming data (such as data arriving from an interface) and outgoing data (such as archive
values for a PI Process Book trend). Data from a PINet/VMS node in a time zone different
from the PI Server will have conversion errors. Likewise, data from a PI Server destined to a
PI API-based application in a different time zone will also have conversion errors.
PI Servers contain a translation layer that identifies connections from PINet/VMS nodes and
PI API applications. The layer translates calls to appropriate PI Server calls and translates
values and timestamps to PI Server values and timestamps.
The timestamp conversion algorithm is quite simple. The offset between local time and
Universal Coordinated Time is calculated and used as shown in the following two equations:
‰ OpenVMS PI Server based time = PI Server based time – offset
‰ PI Server based time = OpenVMS PI Server based time + offset
The offset calculation requires the PI Server’s operating system to be correctly configured to
the correct time zone and ST/DT status. The offset value will vary by one hour during the
year on systems that honor ST/DT. For example a computer in California will have an offset
of 8 hours during standard time and 7 hours during daylight time. The offset is updated within
5 minutes of actual DT/ST transitions.
The following two tables show time conversions from a PI API-based interface flowing into a
PI Server in California during daylight savings time transitions.

Table B-4 PI Server Standard Time to Daylight Savings Time

Universal Local Time PI 2 System Offset PI Server


Coordinated Time Time Time

7-Apr-96 08:30:00 7-Apr-96 00:30:00 PST 828837000 28800 828865800

PI Server Reference Guide Page 117


Appendix B: PI Time Conversions

Universal Local Time PI 2 System Offset PI Server


Coordinated Time Time Time

7-Apr-96 09:00:00 7-Apr-96 01:00:00 PST 828838800 28800 828867600

7-Apr-96 09:30:00 7-Apr-96 01:30:00 PST 828840600 28800 828869400

7-Apr-96 10:00:00 7-Apr-96 02:00:00 PST 828842400 28800 828871200

7-Apr-96 10:00:00 7-Apr-96 03:00:00 PDT 828846000 25200 828871200

7-Apr-96 10:30:00 7-Apr-96 03:30:00 PDT 828847800 25200 828873000

7-Apr-96 11:00:00 7-Apr-96 04:00:00 PDT 828849600 25200 828874800

7-Apr-96 11:30:00 7-Apr-96 04:30:00 PDT 828851400 25200 828876600

Table B-5 PI Server Daylight Savings Time to Standard Time

Universal Local Time PI 2 System Offset PI Server


Coordinated Time Time Time

27-Oct-96 07:30:00 27-Oct-96 00:30:00 PDT 846376200 25200 846401000

27-Oct-96 08:00:00 27-Oct-96 01:00:00 PDT 846378000 25200 846403200

27-Oct-96 08:30:00 27-Oct-96 01:30:00 PDT 846379800 25200 846405000

27-Oct-96 09:00:00 27-Oct-96 02:00:00 PDT 846381600 25200 846406800

27-Oct-96 09:00:00 27-Oct-96 01:00:00 PST 846378000 28800 846406800

27-Oct-96 09:30:00 27-Oct-96 01:30:00 PST 846379800 28800 846408600

27-Oct-96 10:00:00 27-Oct-96 02:00:00 PST 846381600 28800 846410400

27-Oct-96 10:30:00 27-Oct-96 02:30:00 PST 846983400 28800 846412200

These two tables demonstrate how the PI Server solves the data overlap problem of the DT to
ST transition and the continuity problem of the ST to DT transition. However, there is a
limitation to this conversion algorithm. It is assumed that arriving timestamps are from the
current DT/ST state, that is, a timestamp from ST written to the PI Server during DT will be
converted using the DT offset.

B.6 Translating PI Server Timestamps to PI 2 Based Timestamps

Data flowing from a PI Server to a PI API based application uses a slightly different
timestamp conversion algorithm. If the timestamp conversion algorithm from PI 2 to PI
Server were reversible, the PI Server’s ability to solve the data overlap and discontinuity
problems of DT/ST transitions would not be viewable from a PI API application. Conversion
from PI Server timestamps to PI 2 Server based timestamps uses a constant offset value, that
is, the offset value is not a function of the timestamp being converted. The current offset
value in effect is used to convert any archive value regardless of whether the archive value

Page 118
B.7 - How PI Client Applications Handle DST Changes

represents a value during daylight time or standard time. Here’s a table of examples, again
representing systems in California, USA:

Table B-6 PI Examples of Timestamp conversions for California-based systems

PI Server Time Universal DT/ Returned PI 2 Local Time Offset


of Archive Value Coordinated ST System Time
Time

824851800 20-Feb 21:30:00 ST 824823000 20-Feb 13:30:00 PST 28800

840538800 20-Aug 12:00:00 ST 840510000 20-Aug 04:00:00 PDT 28800

824851800 20-Feb 21:30:00 DT 824826600 20-Feb 13:30:00 PST 25200

840538800 20-Aug 12:00:00 DT 840513600 20-Aug 04:00:00 PDT 25200

This table shows conversion of identical PI Server timestamps when called during ST and
during DT; the resulting PI 2 System Time is different in each case. Although this appears to
be ambiguous behavior, it allows preservation of correct DT/ST transitions.
The PI API time parsing/formatting routines have been modified to handle this behavior. The
PI API detects the server type and invokes parsing/formatting routines that account for this
behavior. Applications that make no assumption of PI timestamps and use PI parsing and
formatting routines will behave correctly. Applications that invoke non-PI time formatting
techniques may report invalid times.

B.7 How PI Client Applications Handle DST Changes

Archive timestamps in PI Server are stored as universal times; thus the PI Server is not
impacted by daylight savings time. This is in contrast to PI 2.x, where there is a one-hour
hole in the data during the springtime change, and one hour of data is discarded during the
fall time change.
The client applications reflect the daylight savings time changes as follows: it is up to the
displayer to apply an interpretation. OSIsoft does not choose the day that the changes take
place; our software responds to the system time of the local machine.
The PI API will interpret the time according to the local client machine's settings. The time
zone setup information is part of the PC configuration. The PI API queries the operating
system to find out if a time is in daylight savings time or not. Operating systems other than
OpenVMS have the dates of the daylight savings transition times built in. A table of
transition dates is maintained which spans decades.
It is interesting to examine a PI ProcessBook trend that spans a daylight savings time change.
On the day of the springtime change, against a PI Server System, a trend would show
continuous and complete data for 23 hours (midnight to midnight). If the time changes on 3
April at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly
01:59:59.99999999999... the clock would change to 3:00:00. The x-axis will be missing the
60 minutes between 2 a.m. and 3 a.m. There will not be a 2:00:00 marker.

PI Server Reference Guide Page 119


Appendix B: PI Time Conversions

On the day of the fall time change, against a PI Server System, a trend would show
continuous and complete data for 25 hours (midnight to midnight) on the day of the fall time
change. If the time changes on 31 October at 2:00 am, one could watch a theoretical clock
during this transition and at exactly 01:59:59.99999999999... the clock would change to
1:00:00. The x-axis will have the 120 minutes between 1a.m. and 2 a.m. There will be two
consecutive 2:00:00 markers.
On the day of the springtime change, against a PI 2.x system, a trend would show continuous
data for 24 hours (midnight to midnight). If the time changes on 3 April at 2:00 am, one could
watch a theoretical clock during this transition and at exactly 01:59:59.99999999999... the
clock would change to 3:00:00. The PI 2.x Server must adjust its time, and will interpolate
(adding records to the archive as necessary) in order to span the 1-hour gap. The x-axis will
show the 60 minutes between 2 a.m. and 3 a.m., and the values displayed are the interpolated
data.
On the day of the fall time change, against a PI 2.x system, a trend would show discontinuous
and incomplete data for 24 hours (midnight to midnight). If the time changes on 31 October
at 2:00 a.m., one could watch a theoretical clock during this transition and at exactly
01:59:59.99999999999... the clock would change to 1:00:00.
The PI 2.x Server must adjust its time, and the System Administrator gets to choose which
hour of data to discard. This data is lost forever, and will never be displayed by any
application. The x-axis will show only 60 minutes between 1 a.m. and 2 a.m., with no
indication that data was discarded.

B.8 PI in the 21st Century

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

Page 120
APPENDIX C: PI API AND TOOLKIT USAGE

C.1 Overview

C.1.1 PI API
The PI API is a library of routines originally written to access a PI 2.x System
programmatically. Before the PI-SDK, all of the Microsoft Windows-based PI client
applications (such as PI ProcessBook) were based on the PI API. Today most PI interfaces
continue to use the PI API, and the library is the only programming method supported on
both Windows and UNIX.
The PI API routines reflect the PI 2.x architecture. For example, in PI 2.x, tag descriptors are
limited to 26 characters, while in PI Server the limit is 65535. The PI API routine
pipt_descriptor ( ) returns a maximum of 26 characters even when the PI Server is running
on Windows or UNIX.
PI API version 1.2 first introduced features to take advantage of the PI 3.x architecture. This
included:
‰ Sub-second timestamps
‰ Access to string data types
Beginning with PI API 1.4, new functions were added to take further advantage of the PI 3.x
architecture. This includes support for long tag names, multi-character point sources, and
reading UTC time from the server. These features are only supported when accessing PI
3.4.370 and later.
The PI Server contains a translation layer to provide backward compatibility with most PI
API routines. The translation layer translates calls to appropriate PI Server calls and translates
values and timestamps to PI Server values and timestamps. However, limitations do exist.
These limitations are documented in this appendix.

C.2 PI API Usage on PI Server

This section assumes knowledge of the PI API. Refer to the PI Application Programming
Interface Manual for details.

Error codes of piar_ routines


All archive interface routines interact with the Snapshot Subsystem. Some routines such as
piar_deletevalue() or piar_putarcvaluex() require an existing event at the passed time. The

PI Server Reference Guide Page 121


Appendix C: PI API and Toolkit Usage

Snapshot Subsystem does not have information about archive events unless the passed time is
the Snapshot itself or the latest archive event. In all other cases, these routines return 0
(success) and pass the request to the archive subsystem via the Event Queue. If the required
event does not exist the archive subsystem sends an error to the PI event log.

piar_replacevalue ( )
This routine replaces a single value for the passed time. Replaced archived values require
approximately twice the archive space to accommodate “edited” flags. Therefore, replacing
large amounts of archived values requires significant free archive space.

piar_panvalues ( )
This routine, if passed a count of 0 will always return error -1. PI 2 behavior is to return the
timestamp if an event exists at the passed timestamp or -103 if now events exist at the passed
timestamp.

piel_addevnt ( )
A call to piel_addevent will create an entry in the PI System message log as follows:
0 Eventlogger 19-Sep-96 11:31:02
>> [Group,3,Type,4,timestamp,19-Sep-96 11:31:02]
This is where the message text goes.
The user name will always be Eventlogger. The timestamp is the time the message arrived in
the Message Subsystem. The second line contains group, type, and passed timestamp in
square brackets, followed by the passed message text.

piel_evntactn ( )
This is not supported in the current version of PI Server.

pipt_compspecs and pipt_compspecseng


Compmin and compmax are passed internally as short integers. This limits the values to +/-
32767. If the compmax value for a point is larger than 32767, it will be returned as 32767.

pipt_dates ( )
Rather than returning a PI user name, the creator and changer arguments return a string
containing a number. The number is associated with the PI user name internally on the
Server.

pipt_descriptor ( )
Although the length of a point descriptor has no practical limit, this PI API function returns a
maximum of 26 characters, for compatibility with PI 2.x.

pipt_digcode ( )
Although the length of a digital state string has no practical limit, this PI API function uses
only the first 12 characters, for compatibility with PI 2.x.

Page 122
C.2 - PI API Usage on PI Server

PI Server is designed to support multiple digital state sets, whereas PI 2.x supports a single
state set. The System Digital State Set is provided for backward compatibility with PI 2.x.
The same digital state string may appear multiple times in the System Digital State Set; it
may appear a single time in a custom state set. In PI Server, the state number and the digital
state code both refer to the same number.
Pipt_digcode ( ) returns the first instance it finds, using the following algorithm:
‰ Search through the digital state sets, from lowest set number to highest. This means
that the System Digital State Set (number 0) will always be searched first.
‰ Search through the given digital state set, from lowest state number to highest.
If found, the digital state is returned as a 32-bit value. The high bit is set; this makes it a
negative number. The next 15 bits indicate the state set number. The low 16 bits indicate the
state number. There is no way to request a subsequent instance of the string.

pipt_digcodefortag ( )
Although the length of a digital state string has no practical limit, this PI API function uses
only the first 12 characters, for compatibility with PI 2.x.

pipt_engunitstring ( )
Although the length of an engineering unit string has no practical limit, this PI API function
returns at most the first 12 characters.

pipt_engunstring( )
This function is called with the point number substituted for the engineering unit code
parameter.

pipt_excspecseng
Excmin and excmax are passed internally as short integers. This limits the values to +/-
32767. If the excmax value for a point is larger than 32767, it will be returned as 32767.

pipt_exdesc ( )
Although the length of an extended descriptor has no practical limit, this PI API function
returns a maximum of 80 characters.

pipt_findpoint ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters.

pipt_nextptwsource ( )
Although the length of a point source string has no practical limit, this PI API function
requires that the point source be a single character only. It will not recognize point source
strings longer than a single character. The passed point number is not used. The first call to
this function begins searching for the matching point source at point number 1. Subsequent

PI Server Reference Guide Page 123


Appendix C: PI API and Toolkit Usage

calls return the next point in the PI Server point database that matches the passed point
source.

pipt_pointid ( )
This function should not be used; use pipt_findpoint ( ) instead.

pipt_pointsource ( )
Although the length of a point source string has no practical limit, this PI API function
returns the first character only.

pipt_recordtype ( ) and pipt_rescode ( )


On PI 2, tags with rescode 1, 2 and 3 store their times as steps. If you display a trend of these
tags, the values are interpolated between events, resulting in a smooth curve.
Tags with rescode 4, however, store their times as full timestamps. If you display a trend of
these tags, the values are not interpolated between events, resulting in a step curve.
On a PI 2 system, pipt_recordtype will return a 1 for tags with rescodes 1, 2, or 3. It will
return a 0 for tags with rescode 4.
On PI Server, there are no rescodes. However, there is the step attribute. In PI Server, if you
display a trend of tags with a step attribute = 0, the values are interpolated between events,
resulting in a smooth curve. If you display a trend of tags with a step attribute = 1, the values
are not interpolated between events, resulting in a step curve.
For compatibility, on a PI Server system, pipt_rescode returns a 1 if the step attribute = 0,
and it returns 4 if the step attribute = 1. It will never return 2 or 3.
For compatibility, on a PI Server system, pipt_recordtype returns 1 if the step attribute = 0,
and it returns 0 if the step attribute = 1.
Keep in mind that pipt_rescode and pipt_recordtype are not very useful on a PI Server
system. They are implemented only to provide compatibility for API programs that were
already written.

pipt_tag ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 12 characters. Delimiters are not included, as this was a PI 2.x concept.

pipt_taglong ( ) and pipt_tagpreferred


Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters for compatibility with PI 2.x. Delimiters are not included, as this
was a PI 2.x concept.

pipt_totalspecs ( )
This is not supported in the current version of PI Server.

Page 124
C.2 - PI API Usage on PI Server

pipt_updates ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 12 characters for compatibility with PI 2.x.

pipt_wildcardsearch ( )
Although the length of a tag name has no practical limit, this PI API function uses a
maximum of 80 characters for compatibility with PI 2.x. Subfields are not used, as this is a
PI 2.x concept.

pisn_“X” ( ) {etc.}
The following discussion is for pisn_getsnapshot ( ), pisn_getsnapshots, pisn_putsnapshot
( ), pisn_putsnapshotq ( ), pisn_putsnapshots ( ), pisn_sendexceptionq ( ) and
pisn_sendexceptions ( ).

Sending Digital States to PI2


In PI2, there is one digital state table with 1024 entries, with entries 193-320 reserved for
OSIsoft error codes.
The interface should send the negative of the table offset if it is an error code.
For example, if the error is IO Timeout then the interface should send -246.
The interface should send the positive relative offset from the digstartcode if it is a valid
digital state.
For example, if the tag has digstartcode defined to be 20, and the two valid states are put in
offsets 20 and 21 in the Digital State Table, then the interfaces should send 0 and 1 in order to
get states 20 and 21, respectively. Note that the interface could send -20 and -21 and this
would work, but this is not the recommended algorithm.

Sending Digital States to PI Server


In PI Server, the System Digital State Set is provided, primarily for compatibility with PI2.
This contains 10240 entries, with entries 193-320 reserved for OSIsoft error codes.
The interface should send the negative of the table offset if it is an error code.
For example, if the error is "IO Timeout" then the interface should send -246.
The interface should send the positive offset in the custom digital set if it is a valid digital
state.
For example, if the tag has a custom digital set defined with two states, then the interfaces
should send 0 and 1. Note that the customer could opt to put the two states in the System
Digital State Set, at offsets 20 and 21 for example. Then the interface could send -20 and -21
and this would work, but this is not the recommended algorithm.
If you retrieve a digital state (istat) from PI, it will be a negative number. You do NOT have
to change this into a positive number in order to send it back to PI.

PI Server Reference Guide Page 125


Appendix C: PI API and Toolkit Usage

Retrieving Digital States from PI2


In PI 2, a negative istat is interpreted as a digital state (rather than an integer). The absolute
value of the istat gives the offset into the digital state table that corresponds to the state
string.

Retrieving Digital States from PI Server


In PI Server, a negative istat is interpreted as a digital state (rather than an integer). To
decode the state, first take the absolute value of the istat. The upper 16 bits now indicate the
digital set number. The lower 16 bits now indicates the digital state number for the given
digital set. The System Digital State Set has a number of 0.

pitm_formtime ( ) or pitm_systime ( )
Sometimes the PI API appears to be off by several hours when translating the time. This is
usually a configuration problem.
You must set the time zone and daylight savings time correctly on both server and client
machines. In WinNT and Win95, set this using Control Panel, Date/Time.
For 16-bit applications, you can set the TZ environment variable. Thirty-two-bit applications
should not use this, especially if the site is not in the United States.
The TZ environment variable will overwrite the settings of the Time zone settings of the
Operating System in the Control Panel. If you use the TZ variable, the Daylight Saving Time
change will be calculated with a fixed algorithm, which is only valid for the United States.
The result is that if you are anywhere else in the world, DST will start and end at the wrong
time. For 16-bit software there is no solution to get this working properly for non-U.S. sites at
the moment.
If you use pitm_systime to retrieve number of seconds past Jan 1, 1970, you should also use
pitm_formtime to translate this to a string. If you mix PI API time functions with
Microsoft C++ time functions (time and localtime) you may get results that are off by several
hours.
Here is an excerpt from Microsoft's MSDN Run-time Library Reference:
The _tzset function uses the current setting of the global environment variable TZ to
assign values to three global variables:
_daylight, _timezone, and _tzname.
TZ is a Microsoft extension and not part of the ANSI standard definition of localtime.
These variables are used by the _ftime and localtime functions to make corrections from
coordinated universal time (UTC) to local time, and by the time function to compute
UTC from system time.
Use the following syntax to set the TZ environment variable:
set TZ=tzn[+ | -]hh[:mm[:ss] ][dzn]
where

Page 126
C.3 - PI Toolkit Usage on PI Server

Tzn = Three-letter time-zone name such as PST. You must specify the correct offset
from UTC.

Hh = Difference in hours between UTC and local time. Optionally signed.

Mm = Minutes. Separated from hh by a colon (:).

Ss = Seconds. Separated from mm by a colon (:).

Dzn = Three-letter daylight-savings-time zone such as PDT. These three letters can be
anything you like. If DST is never in effect in the locality, set TZ without a value for
dzn.

For example, to set TZ to correspond to the current time zone in Germany, you can use
one of the following statements:
set TZ=GST1GDT
set TZ=GST-1GDT
These strings use GST to indicate German standard time, assume that Germany is one
hour ahead of UTC, and assume that DST is in effect.
If TZ is not set, _tzset attempts to use the time zone information specified by the
operating system. If _tzset cannot obtain this information, it uses PST8PDT by default,
which signifies Pacific Time zone.
Localtime corrects for the local time zone if the user first sets the global environment
variable TZ.

C.3 PI Toolkit Usage on PI Server

This section assumes knowledge of the PI Toolkit. Refer to the PI System Manual, Volume
II, for OpenVMS for details.

GetCompSpecs ( )
See comments for the PI API function pipt_compspecs ( ).

GetCompSpecsEng ( )
See comments for the PI API function pipt_compspecs ( ).

GetDigCode ( )
See comments for the PI API function pipt_digcode ( ).

GetDigPointers( )
See comments for the PI API function pipt_digpointers ( ).

GetEngCode( )
This function returns with engUnitCode equal to 0.

PI Server Reference Guide Page 127


Appendix C: PI API and Toolkit Usage

GetEngUnits( )
This function returns with engUnitCode equal to pt if pt is less than 32768, else it returns
with engUnitCode equal to 0.

GetEngUnString (engUnitCode, engUnitStr, error)


See comments for the PI API function pipt_engunstring ( ).

GetExcSpecsEng( )
See comments for the PI API function pipt_excspecseng ( ).

Page 128
APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT
CLASSES

D.1 Predefined Attribute Sets

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

PI Server Reference Guide Page 129


Appendix D: Predefined Attribute Sets and Point Classes

D.1.2 base
Attribute Type Default
Archiving BYTE 1
Changedate TimeStamp 31-Dec-69 16:00:00
Changer Uint16 0
Compdev Float32 2.
Compmax Uint32 28800
Compmin Uint16 0
Compressing BYTE 1
Creationdate TimeStamp 31-Dec-69 16:00:00
Creator Uint16 0
Descriptor String
Displaydigits BYTE -5
Engunits String
Excdev Float32 1.
Excmax Uint32 600
Excmin Uint16 0
Exdesc String
Pointsource String Lab
Pointtype UBYTE 12
Scan BYTE 1
Shutdown BYTE 1
Span Float32 100.
Step BYTE 0
Typicalvalue Float32 50.
Zero Float32 0.

D.1.3 classic
Attribute Type Default
Convers Float32 1.
Filtercode Int16 0
Instrumenttag String
location1 Int32 0
location2 Int32 0

Page 130
D.1 - Predefined Attribute Sets

location3 Int32 0
location4 Int32 0
location5 Int32 0
Squareroot Int16 0
Srcptid Int32 0
Totalcode Int16 0
userint1 Int32 0
userint2 Int32 0
userreal1 Float32 0.
userreal2 Float32 0.

D.1.4 sqcalm_parameters
Attribute Type Default
AutoAck String yes
ChartType Int32 0
ClearOnLimitChange String true
ClearOnStart String false
CLTag String
CommentTag String
LCLTag String
LSLTag String
Mixture String
OneSideofCL String
Options String
OutsideControl String
OutsideOneSigma String
OutsideTwoSigma String
PIProductLimits String no
ProductTag String
ReferenceTag String
ResetTag String
SQCAlarmPriority Int32 0
Srcptid Int32 0
Stratification String

PI Server Reference Guide Page 131


Appendix D: Predefined Attribute Sets and Point Classes

TestStatusTag String
Trend String
UCLTag String
USLTag String
WaitOnLimitChange String false

D.1.5 totals
Attribute Type Default
CalcMode String timeweighted
CompValue String ON
Conversion Float32 1.
EventExpr String
FilterExpr String
Function String Total
MovingCount Int16 2
Offset String +0m
Offset2 String +0m
Options String
PctGood Float32 85.
Period String +1h
Period2 String +2m
RateSampleMode String natural
ReportMode String Running
Srcptid Int32 0
TotalCloseMode String clock
Zerobias Float32 0.

D.2 Predefined Point Classes

Alarm Base Classic SQC_Alarm Totalizer


base base base base base
alarmparam classic sqcalm_parameters totals

Page 132
TECHNICAL SUPPORT AND RESOURCES

Technical Support Options

OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a


week. You can read complete information about technical support options, and access all
of the following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.

Help Desk and Telephone Support


Telephone support is available 24 hours a day, 7 days a week. Please note that in some
cases you may need to leave a message, and you will receive a call back within one hour.
• Call the Technical Support Center at (01) 510-297-5828
• FAX Technical Support at (01) 510-352-2349

Email Support
Email support is available 24 hours a day, 7 days a week. Send technical support
inquiries, including the problem description and message logs, to:
techsupport@osisoft.com. Technical Support will respond to your inquiry within 24
hours.

Personalized Online Technical Support


The Online Call Center allows you to create a support call, which will be responded to in
24 hours. It also allows you to review information from your previous support calls. Click
My Support > My Calls. My Support also allows you to review My Products, My
Download History, and SRP Terms, which covers Service Reliance Program (SRP)
service agreements.

Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).

PI Server Reference Guide Page 133


Technical Support and Resources

• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.

Remote Server Access


Technical support engineers can remotely access your PI Server to provide diagnostics,
hands-on troubleshooting, and assistance. For remote assistance, go to Contact Us >
Remote Access Options in the Technical Support Web site.

On-site Technical Support


OSIsoft provides on-site service according to SRP service level agreements. To see
current SRP status, go to My Support > SRP Terms in the Technical Support Web site.

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:


• Product name, version, and/or build numbers
• Computer platform (CPU type, operating system, and version number)
• The time that the difficulty started
• The message log(s) at that time

Find Version and Build Numbers


To find version and build numbers for each PI System subsystem (which vary depending
on installed upgrades, updates or patches) use either of the following methods:
• If you have PI System Management Tools (PI SMT) installed, select Start >
Programs > PI System > PI System Management Tools. In PI SMT, select the
server name, then under System Management Plug-Ins, open Operation > PI
Version. The PI Version tree lists all versions.
• If you do not have PI SMT installed, open a command prompt, change to the
pi\adm directory, and enter piversion –v. To see individual version numbers
for each subsystem, change to the pi\bin directory and type the subsystem name
followed by the option –v (for example, piarchss.exe –v).

View Computer Platform Information


To view platform specifications:
• In Windows, right-click on My Computer and choose Properties. For more
detailed information, select Start > Run, and enter msinfo32.exe
• In UNIX, enter uname –a

Page 134
INDEX OF TOPICS

Absolute Time, 111 base class, 41


Access permissions, 49 changeDate, 55
attributes, 49 changer, 55
Accumulators changing tag names, 42
data types for, 43 changing zero/span, 46
Adm directory, 6 compDev, compMin,
Annotation, 20 compMax, 47
file, 21 compressing, 47
Anti-virus software Compression, 18, 91
OSIsoft recommendation, 7 convers attribute, 51
API Node, 10 creationDate, 55
API, see PI API, 5 creator, 55
Apisnap, 5, 20 ctr_lmap, 52
Application Programming Interface ctr_progid, 52
see PI API, 5 ctr_strmap, 52
Applications, point attributes for, dataAccess, 49
51 dataGroup, 49
Architecture defaults, 52
SQL Subsystem, 97 Descriptor, 44
Archive digitalSet, 45
archiving flag, 48 displayDigits, 49
Files, 19 engUnits, 46
foreign data sources, 17 exception reporting, 87
flag, 53 exDesc, 44
Size for classic points, 50
Considerations, 20 for COM connectors, 52
write cache, 13 for user-written programs, 51
Archiving attribute, 48 instrument tag attribute, 50
Archiving flag, 48 location attributes, 50
Argument newTag, 44
Token pointID, 55
SQL Subsystem, 100 PointSource, 46
Attributes PointType, 43
and point classes, 41 ptAccess, 49
archiving, 48 PtClassName, 42

PI Server Reference Guide Page 135


Index of Topics

ptGroup, 49 Classes
recNo, 55 PtClassName attribute, 42
scan, 47 Classes, base point class, 41
shutdown, 50 Classic Point
sourceTag, 47 Definitions, 98
span, 45 Classic Point class, 50
squareRoot attribute, 50 classicctr point class, 52
srcptid attribute, 51 classicctr.dif, 52
step, 48 Client Applications
system-assigned, 55 Security, 95
tag name restrictions, 42 COM connectors, 14
totalcode attribute, 51 classicctr.dif file, 52
typicalValue, 45 creating point class for, 52
userInt and userReal attributes, longword mapping parameter,
51 52
zero, 45 mapped points, 52
Bad Input digital state, 23 point attributes for, 52
Bad status, 23 program ID parameter, 52
Base class, 41 string mapping parameter, 52
Base Point Class COM objects, 14
Point Attributes, 98 Combined Time Format, 114
Batch Database, 38 Command
bin directory, 6 Ptclass, 41
Blob point type, 43 Command Line Arguments
Buffering SQL Subsystem, 100
PI API, 6 UNIX, SQL Subsystem, 102
Build number, 4 Windows, SQL Subsystem,
C language, 6 102
Capitalization CompDev, 90, 91
case sensitivity in searches, 42 Point attribute, 53
digital state sets, 25 CompDev attribute, 47
Case sensitivity CompDevPercent, 53, 91
digital state names, 25 CompDevPercent attribute, 47
for tags, 42 CompMax, 90, 91
ChangeDate, 53 Point attribute, 53
point attribute, 55 CompMax attribute, 47
Point attribute, 55 CompMax Point attribute range of
values, 51
Changer, 53
CompMin, 90, 91
point attribute, 55
Point attribute, 53
Changing zero/span, 46
CompMin attribute, 47
Chsrc file
Compressing attribute, 47
UNIX, 8

Page 136
Index of Topics

Compression, 47, 90 from foreign data sources,


Deviation, 91, 92 16
flag, 47, 53 Data Archive
foreign data sources, 18 Database, 19
Maximum, 91 Expensive queries, 107
Minimum, 91 Data Compression
out of order events, 48 specifications, 47
Specifications, 53 Data flow
swinging door, 91 overview, 9
Windows Data output
recommendation against, sourceTag attribute, 47
7 Data permissions, 49
Computer platform Data sources
Information, 134 non-PI, 14
Concurrency, 98 Data types
Configuration for accumulators, 43
SQL Subsystem, 99 for negative integers, 43
Configuration files pointType attribute, 43
shutdown.dat, 50 DataAccess
Configuration parameters, 25 Point attribute, 49
Constraints on tag names, 42 DataAccess Point Attribute, 53
Conventions, naming tags, 42 Database
Convers point attribute, 51, 53, 98 Batch, 38
Conversion Firewall, 37
factor, 54 Group, 38
CreationDate, 53 Module, 38
point attribute, 55 Point, 19, 20
Creator, 53 Proxy, 37
point attribute, 55 Snapshot, 20
ctr_lmap, 15 Trust, 37
ctr_lmap attribute, 52 User, 38
ctr_progid, 15 Databases
ctr_progid attribute, 52 non-PI, 14
ctr_strmap, 15 timeout database, 25
ctr_strmap attribute, 52 DataGroup
Current snapshot values, 5 Point attribute, 49, 53
dat directory, 6 DataOwner
Data Point attribute, 49, 53
compression, 47, 90 Daylight Savings Time, 112, 126
foreign data sources, 14 Changes, 115
retrieval PI Client Applications,
119

PI Server Reference Guide Page 137


Index of Topics

to Standard Time, PI 3 Point attribute, 53


Server, 118 DisplayDigits attribute, 49, 50
Default Documentation
Digital State Set, 23 conventions, v
point attributes, 52 for interfaces, vi
Descriptor Engineering units, 46
Point attribute, 53 EngUnitCode, 128
Descriptor attribute, 44 EngUnits
Deviation Point attribute, 53
Compression, 92 EngUnits attribute
Differences about, 46
in PI Systems single quotes in, 46
SQL Subsystem, 98 EngUnitStr, 128
Digcode, 24 Environment variable, 8, 25
Digital code value, 24 Event
Digital point type, 43 Out of order, 91
Digital State processing, 11
Decoding, 126 Event Queue, 11, 12
Retrieving from PI Server, 126 Events
Retrieving from PI2, 126 definition of, 9
Sending to PI Server, 125 shutdown events, 50
Sending to PI2, 125 significant event, 10
strings, 23 ExcDev, 87, 89
Table, 23 Point attribute, 53
Editing, 24 ExcDev attribute, 89
Digital State Set, 23 ExcDevPercent, 53
defining, 24 ExcDevPercent attribute, 89
deleting, 24 Exception Deviation, 89
Digital state sets, 45 Exception Maximum, 89
case sensitivity, 25 Exception reporting
Digital states about, 87
digitalSet attribute, 45 foreign data sources, 17
Digital tag, 24, 92 minimum, 92
DigitalSet, 53 specifications, 47
DigitalSet attribute, 45 turning off, 90
DIGSET_nn, 24 ExcMax, 87
Digstartcode, 125 Point attribute, 53, 89
Directories ExcMax Point attribute range of
PI file system, 6 values, 51
structure, 6 ExcMin, 87
UNIX, 8 Point attribute, 53, 89
DisplayDigits ExDesc, 47

Page 138
Index of Topics

Point attribute, 53 getEngUnString, 128


ExDesc attribute, 44 getExcSpecsEng( ), 128
Executables for the PI System, 8 Group
Expensive Queries assigning users to, 38
clearing, 107 Database, 38
UNIX, 108 file, UNIX, 8
Extended descriptor Security, 95
Point attribute, 53 Handle. See Statement Handle
File System Compression I/O
recommendation against, 7 Timeout, 23
Files Initialization
archive, 19 SQL Subsystem, 100
PI file system, 6 Installation
Filtercode, 53 PI-SQL Checklist, 100
Point Attribute, 98 Instrument tag
Filtercode point attribute, 51 point attribute, 50
Filtering Instrument Tag
turning off exception Point attribute, 53
reporting, 90 int16 point type, 43
Filtering data int32 point type, 43
Exception reporting, 87 Integer point type, 43
Filtering, zero/span, 46 Interface
Firewall, 7, 95 definition of, 5
Database, 37 PerfMon, 5
float16 Ping, 5
changing zero/span, 46 Random and ramp soak, 1
out of range data, 46 sending digital states, 125
span attribute, 45 Sending to PI Server, 125
zero attribute, 45 Simulators, 5
float16 point type, 43 SNMP, 5
float32 Interfaces
Point type, 54 downloading documentation
float32 point type, 43 for, vi
float64 point type, 43 exception reporting, 87
formatting values PointSource attribute, 46
displayDigits attribute, 49 Interpolation, 124
getCompSpecs ( ), 127 of numeric values, 48
getCompSpecsEng ( ), 127 IP Address, 37
getDigCode ( ), 127 ipisql Utility, 103
getDigPointers( ), 127 options for, 104
getEngCode( ), 127 Istat, 126
getEngUnits( ), 128 Korn Shell, 8

PI Server Reference Guide Page 139


Index of Topics

Lab point source, 46 Calculation for timestamp, 117


LibC.ansi.sl OSIsoft
UNIX, 8 Error codes, 125
Libraries, 8 Out of order events
Localtime, 115, 126, 127 compression, 48
Location Codes Out of range
Point attribute, 50, 54, 98 for float16, 46
location1 point attribute, 50 Output to other systems
location2, 54 sourceTag attribute, 47
location2 point attribute, 50 Over Range, 45, 46
location3 point attribute, 50 digital state, 23
location4 point attribute, 50 Parameters
location5 point attribute, 50 COM program ID, 52
log directory, 6 longword mapping, 52
Log files server configuration, 25
location, 8 string mapping, 52
LOG option Password, 38, 95
SQL Subsystem, 106 file, UNIX, 8
Login, remote Performance
command-line tools, 4 impact of file system
Longword mapping parameter, 52 compression, 7
Mapped point, 15, 52 Performance Equations
Maximum use in SQL Subsystem, 99
Compression, 91 Performance tuning
Messages configuration parameters, 25
Timeout, 36 Permissions
Microsoft Common Object Model point and data, 49
(COM) technology, 14 PI 2
Minimum Daylight Savings Time
Compression, 91 Changes, 115
Module Database, 38 timestamps, 115
Naming tags, restrictions, 42 PI API, 121
Negative integers Buffering, 6
data types for, 43 Timestamp Translation to
Windows and UNIX PI
New Event Processing, 11
Systems, 117
NewTag, 54
Timestamps, 115
NewTag attribute, 44
PI point number, 51
No Data digital state, 23
PI Server
NT Services
databases, 19
pisqlss, 102
Daylight Savings Time to
ODBC Driver, 97 Standard Time, 118
Offset

Page 140
Index of Topics

Standard Time to Daylight pipt_pointid ( ), 124


Savings Time, 117 pipt_pointsource ( ), 124
Time Format, 111 pipt_recordtype ( ), 124
Timestamps, 117 pipt_rescode ( ), 124
Toolkit Usage, 127 pipt_tag ( ), 124
PI System pipt_taglong ( ), 124
API Time, 115 pipt_tagpreferred, 124
piadmin, 54 pipt_totalspecs ( ), 124
piapi32.dll, 8 pipt_updates ( ), 125
piar_replacevalue, 122 pipt_wildcardsearch ( ), 125
piartool PI-SDK, 97
remote login, 4 pisetpass utility, 95
piconfig, 20 pisn_getsnapshot ( ), 125
piel_addevnt ( ), 122 pisn_getsnapshots, 125
piel_evntactn ( ), 122 pisn_putsnapshot ( ), 125
pigetmsg pisn_putsnapshotq ( ), 125
remote login, 4 pisn_putsnapshots ( ), 125
pigrp, 8 pisn_sendexceptionq ( ), 125
pilistupd pisn_sendexceptions ( ), 125
remote login, 4 pisnap, 5
PINet/OpenVMS pisnap.bat, 20
Nodes pisnap.sh, 20
Time conversions, 117 pisnapss, 20
PI-ODBC Driver pisqlss, 97, 100
Minimum version, 97 configuring, 99
piparams.default continue command, 108
UNIX, 8 NT services, 99
PIPoint pause command, 108
Table, 98 performance tuning, 100
PIproxy records, 38 pisql.ini, 100
pipt_compspecs, 122 starting as an NT service, 102
pipt_compspecseng, 122 PISysDat
pipt_dates ( ), 122 pisql.ini, 100
pipt_descriptor ( ), 121, 122 PITimeout Table, 36
pipt_digcode ( ), 122 pitm_systime ( ), 126
pipt_digcodefortag ( ), 123 Point
pipt_engunitstring ( ), 123 deleting, 20
pipt_engunstring( ), 123 security, 18, 95
pipt_excspecseng, 123 Source data attribute, 54
pipt_exdesc ( ), 123 Point Attributes
pipt_findpoint ( ), 123 archiving, 48
pipt_nextptwsource ( ), 123

PI Server Reference Guide Page 141


Index of Topics

base class, 41 shutdown, 50


changeDate, 55 sourceTag, 47
changer, 55 span, 45
changing tag names, 42 Squareroot, 99
changing zero/span, 46 squareRoot attribute, 50
classic, 50 srcptid attribute, 51
compressing, 47 step, 48
Convers, 98 system assigned, 55
convers attribute, 51 tag name restrictions, 42
creationDate, 55 tag, case sensitivity, 42
creator, 55 Totalcode, 99
ctr_lmap, 52 totalcode attribute, 51
ctr_progid, 52 typicalValue, 45
ctr_strmap, 52 userInt and userReal attributes,
dataAccess, 49 51
dataGroup, 49 zero, 45
defaults, 52 Point Class, 15
Descriptor, 44 Point classes
digitalSet, 45 base class, 41
displayDigits, 49 classic, 50
engUnits, 46 classicctr point class, 52
exDesc, 44 for COM connectors, 52
Filtercode, 98 PtClassName attribute, 42
filtercode attribute, 51 Point Configuration, 15
for classic points, 50 Point Database, 19
for COM connectors, 52 default attribute values, 52
instrument tag attribute, 50 Point types
location attributes, 50 for accumulators, 43
Location Code, 98 for negative integers, 43
newTag, 44 PointID, 54
pointID, 55 point attribute, 55
Pointid, 98 Point attribute, 55, 98
PointSource, 46 Points
pointType, 43 about, 41
ptAccess, 49 access permissions, 49
PtClassName, 42 archiving attribute, 48
ptGroup, 49 attribute defaults, 52
recNo, 55 base class, 41
Recordtype, 99 case sensitivity, 42
Res, 99 changing tag names, 42
scan, 47 changing zero/span, 46
classic point class, 50

Page 142
Index of Topics

compDev, compMin, Priorities


compMax, 47 in SQL configuration methods,
compressing attribute, 47 100
compression on/off, 47 Profile
convers attribute, 51 File
data types, 43 Unix, 8
dataAccess, 49 Program ID parameter, 52
dataGroup, 49 Programs, point attributes for, 51
Descriptor attribute, 44 Proxy Access
digitalSet attribute, 45 Security, 96
displayDigits attribute, 49 Proxy Database, 37
engUnits attribute, 46 pt Created digital state, 23
exDesc attribute, 44 ptAccess
filtercode attribute, 51 Point attribute, 49, 54
instrument tag attribute, 50 ptclass command, 41
interpolation of values, 48 ptClassName attribute, 42
location attributes, 50 ptGroup
mapped, 52 Point attribute, 49, 54
naming restrictions, 42 ptOwner
newTag attribute, 44 Point attribute, 49, 54
PointSource attribute, 46 Queries
ptAccess, 49 SQL Subsystem, 104
PtClassName attribute, 42 Range
ptGroup, 49 the span attribute, 45
scan attribute, 47 the zero attribute, 45
shutdown attribute, 50 Real point type, 43
sourceTag attribute, 47 RecNo, 54
span attribute, 45 point attribute, 55
squareRoot attribute, 50 Point attribute, 55
srcptid attribute, 51 Records
step attribute, 48 record number attribute, 55
totalcode attribute, 51 Recordtype point attribute, 99
turn off data collection, 47 Redirector, 14
typicalValue attribute, 45 Relative Time, 111
userInt and userReal attributes, Remote adminstration, 4
51 Res point attribute, 99
viewing snapshot value, 5 Rescode, 124
zero attribute, 45 Restrictions on tag names, 42
PointSource attribute, 46 Scan attribute, 47
PointType, 54 Scan Flag, 54
PointType attribute, 43 Scan time
Precision, 11 slow, 92

PI Server Reference Guide Page 143


Index of Topics

Script files Initialization file, 100


classicctr.dif, 52 LOG option, 106
Security, 95 NT services, 99
access permissions, 49 statement handles, 97
Firewall, 37 Submitting Queries, 104
foreign data sources, 18 TRACE Option, 106
Servers Troubleshooting, 103
Time Conversions among, 115 tuning, 99
Shutdown Square root code
digital state, 23 Point attribute, 54, 99
flag, 50 SquareRoot
Point attribute, 54 point attribute, 50
Shutdown attribute, 50 srcptid attribute
Shutdown Events, 23 and sourceTag attribute, 47
Shutdown.dat file, 50 srcptid point attribute, 54
Significant events, 10 srcptid point attribute, 51
Simulator interfaces, 5 Standard Time, 115
Slow scan time, 92 to Daylight Savings Time, PI 3
SMT Server, 117
about, vi, 24 State 16383, 24
Snapshot State sets, 45
definition of, 11 Statement Handle, 97
from foreign data sources, 16 Handle ID
viewing current values, 5 PI-SQL, 107
Snapshot Subsystem Step
database, 20 flag, 93
definition of, 11 Point attribute, 54
Source tag, point number, 51 Step attribute, 48
Source, point source, 46 Step flag, 48
SourceTag, 54 String
SourceTag attribute, 47 Data Types, 121
Span String mapping parameter, 52
Point attribute, 54 String point type, 43
Span attribute, changing, 46 Subsecond timestamps, 121
SQL Subsystem, 97 Subsystem
architecture, 97 PI-SQL, 97
argument, 100 Snapshot, 11
Command line arguments, 100 Subsystems
configuration, 99 dependencies among, 1
methods, conflicts in, 100 Swinging door compression, 91
Generating a Trace, 106 System
state set, 45

Page 144
Index of Topics

State Set, 24 ptGroup, 49


Time, 119 scan attribute, 47
System Management Tools, vi, 24 shutdown attribute, 50
System-assigned attributes, 55 sourceTag attribute, 47
Table span attribute, 45
Digital State, 23, 24 step attribute, 48
PIPoint, 98 turn off data collection, 47
Tables typicalValue attribute, 45
timeout, 25 viewing snapshot value, 5
Tag zero attribute, 45
Digital, 92 Technical Support, 133
system digital state set, 23 Time
Tag attribute, changing, 42 API Time, 115
Tag names between events, 91
capitalization, 42 Changes
Tagname Daylight Savings to
Point attribute, 54 Standard, 118
Tagnames PI 2 Systems, 115
constraints, 42 PI Client Applications,
119
in external systems, 50
conversions, 115
Tags. See points
Format, 111
archiving attribute, 48
Local time, 115
changing names, 42
System Time, 119
changing zero/span, 46
transitions
compDev, compMin,
compMax, 47 from Open VMS and PI
API to Windows and
compressing attribute, 47
UNIX, 117
compression on/off, 47
PI 2 Systems, 115
constraints, 42
PI Server Systems, 117
dataAccess, 49
translations
dataGroup, 49
PINet nodes, 117
Descriptor attribute, 44
Zone, 115, 126
digitalSet attribute, 45
Timeout database, 25
displayDigits attribute, 49
Timeout table, 25
engUnits attribute, 46
Timestamp
exDesc attribute, 44
across time zones on PI 2
in external systems, 50 System, 116
interpolation of values, 48 Conversions
mapped, 52 algorithm, 117
newTag attribute, 44 PI 3 & PI 2, 115
PointSource attribute, 46 PI Server, 117
ptAccess, 49

PI Server Reference Guide Page 145


Index of Topics

Subsecond, 121 Universal Interface


year 2000, 120 downloading documentation
Timestamp point type, 43 for, vi
Timing parameters, 25 UNIX
UNIX, 36 directory and file structure, 8
Toolkit Usage, 127 UNIX directory structure, 8
Totalcode point attribute, 51 User
Totalcode Point Attribute, 99 Database, 38
TRACE Option User programs, point attributes for,
51
SQL Subsystem, 106
UserInt1 point attribute, 51
Trend
UserInt2, 54
seasonal time changes, 120
UserInt2 point attribute, 51
Trends
UserReal1, 55
formatting numbers, 49
UserReal1 point attribute, 51
Troubleshooting
UserReal2, 55
SQL Subsystem, 103
UserReal2 point attribute, 51
Tuning the PI Server
UTC, 126
configuration parameters, 25
Utility
Turning off exception reporting, 90
ipisql, 103
Types
piconfig, 20
about point types, 43
pisetpass, 38
for accumulators, 43
pisnap.bat, 20
for negative integers, 43
pisnap.sh, 20
TypicalValue
Version
Point attribute, 54
PI Server, 4
TypicalValue attribute, 45
Visual Basic, 6
TZ environment variable, 126
Windows
UCT, 117
Directory and file structure, 8
Under Range, 45, 46
Year 2000
Under Range digital state, 23
Timestamps, 120
UniInt
Zero
downloading documentation
for, vi Point attribute, 55
Units, engineering, 46 Zero attribute, 45
Universal Coordinated Time, 115, Zero attribute, changing, 46
117, 126

Page 146

Вам также может понравиться