Академический Документы
Профессиональный Документы
Культура Документы
PI3 Server
Version 3.4.370
Worldwide Offices
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
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.
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).
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.
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
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
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.
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
Table of Tables.................................................................................................................................xv
Page x
Table of Contents
Page xii
Table of Contents
Index of Topics...............................................................................................................................135
Page xiv
TABLE OF TABLES
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.
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.
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.
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.
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.
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
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)
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:
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.
pilistupd PI\adm A tool for monitoring the Update Manager, specifically for looking at
Event Queues.
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 -?
Page 4
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.
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.
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.
The PI Server file organization is a little different for Windows and UNIX platforms. Refer to
the section for the appropriate operating system.
Directory Contents
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.
The PI directory structure for Windows systems differs depending on whether the system is a
new installation or an upgrade.
Page 6
1.5 - PI Directory Structure
Directory Contents
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.
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.
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.
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.
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
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.
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.
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.
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.
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.
Figure 2-2. Data Flow through Snapshot Subsystem, Redirector, and COM Connector
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.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.
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.
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.
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.
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.
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
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.
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
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.
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.
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.
Page 24
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.
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
Archive Archive_CacheTrim 1 – 75 startup only Percentage to trim the read and write
Percent (40 %) cache when low physical memory
resources are detected.
Page 28
3.6 - Timeout Database
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
Page 32
3.6 - Timeout Database
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 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)
Page 34
3.6 - Timeout Database
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_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).
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.
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.
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
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.
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.
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
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.
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.
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.
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.
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.
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
Page 38
3.14 - List of Database Files
PIbasess Databases
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
PINetmgr Databases
PIShutev Databases
Pisnapss Databases
PIbasess Databases
PISqlss Databases
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
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.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.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:
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.
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.
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:
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
Point Default
Class Field Name Value Limits
Classic Convers 1
Base DataAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)
Base DigitalSet no default Used only for digital tags This must
be specified when the point is
created.
Classic Filtercode 0
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 PtAccess O:rw g:r w:r Owner, group, and world may be
assigned read, write, or no access
(blank)
Classic Srcptid 0
Classic Totalcode 0
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
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.
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.
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.
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
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.
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.
The following sub-sections discuss three operations that modify the PI Attribute Set database:
Attribute Set Create
Attribute Set Delete
Attribute Set Edit
Page 60
5.3 - Attribute Sets Database Edit
Float32 (0)
Bool (0)2
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.
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.
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...
*----------
@table piatrset
@mode delete
@istru set
MyAttributeSet
@ends
When finished place the system back in normal mode.
PIartool –standalone 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.
Descriptor String
Exdesc String
Typicalvalue float32
Engunits string
Zero float32
Span float32
Pointtype ubyte
Pointsource string
Scan uint16
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.
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.
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
Renaming an attribute set does not trigger any implicit edits of point classes or points and
does not require standalone mode either.
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.
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.
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.
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
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:
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
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
5 This scenario is unlikely, but if it ever happens, it can be rectified by editing the class.
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
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.
Point DB 0 1
Attribute Sets DB 2 4
Point Classes DB 4 16
6 Starts from 0.
Field Description
PI Database PIPointAttributeSets
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 Database PIPointClasses
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
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.
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
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
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:
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.
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.
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.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.
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
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.
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
Time
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
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.
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.
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.
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.
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.
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.
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.
Convers 0.0
Filtercode 0
location1, location2, 0
location3, location4,
location5
Page 98
9.3 - Configuration
Squareroot 0
Totalcode 0
The keyword pointnumber originally came from the pidiff utility in PI for OpenVMS. This
name is also used in the PI API User Guide. Most PI API calls require a 32-bit integer
PointIdentifier (pt or ptnum - referenced in the PI API User Guide as PI point number).
9.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.
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.
Details of the settings can be found in Appendix B of the PI ODBC Driver Manual.
Page 100
9.3 - Configuration
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.
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.
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.
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.
Page 102
9.4 - Troubleshooting
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.
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
Command Line
Argument Description
-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”.
-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.
-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"
Page 106
9.4 - Troubleshooting
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.
Page 108
9.4 - Troubleshooting
Many PI System utilities prompt for a date and time. The PI time formats are:
Relative
Absolute
Combined
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
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
Caution should be used with the default settings. Here are some examples of timestamps that
may be confusing.
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.
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.
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.
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.
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
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
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
This section assumes knowledge of the PI API. Refer to the PI Application Programming
Interface Manual for details.
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_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
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_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_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 ( ).
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.
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.
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.
GetEngUnits( )
This function returns with engUnitCode equal to pt if pt is less than 32768, else it returns
with engUnitCode equal to 0.
GetExcSpecsEng( )
See comments for the PI API function pipt_excspecseng ( ).
Page 128
APPENDIX D: PREDEFINED ATTRIBUTE SETS AND POINT
CLASSES
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
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
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.
Page 132
TECHNICAL SUPPORT AND RESOURCES
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.
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical
data, as well as a special collection of resources for system managers. For these options,
click Knowledge Center in the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support
Pages, Known Issues, Enhancements, and Documentation (including User
Manuals, Release Notes, and White Papers).
• System Manager Resources include tools and instructions that help you
manage: Archive sizing, Backup scripts, Daily Health Check, Daylight Saving
Time configuration, PI Server security, PI System sizing and configuration, PI
Trusts for Interface Nodes, and more.
Page 134
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
Page 138
Index of Topics
Page 140
Index of Topics
Page 142
Index of Topics
Page 144
Index of Topics
Page 146