PI Server Applications User Guide

October 2009
OSIsoft, Inc. International Offices
777 Davis St., Suite 250 OSIsoft Australia
San Leandro, CA 94577 USA Perth, Australia
Auckland, New Zealand
Additional Offices OSIsoft Germany GmbH
Houston, TX Altenstadt, Germany
Johnson City, TN
OSIsoft Asia Pte Ltd.
Longview, TX
Mayfield Heights, OH Singapore
Philadelphia, PA OSIsoft Canada ULC
Phoenix, AZ
Montreal, Canada
Savannah, GA
Calgary, Canada
Sales Outlets/Distributors OSIsoft, Inc. Representative Office
Middle East/North Africa Shanghai, People’s Republic of China
Republic of South Africa OSIsoft Japan KK
Russia/Central Asia Tokyo, Japan
South America/Caribbean
Southeast Asia OSIsoft Mexico S. De R.L. De C.V.
South Korea Taiwan Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda.
Sao Paulo, Brazil

Contact and Support:

Main phone: (01) 510-297-5800
Fax: (01) 510-357-8136
Support phone: (01) 510-297-5828
Web site: http://www.osisoft.com
Support web site: http://techsupport.osisoft.com
Support email: techsupport@osisoft.com

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

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

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

U.S. GOVERNMENT RIGHTS

Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, Inc. license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, Inc.

Published: 10/1/2009
Table of Contents
Chapter 1 PI Server Applications ................................................................................................. 1
PI Server Applications Overview ........................................................................................ 1

Chapter 2 PI Performance Equations Scheduler ........................................................................ 5

About PE Points ................................................................................................................. 5
About the PE Subsystem ................................................................................................... 6
Creating PE Points ............................................................................................................. 7
Determine Scan Classes and Point Source ....................................................................... 7
Choose a Scheduling Method .......................................................................................... 10
Set Attributes for PE Points .............................................................................................. 11
Tips and Troubleshooting ................................................................................................. 16

Chapter 3 PI Performance Equations Recalculator ................................................................. 19

Recalculator Overview ..................................................................................................... 19
PE Recalculator Functionality .......................................................................................... 20
Types of PE Point/Time Relationships ............................................................................. 23
Special Performance EquationTime Functions ................................................................ 31
Examples of Archive Retrieval / Search Functions ..........................................................31
Recalculation Limitations ................................................................................................. 32
Recalculator Point Configuration ...................................................................................... 33
Start Recalculator as a Service ........................................................................................ 36
Start Recalculator Manually ............................................................................................. 42
Stop Recalculator ............................................................................................................. 44
Optimize Recalculator Performance ................................................................................ 44
Error and Information Messages ...................................................................................... 44

Chapter 4 PI Performance Equations Syntax and Functions Reference ...............................45

Performance Equation Syntax ......................................................................................... 45
Performance Equations Functions ................................................................................... 59
Built-in Functions .............................................................................................................. 60
Performance Equations Functions Reference ................................................................. 67

Chapter 5 PI Steam Functions Reference ............................................................................... 155

Steam Functions Overview ............................................................................................ 155
Range of Steam Functions ............................................................................................. 157
Steam Property Reference States ................................................................................. 159
Steam Functions Reference ........................................................................................... 159

PI Server Applications User Guide iii

Table of Contents

Chapter 6 PI Batch Database.................................................................................................... 193

PI Batch Overview .......................................................................................................... 193
Installation ...................................................................................................................... 195
Configuration .................................................................................................................. 195
Batch Data Information................................................................................................... 204
Batch Subsystem Operation .......................................................................................... 208
Client Access to Batch Subsystem Batches .................................................................. 208
Complete Example ......................................................................................................... 209
Chapter 7 PI Totalizer Subsystem............................................................................................ 211
Totalizer Subsystem Overview....................................................................................... 211
Totalizer Configuration Overview ................................................................................... 213
Totalizer Point Class Attributes ...................................................................................... 215
Build Totalizer Points...................................................................................................... 244
Program Operation ......................................................................................................... 246
PI for OpenVMS Upgrade Considerations ..................................................................... 247
Demonstration Points ..................................................................................................... 249
Chapter 8 PI Alarm Subsystem ................................................................................................ 251
Alarm Subsytem Overview ............................................................................................. 251
Alarm Point Configuration .............................................................................................. 253
Alarm State Sets ............................................................................................................ 267
Alarm Groups ................................................................................................................. 271
Build Alarm Points .......................................................................................................... 272
Build Alarm Group Points ............................................................................................... 273
Override Default PointSource Values for Alarms ...........................................................274
Build Alarm Digital State Sets ........................................................................................ 275
Program Operation ......................................................................................................... 277
PI for OpenVMS Upgrade Considerations ..................................................................... 278
Alarm State Set Encoding and Decoding ....................................................................... 279
Chapter 9 PI Real-Time SQC..................................................................................................... 289
Introduction to Statistical Quality Control ....................................................................... 289
Case Study for PI Real-Time SQC ................................................................................. 290
Real-Time SQC Definitions and Terminology ................................................................ 291
Tests for Unnatural Patterns .......................................................................................... 293
PI Real-Time SQC Configuration ................................................................................... 297
Pattern Tests .................................................................................................................. 297
SQC Alarm Priority and Precedence.............................................................................. 298
Create a New SQC Alarm .............................................................................................. 299
Start and Run the PI Alarm Subsystem ......................................................................... 300
Associated Point Configuration ...................................................................................... 303
PI SQC Alarm Point Configuration ................................................................................. 308
PI Real-Time SQC Chart Types ..................................................................................... 316
Default SQC Alarm Digital States .................................................................................. 316
Log Messages ................................................................................................................ 319
Appendix A Technical Support and Resources ..................................................................... 323
Index ............................................................................................................................................ 327

iv
Chapter 1

PI Server Applications

PI Server Applications Overview

The power of the PI System is enhanced by the PI Server Applications, which work on top of
the PI Server. PI Server Applications are a set of processing tools that help you get more out
of your data by automating specific processes.

PI Performance Equations Scheduler

The PI Performance Equations Scheduler (page 5) provides an equation syntax and library of
built-in functions that allow you to perform a wide variety of calculations on PI data.
Performance Equations can work with frequently updating Snapshot and Archive values,
whereas tools such as spreadsheets only have access to Archive data and limited access to
Snapshot update values.
Each Performance Equation is associated with a PI point, and the calculation results are
stored in the PI Archive. The performance equation point may be configured to be evaluated
periodically by the PE Scheduler (time-based). Alternatively, it may be configured to be
evaluated when an event is received on a specified trigger point (event-based).

PI Performance Equations Recalculator

The PI Performance Equations Recalculator (page 19) is designed to adjust values of

Performance Equation points automatically. The adjustment occurs when Archive values of
points that are used in Performance Equation expressions are added, changed, or deleted. You
can also use Recalculator as an offline utility to reprocess explicit periods of time for specific
points.

PI PE Syntax and Functions Reference

PI Performance Equations allows you to easily implement sophisticated, real-time

calculations, using data in the PI System. Calculations can include unit performance, real-
time cost accounting, real-time yield accounting, batch summary, conversions and
totalizations not performed by PI Totalizer, logical operations, and calculating aggregates.
PI Performance Equations Syntax and Functions Reference (page 45) provides
comprehensive instructions for using Performance Equations syntax and functions.

PI Server Applications User Guide 1

PI Server Applications

PI Steam Functions Reference

The PI Steam Functions module is an extension to the PI Performance Equations Scheduler.

Steam Functions provide a complete set of functions for deriving the thermodynamic
properties of steam and water. PI Steam Functions support both English and SI units, and are
based on the ASME (American Society of Mechanical Engineers) Steam Tables, 6th Ed.
PI Steam Functions Reference (page 155) provides a comprehensive reference for setting up
Steam calculations.

PI Batch Database

Most processes have repeatable time segments or stages. PI Batch Database (page 193)
technology maps process or manufacturing events to slices of time and data, and stores these
in the PI Data Archive. Identifying these process stages and measuring their repeatability is
the purpose of PI Batch. Building this fundamental association enables powerful data and
process analysis for both traditional and non-traditional batch processes.
While industries such as chemical and pharmaceutical use PI Batch to track and analyze
batches, it is also widely used in non-batch applications to identify and track process events.
PI Batch tracks and stores batch and process based events hierarchically as Batches, Unit
Batches, or Sub Batches.
PI Batch is used in conjunction with its companion client application PI BatchView, which
allows you to view and compare events that have been collected by PI Batch and stored in the
PI System.

PI Totalizer Subsystem

The PI Totalizer Subsystem (page 211) performs common calculations such as totals,
averages, minimum and maximum values, and standard deviations. The output of a
calculation is stored in a PI point.
The main difference between a Performance Equations point and a Totalizer point is that
Performance Equations are based on Archive events, while Totalizer results are based on
Snapshot events.
PI Totals are the most accurate way to represent production summary data. Totalizers can be
started and reset based on time and event, and ensure the highest accuracy in the calculation
of flow volumes and other critical variables used to monitor product transfers or production
performance. Totalizer is especially practical for totaling measurements or other process
variables at the end of specific time periods, such as the end-of-day yields.

2
 PI Server Applications Overview

PI Alarm Subsystem

The PI Alarm Subsystem (page 251) provides the capability to establish alarms for PI points.
PI Alarm allows you to track, manage and acknowledge alarm conditions caused by
processes that exceed user-specified parameters.
PI Alarm keeps a constant eye on process conditions. PI Alarm can monitor many variables
such as temperatures, volumes, flow rates, product quality or raw material consumption.
Alarms can be triggered by the duration of an event or deviation from norm.
PI Alarm assesses the condition as well as the priority of an event, as you define it.
Depending on the longevity and/or severity of the event, it can notify specific personnel. PI
Alarm includes client functionality through the PI API to alert operators to selected alarms.
Data from PI Alarm are displayed in its companion client application, PI AlarmView. Alarm
conditions are historized together with an acknowledgment status.

PI Real-Time SQC

PI Real-Time Statistical Quality Control (SQC) (page 289) uses numerical methods to
monitor the characteristics of a process, making sure they remain within pre-determined
boundaries. When Real-Time SQC perceives an unacceptable deviation in a process, PI Real-
Time SQC Alarms alert the appropriate personnel.
The PI Real-Time SQC component makes it easy to apply the Western Electric Pattern Tests
to all of your process or laboratory data collected by the PI System. PI Real-Time SQC
continually reviews any SQC tests in the PI System. It stores test results and a record of SQC
control limits back into your PI System. The results are available for viewing and analysis via
PI ProcessBook and the PI SQC Add-In.
The SQC Subsystem is a part of the PI Alarm Subsystem, which provides continual
evaluation of SQC pattern tests and the management of alarms generated from them.

PI Server Applications User Guide 3

Chapter 2

PI Performance Equations Scheduler

This chapter explains how to create Performance Equation Points using the PI Performance
Equations (PE) Scheduler. The PE Scheduler allows you to implement sophisticated online
calculations without having to program in high-level languages.
The PE Scheduler provides an equation syntax and library of built-in functions that allow you
to perform a wide variety of calculations on PI data. For details, see PI Performance
Equations Syntax and Functions Reference (page 45). Performance Equations can work with
frequently updating Snapshot and Archive values, whereas tools such as spreadsheets only
have access to Archive data and limited access to Snapshot update values.
PE Scheduler allows you to easily implement sophisticated, real-time calculations, such as:
• Unit performance
• Real-time cost accounting
• Real-time yield accounting
• Grade-based costing
• Batch summary
• Conversions and totalizations not performed by PI Totalizer
• Logical operations
• Calculating aggregates
Each Performance Equation is associated with a PI point, and the calculation results are
stored in the PI Archive as a PE point. You can configure a PE point to be evaluated
periodically by the Performance Equation Scheduler on a time-based basis, or when an event
is received on a specified trigger point, called event-based scheduling.
Typically, you use Performance Equations in one of two ways:
• To create PE points, which are points that have the PE Scheduler as their source. The PE
Scheduler determines the value of these points by performing Performance Equation
calculations specified during the creation of the PE point.
• Programmatically, via the PI SDK, PI DataLink, or PI ProcessBook. See the product
documentation for applicable Performance Equations instructions.

About PE Points
PE points perform calculations on one or more PI points. PE points are similar to other PI
points, but they use the Performance Equation Scheduler as the point source. (The point
source is specified in pipeschd.bat in the \pi\bin directory. The default value is'C'.)

PI Server Applications User Guide 5

PI Performance Equations Scheduler

The PE Scheduler performs the calculations specified for the point at the scheduled time
(based on "time" or "event") and sends the result to the Snapshot.
To create a PE point, you put a calculation expression in the Extended Descriptor (ExDesc)
attribute field and you set the point source to the point source for the Performance Equation
Scheduler. The value for the PE point at any given time is the result of this calculation
expression. The PE Scheduler calculates a new value for the point according to the schedule
you define for it, either at regular intervals or using an event trigger.
You can use PE points in other calculations, graph them in trend displays, or include them in
reports, just like any other point. PE points cannot have a Point Type (PtType) of blob.

About the PE Subsystem

The PE Scheduler works a lot like an interface, except that it runs locally, on the PI Server. It
has an associated point source location and scan classes. The PE Scheduler evaluates the
calculation expression for each PE point according to the schedule you configure for that
point, and sends the resulting value and timestamp to the Snapshot. PE points are subject to
exception and compression tests, just as other points are.
Like an interface, the Performance Equation Scheduler needs to be running in order to
calculate data and send it to the Snapshot. The PE Scheduler executable is located in the
PI/bin directory and is called pipeschd.exe.

Start and Stop the Performance Equation Scheduler

The PI startup script starts the Performance Equation Scheduler, along with the other
PI Server subsystems. Like other PI Server subsystems, if your PI Server is Windows-based it
is a good idea to run the Performance Equation Scheduler as a Windows service, so that it can
run in the background, independent of any particular login session.
On Windows computers, the Performance Equation Scheduler typically runs as a Windows
service and you manage it as you would any other Windows Service. The PE Scheduler
service is called the PI Performance Equation Scheduler. Open the Services control panel
(Control Panel > Administrative Tools > Services), right-click on the PI Performance
Equation Scheduler service, then start, stop or restart the service.

6
 Creating PE Points

Creating PE Points
To perform a calculation on PI data, you must create a PI point; put your calculation
expression in the ExDesc attribute field; set the PointSource attribute to the point source
specified in the pipschd.bat file; and set location4 to the Scan class for clock-scheduled
calculations.
You can use the Interface Configuration Utility (ICU) to configure the scan classes of points
to use with the Performance Equation Scheduler.
Follow these steps to perform a calculation on PI data:
1. Determine the scan classes and point source (page 7).
2. Choose a scheduling method (page 10). You can use either clock-based or event-based
scheduling.
3. Create the point and set the required attributes (page 11). Create a new PI point using the
PI tool of your choice, such as PI Tag Configurator or piconfig. Set the required
attributes as follows:
ο PointSource: Set PointSource to the point source location specified in
pipeschd.bat. The default point source location for PE points is C, but you can
edit pipeschd.bat to use another string. See the PI Server Reference Guide for
details on point source attributes.
ο Location4: If you're using clock-based scheduling for this calculation, put the
appropriate scan class in location4. The available scan classes are listed in
pipeschd.bat. If you're using event-based scheduling, leave location4 blank.
ο ExDesc: Put your calculation expression in the Extended Descriptor (ExDesc)
attribute field. The exact ExDesc expression depends on what type of scheduling
(clock- or event-based) the point uses.
ο PtClass: classic
ο Type: The point type can be any type except blob.
4. Test the PI Performance Equation calculation expression. You can use the pipetest utility
(page 58) or the PI SMT Performance Equations plug-in to check whether an equation is
syntactically correct.

Determine Scan Classes and Point Source

PE Points use the scan classes and point source configuration for the Performance Equation
Scheduler defined in pipeschd.bat. By default, pipeschd.bat is located in the
directory PI\bin where PI\ is the path to the main directory in your PI installation.

PI Server Applications User Guide 7

PI Performance Equations Scheduler

Find the PE Scheduler Point Source

To find the correct PE point source location for your PE points, open pipeschd.bat with
a text editor and look for the entry /ps=. The point source is usually C, but it can be any
string.

Note: Make a note of the character. This is the value you must use for the PointSource
attribute on all PE points.

Change the Point Source

From a PI Administrator account, you can change the point source for Performance
Equations. Do not do this unless absolutely necessary. If you change the point source
location, any existing PE points do not work unless you change the PointSource attribute to
match the new location.
To change the point source location for your PE points:
1. Stop the Performance Equation Scheduler.
2. Change the point source to any string. This is the value you must use for the PointSource
attribute on all PE points.
3. Make a note of the character and be sure to publish the new character to everyone who
creates PE points for this server.
4. Edit all existing PE points to reflect the new point source.
5. Start the Performance Equation Scheduler.

Specify the Optional Instance ID

Within pipeschd.bat, you can optionally specify an instance ID (/id=n). When the
instance ID is specified, PI PE Scheduler only loads and calculates PE points with Location1
attribute matching the /id value.

8
 Determine Scan Classes and Point Source

Find the Performance Equation Scheduler Scan Classes

All the scan classes available for a PE point are listed in pipeschd.bat. If you don't see
the scan class you need for a particular PE point, you can add a new scan class (requires PI
Administrator privileges.)

What is a Scan Class?

A scan class is a code that the Performance Equation Scheduler and other PI interfaces use to
specify scheduling. A scan class consists of:
• A period specifying the interval between calculations
• Optional: an offset specifying a start time for the calculations to begin
• A code that specifies the UTC time to use for scheduling

Scan Class Period

The period specifies the interval between calculations. The first two digits are the hours, the
second two the minutes, and the third two the seconds. For example, the scan class can
specify that the calculation take place every hour (01:00:00), every three minutes (00:03:00),
every 52 seconds (00:00:52), and so on.

Scan Class Offset

The offset specifies a start time for the calculation. The offset is optional. If no offset is
included in the scan class, the first calculation takes place immediately. The offset is counted
from midnight of the current day and, as with the period, the first two digits are the hours, the
second two the minutes, and the third two the seconds. So, for example, the offset can specify
that the first calculation occur at midnight (00:00:00), at 1AM (01:00:00), at 1PM (13:00:00),
at 2:05PM (14:05:00), at 25 seconds past noon (12:00:25), and so on.

Scan Class UTC Time Flag

The UTC time flag specifies that the scheduling should sync with Universal Time
Coordinate (UTC). The UTC time is optional. If a scan class has a frequency of more than an
hour, make it a UTC scan class by adding a comma followed by a capital U:
(/f=08:00:00,07:00:00,U). If you don't do this, then your scheduling might be inaccurate the
next time there is a change to (or from) daylight savings time. UTC scan classes don't have
this problem because they force the scan class scheduling to sync with UTC, rather than local
time.

PI Server Applications User Guide 9

PI Performance Equations Scheduler

Find the Performance Equation Scan Classes

To see all currently available scan classes for your PE points, follow these steps.
Open pipeschd.bat with a text editor and look for all the entries that begin with the
characters "backslash" f (/f). These are the scan classes. Choose the scan class that you want
to use for the PE point and set the location4 attribute to the appropriate value.

The position within the startup command line defines the scan classes; that is, the first /f=
refers to scan class 1, the second /f= refers to scan class 2, and so on. Simply add more /f=
parameters to define more scan classes. The PE point is assigned to a scan class using the
location4 attribute. For example, if location4 is set to 2, the PE point is evaluated every 2
minutes.

Add New Scan Classes

You can add new scan classes, if you have PI Administrator privileges. Stop the Performance
Equation Scheduler before editing pipeschd.bat.
Add your new scan class at the end of the line containing scan classes, as the last scan class in
the list. If you add a new scan class earlier in the list, you change the location4 values for the
existing scan classes. You can add as many new scan classes as you like to the end of the
scan class list in pipeschd.bat.

Restart the Performance Equation Scheduler when you finish editing pipeschd.bat.

Choose a Scheduling Method

The attributes you set for a PE point depend in part on the type of scheduling you use for the
point. Each PE point must use either clock (time-based) scheduling or event scheduling:

10
 Set Attributes for PE Points

• Clock Scheduling: With clock scheduling, you use scan classes to schedule the
calculation. The PE Scheduler calculates a new value for the point at the specified
intervals, such as every hour, every five seconds, every 20 minutes, and so on. You can
optionally specify an initial start time for the calculation interval.
For clock-scheduled points, define the Performance Equation calculation expression in
the ExDesc attribute field (page 13) and specify a scan class in the location4 attribute
field (page 12).
• Event Scheduling: With event scheduling, you configure the calculation to occur when a
specified point gets a new Snapshot value. For example, you might want a calculation
performed whenever the point ba:level.1 receives a new Snapshot event.
For event-scheduled points, put both the Performance Equation expression and the trigger
tag name in the ExDesc attribute field (page 13) and set the location3 attribute field (page
12) to specify the timestamp of the point.

Set Attributes for PE Points

Following are the attributes that require a special setting for PE points (page 5).
Attribute Requirement
location1 Instance ID. For details, see Specify the Optional Instance ID (page 8).
ptClassName Classic
PointSource Set to value specified in pipeschd.bat file. The default value is C.

location3 Output timestamp setting for event-based scheduling

location4 Put the scan class here for clock-scheduled points. Leave blank for event-
based points.
ExDesc This is where you put your performance equation
scan Set the scan attribute to 1 (the default value)

shutdown Marker inserted in Archive at shutdown

All point attributes that are not listed in this table work just the same as they do for other
points. However, the following attributes do not apply to PE points:
• Location2
• Location5
• UserInt1
• UserInt2
• UserReal1
• UserReal2
• EventTag
• InstrumentTag
• SquareRoot

PI Server Applications User Guide 11

PI Performance Equations Scheduler

Set the Point Source

The PointSource attribute for PE points is defined in pipeschd.bat, discussed in Find

the Performance Equation Scheduler Point Source (page 8). The default value is C, but you
can change the defined value to any string by editing pipeschd.bat.

Set the Location3 Attribute: Timestamp

If the PE point uses clock scheduling (page 22), do not set the location3 attribute. Use the
location3 attribute for event-scheduled points, to specify how PI determines the timestamp
for the PE point. When location3 is set to 0 (the default value), set the timestamps for the PE
point to the time when the expression is evaluated.
When location3 is set to a non-zero value, the expression is evaluated at the timestamp of the
triggering event and the timestamp of the resulting value is set to the timestamp of the
triggering event.

Set the Location4 Attribute: Scan Class

If the PE point uses event scheduling, do not set the location4 attribute. If the point uses
clock scheduling, set a value for location4 to a positive non-zero integer that specifies a valid
scan class.
You select a particular scan class for a PE point by setting the value of the location4 attribute
for that point. All the scan classes available for a PE point are listed in pipeschd.bat. To
select the first scan class in the list, set the location4 attribute to 1; to select the second scan
class, set the location4 attribute to 2; and so on.

For an explanation of scan classes and how to configure them, see Find the Performance
Equation Scheduler Scan Classes (page 9).

Set the ExDesc Attribute: Calculation Expressions

For each PE point, specify the PE calculation for the PE Scheduler to perform. PE calculation
expressions use PE syntax and functions to define calculations, using data from other points.
PE calculation expressions are similar to arithmetical expressions. You can use any of the
standard arithmetic operators in a PE expression (such as +, -, or *) to add the values of two
points together, add a number to the value of a point, and so on. You can also use
Performance Equation functions (page 45) and Steam Table functions (page 155) in your PE
calculation expressions.

12
 Set Attributes for PE Points

Note: You cannot use points with a point type of blob in PE expressions.

You define the PE calculation expression in the Extended Descriptor (ExDesc) attribute field,
but the exact syntax you use depends on the type of scheduling you're using. For clock-
scheduled points, you type only the PE calculation expression into the ExDesc attribute field,
but for event scheduling you must also specify the point that acts as the event trigger.

Note: If the equation begins with a single quote (') and you are working with PI Tag
Configurator, enclose the calculation expression in parentheses. Otherwise Excel
removes the single quote.

Set the ExDesc Attribute for Clock-Scheduled Points

For clock-scheduled points, the ExDesc field contains only the calculation expression itself.
Following are several examples of simple calculation expressions.
The following example adds the current value of the sinusoid point to the current value of the
ba:level.1 point.
'sinusoid' + 'ba:level.1'

The following example takes the total time during the last hour that the sinusoid point had a
value between 30 and 70.
timegt('sinusoid', '*-1h', '*', 30) - timegt('sinusoid', '*-1h',
'*', 70)

For more examples of calculation expressions, see Examples of Calculation Expressions

(page 14). For a complete reference on the Performance Equation syntax and functions, see
PI Performance Equations Syntax and Functions Reference (page 45).

Set the ExDesc Attribute for Event-Scheduled Points

For event-scheduled points, the syntax for the ExDesc attribute field is:
event = tagname, CalculationExpression

where tagname is the name of the point that triggers the calculation and
CalculationExpression is the calculation expression that PE Scheduler uses to calculate the
value for the point.
For example, to set up a one-hour average of the sinusoid point that triggers whenever
sinusoid gets a new Snapshot value, use the following expression in the ExDesc attribute
field:
event=sinusoid,TagAvg('sinusoid', '*-1h', '*')

The PE Scheduler uses the Snapshot value as the event trigger. This means that events that do
not enter the Snapshot do not trigger the calculation. For example, an event that does not pass
the exception reporting does not trigger a new calculation.

PI Server Applications User Guide 13

PI Performance Equations Scheduler

Character Limits on the Extended Descriptor Attribute

For both clock and event scheduling methods, there is a set limit on the number of characters
that you can use for the extended descriptor. These limits depend on the tool you use to create
your PE point, but in all cases, the Performance Equation Scheduler imposes a limit of 4096
characters. In the PI TagConfigurator, the limit is 4096 characters.
Regardless of the limits on the extended descriptor, OSIsoft recommends that you keep
expressions less than 300 characters, if possible. Expressions that are much longer than that
are difficult to debug and maintain. If you need a longer expression, consider breaking down
your equation into parts and creating PE points to handle each of the parts. Be careful to
schedule the calculations so that PE Scheduler can perform them in the correct order. See
Prevent Scheduling Errors (page 17), for more details.

Set the Scan Attribute

Always set the scan attribute to 1 for PE points. When the scan attribute is set to 0, PI does
not perform the calculations or generate any values for the point. Since 1 is the default value
for the scan attribute, you can usually leave this attribute as-is.

Set the Shutdown Attribute

Performance Equations are not calculated if the PI Server is not running, so you should
always set the Shutdown attribute to 1. When Shutdown is set to 1, the system inserts a
shutdown event with the timestamp of the PI Server shutdown. Note that the shutdown event
is inserted only when the PI Server itself stops—it is not inserted if the Performance Equation
Scheduler stops independently of the PI Server.

Examples of Calculation Expressions

This section provides some helpful hints and examples for writing Performance Equations.

Totalization of Digital Point Example

In this example, the goal is to obtain the total of the number of times a point goes into a
digital state for the month. Accumulator is the PE point. OnOffSwitch is the digital point that
uses a Digital State Set with two digital states: ON and OFF.
If day('*')=1 and day(PrevEvent('Accumulator', '*'))<>1 then 0
else if PrevVal('OnOffSwitch', '*') <> "ON" and 'OnOffSwitch' =
"ON" then 'Accumulator' +1 else NoOutput()

This performance equation checks whether it is the first of the month and whether the last
event did not occur on the first of the month. If it is the first of the month, Accumulator
resets. Otherwise if the previous value of OnOffSwitch is not the digital state ON and the
current value is ON, then Accumulator increments.

14
 Set Attributes for PE Points

TagTot Example
In this example, the goal is to use the TagTot function to obtain a total on a point that has
engineering units other than the default per day. RateTag has engineering units of gallons per
hour and the objective is to get the number of gallons for the previous day.
If PctGood('RateTag', 'y', 't')>85 then TagTot('RateTag', 'y',
't')*24 else "Bad Total"

First, the performance equation checks the percent of good values starting from the midnight
yesterday to the midnight of the current day. If the percentage is greater than 85, then a total
of RateTag is calculated for that given period. The total is multiplied by 24 hours per day to
obtain the units of gallons. If the percentage is less than or equal to 85, the digital state of
Bad Total is given. In this example, although the RateTag would have an integer or real
point type, digital states only in the SYSTEM Digital State Set are allowed.

TagMax vs. Max Example

In this example, the objective is to obtain the maximum of a point for the month. One method
for doing this is the TagMax function, shown in the next paragraph. An alternative method,
also shown below, uses the Max function. Here's the calculation expression with TagMax:
If Day('*')=1 and Day(PrevEvent('RateTag', '*'))<>1 then
TagMax('RateTag', Bom(PrevEvent('RateTag', '*')), Bom('*')-'+1s')
else NoOutput()

The performance equation first checks that it is the beginning of the month and then finds the
maximum of RateTag from the prior month up to one second before the beginning of the
current month. Notice that the beginning of the month function Bom was not used to check
for the first of the month. The following expression:
Bom('*')= '*'

is not as accurate as the previous expression because the current time of the scan might not
exactly equal the beginning of the month. Also the TagMax function may use too many
resources accessing the Archive for data of the previous month and slow down the system.
Here's the calculation expression with Max:
If Day('*')=1 and Day(PrevEvent('RateTag', '*'))<>1 then
Max(TagZero('RateTag'), 'RateTag') else Max('RateTag', 'MaxTag')

This expression has the tagname of MaxTag and compares the point to be maximized
RateTag to the current maximum in MaxTag. If the current time is the first of the month,
MaxTag is reset by comparing the maximum between the current value of RateTag to the
tagzero of RateTag. This version of obtaining a maximum makes only one Archive call as
opposed to Archive calls to obtain one month of data.

PI Server Applications User Guide 15

PI Performance Equations Scheduler

Tips and Troubleshooting

Tips for Creating PE Points

To avoid problems with your Performance Equations, follow these guidelines:

• Use the BadVal function to check to see if the value to be evaluated is bad, before
carrying out a calculation.
• Use the PctGood function to check if the amount of data that is good, is within an
acceptable level.
• Use double quotes (") whenever required.
• Cascade calculations that occur in the same scan class by using offsets.
• Don't use ambiguous timestamps.
• Set the Step attribute to 1 if you wish to have your data tracked as a stair-step instead of
straight-line interpolation.

Common Performance Equation Problems and Errors

If you do not see results for a PE point:

• Make sure the Performance Equation Scheduler is running.
• Use the pipetest utility to check your equation syntax. Check your equation for the
following common errors:
ο Are all PI times and tag names enclosed in single quotes?
ο Did you spell your tag names and function names correctly?
ο If the equation text begins with the single quote character ( ' ), did you enclose the
entire string in parentheses? Excel removes the leading single quote.
ο Are you (not) using tag names that are also valid PI time expressions?
• Check the file pipc.log in the pipc\dat directory for errors in the equations during
compilation. In the log file, error at offset x indicates that a syntax error x characters from
the beginning of the equation has been detected.
When the Performance Equation evaluator cannot perform a calculation during runtime, it
returns the error value Calc Failed. This means that the PE point has the correct equation
syntax and is running. Some possible causes are:
• Source tags have unexpected values. For example, the expression 'sinusoid' + 12
results in Calc Failed if the value for the source tag sinusoid equals the digital state
Shutdown.
• The source data do not meet the minimum pctgood value in a summary calculation. For
example, TagAvg('sinusoid', '*-1h', '*', 80) results in Calc Failed if
less than 80% of the values for sinusoid are good for the last hour.
• Runtime data type conversion fails. For example, suppose the PE point is a digital point
and has the expression 'StringTag'. If the string source tag StringTag has a string

16
 Tips and Troubleshooting

that cannot be converted to a digital state either in the PE point's digital state set or the
System Digital State Set, then the result is Calc Failed.

Prevent Scheduling Errors

If two clock-scheduled calculations are evaluated at the same period and offset, there is no
way to determine which calculation should be performed first. If your PE point references
other PE points, you need to use an appropriate scan class offset to force PI to evaluate the
calculations in a specific sequence.
For example, suppose points A, B, and C all represent PE points. Point C is calculated as A/B
(A divided by B), so point C should be calculated after points A and B are calculated. If all
three points have the same scan class, there is nothing that ensures that points A and B are
calculated before point C is calculated. To trigger the point C calculation to take place after
the point A and point B calculations, you can use a scan class with a slight offset for point C.
For example, if you use the following scan classes for points A, B and C, then PI calculates
point A and B every hour on the hour, and then calculates point C a second later.
Point Scan class
A /f=01:00:00,01:00:00
B /f=01:00:00,01:00:00
C /f=01:00:00,01:00:01

Prevent Skipped Calculations

Although the only limit on the number of performance equations on a PI Server is the number
points available to the PI Server, there are practical limits on the performance of PE
Scheduler. It is possible for the Performance Equation Scheduler to get overloaded.
If a scan class is more than one scan period behind, it skips the calculation in order to catch
up.
To find out if the Performance Equation Scheduler is skipping calculations, look at the
pipc.log file located in the pipc\dat directory.
If you find that the Performance Equation Scheduler is skipping calculations, OSIsoft
recommends that you increase the scan periods and/or the exception reporting settings for
trigger points. You can also upgrade the hardware..

When Data Types Do Not Match

When a PE point's type does not match the type of the calculation, PE Scheduler converts the
data type of the result to the data type of the PE point (unless the result is a digital state).
In other words, for string points, the Performance Equation Scheduler converts the
calculation result into a string. For digital points, Performance Equation Scheduler first
converts the result into a digital state within the digital state set for the PE point. If this initial
conversion is not successful, the Performance Equation Scheduler converts the result into a
digital state within the System Digital State Set. For numeric points, the Performance

PI Server Applications User Guide 17

PI Performance Equations Scheduler

Equation Scheduler converts the calculation result to an appropriate numeric value, such as
integer or float.
If the data type conversion fails (for example, it is not possible to convert the string “ABC”
into a numeric value), then the calculation expression returns the digital state Calc Failed.

18
Chapter 3

PI Performance Equations Recalculator

The PI Performance Equations (PE) Recalculator is designed to adjust values of PE points
automatically. The adjustment occurs when Archive values of points that are used in
Performance Equation expressions are added, changed, or deleted. You can also use PE
Recalculator as an offline utility to reprocess explicit periods of time for specific points.

Recalculator Overview
The PE Recalculator automatically adjusts values of PE points when values of points used in
Performance Equation expressions are added, changed, or deleted. Delayed or out-of-order
Snapshot events can also trigger recalculations.

Note: Performance Equation evaluations based on new Snapshot values are performed
by the PE Scheduler as described in Choose a Scheduling Method (page 10).
Recalculator covers all times before the Snapshot value of a PE point.

The Recalculator supports multi-level (but not recursive) dependencies and takes into account
the resulting time dependency. Explicit time dependency expressions and time-related
functions are supported as well. Some point attributes of the dependent PE point and the
source points are considered.
Like other standard PI subsystems, Recalculator runs on a PI Server Home Node, either as a
service or manually as a console application. When Recalculator is started as a service,
messages are sent to the PI Message Subsystem and additional debug output may be sent to a
log file. When Recalculator is started as an application, messages are written to the console.
There are several limitations and side effects to keep in mind, due to compression and other
factors, which are described in this chapter.
It is important to realize that recalculation “is expensive” as it bypasses exception reporting,
may retrieve a lot of Archive data for many tags, and may generate many out-of-order events.
All of these factors place a significant overhead on a PI Server. In addition to these
considerations, check that any affected Archive file contains the point definitions and has
sufficient space.

PI Server Applications User Guide 19

PI Performance Equations Recalculator

Recalculation Terms

The following recalculation terms are used in this chapter.

Name Description
Dependent A PI point that normally receives its values from the PE Scheduler when it
PE Point evaluates an expression. These are also the points that are modified by the PE
Recalculator when necessary.
Source Point A PI point whose tag appears in a Performance Equation expression. In general,
additions, changes, and deletions of source point values trigger recalculations.
Absolute A date/time expression that evaluates to the same time regardless of the time of
Timestamp the calculation. Examples are '10-oct-99' and '01-jan-70'.

Relative A date/time expression defining an offset from the actual time of the calculation.
Timestamp Examples are '+7h' and '-30d'.
Note: One exception to this rule occurs when a Relative Timestamp appears as
one of the two time arguments of a PI Performance Equation Archive retrieval
function. If the other time is an absolute time, it becomes the basis time.
Basis Time The time to which the offset defined by the Relative Timestamp is applied. When
evaluating PE point values, the PE Recalculator determines the basis time of the
dependent values to be corrected and applies the offsets from that basis.
Combination A date/time expression consisting of an absolute timestamp and a relative
Time timestamp as an offset. For example, 'T+7h'.

Performance Same as Dependent Point.

Equation
Point

PE Recalculator Functionality
When the PE Scheduler starts, it finds the PE points by scanning the PI Point Database for
points with a specific point source defined in pipeschd.bat, usually C.
Since the Recalculator sends events to the same PE points, it also scans the PI Point Database
on startup, scanning for the same point source. By default, all PE points are considered for
recalculation. If you wish, you may assign values to the Location1 attribute of any PE point.
The Recalculator can be configured to consider only points with a specific Location1
parameter value.
The PE Scheduler signs up for exceptions for any event trigger points. The Recalculator signs
up for Archive events of all source points. The reason for the difference is that the
Recalculator must be aware of any changes to any source point, not just event trigger points.
Only events that were not handled in time by the PE Scheduler are considered by the
Recalculator. The timestamp of the source point event has to be older than the Snapshot time
of the corresponding dependent PE point. The delay caused by the normal scan cycle does not
trigger a recalculation.
Recalculation is done in two steps: For a source point event, first the affected PE point
periods are found. Then, all these periods are processed for existing events to replace, and
new events to insert. When inserting new events, their timestamps are derived from the
timestamps of the source events.

20
 PE Recalculator Functionality

Generally, there are three main questions:

• Which dependent PE points are affected?
• What time range has to be recalculated?
• How do other point attributes influence the recalculation?
These questions are discussed here and lead to a definition of different recalculation types.
The recalculation types are described in a subsequent section.

Point Dependency Considerations

Generally, all tags used in the ExDesc field of a PE point in the PI Point Database are
classified as source tags. These tags may be used in arithmetic expressions or as function
parameters.
With the PI Server, it is possible to dynamically construct tags by concatenating string
constants and values of one or more string points. The Recalculator is unable to process
expressions that use this construct.

Time Range Considerations

Time ranges are defined by two timestamp expressions, usually passed as two arguments to
the same PI Performance Equation function. Examples include TagAvg and FindEq. It
occurs frequently that the timestamp expression '*' is used. This is basis time for the
calculation. For PE points evaluated normally by the PE Scheduler, the basis time is the
current time except for an event-based PE point with Location3 set to one. In that case, the
basis time is the trigger event time. For the Recalculator, the basis time is in general the time
of the new or changed source point event.
Any new event for the source point not handled by the PE Scheduler causes a series of
Archive events within the time range to be recalculated. The Recalculator must determine the
start and end time of the affected time range.
Time calculations resulting in a timestamp or in an interval can be inverted if no absolute
timestamps are involved. For example, consider a Performance Equation expression such as:
TagVal('input_pt', '*-1h')

If 'input_pt' receives a new event earlier than the Snapshot time of the PE point, its
timestamp is the basis time for recalculation. PE point events one hour after the 'input_pt'
event are affected. The minus sign is effectively inverted to a plus sign, as in '*+1h'.
Inversion also applies to time periods:
TagAvg('input_pt', '*', *-1h')

If a new event for 'input_pt' is received, its timestamp is the basis time, or '*' in the
expression. The new event affects the period '*' until '*+1h'.
If there are absolute times in an expression, it would mean that all PE point values would
have to be recalculated. In other words, if an absolute time appears in an expression, all
values after the timestamp of a new or changed event would need to be recalculated.

PI Server Applications User Guide 21

PI Performance Equations Recalculator

Time Range Examples

Tag Expression
TimeCalc If BadVal('xsource','*-8H') then NoOutput() else
Tagval('xsource','*-8H')

CalcInt TagAvg('xsource','*-1h','*')

AllCalc If BadVal('xsource') then Tagval('xsource','12-Jan-98

08:00') else 'xsource'

TimeCalc: In the first example, if the value of xsource at 12-Jan-98 12:12:00 is changed,
TimeCalc at 12-Jan-98 20:12:00 (8 hours later) has to be recalculated.
CalcInt: In the second example, the expression has to be recalculated for a 1-hour period past
the time of a modification of xsource.
AllCalc: If the value of xsource at 12-Jan-98 08:00:00 were to be modified, then all values of
the PE point after 12-Jan-98 08:00 would have to be recalculated whenever xsource is in a
bad state.

Clock-Scheduling vs. Event-based Scheduling

If a PE point is clock-scheduled, a new source point event causes a search for existing PE
point events up to one scan cycle after the source point event to take place. The time between
calculations depends on the Location4 attribute indicating the scan cycle defined in
pipeschd.bat. If there is no Archive event found in the searched period, a new one is
created.
In event-based calculations, no scan classes are defined and Location4 is ignored. If an event
within a default period (10 sec) does not exist, a new one is created for simple dependencies.

Step Point Attribute

The Step attribute defines how a trend of data values appears between events stored by PI
Server.
If Step = 0, data values are linearly interpolated between archived events for numeric points.
Changing a source point value implies changing all archived PE point values between the
previous and the next event of the source point.
If Step = 1, data values value between archived events are considered to be the same as the
previous event. Changing a source point event influences a dependent PE point between the
modified source point event and its next event. Data values prior to the modified event are not
affected.

Compression / Exception

Because of exception reporting and compression, not every original PE point event is found
in the PI Data Archive. The Recalculator cannot simulate the original exception or
compression algorithm because it no longer has the original Snapshot values. It recalculates

22
 Types of PE Point/Time Relationships

for all events of all source points, plus all existing PE point events, plus the start and end
times of the affected period.
There might be more Archive events after a recalculation. This might fail or take rather long
when performed on Archive periods that are no longer covered by the primary Archive file.

Scan and Archiving Attributes

Set the Scan attribute to 0 to turn off the PE Scheduler. Setting the Archiving flag to off (or
0) causes no events to be sent to the PI Data Archive for storage.
If the Scan attribute is set to 0, then there are no values generated by the PE Scheduler at
some time in the past. If Archiving is 0, values generated by the PE Scheduler are not stored.
The times at which the Scan and Archiving attributes were edited are not recorded.

Note: The ability to recalculate events may be affected if either of these attributes is set
to 0. It is impossible to accurately correct history if there were no original events to
adjust.

Location1

The Location1 attribute may be used to exclude points or to schedule multiple instances of
the Recalculator for performance reasons. This corresponds to the number in the /in startup
parameter or in the Instance Registry setting. By default, all PE points are examined for
recalculation.

Types of PE Point/Time Relationships

The types of the relationship between a PE point and time are summarized in the following
table, and explained in subsequent sections.
Relationship Short Description
Simple The expression consists of arithmetic operations and functions.
There are no time parameters except *.
Multilevel Point A PE point is source for another point. Archive modifications should
Dependency trigger another recalculation.
Recursive One of the source points in the expression is the PE point.
Relative Time Shift The period to be recalculated is shifted according to the Performance
Equation. No additional event for PE point is created at source event
time.
Special Event If the source event range covers the indicated event (such as T), the
period to be recalculated is determined according to the Performance
Equation. Otherwise, the dependency relation can be ignored.
Time Period Reference The Performance Equation contains Archive functions with start and
end time. Start and End time have to be relative to a basis time (such
as * and T)

PI Server Applications User Guide 23

PI Performance Equations Recalculator

Relationship Short Description

Multilevel Time The time parameter of an Archive function is the result of another
Dependency function.
Absolute Time Reference Automatic recalculation is not supported. This type of expression can
only be recalculated manually.

Type 1: Simple Point Relationship

This type of recalculation covers all arithmetic functions and operations and all functions
working on actual values only. Bad digital states are evaluated as with normal Performance
Equations. Other errors do not change existing Archive events.
The question of the affected time range of the PE point has to be resolved even in this case.
Tag Expression
TestCalc 100 - 'sinusoid'

T2Calc TagVal('TestCalc' , '*') * (('sinusoid'-50.0)/50.0)

Finding Corresponding Timestamps

The main task is to find the timestamps for the modified source points that define the period
of time that needs to be recalculated. In general, the timestamp of a PE point event is different
from the timestamp of a source point. For the Simple recalculation type, the following
situations depending on point attributes are considered:
• The Performance Equation always uses the values prior to the beginning of the scan
cycle. In the example above, T2Calc is always one cycle behind TestCalc. The cycle is
defined by the scan class of the PE points and by the scan parameters in
pipeschd.bat.
• To insert a value, Performance Equation uses the system time, not the timestamp of an
event trigger point by default.
As the PE point may depend on more than one source point, the Archive is examined for
events until the next event of the modified source point. All these events have to be
recalculated. See the figure in Inserting New Archive Events (page 24).

Inserting New Archive Events

When a new data event is inserted for the source point, a new event of the dependent PE point
may need to be inserted as well. The Recalculator searches the Archive for the next
dependent PE point event after the trigger event. A point event found within one scan cycle is
modified; otherwise a new event for the dependent PE point is inserted. An inserted event is
set at the source event's timestamp +1 sec.

24
 Types of PE Point/Time Relationships

Recalculation Period on Type = Simple, Step=1, No Compression

Source Data with Step=0

If the Step attribute is 0, a modification even affects the time prior to the changed value. The
Recalculator examines the Archive in the range from the previous event to the next event of
the modified source point. All events of the PE point in this period have to be recalculated.
Notice that a PE point event prior to the initiating source point may be modified. See the
exclamation mark (!) in the following figure.

Note: With Step = 0, entering a single event into the Data Archive always affects the
period between the previous and the next unmodified event. If you intend to enter
a single peak or to mark the last “originally good value”, you have to enter
additional events.

Recalculation Period on Type = Simple, Step=0, No Compression

PI Server Applications User Guide 25

PI Performance Equations Recalculator

Exception Reporting Algorithm

The PE Scheduler sends data to the Snapshot by exception to create events for dependent PE
points. Depending on the exception parameters, this may result in suppressing new events if
there are no relevant changes to the previous value. The compression algorithm minimizes
the amount of available Archive events. In the following considerations, this is generally
called Compression. The effect of the exception algorithm is not considered separately.

Compression on Calculated Values

There are no events in the Archive as long as the interpolated line between two events fits to
the "real" values. The exception/compression algorithm cannot be simulated when the actual
values are no longer available.
This implies extra considerations:
• The modified range of the PE point may be even larger than the affected source point
range.
• Depending on the unmodified source point's event, a recalculation may yield different
results compared to the straight-line result of recalculating only the given events of the
PE point.

Recalculation Period on Type = Simple, Step=0, PE Point with Compression

Recalculator inserts extra events at the beginning and the end of the modified period (?3) if
necessary, so there are no new results without changed input. Due to the compression
algorithms, the new values may still be slightly different from the original interpolated
values.
Recalculator inserts extra events according to the modified source point event. Recalculator
does not insert additional events due to unmodified source events (?2).
Recalculator recalculates all existing dependent events in the time range affected by the
modified source event (?1). It does not simulate the exception reporting and compression
algorithm.

26
 Types of PE Point/Time Relationships

Conditional Dependency
“If-then-else” constructions are evaluated only during recalculation. The point and time
dependency is stated by parsing the expression in the ExDesc parameter for all cases on
startup.

Type 2: Multi-level Dependency Point Relationship

A → B → C → …
(x → y means x influences y, y is dependent, and x is source)
Normally, no other special considerations are required if PE points are used as source points
again. As new values of PE points are sent to the archive, there is an event on which the
Recalculator has signed up, so the standard mechanism does all the work.
Recursive Point Relationship is checked for this dependency, too.

Type 3: Recursive Point Relationship

A → B → A or directly A → A
Such a recursive dependency is legal; you may use it for counting, and so on. The result
depends normally on “if-then-else” and on scan cycle parameters.
If a recursive dependency is detected, no automatic recalculation occurs. You may start a
complete recalculation manually by using the /execute option and stating the desired time
range. The result, however, depends on previous values and recalculations.

Examples
Tag Expression
TestCalc If BadVal('TestCalc') then 0 else (if 'TestCalc' > 9999 then 0
else 'TestCalc' + 1)

EvCount Event=CountMe, if BadVal('EvCount') then 0 else ('EvCount' + 1)

TestCalc increments by one on every scan cycle and resets if the value is bad or is larger than
9999.
EvCount shows the number of events for the point CountMe.
The BadVal() constructions are required to quit any non-numeric initial state (Shutdown,
PtCreated).
These recursive calculations are very sensitive to the previous state of the variable and may
give different results when they have already been recalculated before. In example 2
(EvCount), there is no possibility to detect all events from the Archive. Additionally, they
would generally result in a recalculation of the whole period up to now.
For these reasons, PE points depending recursively on themselves are generally excluded
from recalculations.

PI Server Applications User Guide 27

PI Performance Equations Recalculator

There is no explicit limit on the number of levels to detect a recursive dependency.

A → B → C → … (any number of PE points) … → Z → A

Type 4: Relative Point Relationship

* - n X ; X ∈ {S, M, H, D }

This relationship type is also known as a time shift relationship. For example:
Tagval('s_pt', '*-3h')

Inverting results in * + nX, so the Recalculator schedules recalculations at '*+3h', when

's_pt' receives an Archive modification event.

Type = Relative Time Shift

The algorithm described for type = Simple (without explicit time dependency) is applied to a
period shifted by the indicated offset. Extra events are not created.
For the example here, this results in a recalculation period for the dependent PE point from
t1=(prevevent(source) + 3h) to t2=(nextevent(source) + 3h).

Note: Future references '*+nX' are syntactically correct. Based on actual values, they
result in 'No Data' or 'Bad'. On recalculation, they may result in numeric values.
These are processed normally without error messages.

Type 5: Special Event Point Relationship

B ± n X ; B ∈ {T, Y, 1 .. 31, Mon, Tue, ... }

This relationship type is also known as a Relative Time Reference.

28
 Types of PE Point/Time Relationships

The recalculation period may be one complete day relative to the given timestamp. The sign
of the offset fraction is inverted. Note that only changes effective at the specified special time
result in a recalculation.

Examples
Tag Expression
BASEVAL TagVal('xsource','T')

DIFFVAL 'xsource' - TagVal('xsource','T')

BASEVAL holds the midnight value of xsource of each day. If this value changes, all
Archive values of BASEVAL for that day have to be modified. Every recalculation on this
day yields the same new result. If there are changes of xsource at other timestamps, nothing
is recalculated.
DIFFVAL has to be recalculated for the whole day, when xsource at midnight is modified.
Other changes of xsource affect values of DIFFVAL only at the event timestamp of xsource,
and the period of time between the previous and next events of xsource. The period of time
between the new xsource event and the next xsource event would have to be recalculated if
the Step point attribute is 1.

Type = Relative Time Reference

Type 6: Time Range Point Relationship

In the following example, any change of xsource affects the value of YSUM for the whole
next day's period.

PI Server Applications User Guide 29

PI Performance Equations Recalculator

Tag Expression
YSUM TagTot ('xsource','Y', 'T')

This dependency type requires that both time parameters be relative to the calculation time.
Expressions like '-1h' are valid as one of the time parameters. They are interpreted relative to
the other.

Type 7: Multi-level Time Dependency

The time parameter of an archive function is the output of another function. For example, this
expression finds the average value of sinusoid from the time yesterday at which the value of
'starttrigger' was 50 to the current time:
TagAvg('sinusoid', FindEq('starttrigger','y','t',50), '*')

For recalculation purposes, the relation to the point sinusoid is considered a Type 1 (Simple)
point relation. As the detection of the affected period does not consider the time dependency,
not all possibly affected Performance Equation events are automatically recalculated. For
example an edited value of sinusoid does not force the recalculation of the dependent PE
point for the whole next day.
The calculation itself uses the time parameters correctly, so requesting a recalculation
manually could be used as a workaround, if necessary.

Type 8: Absolute Time Reference Point Relationship

In the first example below, if the value of xsource at 01-Jan-98 is changed, the Recalculator
would have to calculate everything from the timestamp stated in the Performance Equation
expression up to now.
In the second example below, other changes of xsource affect the value of DIFFVAL only at
the timestamp of xsource and the interval of time between the previous and next events of
xsource.
Tag Expression
BASEVAL TagVal('xsource','01-Jan-98')

DIFFVAL 'xsource' - TagVal('xsource','01-Jan-00')

A change in an absolute timestamp in an expression does not cause recalculation of the whole
Archive automatically. If this function is desired, you have to run the Recalculator as a
console application, stating which point and time period has to be recalculated.

30
 Special Performance EquationTime Functions

Special Performance EquationTime Functions

Some of the time functions in the Performance Equation library change the data type of their
arguments, or extract information from timestamps. This category of time functions requires
special consideration.

Modify a Timestamp

There are several time functions that modify a given timestamp including Bod (), Bom (),
Bonm (), Noon(). If the timestamp parameter is relative to calculation time (normally * or
something based on it), the result refers to a special timestamp relative to the parameter. If
this timestamp is modified, the Recalculator must recalculate a whole day or a whole month.
This is similar to the "B ± n X " problem in Type 4: Relative Point Relationship (page 28). If
the timestamp parameter is absolute, the result is an absolute timestamp; an automatic
recalculation is suppressed. See Type 8: Absolute Time Reference Point Relationship (page
30).

Parsetime Function

Parsetime () converts any string to a timestamp. If the input string is a constant and complete
time expression, this has the same effect as a direct time parameter in single quotes. Here
Parsetime() is not necessary (PI2 compatibility).
If the input string is an incomplete constant time expression, we have something relative to '*'
that evaluates similar to the previous functions.
If the input string is a variable, evaluation at compile time is impossible: Any automatic
recalculation is suppressed.

Extract a Number from a Timestamp

Other functions extract a number out of a timestamp, including Day (), DaySec (), Hour (),
YearDay ().
These functions don't affect the recalculation period. If the results are used in other time
expressions, they have the same effect as any other variables. The effects can only be
evaluated during the recalculation process.

Examples of Archive Retrieval / Search Functions

A simple form of filter, assuming no compression, with scan-based values; this avoids
recursive use of the PE point:
('xsource' + (PrevVal('xsource', '*')*9) / 10

Yesterday's average value:

TagAvg('xsource', 'Y', 'T')

PI Server Applications User Guide 31

PI Performance Equations Recalculator

Performs an integration (sum) on xsource since tsource's value first exceeded 10.0
yesterday; assuming xsource has a per day EngUnit:
TagTot(xsource, FindGt(tsource,'Y','T',10.0),'T')*24

These functions have several time parameters, defining a time range of Archive values to use.
See the limits of the Time Range Reference type, as detailed in Type 7: Multi-level Time
Dependency (page 30).
PrevEvent(), or NextEvent () return an absolute timestamp outside a given time range. This
means theoretically that we cannot determine the reverse time. Practically they return the
neighbor timestamp to the input timestamp. This is the same algorithm the recalculation
performs anyway (if source point's Step=0). Therefore, no extra time dependency is
evaluated. This applies also to the functions PrevVal() and NextVal().

Note: Multilevel functions, such as PrevVal('tagname'), or PrevEvent('tagname')-1s,

are calculated properly, but determining the affected recalculation period is not
supported properly.

Recalculation Limitations
There are some restrictions and limitations on the Recalculator's ability to reprocess
Performance Equation expressions. This section outlines these limitations.

Source Variables without Archive Values

If any of the source variables do not have Archive values, the recalculation results in No
Data. This is not inserted into the Archive. If the original PE Scheduler calculation created
Archive events, they are preserved. Recalculation of these equations is not performed.

Exact Simulation of the Original Scan Cycles

A point event found within one scan cycle is modified; otherwise a new event for the
dependent PE point is inserted. An inserted event is set at the source event's timestamp +1
sec.

Modifications of the Performance Equation

When you modify a Performance Equation, recalculation is not initiated. Whenever

recalculation does occur, the current expression is used. Previous expressions are not
retained.
If you want to apply a new formula to past values, you must run the Recalculator explicitly
on the desired point and period.

32
 Recalculator Point Configuration

Archive and Time Functions

These generally result in recalculating some period between the input event and now. If these
functions are used, they can cause a heavy amount of system load. As noted earlier, the
recalculation of the whole Archive up to now because of absolute timestamps is suppressed
on automatic recalculation.
Timestamps as a result of other embedded functions are not supported completely. If the
timestamp expression cannot be evaluated at compile time (subsystem start), a dependency
Type 1 (page 24) (that is, Simple) is assumed. This applies to expressions like:
TagVal('input_tag', PrevEvent('input_tag','*')-3600)

Not all affected PE point events might be found correctly. See Type 7: Multi-level Time
Dependency (page 30) for another example.
It is syntactically correct to have relative time expressions referencing future values. PE
Scheduler works on No Data and gets a Calc Failed result. If the Recalculator has to perform
this calculation, this is not considered specially. A numerical value might be returned and
stored in the archive. So there are different results without any change in the source data.

Unsupported Dynamic Functions

Recalculator does not support the following functions: Arma (), Delay (), Impulse (), and
MedianFilt ().

Incomplete Timestamps

An incomplete absolute timestamp (such as '25' = midnight on the 25th of the actual month)
refers to the actual time of compilation, which gives different results depending on the time
of recalculation. For more details, see Set the Location3 Attribute: Timestamp (page 12).
Avoid these expressions.
The calculation is independent of the Archive time for which it is used.
As incomplete timestamps are not absolute dates, they don't lead to a total recalculation of
any dependent PE point. As they are not valid relative time expressions, inverting of time
dependency is not performed.

Blob Support

Like the PE Scheduler, the Recalculator does not handle Blob type points.

Recalculator Point Configuration

Points used by the Recalculator are completely defined by the requirements of the
Performance Equation Scheduler. For more details on point configuration, see PI
Performance Equations Recalculator (page 19).

PI Server Applications User Guide 33

PI Performance Equations Recalculator

In addition, the Location1 parameter is used. The Location1 value does not influence the
operation of the PE Scheduler.
The Recalculator uses the Point Name and Step parameters from the source points. The
Recalculator signs up for events of the source points, which may belong to any point source.
The Recalculator is scheduled with the point source class of PE points, and uses the following
parameters of the dependent PE points: Extended Descriptor (ExDesc) (page 34), Point
Source (page 34), Scan flag (page 34), Archiving flag (page 34), Location 4 (page 35), and
Point Type (page 35).

Point Name

The point names for the PE point and the source points follow the normal PI point-naming
conventions.

Extended Descriptor

The Extended Descriptor (Exdesc) contains the Performance Equation. It is analyzed to find
source points and time expressions. It is calculated to get the new Archive values.

Point Source

All points defined in the PI Point Database for use with this module must share the point
source of the Performance Equation Scheduler. The standard for the Performance Equation
Scheduler is C.

Scan

The Scan flag must be set to 1 for the PE Scheduler to work on this point. The Recalculator
does not use or change the Scan flag.

Archiving

Archiving has to be set to 1 for the PE Scheduler to create Archive events of this point. The
Recalculator does not use or change the Archiving flag, but the Archiving flag must be set to 1.

Location1

By default, the Recalculator considers all PE points as candidates for recalculation and does
not use this attribute value. However, if there is a parameter "/IN=n" where n > 0) in
the startup file or an Instance value in the Registry, only points with the corresponding value
in Location1 are recalculated. This feature can be used to assign PE points into recalculation
groups.

34
 Recalculator Point Configuration

Note: It is possible to start multiple instances of the Recalculator. Every instance should
be controlled by a different /in parameter.

Location4

This parameter specifies the scan class used by PE Scheduler.

PointType

As with the PE Scheduler, the point types Int16, Int32, Float16, Float32, Float64, Digital
and String may be used.

Step

This value for the source point is used to determine if any event any time prior to the
scheduled event must be examined. See Point Dependency Considerations (page 21).

Other Attributes

The Recalculator does not use any other point attributes. They may be used by the PE
Scheduler and retain their normal meanings for other operations.
The following attributes are not used:
• Location2
• Location3
• Location5
• UserInt1
• UserInt2
• UserReal1
• UserReal2
• EventTag
• InstrumentTag
• Square root code

PI Server Applications User Guide 35

PI Performance Equations Recalculator

Start Recalculator as a Service

The Recalculator can run as a Windows service, to automatically recalculate PE points that
have source points that receive edits, deletions, or new delayed or out-of-order events.
The Recalculator module is normally installed automatically when the PI Server is installed.
This section explains how to configure the PE Recalculator startup.

Configure Startup and Shutdown

The Recalculator is not set to start automatically upon system startup, even if you chose to
have the PI Server start automatically. To start Recalculator automatically, edit the startup
and shutdown scripts, and change the startup settings for the Recalculator service. You should
do both since you may start the PI Server by starting the computer, or by running the startup
script when the computer is already running.

Startup and Shutdown Scripts

Edit \pi\adm\pisrvsitestart.bat and add the line:
net start pirecalc

Edit \pi\adm\pisrvsitestop.bat and add the line:

net stop pirecalc

Edit \pi\adm\pisitestart.bat and add the line:

start "PI Recalculator Subsystem" /min cmd /k ..\bin\pirecalc.exe

Configure Automatic Startup

Use one of the following methods to configure the Recalculator.

Using the Services Control Panel

Open the Control Panel and start the Services. Locate the PI Recalculator Subsystem in
the list of services. Click the Startup button:

36
 Start Recalculator as a Service

Click the Automatic radio button. The Recalculator starts automatically on your next reboot.

Using Recalculator Command-Line Arguments

The Recalculator executable supports command-line arguments that can be used to configure
it to run as a Windows service.
Issue the following commands:
\pi\bin\pirecalc -remove
\pi\bin\pirecalc -install -auto -depend piarchss
-display "PI Recalculator Subsystem"

Specify Options with a Startup Script File

When the Recalculator starts, it searches for \pi\bin\pirecalc.bat. This file may
contain startup and debugging options, and can also be used as the startup file when starting
the Recalculator manually. This file is not created automatically when the PI Server is
installed or upgraded.

Note: When specifying file names in the script, be sure to use full path names.

You can also set some of these options by editing the Windows Registry. See Specify Options
with Windows Registry (page 40) for details.

PI Server Applications User Guide 37

PI Performance Equations Recalculator

Recalculator Startup Options

The following table shows the command line switches for the PE Recalculator. These options
are detailed after the table.
Some of these options are best used only when the Recalculator is started manually (page
42).
Parameter Description
/in=0 Interface number (corresponds to Location1 point
attribute). Omitting this parameter or a value of 0 means
ignore Location1 values.
/output=c:\….\pirecalc.log Module-specific debug log file pathname. The default
output is to the screen, if run as console application.
/ex[ecute]=tag,start[,stop][,TEST] Recalculate a specific PE point and exit. This option can
accept one timestamp to specify a point in time, or two
timestamps to specify a range. Adding the word TEST
causes the display of recalculated results with no storage
in PI.
Wildcard characters can be used in the tag. If present, an
/in= startup parameter is checked, too.
This option may only be used only in manual mode.
/deb=0 Debug level. See /deb=0 (page 40) for debug level options.

These parameters of pipeschd.bat are also read and interpreted:

Parameter Description
/f=... Scan Class frequency, optional use of multiple /f=…
no default values provided
/ps=C Point Source

Note: Command-line parameters are not case-sensitive. You can use a leading hyphen
(-) instead of forward slash (/) as well.

Command-Line Parameter Reference

/ps = C
Specifies the point source of the points on which the module operates. This parameter is
taken from the PE Scheduler startup script file, pipeschd.bat.

/in = 1
This parameter corresponds to the Location1 attribute of a point. If you omit this parameter
or set it to zero, all PE points, determined by the /ps parameter in pipeschd.bat, are
checked for recalculations.

38
 Start Recalculator as a Service

/f = 00:00:30[,00:00:00]
This parameter is set in pipeschd.bat. It defines the scan frequency for different scan
classes. There is no limit on the number of scan classes. An offset may be added.
These parameters in combination with the Location4 point attribute determine where an
existing Performance Equation event is searched, or if a new event is created. The offset
portion is not used.

/output = c:\pi\log\pirecalc.log
The /output option causes Recalculator to generate debug output and error messages and
send them to PI\log\pirecalc.log. If you omit this parameter and start Recalculator
(manually) as a console application, output is sent to the console window.
If you start Recalculator as a service and the output parameter is missing, output goes to the
PI System Message Log. Use the PIGetMsg utility or PIHealthCheck to retrieve this
information. Debug messages are not sent to the PI System Message Log.

/execute = tagmask,starttime[,endtime][,TEST]
The /execute mode allows you to test or modify single Dependent PE points. Use this option
only when you manually start the Recalculator.
For example, the following means recalculate the PE point tag1 at the given timestamp, then
exit.
/execute=tag1,12-dec-98 15:00:00

• For starttime and endtime the PI time syntax is allowed.

Note: Do not use quotes around tagname and time. If this option contains space
characters (timestamps require a space between date and time), enclose the
whole option in double quotes.

• Tagmask is searched among the tags with the same point source as stated in parameter
/ps in pipeschd.bat.
• If a parameter /in is present, Location1 is checked, too.
• Tagmask can contain wildcard characters * and ? All matching points are recalculated.
• If there are two time parameters, they define a time range to be recalculated.
• If there is a single time parameter and no event exists at that time, within limits given by
the corresponding scan cycle, a new Archive event is created.
• If the additional sub-parameter TEST is applied, the results are not stored in the Data
Archive but are printed only, according to the /output parameter.
• This mode does not work when run as a service.
• The option keyword may be abbreviated up to "/ex="

PI Server Applications User Guide 39

PI Performance Equations Recalculator

/deb=0
The module is able to print additional debug information into the module-specific log file,
depending on the debug level used. The amount of log information increases with the value.
All information of lower levels is included.

Recalculator Debug Levels and Output

Debug Output
Level
0 Start / Version / Number of points / Stop (As sent to Message Subsystem). Test mode
results. Internal errors.

1 Additional information about module operation. Examples: startup parameter / defaults,

results of dependency check on start/update.

2 Information about problems that are handled by the module and do not cause data
loss. Start of a recalculation period.
3 Display result dependency. More calculation period information.

4 Print out each calculation the program performs. Only for onsite test purposes. Use this
mode if directed by OSIsoft Technical Support. Log file might increase rather quickly.

5 More information than Level 4.

6…8 Additional internal debugging information

9 Maximum internal dump output.

Specify Options with the Windows Registry

To control Recalculator when started as a service, you can specify startup options in the
Windows Registry rather than creating a startup script file. Registry values are not created
automatically when the PI Server is installed or upgraded. Use the RegEdit application to
update the Registry.
You can include the following startup parameters in the Registry key
HKLM\SYSTEM\CurrentControlSet\Services\pirecalc:
Startup Parameter Registry Value Name Data Type
/output DebugLogFile REG_SZ
/deb DebugLevel REG_DWORD
/in Instance REG_DWORD

Note: Startup file settings located in pi\bin\pirecalc.bat have priority over

Registry settings.

If there is no path information for DebugLogFile, the standard PI Server log directory
\PI\log\ is assumed.

40
 Start Recalculator as a Service

The example above shows the Recalculator service configured for a debug level of 1, with a
debug log file specified.
A normal installation has neither Registry keys nor the pirecalc.bat file.

Run Multiple Instances

To recalculate several subsets of Performance Equation points you may wish to run multiple
instances of pirecalc. Create a startup script for each instance, such as:
\pi\bin\pirecalc.bat
\pi\bin\pirecalc2.bat
\pi\bin\pirecalc3.bat

They should differ by the /in=# startup parameter. If they are intended to start console
applications, they may refer to the same executable, \pi\bin\pirecalc.exe. See Start
Recalculator Manually (page 42) for more details.
To run multiple instances of Recalculator, create copies of pirecalc.exe and rename
them, for example:
\pi\bin\pirecalc2.exe
\pi\bin\pirecalc3.exe

Then install them as services by running

\pi\bin\pirecalc2.exe -install -auto -depend piarchss
-display "PI Recalculator Subsystem (Subset 2)"

It is necessary that corresponding .exe and .bat files have the same base names and reside
in the same directory \pi\bin\. You may change the display (icon) names. OSIsoft
recommends you start them with "PI." They must be unique.

PI Server Applications User Guide 41

PI Performance Equations Recalculator

Edit the start and shutdown scripts. See Start and Stop the Performance (page 6)Equation
Scheduler for more details. The notes there about automatic vs. manual service start apply to
the additional instances as well.
To rename the originally installed instance, you have to remove the service first. Use the
command:
\pi\bin\pirecalc.exe -remove

And proceed as described above.

Alternatively to different .bat files, you may add the Instance=# Registry value as
described in Specify Options with a Startup Script File (page 37). The Registry key pirecalc2
might look like this:

Start Recalculator Manually

You can start Recalculator as a console application instead of, or as well as, a Windows
service. This is useful if you want to watch debug message output on the screen, or to
reprocess Performance Equation expressions on demand.

Recalculator Startup Options

When started manually, the Recalculator interprets the same startup options as when run as a
service.
An example of a startup script is:
pirecalc.exe /deb=1 /output=c:\pi\log\pirecalc.out

You can start the Recalculator by running a batch file (such as \pi\bin\pirecalc.bat)
containing these startup options.

42
 Start Recalculator Manually

You can recalculate a subset of PE points if they have the same Location1 parameter. This is
specified with the /in startup parameter. Different subsets can be processed in parallel by
other instances of pirecalc that are run as console or as a service. Running several console
application instances in parallel simply requires different startup scripts, containing different
/in parameters.

Manual Recalculations

This section describes recalculation operations that you can perform when you start
Recalculator manually.

Note: Only existing archive events for the Performance Equation tag are replaced. No
recalculation (except on the boundary) occurs if there are no archive events within
the specified interval.

Recalculate a Single PE Point over a Period of Time

Use the /execute option with two timestamps. For example:
/execute=MyAvgTag,"01-dec-98","01-jan-99"

Recalculate a Single PE Point at a Specific Time

Use the /execute option with a single timestamp:
PIRECALC "/exec=petag,timestamp"

A new value is added if there is no event in the Archive at or directly (within one scan period)
after the timestamp. For example:
/execute=MyOtherTag,"30-nov-98 23:59:59"

Test Recalculation over a Period of Time

Recalculator shows the expected value of a PE point by recalculating it, but does not store the
result in the PI Data Archive:
pirecalc /exec=T2Calc,Y+7h,Y+15h,TEST

Recalculator shows T2Calc's values from yesterday at nine o'clock in the morning, to three
o'clock in the afternoon. The Archive remains unmodified and might contain different values.
T2Calc is assumed to be a dependent PE point.

Test Recalculation at a Specific Time

Recalculator shows the expected value of a PE point by recalculating it, but does not store the
result in the PI Data Archive:
pirecalc /exec=T2Calc,Y+9h,TEST

PI Server Applications User Guide 43

PI Performance Equations Recalculator

The Recalculator shows T2Calc's value from yesterday morning at nine o'clock. The Archive
remains unmodified and might contain a different value. T2Calc is assumed to be a
dependent PE point.

Stop Recalculator
If you start Recalculator in single execution mode (that is, manually with the parameter
/execute), the module stops itself when finished. If you start Recalculator as a console
application, use the Ctrl+C or Ctrl+Break key command.
If you start Recalculator as service, you can stop it via the Control Panel, or with the
command: (where PI\ is the full path of the PI directory)
PI\bin\pirecalc -stop

or
net stop pirecalc

Optimize Recalculator Performance

Recalculator is intended to operate as a background task on already existing Archive events.
To limit the system load, recalculation is divided into several steps with decreasing priority:
• Find the PE point and period to be calculated, whenever triggered by a source event.
• Perform calculations of periods found in the previous step.
• Check for point attribute updates.
These steps are triggered in different cycles and are limited to a number of operations per
cycle. You cannot change the parameters controlling this behavior.
To speed up the performance of the single execution mode, select an appropriate subset of
dependent PE points using the point attribute Location1 and the /in= startup parameter.

Error and Information Messages

You can view Recalculator system (log) messages in two locations.
• The standard PI System Message Log contains general information and error messages,
such as: subsystem start / stop, used point source character, and number of points
handled. Use pigetmsg or PIHealthCheck to read the Message Log.
• You can instruct Recalculator to generate a user-configurable message log file. Output
messages to any filename with the /output startup parameter. (If you start Recalculator as
an application, the output defaults to the console window.) Configure the error and debug
information recorded with the /deb=level startup parameter. The log also records results
if you use the /execute=tagname,period,TEST startup argument.

44
Chapter 4

PI Performance Equations Syntax and Functions

Reference
The Performance Equations (PE) Scheduler (page 5) allows you to easily implement
sophisticated, real-time calculations, using data in the PI System.
The PE Scheduler includes an equation syntax and a library of built-in functions, which allow
you to easily perform a wide variety of calculations on PI data. Typical calculations include
unit performance, real-time cost accounting, real-time yield accounting, heat and material
balances, batch summary, conversions and totalizations not performed by PI Totalizer, logical
operations, and calculating aggregates.
This chapter provides comprehensive instructions for using Performance Equations syntax
and functions.

Performance Equation Syntax

Writing a Performance Equation calculation expression is very similar to writing an
expression in arithmetic. In fact, you can use any of the standard arithmetic operators in a
Performance Equation expression (such as +, -, and *) to add the values of two points
together, add a number to the value of a point, and so on.
As with arithmetic expressions, the building blocks of a Performance Equation calculation
expression are operands and operators. Performance equations are simply expressions in
which operators act on operands. A basic Performance Equation expression takes the form:
operand operator operand as shown:

Operand Operator Operand

TagA + TagB
3 - 7
7 * Sqr('TagD')

The PE Scheduler evaluates the first example as the value of TagA plus the value of TagB.
The second example is 3 minus the value of TagC. The third example is 7 times the square
root of TagD.
You can construct more complex Performance Equation expressions, just as you can in
arithmetic. The PE Scheduler performs most operations in the same order as they'd be
performed in a mathematical expression. For a complete listing of Performance Equation
operator priority, see Operator Priority (page 56).
Use parentheses to group together expressions you want to evaluate first.

PI Server Applications User Guide 45

PI Performance Equations Syntax and Functions Reference

The following example evaluates as the sum of the values of TagA and TagB, divided by the
difference of 3 minus TagC:
(TagA + TagB)/(3 - TagC)

This next example is TagA divided by the sum of TagA and TagB:
TagA/(TagA + TagB)

This next example is 3 plus the product of 7 and the square root of TagD:
3 = (7 * Sqr('TagD'))

Performance Equation Operands

The operands that the PE Scheduler recognizes are listed in the following table. (As indicated
under Syntax Requirements, certain operands must always be enclosed in single or double
quotes.)

Operands in Performance Equations

Operand Type Syntax Requirements Examples

Numbers (none) 1342
98.6
.0015
1.2e2

Tagnames In single quotes 'sinusoid'

'ba:level.1'
'ba.phase.1'

PI Time Expressions In single quotes '01-dec-03'

'16-jul-94'
'*'

Strings In double quotes "string string string"

"sinusoid"

Functions Must be a Performance TagVal('sinusoid')

Equation function TagAvg('sinusoid')
Cos('sinusoid')

Number Operands
You can use numbers in Performance Equations. The PE Scheduler processes all numbers as
floating point numbers. Examples of numbers are:
3.14159
299792458
299792458.
0.671
.671
6.71e-1

Note: The second and third examples are equal, as are the fourth, fifth, and sixth.

46
 Performance Equation Syntax

Tagname Operands
You can use tagnames in Performance Equations to represent values from the Snapshot. You
must put the tagname in single quotes, unless you are using the tagname as a string, in which
case you must enclose it in double quotes. The PE Scheduler evaluates the tagname according
to its use it in an expression, as a function argument, or as a time expression.

Tagnames in Expressions
If you use the tagname in a Performance Equation expression, the tagname is evaluated as
that point's value at the current time. For example:
3 + 'sinusoid'

is equal to the value of sinusoid at the current time (see note), plus three. The same value
results from the expression:
3 + TagVal('sinusoid', '*')

Note: The exception is when this expression is used in a PE point, the PE point is event-
based, and the Location3 attribute is set to one.

Tagnames as Function Arguments

If you use the tagname as an argument in one of the Performance Equation built-in functions,
then the Performance Equation Scheduler evaluates the tagname according to the type of
value expected by that particular function.
For example, if the function expects a tagname, then the Performance Equation passes a
tagname to the function. If the function expects any other data type such as a string or a
number, PE Scheduler gets the current value of the point and passes that to the function —as
whatever data type is expected.
For example, the Concat function expects two or more strings as arguments. It concatenates
all the arguments into a single string:
Concat('sinusoid', 'ba:level.1')

To evaluate this expression, the Performance Equation Scheduler takes the current value of
the sinusoid point and the ba:level.1 point and passes these to the Concat function as strings.
Concat then returns a string that is composed of the value of the sinusoid point followed by
the value of the ba:level.1 point. If the current values of these points are, respectively, 85.329
and 30.478, Concat returns the following string:
85.32930.478

Tagnames that Are Valid Time Expressions

Wherever possible, choose tagnames that cannot possibly be interpreted as time expressions.
The tagname t-151d, for example, is also a valid time expression meaning today minus 151
days. If you must work with tagnames that are also valid time expressions, use the built-in
function TagNum to ensure that the Performance Equation Scheduler does not treat the
tagname as a time. For example, Abs(TagNum("t-151d")) would return the absolute

PI Server Applications User Guide 47

PI Performance Equations Syntax and Functions Reference

Snapshot value of point t-151d. Note that TagNum interprets a double-quoted string as the
argument.
To the Performance Equation Scheduler, an expression within single quotes can correspond
either to a time or a tagname. The PE Scheduler treats expressions in single-quotes as
tagnames for all the built-in functions that take a point as the first argument (examples
include TagVal, TagAvg, and AlmCondition). In all other cases, the Performance Equation
Scheduler first attempts to resolve the expression as a time. If the expression is not a valid
time, then the Performance Equation Scheduler tries to resolve it to a tagname. If the point
does not exist, the subsystem returns the error Calc Failed.
For example, TagVal('t-151d') returns the Snapshot value for the point t-151d, if it
exists. However, the expression t-151d returns the date corresponding to 151 days before
today—because it is a valid time expression.

String Operands
Strings are sequences of any printable characters. Strings are always enclosed in double-
quotes. Some examples are:
"This is a string"
"sinusoid"
"14-Dec-97"

Note: Character strings might look like tagnames or time expressions, as in the second
and third examples above. In some cases, the string in the third example might be
interpreted as a time. The difference is that a character string is enclosed in
double quotes (for example, "string") while a tagname must be enclosed in
single quotes (for example, 'tagname') and a time expression may be enclosed
in either single or double quotes.

Time Expression Operands

In a Performance Equation, you can use any standard PI time expression if you enclose it in
single quotes. The following topics briefly explain PI time expressions and how to work with
them in Performance Equations. For more details about PI time, see the PI Server System
Management Guide.

PI Time Expressions
PI allows three basic types of time expressions: relative time, combined time, and absolute
time.

48
 Performance Equation Syntax

RELATIVE TIME
Relative time expressions are some number of a number of days, hours, minutes, or seconds,
specified with either a leading plus sign or a leading minus sign.
The reference time, or starting time, for the relative time expression is usually the current
time. In Performance Equations, OSIsoft recommends you use a combined time expression,
rather than a relative time expression.
+1d
-24h
-3m
+24s

COMBINED TIME
A combined time expression is a specific reference time, followed by a relative time
expression. In Performance Equations, you enclose the combined time expression in single
quotes (or double quotes, if you are passing the time expression to a Performance Equation
function as a string).
'*+8h'
'18-dec-02 -3m'
'T+32s'

Combined time expressions should contain only a single operator. If you add additional
operators, you get unpredictable results. For example, the following are not valid time
expressions:
'*+1d+4h'
'T-1d+12h'

ABSOLUTE TIME
Absolute time expressions are everything else—in other words, any time expression that is
neither a relative nor a combined time expression is an absolute time expression. When using
absolute time expressions in Performance Equations, put the time expression in single quotes.
'*'
'14-Dec-97'
TagVal('Sinusoid', "1-Jun-2000")
'11-Nov-96 2:00:00.0001'
't'

TIPS FOR WORKING WITH PI TIME EXPRESSIONS

When working with time expressions in Performance Equations, please follow these
important guidelines:
• Use absolute or combined time expressions, rather than relative time expressions. If you
don't, depending on the context of the expression, you might get an error message or PI
might choose a starting time that is not what you expect.
• Relative and combined time expressions do not provide any special processing for clock
or calendar events such as daylight savings time boundaries. If you need intervals based
on local clock time, use Noon( ) and Bod( ) functions.

PI Server Applications User Guide 49

PI Performance Equations Syntax and Functions Reference

• Relative and combined time expressions contain only a single operator: either a single
plus sign (+) or a single minus sign (-). If you add additional operators, you get
unpredictable results. For example, the following are not valid time expressions:
'*+1d+4h'
'T-1d+12h'

TIMES AS STRINGS
You can also pass a time expression as a string to a function that expects a string. In this case,
enclose the time expression in double quotes, rather than single quotes.

PERFORMANCE EQUATIONS TIME SYNTAX REFERENCE

The following table shows PI time syntax examples.
Description Code Example Description
Now * * Now—current time
Midnight at specified dd 25 Midnight the 25th of the
date and current current month
month
Midnight at specified dd-mmm-yy 25-aug-02 Midnight on August 25th
date 2002
Specified time at dd-mmm-yy hh:mm:ss 25-aug-02 Noon on August 25th 2002
specified date 12:00:00

Specified hour at h: 8: 8:00 at current date

current date
Specified hour and dd h: 25 8: 8:00 on the 25th day of the
day of current month, current month
year and minute
Today at 00:00:00 t t+7h Today at 7 A.M.
Yesterday at y y+15h Yesterday at 3 P.M
00:00:00
Day of the week at sat,sun,mon,tue,wed, mo+6.5h Monday at 6:30 A.M.
00:00:00 thu,fri

Time interval (days) #.#d 1.3d 1.3 days

Time interval (hours) #.#h 1.5h One hour and a half
Time interval #.#m 32m 32 minutes
(minutes
Time interval #.#s 49s 49 seconds
(seconds)

Function Operands
The PE Scheduler provides built-in functions that perform a variety of operations. You can
use any of these functions as an operand in a Performance Equation.

50
 Performance Equation Syntax

Numbers and Strings as Digital States

Digital state values consist of a state set specifier and a state number within that set. Each set
has a list of text names for the states. You can set a digital point with an expression that
results in either a number (specifying the offset) or a string (specifying the state name).

COMPARING THE VALUE OF DIGITAL AND NUMERIC POINTS TO STRINGS

In Performance Equations, you can use expressions that compare the value of a digital or
numeric point to a string. For example, if the string "Run" is in the state set for digital point
PumpStatTag, then the following expression is valid:
If 'PumpStatTag' <> "Run" then 1 else 0

The state set for a numeric point is the System State Set. The System State Set is the default
state set for all points and it contains a collection of all the states that any point can use, such
as Shutdown, Over Range, and I/O Timeout. For example, the following expression is true
if the numeric point sinusoid contains the digital state Shutdown from the System Digital
State Set.
'sinusoid' = "Shutdown"

COMPARING A DIGITAL STATE TO A STRING POINT

If you want to compare a digital state to a string point, use the DigState function to convert a
string to a digital state explicitly. For example, the following are different:
If 'StringTag' = "Shutdown" then 0 else 1
If 'StringTag' = DigState("Shutdown") then 0 else 1

The former is true if the string point contains the string "Shutdown" while the latter is true if
the point contains the digital state Shutdown.

SETTING THE DIGITAL STATE FOR A NUMERIC OR DIGITAL POINT

You can use a string to set the digital state for a numeric or digital point. When you do this,
PE Scheduler looks first in that point's state set for a state that corresponds to the string. If the
state does not exist in the point's state set, PE Scheduler searches the System Digital State Set
for the state string. If PE Scheduler cannot find the state string in either the Digital State Set
for that point or in the System Digital State Set, it returns Calc Failed. The state set for a
numeric point is the System Digital State Set.

Performance Equation Operators

You use Performance Equation operators in Performance Equation expressions to act on

operands such as tagnames, numbers, and time expressions. Operator priority works basically
as it does in math—multiplication and division are performed before addition and subtraction,
and so on. You can also use parentheses to group operations, just as you do in math. For a
complete explanation of operator priority, see Operator Priority (page 56).
The following table lists all the Performance Equation operators, according to type. A, B, C,
and D are all operands.

PI Server Applications User Guide 51

PI Performance Equations Syntax and Functions Reference

Type Operator Syntax Example Meaning

Arithmetic + A + B Addition: A + B
- A - B Subtraction: A minus B
* A * B Multiplication: A times B
/ A / B Division: A divided by B
^ A ^ B Raising to a power: A to the power of B (AB)
Mod A mod B Modulus: the remainder of A divided by B
Relational < A < B Less than: returns true if A is less than B
= A = B Equal to: returns true if A equal to B
> A > B Greater than: returns true if A is greater than B
<= A <= B Less than or equal to: returns true if A is less than or equal
to B
<> A <> B Not equal to: returns true if A is not equal to B
>= A >= B Greater than or equal to: returns true if A is greater than or
equal to B
Prefix Not NOT A Complementation: returns true if A is 0 and False otherwise
- - A Negation (as prefix operator): returns the negative of A
Conjunction, And A and B Conjunction: returns true if operands A & B both evaluate to
Disjunction true. If both A and B are integers, returns the result of a
and Inclusion bitwise AND operation.
Or A or B Inclusive disjunction: returns true if either operand A or
operand B evaluates to true. If both A and B are integers,
returns the result of a bitwise OR operation.
in .. A in B..D Membership in a range: returns true if the value of A is
between B and D
in ( ) A in (B1, B2, Membership in a discrete set: returns true if the value of A
…BN) matches any of the values enclosed in the parentheses.
If-Then-Else if then if A then B else If-then-else expression: returns B if A is true—otherwise it
Expressions else D returns D

Arithmetic Operators
Performance Equation operators include the following simple arithmetic operators:
Operator Meaning
+ Addition
- Subtraction
* Multiplication
/ Division
^ Raising to a power
mod Modulus

52
 Performance Equation Syntax

Note: The mod operator returns the remainder after its left operand is divided by its right
operand. For example, 17 mod 3 equals 2.

For a complete list, see Performance Equation Operators (page 51).

Arithmetic Operations on Time Values

You can perform certain arithmetic operations on times, such as adding two time expressions,
or subtracting one absolute time expression from another. The result of the operation is one of
the following:
• Timestamp: A date and time in the PI timestamp format. For example: 25-aug-02
12:00:00
• Period: A number of seconds.
• Number
The following table shows valid operations and results, where N represents a number, T
represents an absolute or combined time expression, and P represents a period.
Operator Expression Result Example

+ T + P T '*' + '+3h'

T + N T '*' + 10
P + N P ('t'- 'y') + 10
P + P P ('t'- 'y') + ('t'-'y')

- (infix) T - P T '*' - '+3h'

T - N T '*' - 10
T - T P 't' - 'y'
P - N P ('t'- 'y') - 10
P - P P ('t'- '*') - ('t'-'y')

* P * N P ('t' -'y') * 5
N * P P 5 * ('+1d' -'+1h')

/ P / P N ('t'- '*') / ('t'-'y')

P / N P ('t'- '*') / 2
N / P N 2 / ('t'- '*')

mod T mod P T (see note) '*' mod ('*'-'t')

T mod N T (see note) '*' mod 2

P mod P P ('*'-'y') mod ('*'-'t')

P mod N P ('*'-'y') mod 3

- (prefix) -P P -('*'-'y')

PI Server Applications User Guide 53

PI Performance Equations Syntax and Functions Reference

Note: The timestamp returned is the result of T mod P or T mod N added to January 1,
1970 Universal Coordinate Time (UTC). So depending on the time zone, different
results are expected; in some case, even an error value is returned. In PI for
OpenVMS systems, the use of T mod P or T mod N returns P.

Relational Operators
A relational operator returns a value of 0 for false or 1 for true. You can use these operators
to compare numbers, times, digital states, or character strings. With relational operators, you
can compare bad values, or values of different types without generating an error. The
relational operators in Performance Equations are:
Operator Meaning
< Less than
= Equal to
> Greater than
<= Less than or equal to
<> Not equal to
>= Greater than or equal to

Comparing Bad Values

If you're comparing two operands of the same type, and one or both operands has a bad value,
the expression returns 0, rather than an error value.

Comparing Operands of Different Types

When you use the <> operator to compare any two operands of different types, the expression
always returns a 1 (that is, true). When you use any other relational operator (anything except
<>) to compare two operands of different types, the expression returns a 0 (that is, false)
except in the following cases:
• If one of the two operands is the digital type, then the Performance Equation Scheduler
compares the digital operand to the digital state of the other operand, if it exists. For
example:
'sinusoid' = DigState("Shutdown")

• If the sinusoid point has a digital state Shutdown, then this expression returns a value of
1 (that is, true). Otherwise, it returns a value of 0 (that is, false)
• If one of the two operands is the string type and the other is neither digital nor string type,
then the Performance Equation Scheduler compares the string operand to the digital state
of the other operand, if it exists. This allows the string substitution of its corresponding
digital state; that is, Shutdown and DigState("Shutdown") would be the same.

54
 Performance Equation Syntax

Time Comparisons
You can perform all comparisons, including in, on times.
'*+20m' >= '*+300s'
PrevEvent('tag1', '*') > PrevEvent('tag2', '*')

If a comparison is true, the result is 1; otherwise, it is 0.

Prefix Operators
A prefix operator is simply an operator that appears to the left of its operand, for example, "-
x".

Operator Meaning
- Negation
Not Complementation: Returns 1 if operand is 0 (or rounding to 0) and 0 otherwise

The expression following a prefix operator should be numeric. If you use a tagname as the
operand, make sure that the point returns a number. Note too, that even points that typically
return a number, sometimes return a digital state, such as Shutdown. Valid examples include:
-3
Not 7
-TagVal ('sinusoid')
Not Cos('ba:level.1')
-StateNo('DigitalTag')
Not TagBad('StringTag'))

The last two examples use digital and string points (DigitalTag and StringTag) but these are
used as arguments to functions that return numbers (StateNo and TagBad).

Conjunction, Disjunction, and Inclusion Operators

Operator Meaning Returns
and Conjunction True if operands A and B both evaluate to true. If
both A and B are integers, returns the result of a
bitwise AND operation.
or Inclusive disjunction True if either operand A or operand B evaluates to
true. If both A and B are integers, returns the result
of a bitwise OR operation.
in .. Membership in a range 1 if true and 0 if false
in ( ) Membership in a discrete set 1 if true and 0 if false

Inclusion Operator Examples

The following are two examples that use inclusion operators.
If 1 in 0 .. 2 Then 1 Else 0

The result is 1, since 1 is between 0 and 2.

If 1 in (0, 2) Then 1 Else 0

The result is 0, since 1 does not equal either 0 or 2.

PI Server Applications User Guide 55

PI Performance Equations Syntax and Functions Reference

Using the Inclusion Operator with Digital State Functions

You can use the in .. operator with functions that return digital states, in which case the
operator uses the offset within the Digital State Set for comparison. The digital states must all
be in the same Digital State Set. Lexical comparisons are made with character strings.

Time Comparisons
You can use the Inclusion operators (in.., in()) on time expressions. If the comparison is
true, the result is 1; otherwise, it is 0.

If-Then-Else Expressions
The if-then-else operator is a compound operator whose operands are used as follows:
if expr0 then expr1 else expr2

where expr0, expr1, and expr2 are expressions. If expr0 is true (nonzero), this operator
returns the value of expr1; if expr0 is false (zero), it returns the value of expr2.
Here are some examples:
if 'tag1' > 50 then "overlimit" else "good"
if 'tag1'= 1 then Sin('tag2') else if 'tag1'= 2 then Cos('tag2')
else Tan('tag2')
if 'tag3'<> "shutdown" then (if 'tag1' > 'tag2' then 'tag1' else
'tag2') else "error"
'*' + (if 'tag2' = 0 then 3600 else 0)

Note: You must include the if, the then, and the else. Nested operations are supported.

Operator Priority

The Performance Equation Scheduler executes operators in order of priority, from highest to
lowest. When multiple operators have the same priority, the order of execution is either from
left-to-right or right-to-left, depending on the operator, as listed in the following table.
Operator Priority Order
- (prefix) 9 (done first) L-R
^ 8 R-L
Not 7 L-R
* 6 L-R
/
mod
+ 5 L-R
-

56
 Performance Equation Syntax

Operator Priority Order

< 4 L-R
=
>
<=
<>
>=
in .. 3 L-R
in( )
And 2 L-R
Or 1 (done last) L-R

Note: The Not operator has a priority between ^ and *. This differs from conventional
priority schemes.

You can use parentheses to affect the order of calculation. Regardless of operator priority,
operations within parentheses are evaluated before operations outside those parentheses. For
example:
(2 + 3) * 5 equals 25

while
2 + 3 * 5 equals 17

Data Types

The Performance Equation Scheduler recognizes these data types:

• Number
• Character string
• Tagname
• Time
• Period
Every variable has one of these data types; every function returns one of these data types. The
PE Scheduler cannot typically use one data type where another is expected. For example, you
cannot add two character strings, or multiply two times together. Additionally, the built-in
functions might require particular data types for particular arguments.

PI Server Applications User Guide 57

PI Performance Equations Syntax and Functions Reference

Type Checking
At compile time, the Performance Equation Scheduler checks type compatibility as far as
possible. This process catches some errors, such as trying to add a number to a character
string.
However, not all type compatibility errors can be detected at compile time. The expression
'sinusoid' / 2.0

works well if sinusoid has a numeric value, but if sinusoid is equal to the digital state
Shutdown the expression returns an error (Calc Failed).

Note: Comparisons (expressions using relational operators) are an exception to this

rule. Every comparison is valid, regardless of its operand types.

Error Values

When the PE Scheduler cannot perform a calculation during runtime, it returns the error value
Calc Failed. Error values propagate through most calculations. For example, an error value
plus one is an error value. Exceptions to this rule are:
• The BadVal and Concat functions
• The relational operators when a value of 0 is returned
To check for compile time errors on Windows-based computers, check the pipc.log file
located in the \pipc\dat\ directory.

Test the Performance Equation Syntax

The pipetest utility is a command line function that checks the syntax of a Performance
Equation. There is also an System Management Tool (SMT) plug-in to test a performance
equation (see the SMT documentation for details). It can operate interactively, take its input
from a file or check the extended descriptor of a point.

Run the pipetest Utility

The pipetest utility is located in the pi\adm directory. To start pipetest, open a command
window, change to the pi\adm directory, and type a pipetest command. For a complete list
of pipetest commands, type:
pipetest -?

The pipetest utility is limited to equations that are 4095 characters or less and you can not
use it to test dynamic response functions.

58
 Performance Equations Functions

Using pipetest in Interactive Mode

To run the pipetest utility interactively from a command prompt window, open a command
window, change to the pi\adm directory and enter:
pipetest

At the pipetest equation prompt, type in the equation you want to test. If the equation syntax
is not valid, pipetest displays a syntax error. If the syntax is valid, pipetest displays the result
of the equation.

Using pipetest in File Input Mode

You can also put one or more performance equations in a simple text file, and pass the entire
file to pipetest using the -f switch. In the text file, you put each equation on a single line. You
can include comment lines by beginning the line with an exclamation mark (!).
Here's the text from an example pipetest file, called peTestEquations.txt:
! test calculation for point A
if BadVal('sinusoid') then 0 else ('sinusoid')/25
! test calculation for point B
TimeLT('sinusoid', 'y' , 't', TagVal('sinusoid', '*'))

To test the equations in the file, type:

pipetest -f peTestEquations.txt

Each input line in turn is echoed and the evaluated result is displayed.

Performance Equations Functions

In addition to all the basic arithmetic operators, the Performance Equation Scheduler provides
a large number of built-in functions that you can use to perform more complex operations,
such as taking the sine or cosine of a point value, taking the average of a tag's value over
time, and so on.

Function Arguments

Functions have one or more arguments, or inputs, which are enclosed in parenthesis
following the function name. Some of the arguments may be optional. If there are several
arguments, they are separated by commas:
functionName(argument1, argument2, argument3)

The following are examples of function expressions:

Max(3, 5, 12.6, 'sinusoid')

PrevEvent('sy:arc001', '*-2h')

Sqr(Abs(TagMax('tag', 'y', 't')))

PI Server Applications User Guide 59

PI Performance Equations Syntax and Functions Reference

Log(if 'tag'=2 then .5 else .2)

Functions can also be nested and joined in expressions:

Avg(TagVal('TagA', 'y'), TagVal('TagB', 'y'), TagVal('TagC', 'y')
)
if TagVal('TagA', '*') < TagVal('TagB', '*') then sin('TagB')
else sin('TagA')

You can use a tagname in any argument where a number or character string is called for. A
tagname in single quotes is evaluated as if it had been written TagVal(tagname), which
is the same as TagVal('tagname', '*' ). This gets the point's value at the "current"
time for the calculation.
If the argument calls for a number, but the point's value is a digital state when the function is
evaluated, a run-time error (Calc Failed) is generated.

Built-in Functions
The PE Scheduler provides a wide range of built-in functions that make it easier for you to
perform calculations on PI data. (You can also use Steam Table Functions in Performance
Equations.)
The following tables provide a complete listing of all built-in Performance Equation
functions.

Functions Listed By Type

The following tables list all functions by type.

Math Functions

Name Description
Abs Absolute value
Asin Arc sine
Acos Arc cosine
Atn Arc tangent
Atn2 Arc tangent (two arguments)
Cos Cosine
Cosh Hyperbolic cosine
Exp Exponential
Float Conversion of string to number
Frac Fractional part of number
Int Integer part of number
Log Natural logarithm
Log10 Common logarithm

60
 Built-in Functions

Name Description
Poly Evaluate polynomial
Round Round to nearest unit
Sgn Numerical sign
Sin Sine
Sinh Hyperbolic sine
Sqr Square root
Tanh Hyperbolic tangent
Tan Tangent
Trunc Truncate to next smaller unit

Aggregate Functions

Name Description
Avg Average
Max Maximum
Median Median selector
Min Minimum
PStDev Population standard deviation
SStDev Sample standard deviation
Total Sum

Miscellaneous Functions

Name Description
BadVal See if a value is bad (not a number or time)
Curve Get value of a curve
DigState Get digital state from a string
IsDST Test whether a time is in local daylight savings time period
IsSet Test if a PI value is annotated, substituted, or questionable
StateNo The code number of a digital state
TagBad See if a point has an abnormal state

PI Archive Retrieval

Name Description
NextEvent Time of a point's next Archive event
NextVal Point's next value after a time
PrevEvent Time of a point's previous Archive event
PrevVal Point's previous value before a time
TagVal Point's value at a time

PI Server Applications User Guide 61

PI Performance Equations Syntax and Functions Reference

PI Archive Search

Name Description
FindEq Timestamp when point = value
FindGE Timestamp when point >= value
FindGT Timestamp when point > value
FindLE Timestamp when point <= value
FindLT Timestamp when point < value
FindNE Timestamp when point ~= value
TimeEq Total period when point = value
TimeGE Total period when point >= value
TimeGT Total period when point > value
TimeLE Total period when point <= value
TimeLT Total period when point < value
TimeNE Total period when point ~= value

PI Archive Statistics

Name Description
EventCount Number of Archive events
PctGood Percent of good time in a period
Range Range of minimum to maximum value
StDev Time-weighted standard deviation
TagAvg Time-weighted average
TagMean Event-weighted average
TagMax Maximum value in a period
TagMin Minimum value in a period
TagTot Time integral over a period

Point Attributes

Name Description
TagDesc Get a point's descriptor
TagEU Get a point's engineering unit string
TagExDesc Get a point's extended descriptor
TagName Get a point's name
TagNum Get a point's ID
TagSource Get a point's point source string
TagSpan Get a point's span
TagType Get a point's type character
TagTypVal Get a point's typical value

62
 Built-in Functions

Name Description
TagZero Get a point's zero value

Time Functions

Name Description
Bod Timestamp for beginning of the day for given time
Bom Timestamp for beginning of the month for given time
Bonm Timestamp for first of the next month for given time
Day Day of the month from a time
DaySec Seconds since midnight from time
Hour Hour from a time
Minute Minute from a times
Month Month from a time
Noon Timestamp for local noon of day of a times
ParseTime Convert character string to time
Second Second from a times
Weekday Day of the week from a times
Year Year from a time
Yearday Day of the year from a time

Dynamic Response

Name Description
Arma Dynamic response from Auto Regressive Moving Average model
Delay Introduce time delay
MedianFilt Select the median value of time series
Impulse Dynamic response characterized by impulse response shape

Alarm Status Functions

Name Description
AlmAckStat Alarm acknowledgment status code
AlmCondition Condition code number for Alarm State
AlmCondText Alarm condition as text
AlmPriority Alarm priority number

String Functions

Name Description
Ascii ASCII character code for a character
Char String for ASCII character code(s)
Compare Wild comparison of two strings

PI Server Applications User Guide 63

PI Performance Equations Syntax and Functions Reference

Name Description
DigText Text for a digital state
Format Formatting of a numerical number
InStr Instance of a sub-string
LCase Conversion of all characters to lower case
Len Length of a string
Left First characters in a string
LTrim Removal of blanks on the left side of a string
Mid Extraction of a sub-string from a string
Right Last characters in a string
RTrim Removal of blanks on the right side of a string
Trim Removal of blanks on both sides of a string
UCase Conversion of all characters to upper case

String Conversion

Name Description
Concat Concatenate two or more strings
String String representing any PI value
Text Concatenation of strings for a series of PI value arguments

Functions Listed Alphabetically

Name Description
Abs Absolute value
Acos Arc cosine
AlmAckStat Alarm acknowledgment status code
AlmCondition Condition code number for Alarm State
AlmCondText Alarm condition as text
AlmPriority Alarm priority number
Arma Dynamic response from Auto Regressive Moving Average model
Ascii ASCII character code for a character
Asin Arc sine
Atn Arc tangent
Atn2 Arc tangent (two arguments)
Avg Average
BadVal See if a value is bad (not a number or time)
Bod Timestamp for beginning of the day for given time

64
 Built-in Functions

Name Description
Bom Timestamp for beginning of the month for given time
Bonm Timestamp for first of the next month for given time
Char String for ASCII character code(s)
Compare Wild comparison of two strings
Concat Concatenate two or more strings
Cos Cosine
Cosh Hyperbolic cosine
Curve Get value of a curve
Day Day of the month from a time
DaySec Seconds since midnight from time
Delay Introduce time delay
DigState Get digital state from a string
DigText Text for a digital state
EventCount Number of Archive events
Exp Exponential
FindEq Timestamp when point = value
FindGE Timestamp when point >= value
FindGT Timestamp when point > value
FindLE Timestamp when point <= value
FindLT Timestamp when point < value
FindNE Timestamp when point ~= value
Float Conversion of string to number
Format Formatting of a numerical number
Frac Fractional part of number
Hour Hour from a time
Impulse Dynamic response characterized by impulse response shape
InStr Instance of a sub-string
Int Integer part of number
IsDST Test whether a time is in local daylight savings time
IsSet Test if a PI value is annotated, substituted, or questionable
LCase Conversion of all characters to lower case
Len Length of a string
Left First characters in a string
Log Natural logarithm
Log10 Common logarithm
LTrim Removal of blanks on the left side of a string
Max Maximum

PI Server Applications User Guide 65

PI Performance Equations Syntax and Functions Reference

Name Description
Median Median selector
MedianFilt Select the median value of time series
Mid Extraction of a sub-string from a string
Min Minimum
Minute Minute from a time
Month Month from a time
NextEvent Time of a point's next Archive event
NextVal Point's next value after a time
Noon Timestamp for local noon of day of a time
ParseTime Convert character string to time
PctGood Percent of good time in a period
Poly Evaluate polynomial
PrevEvent Time of a point's previous Archive event
PrevVal Point's previous value before a time
PStDev Population standard deviation
Range Range of minimum to maximum value
Right Last characters in a string
Round Round to nearest unit
RTrim Removal of blanks on the right side of a string
Second Second from a time
Sgn Numerical sign
Sin Sine
Sinh Hyperbolic sine
Sqr Square root
SStDev Sample standard deviation
StateNo The code number of a digital state
StDev Time-weighted standard deviation
String String representing any PI value
TagAvg Time-weighted average
TagBad See if a point has an abnormal state
TagDesc Get a point's descriptor
TagEU Get a point's engineering unit string
TagExDesc Get a point's extended descriptor
TagMax Maximum value in a period
TagMean Event-weighted average
TagMin Minimum value in a period
TagName Get a point's name

66
 Performance Equations Functions Reference

Name Description
TagNum Get a point's ID
TagSource Get a point's point source string
TagSpan Get a point's span
TagTot Time integral over a period
TagType Get a point's type character
TagTypVal Get a point's typical value
TagVal Point's value at a time
TagZero Get a point's zero value
Tan Tangent
Tanh Hyperbolic tangent
Text Concatenation of strings for a series of PI value arguments
TimeEq Total period when point = value
TimeGE Total period when point >= value
TimeGT Total period when point > value
TimeLE Total period when point <= value
TimeLT Total period when point < value
TimeNE Total period when point ~= value
Total Sum
Trim Removal of blanks on both sides of a string
Trunc Truncate to next smaller unit
UCase Conversion of all characters to upper case
Weekday Day of the week from a time
Year Year from a time
Yearday Day of the year from a time

Performance Equations Functions Reference

Abs

Return the absolute value of an integer or real number.

Format
Abs(x)

Arguments
x

Must be an integer or real number.

PI Server Applications User Guide 67

PI Performance Equations Syntax and Functions Reference

Returns
The absolute value of x.

Exceptions
If x is not an integer or real number, returns an error value.

Examples
Abs(1)
Abs(-2.2)
Abs('tag1')
Abs('tag1'- 'tag2')

Acos

Return the inverse (or arc) cosine of an integer or real number. The inverse cosine of x is the
angle in radians whose cosine is equal to x.

Format
Acos(x)

Arguments
x

Must be a real number between -1.0 and 1.0, inclusive.

Returns
The inverse cosine of x, in radians.

Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value.

Examples
Acos(1-.5)
Acos(-.5)
If 'tag1' < 1 and 'tag1' > -1 then Acos('tag1') else 0

See Also
Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page 82), Sin (page 122),
Sinh (page 122), Tan (page 140), Tanh (page 141)

68
 Performance Equations Functions Reference

AlmAckStat

Return the acknowledgment status code for an alarm point.

Format
AlmAckStat(alm)

Arguments
alm

An alarm tagname.

Returns
The acknowledgement status code for the given Alarm State. Possible values are:
0 - acknowledged (or no alarm)
1 - unacknowledged
2 - missed alarm

Exceptions
If the argument is not a digital state tagname, an error condition is returned.

Examples
AlmAckStat('alarmtag')

See Also
AlmCondition (page 69), AlmCondText (page 70), AlmPriority (page 71)

AlmCondition

Returns the condition code for an Alarm State.

Format
AlmCondition(alm)

Arguments
alm

An alarm tagname.

PI Server Applications User Guide 69

PI Performance Equations Syntax and Functions Reference

Returns
The code number of the condition for the alarm tagname.

Exceptions
If the argument is not a digital state tagname, an error is returned.

Examples
AlmCondition('alarmtag')

See Also
AlmAckStat (page 69), AlmCondText (page 70), AlmPriority (page 71)

AlmCondText

Return the string for the condition of an Alarm State.

Format
AlmCondText(alm)

Arguments
alm

An alarm tagname.

Returns
The condition text for the condition represented by the alarm status.

Exceptions
If the argument is not a digital state tagname, an error condition is returned.

Examples
AlmCondText('alarmtag')

See Also
AlmAckStat (page 69), AlmCondition (page 69), AlmPriority (page 71)

70
 Performance Equations Functions Reference

AlmPriority

Return the priority of an Alarm State.

Format
almPriority(alm)

Arguments
alm

A digital state value from a PI Alarm State Set.

Returns
The priority of the given alarm. Priorities are small positive integers. Priority 0 is an alarm
that is never unacknowledged.

Exceptions
If the argument is not from a valid Digital State Set for alarms, an error condition is returned.

Examples
almPriority('alarmtag')

almpriority(digstate("__ Lolo"))

See Also
AlmAckStat (page 69), AlmCondition (page 69), AlmCondText (page 70)

Arma

Calculate dynamic response for Auto Regressive Moving average model as shown in
Examples (page 72).

Format
Arma(in, runflag, (a1, a2, … aN),(b0, b1, b2, … bN))

PI Server Applications User Guide 71

PI Performance Equations Syntax and Functions Reference

Arguments
The denominator and numerator coefficient series are enclosed in parenthesis with a comma
between the two. There must be only one more term (b0) in the numerator than denominator.
Both in and runflag may be any expression that evaluates to a number.
in

Must be an integer or real number.

runflag

Non-zero enables filter to run.

a1, a2, ...

Coefficients of past output terms.

b0, b1, b2 ...

Coefficients of the present and past input terms of the model.

Returns
The next output value in time series response to past and present input.
ut = a1 * ut-1 + a2 * ut-2 + … + an * ut-n + b0 * yt +
b1 * yt-1 + b2 * yt-2 + … + bn * yt-n

Where ut is model output at time t, now. ut-1 is output one sample interval in the past. yt is
the input signal at time t. If runFlag expression result is 0, the model is reset. Depending on
the number of coefficients used, Arma stores the inputs and outputs until an evaluation of the
model is available. For example, in
Arma( 'input_tag', 1, ( 0. ,1), ( 1, -1 ,1))

Arma stores two previous values of the input and output. Hence when the point is first
created, no good results are returned until two prior values of the input are stored. From then
on, the two most current previous values are stored.

Exceptions
Arma gives different results depending on which type of scheduling is used. In scan class
scheduling, the interval between time series values depends on the scan class and gives values
at evenly spaced time intervals. On the other hand, event based scheduling is dependent on a
trigger from another point. If the exception deviation is not zero, the intervals for events are
not evenly spaced in time and hence Arma gives results that are not trustworthy. Arma is not
supported in the pipetest utility or in PI DataLink. If the input point is not a real number or
integer, Arma returns an error.

Examples
Derivative: Arma('input_tag', 1, (0.), (1, -1))
Integration: Arma('input_tag', 1, (1.), (.05, 0.))
Second order filter: Arma('input_tag', 1, (.25,.25), (.1,.25,.15
))

72
 Performance Equations Functions Reference

Ascii

Return the ASCII character code of the first character of a string.

Format
Ascii(String)

Arguments
string

Any expression evaluating to a string.

Returns
The character code of the first character of the string.

Exceptions
If the argument is not a string, an error value is returned.

Examples
Ascii( "D" ) = 68
Ascii( string('cdm158' ) )

PI Server Applications User Guide 73

PI Performance Equations Syntax and Functions Reference

Asin

Return the inverse (or arc) sine of a number. The inverse sine of x is the angle in radians
whose sine is equal to x.

Format
Asin(x)

Arguments
x

Must be a real number between -1.0 and 1.0, inclusive.

Returns
The inverse sine of x, in radians.

Exceptions
If x is not a number, or is less than -1.0 or greater than 1.0, returns an error value.

Examples
Asin(TagVal('tag1','y'))
Asin(-0.5)
Asin('tag1')

See Also
Acos (page 68), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page 82), Sin (page
122), Sinh (page 122), Tan (page 140), Tanh (page 141)

Atn

Return the inverse (or arc) tangent of an integer or real number. The inverse tangent of x is
the angle in radians whose tangent is equal to x.

Format
Atn(x)

Arguments
x

Must be an integer or real number.

74
 Performance Equations Functions Reference

Returns
The inverse tangent of x, in radians.

Exceptions
If x is not an integer or real number, returns an error value.

Examples
Atn(1)
Atn(-2.2)
Atn('tag1')
Atn('tag1'- 'tag2')

See Also
Acos (page 68), Asin (page 74), Atn2 (page 75), Cos (page 81), Cosh (page 82), Sin (page
122), Sinh (page 122), Tan (page 140), Tanh (page 141)

Atn2

Calculate the inverse (or arc) tangent of a pair of numbers, which represent a point on the
plane. If you draw a line between the point whose Cartesian coordinates are (a, b) and the
origin, the angle between that line and the x-axis is the inverse tangent of (a, b).

Format
Atn2(a, b)

Arguments
a

Must be an integer or real number.

b

Must be an integer or real number.

Returns
The inverse tangent of (a, b), in radians.

Exceptions
If a or b is not an integer or real number, returns an error value.

PI Server Applications User Guide 75

PI Performance Equations Syntax and Functions Reference

Examples
Atn2(TagVal('tag1','y'),TagVal('tag1', 'y'))
Atn2(1,1)
Atn2('tag1', 'tag2')

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Cos (page 81), Cosh (page 82), Sin (page 122),
Sinh (page 122), Tan (page 140), Tanh (page 141)

Avg

Return the average of all the arguments.

Format
Avg(x1, x2, ..., xn)

Arguments
x1...xn

May be numbers, times, or periods but all must be the same data type.

Returns
The average of the arguments. The result is the same data type as the operands.

Exceptions
Arguments whose run-time values are character strings or digital states are not included in the
average. If all values are character strings or digital states, Avg returns an error value.

Examples
Avg(TagVal('tag1','y'),TagVal('tag1', 'y'),1,2)
Avg('y', 't', '14-Dec-97', '14 8:00')
Avg('tag1', 'tag2')

Badval

Test a value to see if it is bad. For real and integer points, a bad value is a digital state value.
For Digital points, a bad value is a digital state value outside its own Digital State Set.

76
 Performance Equations Functions Reference

Format
Badval(x)

Arguments
x

A value to be tested.

Returns
1 if the value is bad
0 if the value is not bad

Exceptions
Returns 1 for blob points. Returns 0 for character strings.

Examples
BadVal('tag1')
BadVal('digitaltag')
BadVal(TagVal('stringtag', '14-Dec-97 8:00:00'))

Bod

Gets the timestamp for midnight at the start of a day.

Format
Bod(time)

Arguments
time

A time expression.

Returns
Timestamp for the start of the day.

Exceptions
None.

PI Server Applications User Guide 77

PI Performance Equations Syntax and Functions Reference

Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.

Examples
Bod('*')
Bod('y')
Bod(FindEq('tag1', '14-Dec-06', '+17d',50))

See Also
Bom (page 78), Bonm (page 79), Noon (page 111)

Bom

Gets the timestamp for midnight at the beginning of the month.

Format
Bom(time)

Arguments
time

A time expression.

Returns
Timestamp for the start of the month.

Exceptions
None.

Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.

Examples
Bom('*')
Bom(PrevEvent('tag', '*'))
Bom(FindEq('tag1', '14-Dec-97', '+17d',50))

78
 Performance Equations Functions Reference

See Also
Bod (page 77), Bonm (page 79), Noon (page 111)

Bonm

Gets the timestamp for midnight at the beginning of the next month.

Format
Bonm(time)

Arguments
time

Time expression.

Returns
Timestamp for the start of the next month.

Exceptions
None.

Usage Note
This function is useful for establishing a time at a unique clock time independent of the
length of particular days.

Examples
Bonm('*')
Bonm('y')
Bonm(FindEq('tag1', '14-Dec-97', '+17d',50))

See Also
Bod (page 77), Bonm (page 79), Noon (page 111)

Char

Build a string from ASCII character codes.

PI Server Applications User Guide 79

PI Performance Equations Syntax and Functions Reference

Format
Char( n1 [, n2, … ] )

Arguments
n1, n2, ...

Numeric numbers or expressions.

Returns
A string built from the character codes.

Exceptions
If an argument is not a number, returns an error.

Examples
Char(65) = "A"
Char(80, 73) = "PI"
Char(6 * 9) = "6"

Compare

Compare two strings with wild characters ("*" and "?").

Format
Compare(str1, str2 [,casesen])

Arguments
str1, str2

Strings. Str2 may contain wild characters.

casesen

Optional flag indicating if the comparison is case sensitive. If 0 (the default), the comparison
is case-insensitive. If 1, the comparison is case-sensitive.

Returns
1 if Str1 = Str2
0 otherwise

80
 Performance Equations Functions Reference

Exceptions
Wild characters in str1 are not treated as wild.

Examples
compare("?","a") = 0
compare("What","wh") = 0
compare("What","wha?") = 1
compare("What","wh*") = 1
compare("What","wh*", 1) = 0

Concat

Concatenate two or more strings.

Format
Concat(s1, s2, ..., sn)

Arguments
s1...sn

Must be character strings, or expressions yielding character strings.

Returns
The character strings, concatenated together. This function does not insert blanks between its
arguments. If you need blanks, you must add them yourself.

Note: Consider using Text (page 141), which is more general and more precise in many
cases than Concat.

Examples
Concat("shut", "down") = "shutdown"

Cos

Return the trigonometric cosine of an integer or real number.

Format
Cos(x)

PI Server Applications User Guide 81

PI Performance Equations Syntax and Functions Reference

Arguments
x

Must be an integer or real number, which represents an angle in radians.

Returns
The cosine of x.

Exceptions
If x is not an integer or real number, returns an error value.

Examples
Cos('tag1')
Cos(1)
Cos(1.1)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cosh (page 82), Sin (page
122), Sinh (page 122), Tan (page 140), Tanh (page 141)

Cosh

Return the hyperbolic cosine of an integer or real number.

Format
Cosh(x)

Arguments
x

Must be an integer or real number.

Returns
The hyperbolic cosine of x.

Exceptions
If x is not an integer or real number, returns an error value.

82
 Performance Equations Functions Reference

Examples
Cosh('tag1')
Cosh(.9)
Cosh(1)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Sin (page 122),
Sinh (page 122), Tan (page 140), Tanh (page 141)

Curve

Returns the y value of a curve given the x value.

Format
Curve( x, (x1,y1) (x2,y2) … (xn,yn) )

Arguments
x

Expression evaluating to a number.

x1, y1

The first point on the curve. The xi's and yi's are numeric constants evaluated at compile time.
The values set for xi's must be in ascending order.

Returns
Returns the y value on the curve corresponding to the value of x. Linear interpolation is used
between points defining the curve. If the value of x is less than x1 then y1 is returned and if it
is greater than xn, yn is returned. The points are assumed to be ordered in the x direction
from smallest to largest.

Exceptions
If the value of x is not an integer or real number, an error value is returned.

Examples
curve('tag1', (0,100) (100,0) ) //inverter
curve('tag3', (25,25) (75,75) ) //limiter

Day

Extract the day of the month from a time expression.

PI Server Applications User Guide 83

PI Performance Equations Syntax and Functions Reference

Format
Day(time)

Arguments
time

A time expression.

Returns
The day of the month of time, in the range 1-31.

Exceptions
None.

Examples
Day('*')
Day('t')
Day(FindGt('tag1', '*-30d', '*',50))

See Also
DaySec (page 84), Hour (page 96), Minute (page 108), Month (page 109), Second (page 120),
Weekday (page 151), Year (page 152), Yearday (page 152)

DaySec

Extract the number of seconds since midnight from a time expression.

Format
DaySec(time)

Arguments
time

A time expression.

Returns
The number of seconds of time since midnight, in the range 0-86399.

84
 Performance Equations Functions Reference

Exceptions
None.

Usage Note
This function is the same as the Time function in the PI 2.x Performance Equation package.
For example, if the current time is 8:30 A.M., DaySec('*') returns 30600.

Examples
DaySec('*')
DaySec('t')
DaySec(FindGt('tag1', '*-30d', '*',50))

See Also
Day (page 83), Hour (page 96), Minute (page 108), Month (page 109), Second (page 120),
Weekday (page 151), Year (page 152), Yearday (page 152)

Delay

Delay line, the output tracks the input. For use in real time calculations, in pipeschd.exe
for example, this function might be a better choice than PrevVal (page 115).

Format
Delay( x, runflag, n )

Arguments
x

Must be an integer or real number.

runflag

Non-zero enables filter to run.

n

Length of the delay, integer.

Returns
The input signal delayed by n calculation intervals. For scan class scheduling, the calculation
interval is based on the scan class. For event based scheduling, the calculation interval is
dependent on the trigger and the exception deviation.

PI Server Applications User Guide 85

PI Performance Equations Syntax and Functions Reference

Exceptions
Delay is not supported in the pipetest utility or in PI DataLink. If the input point is not a real
number or integer, Delay returns an error. Delay returns Calc Failed until n scans have
elapsed after startup.

Examples
Delay('tag1',1,2)

DigState

Translate a character string representing a digital state into its corresponding digital state.

Format
DigState(s1 [, x])

Arguments
s1

A character string representing a digital state.

x

A digital point in which the character string represents a digital state. Optional. If omitted, all
Digital State Sets, starting with the System Digital Set, are searched for the given string.

Returns
A digital state

Exceptions
If the character string does not represent a digital state in the Digital State Set of the reference
digital point, the function returns Calc Failed. If digital point is omitted and character string
does not represent a digital state in any of the digital sets, Calc Failed is returned.

Examples
DigState("digitalstring", 'digitaltag')
StateNo(DigState("digitalstring", 'digitaltag'))

DigText

Obtain the text corresponding to the current digital state of a point.

86
 Performance Equations Functions Reference

Format
DigText(tagname)

Arguments
tagname

A tagname that represents a digital state variable.

Returns
The text for the digital state.

Exceptions
If the argument is not a digital state tagname, an error condition is returned.

Examples
DigText('alarmtag')
DigText('cdm158' )
DigText('nondigitaltag') would not compile and returns an error
message

EventCount

Find the number of Archive events for a point over a given time.

Format
EventCount(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point must represent a continuous variable.

starttime

A time expression representing the beginning of the time range to search.

endtime

A timestamp that is greater than starttime; the end of the time range to search.

Caution: When endtime is a future time (such as '*+1h'), TagCount might include the
system digital state No Data and thus is larger than the number of events stored
in the PI Archive. Avoid using a future time if possible.

PI Server Applications User Guide 87

PI Performance Equations Syntax and Functions Reference

pctgood

Optional. Minimum time percentage, over the given time range, that the point's archived
values must be good.

Returns
Number of Archive events for the point within the specified interval.

Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.

Examples
EventCount('tag1', 'y', '*')
EventCount('tag1', '14-Dec-97', '+1d',70)
EventCount('tag1', '14-Dec-97', '15-Dec-97')

Exp

Return the exponential of an integer or real number. This is the number ex, where e =
2.7182818...

Format
Exp(x)

Arguments
x

Must be an integer or real number.

Returns
The exponential of x.

Exceptions
If x is not an integer or real number, returns an error value.

Examples
Exp('tag1')
Exp(TagVal('tag1','14-Dec-97'))
Exp(11)

88
 Performance Equations Functions Reference

FindEq

Find the first time, within a range, when a point is equal to a given value.

Format
FindEq(tagname, starttime, endtime, value)

Arguments
tagname

A tagname enclosed in single quotes.

starttime

A time expression representing the beginning of the time range to search Relative times are
relative to endtime if endtime is not itself a relative time.
endtime

A time expression representing the end of the time range to search. Relative times are relative
to starttime if starttime is not itself a relative expression. If endtime is earlier than starttime,
the range is searched backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was equal to
the given value.

Exceptions
If the point was never equal to the given value, FindEq returns an error value.

Usage Note
FindEq interpolates between Archive events, if necessary, to find the value it is looking for.

Examples
FindEq('tag1', 't', '*',40.0)
FindEq('digitaltag', '-1d', '*', TagVal('digitaltag', '14-Dec-
97'))
FindEq('digitaltag', '14-Dec-97', '*', "On")

PI Server Applications User Guide 89

PI Performance Equations Syntax and Functions Reference

FindGE

Find the first or last time, within a range, when a point is greater than or equal to a given
value.

Format
FindGE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

A time expression representing the beginning of the time range to search or a time relative to
endtime, if endtime is a time.
endtime

A time expression representing the end of the time range to or a time (in seconds) relative to
starttime, if starttime is a time. If endtime is earlier than starttime, the range is searched
backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was greater
than or equal to the given value.

Exceptions
If the point was always less than the given value, FindGE returns an error value.

Usage Note
FindGE interpolates between archive events, if necessary, to find the value it is looking for.

Examples
FindGE('tag1', 't', '*',40.0)
FindGE('digitaltag', '-1d', '*', TagVal('digitaltag', '14-Dec-
97'))
FindGE('tag1', '-1d', '*','tag2')

90
 Performance Equations Functions Reference

FindGT

Find the first time, within a range, when a point is greater than a given value.

Format
FindGT(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

A time expression representing the beginning of the time range to search. Can be a time
relative to endtime if endtime is a time.
endtime

End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was greater
than the given value.

Exceptions
If the point was never greater than the given value, FindGT returns an error value.

Usage Note
FindGT interpolates between Archive events, if necessary, to find the value it is looking for.

Examples
FindGT('tag1', 't', '*',40.0)
FindGT('tag1', '-1d', '*',40.0)
FindGT('digitaltag', '-1d', '*', TagVal('digitaltag', 'y'))

FindLE

Find the first time, within a range, when a point is less than or equal to a given value.

PI Server Applications User Guide 91

PI Performance Equations Syntax and Functions Reference

Format
FindLE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search; time expression or time relative to endtime if endtime
is a time.
endtime

End of the time range to search, timestamp or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was less than
or equal to the given value.

Exceptions
If the point was always greater than the given value, FindLE returns an error value.

Usage Note
FindLE interpolates between Archive events, if necessary, to find the value it is looking for.

Examples
FindLE('tag1', 't', '*',40.0)
FindLE('tag1', -3600, '*',40.0)
FindLE('tag1', 'Saturday', '*',40.0)

FindLT

Find the first time, within a range, when a point is less than a given value.

Format
FindLT(tagname, starttime, endtime, value)

92
 Performance Equations Functions Reference

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search; time expression or time relative to endtime if endtime
is a time.
endtime

End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was less than
the given value.

Exceptions
If the point was never less than the given value, FindLT returns an error value.

Usage Note
FindLT interpolates between Archive events, if necessary, to find the value it is looking for.

Examples
FindLT('tag1', 't', 3600,40.0)
FindLT('tag1', -1h, '*',40.0)
FindLT('tag1', '14-Dec-97 01:00:00.0001, '*',40.0)

FindNE

Find the first time, within a range, when a point is unequal to a given value.

Format
FindNE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.

PI Server Applications User Guide 93

PI Performance Equations Syntax and Functions Reference

starttime

Beginning of the time range to search; time expression or time relative to endtime if endtime
is a timestamp.
endtime

End of the time range to search, time expression or time (in seconds) relative to starttime if
starttime is a time. If this time is earlier than starttime, the range is searched backwards.
value

Must be an integer or real number or digital state (character string), the value to search for.

Returns
The timestamp closest to starttime, within the given range, for which the point was unequal to
the given value.

Exceptions
If the point was always equal to the given value, FindNE returns an error value.

Examples
FindNE('tag1', 'y', '*',40.0)
FindNE('tag1', '14-Dec-97', '*',40.0)
FindNE('tag1', '14-Dec-97', 'Monday',40.0)

Float

Convert a string to a number.

Format
Float(x)

Arguments
x

A string or number.

Returns
A number for a numeric string and Calc Failed for a non-numeric string. If x is already a
number, x is returned.

94
 Performance Equations Functions Reference

Examples
Float(12.3) = 12.3
Float('sinusoid')
Float("-12.3") = -12.3

Format

Convert a number to string according to a format expression.

Format
Format(num, format [,num_type ])

Arguments
num

A number (real or integer).

format

Format-control string. This is the same as that used by the C language function Sprintf.
num_type

Optional. Number-type character. This must be either R(eal) or I(nteger). The default is R.

Returns
A formatted string.

Examples
Format('sinusoid', "%3.3f", "R") = "66.890"
Format(45, "%3.3d") = "045"
Format(45, "%3.3d", "I") = "045"
Format(45, "%3.3d", "R") = "000" (Don't do this!)

Frac

Returns the fractional part of a real number. Returns 0 for integers.

Format
Frac(x)

Arguments
x

Must be an integer or real number.

PI Server Applications User Guide 95

PI Performance Equations Syntax and Functions Reference

Returns
The fractional part of x.

Exceptions
If x is not an integer or real number, returns an error value.

Usage Note
By definition: Int(x) + Frac(x) = x.

Examples
Frac('tag1')
Frac(1.1)
Frac(TagVal('tag1', '14-Dec97'))

Hour

Extract the hour from a time expression.

Format
Hour(time)

Arguments
time

A time expression.

Returns
The hour of time, in the range 0-23.

Exceptions
None.

Examples
Hour('*')
Hour('Saturday')
Hour('t')

96
 Performance Equations Functions Reference

See Also
Day (page 83), DaySec (page 84), Minute (page 108), Month (page 109), Second (page 120),
Weekday (page 151), Year (page 152), Yearday (page 152)

Impulse

Dynamic response specified by the impulse response.

Format
Impulse(tagname, runflag, i1,i2 … )

Arguments
tagname

Must be a tagname for a numerical point.

runflag

Non-zero enables filter to run.

i1, i2, …

Unit impulse response specifying dynamic model, text sequence of numbers.

Returns
Dynamic model output as function of time.
u(t)=i1*u(t-1) + i2*u(t-2) + …

Where u(t) is the current output and u(t-1) is the output one sample interval in the past.

Exceptions
Impulse gives different results depending on which type of scheduling is used. In clock
scheduling, the interval between time series values depends on the scan class and gives values
at evenly spaced time intervals.
On the other hand, event-based scheduling is dependent on a trigger from another point. If the
exception deviation is not zero, the intervals for events are not evenly spaced in time—hence
Impulse gives results that are not trustworthy. Impulse is not supported in the pipetest utility
or in PI DataLink. If the input point is not a real number or integer, Impulse returns an error.

Examples
Impulse('tag1',1,1,1,1)

PI Server Applications User Guide 97

PI Performance Equations Syntax and Functions Reference

InStr

Determine the location within a string where a sub-string match is first found.

Format
InStr([start,] str1, str2 [,casesen])

Arguments
start

Optional. An integer specifying which character in str1 to start the comparison. Must be
larger than or equal to 1.
str1, str2

Two strings and/or points with string pointtypes to be compared.

casesen

Optional flag indicating if the comparison is case sensitive. If 0 (the default) the comparison
is case insensitive, if 1, the comparison is case sensitive.

Returns
0 if str2 is not a sub-string of str1 starting from the start position; otherwise, the location of
character where str2 first matches the characters in str1 from the start position.

Exceptions
Wild characters are not treated as wild.

Examples
InStr("What", "At") = 3
InStr("What What What", "What") = 1
InStr("what", "At", 1) = 0
InStr(4,"what","At") = 0
InStr('StringTag', "Error") = 1 (if the tag value for 'stringtag'
is "Error")
InStr('StringTag',"StringTag") = 0 (if the tag value for
'stringtag' is "Error")

Int

Return the integer part of an integer or real number.

98
 Performance Equations Functions Reference

Format
Int(x)

Arguments
x

A number or string.

Returns
The integer part of x. If x is a string, it is first converted into a number.

Exceptions
If x is not a number or a numeric string, returns Calc Failed.

Examples
Int('tag1')
Int(1)
Int(2.1)
Int("2.1")

IsDST

Determine if a time expression is in a daylight saving time (DST) period on the local
machine.

Format
IsDST(time)

Arguments
time

A time expression.

Returns
1 if the time is in a DST period and 0 otherwise.

Exceptions
If the argument is not a time value, an error condition is returned.

PI Server Applications User Guide 99

PI Performance Equations Syntax and Functions Reference

Examples
IsDST('*')
IsDST('*-182.5d')
IsDST('t')
IsDST('timestringtag')

IsSet

Determine if a PI value is annotated, substituted, or questionable.

Format
IsSet(pivalue, select)

Arguments
pivalue

Any PI value. May be an integer, real number, digital state, or character string.
select

A string but only the first character is considered. "a" for annotated; "s" for substituted; and
"q" for questionable. It is case-insensitive.

Returns
1 if true and 0 otherwise.

Exceptions
None.

Examples
IsSet('sinusoid', "a")
IsSet('sinusoid', "annotated")
IsSet('sinusoid', "annotatted is mispelled")
IsSet('stringtag',"annotatiiion is mispelled but it does not
matter.")
IsSet('stringtag',"A")
IsSet('alarmtag1',"q")
IsSet('stringtag',"s")

LCase

Convert a string to a lowercase string.

100
 Performance Equations Functions Reference

Format
LCase(strexp)

Arguments
strexp

Must be a string.

Returns
A string that has been converted to lowercase.

Exceptions
If the argument is not a string, returns an error value.

Examples
LCase("Stringtag") = "stringtag"
LCase('Stringtag') = "error" if the Snapshot value for the
stringtag equals "Error"

See Also
UCase (page 150)

Left

Determine a specified number of characters of a string from the left.

Format
Left(str, len)

Arguments
str

A string.
len

An integer.

Returns
len characters of the string from the left.

PI Server Applications User Guide 101

PI Performance Equations Syntax and Functions Reference

Exceptions
If the arguments are not of the required types, returns an error.

Examples
Left("Stringtag", 3) = "Str"
Left('Stringtag', 3) = "Err" if the Snapshot value for the
stringtag equals "Error"

See Also
Mid (page 107), Right (page 118)

Len

Determine the length of a string.

Format
Len(str)

Arguments
str

A string.

Returns
The length of a string.

Exceptions
If the argument is not a string, returns an error value.

Examples
Len("Stringtag") = 9
Len('Stringtag') = 5 if the Snapshot value for the stringtag
equals "Error"

Log

Return the natural (base-e = 2.7182818...) logarithm of an integer or real number.

102
 Performance Equations Functions Reference

Format
Log(x)

Arguments
x

Must be an integer or real number greater than zero.

Returns
The natural logarithm of x.

Exceptions
If x is zero or negative, or not a number, returns an error value.

Examples
Log('*')
Log(14)
Log(TagVal('tag1', '14-Dec-97'))

See Also
Log10 (page 103)

Log10

Return the common (base-10) logarithm of an integer or real number.

Format
Log10(x)

Arguments
x

Must be an integer or real number greater than zero.

Returns
The common logarithm of x.

PI Server Applications User Guide 103

PI Performance Equations Syntax and Functions Reference

Exceptions
If x is zero or negative, or not a number, returns an error value.

Examples
Log10('*')
Log10(14)
Log10(TagVal('tag1', '14-Dec-97'))

See Also
Log (page 102)

LTrim

Remove the leading blanks from a string.

Format
LTrim(str)

Arguments
str

A string.

Returns
A string with leading blanks removed.

Exceptions
If str is not a string, an error value is returned.

Examples
LTrim(" Stringtag") = "Stringtag"
LTrim("Stringtag ") = "Stringtag "
LTrim('Stringtag') = "Error" if the Snapshot value for the
stringtag equals " Error"

See Also
RTrim (page 120), Trim (page 149)

104
 Performance Equations Functions Reference

Max

Return the maximum of arguments.

Format
Max(x1, x2, ..., xn)

Arguments
x1...xn

May be numbers, times, or time periods, but all must be the same.

Returns
The maximum of the arguments. The result has the same data type as the arguments.

Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
Max returns an error value.

Examples
Max('*', 'y', 'Saturday')
Max(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Max('*'-'*-h', 't'-'y', TimeEq('tag1', 'y', 't',50))

See Also
Min (page 108)

Median

Return the median (middle) value of three or more arguments.

Format
Median(x1, x2, ..., xn)

Arguments
x1...xn

May be only integers, real numbers, times, or time periods, but all arguments must be the
same data type.

PI Server Applications User Guide 105

PI Performance Equations Syntax and Functions Reference

Returns
The median value of the input arguments. If the number of arguments is even, the average of
the two middle values is returned.

Exceptions
Arguments whose run-time values are digital states are ignored. The function must have
greater than two arguments that evaluate to non-digital states; otherwise, Median returns an
error value.

Usage Note
Median allows for mixed integer and real data types. Median follows the data type of the first
argument. Hence if the first argument is a point that evaluates to an integer then all the other
entries are converted to integers by truncation (not by rounding).

Examples
Median('*', 'y', 'Saturday')
Median(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Median('*'-'*-1h', 't'-'y', TimeEq('tag1', 'y', 't',50))

MedianFilt

Return the median value of the last specified number of values of a time series.

Format
MedianFilt( tagname, runflag, number )

Arguments
tagname

Must be a numerical point.

runflag

Non-zero enables filter to run.

number

The number of series elements to be considered. A numeric constant greater than or equal to
3.

Returns
The median value of the last number values in the series of values.

106
 Performance Equations Functions Reference

Exceptions
Arguments whose run-time values are digital states are ignored. MedianFilt is not supported
in the pipetest utility or in PI DataLink. If all values are digital states, MedianFilt returns an
error value.

Examples
MedianFilt('tag1',1,3)

Mid

Return a sub-string within a string.

Format
Mid(str, start [,len])

Arguments
str

A string.
start

An integer specifying the position of the first character within the string. The first character in
the string is number 1.
len

Optional. The maximum length of the returned string. The default is the length of the string.

Returns
len characters of the string to the left of (and including) the first character whose position is
specified by start.

Exceptions
If the arguments are not of the required types, an error value is returned. The maximum
number of characters that can be returned is 999.

Examples
Mid("Stringtag", 3) = "ringtag"
Mid("Stringtag", 3, 2) = "ri"
Mid('Stringtag', 1, 1) = "E" if the Snapshot value for the
stringtag equals "Error"

PI Server Applications User Guide 107

PI Performance Equations Syntax and Functions Reference

See Also
Left (page 101), Right (page 118)

Min

Return the minimum of arguments.

Format
Min(x1, x2, ..., xn)

Arguments
x1...xn

May be numbers, times, or time periods, but all must be the same data type.

Returns
The minimum of the arguments. The result has the same data type as the arguments.

Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
Min returns an error value.

Examples
Min('*', 'y', 'Saturday')
Min(14, 'tag1', 14.5, TagVal('tag2','14-Dec-97'))
Min('*'-'*-1h', 't'-'y', TimeEq('tag1', 'y', 't',50))

See Also
Max (page 104)

Minute

Extract the minute from a time expression.

Format
Minute(time)

108
 Performance Equations Functions Reference

Arguments
time

A time expression.

Returns
The minute of time, in the range 0-59.

Exceptions
None.

Examples
Minute('*')
Minute('1')
Minute('*-1h')

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Month (page 109), Second (page 120),
Weekday (page 151), Year (page 152), Yearday (page 152)

Month

Extract the month from a time expression.

Format
Month(time)

Arguments
time

A time expression.

Returns
The month of time, in the range 1-12.

Exceptions
None.

PI Server Applications User Guide 109

PI Performance Equations Syntax and Functions Reference

Examples
Month('*')
Month('1')
Month('*-1h')

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Minute (page 108), Second (page 120),
Weekday (page 151), Year (page 152), Yearday (page 152)

NextEvent

Find the time of a point's next Archive event after a given time.

Format
NextEvent(tagname, time)

Arguments
tagname

A tagname.
time
A time expression.

Returns
The timestamp of the next Archive event for tagname after time.

Exceptions
If point has no Archive data after time, returns an error value.

Examples
NextEvent('tag1','*')
NextEvent('digitaltag', '*')

See Also
NextVal (page 111), PrevEvent (page 115), PrevVal (page 115), TagVal (page 138)

110
 Performance Equations Functions Reference

NextVal

Find the value of a point's next Archive event after a given time.

Format
NextVal(tagname, time)

Arguments
tagname

A tagname.
time
A time expression.

Returns
The value of the next Archive event for tagname after time.

Exceptions
If point has no Archive data after time, returns an error value.

Examples
NextVal('tag1','*-1h')
NextVal('digitaltag', '14-Dec-97')

See Also
NextEvent (page 110), PrevEvent (page 115), PrevVal (page 115), TagVal (page 138)

Noon

A timestamp for noon on the day of a given time expression.

Format
Noon(time)

Arguments
time

A time expression.

PI Server Applications User Guide 111

PI Performance Equations Syntax and Functions Reference

Returns
A timestamp corresponding to noon of the day of the input time.

Exceptions
None.

Usage Note
This function is useful for establishing a unique clock time independent of the length of
particular days.

Examples
Noon('*')
Noon('14-Dec-97')

See Also
Bod (page 77), Bom (page 78), Bonm (page 79)

NoOutput

Do not send the current calculation result to PI.

Format
NoOutput()

Arguments
None

Usage Note
It is important to include the parentheses after this function (use NoOutput() instead of
NoOutput as NoOutput is an invalid syntax). This function applies only to the current
calculation. The output of this function in pipetest.exe is "NoOutput() Called".
Example:
If 'PITag' < 100 or 'PItag' > 0 then 'PITag' else NoOutput()

ParseTime

Translate a PI time expression to a timestamp.

112
 Performance Equations Functions Reference

Format
ParseTime(s)

Arguments
s

Must be a character string in PI time format.

Returns
The timestamp corresponding to s.

Exceptions
If s is not a character string, or if there is a syntax error, returns an error value.

Usage Note
There is no difference between ParseTime("14-Nov-92") and the time expression '14-Nov-
92', except that the ParseTime call takes more time. This is because the time expression
(enclosed in single quotes) is evaluated at compile time, not run time.
If you write ParseTime('14-Nov-92') (using single quotes, not double quotes) the parser
detects an error, because the expression in single quotes is already translated to a timestamp
at compile time.
The expression ParseTime(":12:00:00") is not the same as the time expression ':12:00:00'.
The ParseTime expression is evaluated at runtime and translated using '*' as the relative time
base, while the time expression is evaluated at compile time and uses the time the expression
is parsed as the relative time base.

Examples
ParseTime("14-Dec-97")
ParseTime("t")

PctGood

Find the time percentage, over a given range, when a point's archived values are good.

Format
PctGood(tagname, starttime, endtime)

PI Server Applications User Guide 113

PI Performance Equations Syntax and Functions Reference

Arguments
tagname

A tagname.
starttime

Must be a time expression, the beginning of the time range to search.

endtime

Must be a time expression, greater than starttime; the end of the time range to search.

Returns
An integer or real number from 0.0 to 100.0: the percentage of the given time when the point
had good values.

Examples
PctGood('tag1', 'y','*')
PctGood('tag1', '-1h', '*')

Poly

Evaluate the polynomial c0 + c1x + c2x2 + … +cnxn.

Format
Poly(x, c0, ..., cn)

Arguments
x

The variable. It must be an integer or real number.

c0...cn

The coefficients. There must be at least one coefficient. All must be numbers.

Returns
The value of the polynomial.

Exceptions
If x or any coefficient is not an integer or real number, Poly returns an error value.

114
 Performance Equations Functions Reference

Examples
Poly('tag1',1,1)

PrevEvent

Find the time of a point's previous Archive event before a given time.

Format
PrevEvent(tagname, time)

Arguments
tagname

A tagname.
time

A time expression.

Returns
The timestamp of the previous Archive event for tagname before time.

Exceptions
If point has no Archive data before time, returns an error value.

Examples
PrevEvent('tag1', '*')
PrevEvent('tag1','14-Dec-97')

See Also
NextEvent (page 110), NextVal (page 111), PrevVal (page 115), TagVal (page 138)

PrevVal

Find the value of a point's previous Archive event before a given time.

Format
PrevVal(tagname, time)

PI Server Applications User Guide 115

PI Performance Equations Syntax and Functions Reference

Arguments
tagname

A tagname.
time

A time expression.

Returns
The value of the previous Archive event for tagname before time.

Exceptions
If point has no Archive data before time, returns an error value.

Examples
PrevVal('tag1', '*')
PrevVal('tag1','14-Dec-97')

See Also
NextEvent (page 110), NextVal (page 111), PrevEvent (page 115), TagVal (page 138)

PStDev

Return the standard deviation of two or more arguments, where those arguments represent the
whole population. The standard deviation of a population x1...xn is

where is the mean of the arguments; that is,

Format
PStDev(x1, x2, ..., xn)

116
 Performance Equations Functions Reference

Arguments
x1...xn

May be numbers or time expressions, but all must be the same.

Returns
The standard deviation of the arguments. If the arguments are numbers, the result is a
number; if the arguments are times or time periods, the result is a time period.

Exceptions
Arguments whose run-time values are digital states are ignored. If all values are digital states,
PStDev returns an error value.

Usage Note
In most cases you should use Sstdev (page 124) instead of PstDev. Sstdev calculates the
standard deviation of a sample.

Examples
PStDev('tag1', 'tag2')
PStDev('*','14-Dec-97', 'y')
PStDev('*'-'y','14-Dec-97'-'*', '-1h')

Range

Find the difference between a point's maximum and minimum values during a given time,
according to values stored in the PI Archive.

Format
Range(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point should represent a continuous variable.

starttime

Must be a time expression, the beginning of the time range to search.

endtime

Must be a time expression, greater than starttime; the end of the time range to search.
pctgood

Optional. Minimum time percentage, over the given time range, that the point's archived
values must be good.

PI Server Applications User Guide 117

PI Performance Equations Syntax and Functions Reference

Returns
The difference between the point's maximum and minimum values during the given time.

Exceptions
If the point has no good values or the pctgood minimum is not reached in the given time
range, returns an error value.

Caution
The OverRangeStat and UnderRangeStat digital states are not taken into account when
calculating this value.

Examples
Range('tag1', 'y', '*')
Range('tag1','-1h', 'y')
Range('tag1','y', '+1h',70)

Right

Determine a specified number of characters of a string from the right.

Format
Right(str, len)

Arguments
str

A string.
len

An integer.

Returns
len characters of the string from the right.

Exceptions
If the arguments are not of the required types, an error value is returned.

Examples
Right("Stringtag", 3) = "tag"
Right('Stringtag', 4) = "rror" if the Snapshot value for the
stringtag equals "Error"

118
 Performance Equations Functions Reference

Right("Stringtag", 20) = "Stringtag"

See Also
Left (page 101), Mid (page 107)

Round

Round a number or time to the nearest unit.

Format
Round(x [, unit])

Arguments
x

Must be an integer or real number or time expression.

unit

Optional. The size of the unit to round to. If x is a number, unit must be a number. If x is a
time expression or time period, unit must be a time period. If unit is omitted, Round rounds
to the nearest integer (for a number) or second (for a time period).

Returns
The nearest value to x which is an integer multiple of unit. Returns the same data type as x.
For more details, see the following examples.

Exceptions
If x is a string, or if unit is of the wrong data type, returns an error value.

Examples
Expression Value Comments
Round(12.499) 12.0 Round to nearest integer
Round(12.500) 13.0 Half a unit rounds up
Round(12.8, 10) 10.0 Round to nearest ten
Round('14-Dec-97 11:47, '+1h') 14-Dec-97 12:00 Round to nearest hour (returns timestamp)
Round('18:47' -'15:00','+1h') 10800 Round period to nearest hour (returns
period in seconds)

Note: Round to the nearest day results in a timestamp of the closest day in UTC time
and not local time.

PI Server Applications User Guide 119

PI Performance Equations Syntax and Functions Reference

Usage Note
If x is time and unit is omitted this routine has no effect: times are accurate only to 1 second.

See Also
Trunc (page 149)

RTrim

Trim trailing blanks from a string.

Format
RTrim(str)

Arguments
str

A string.

Returns
The source string with trailing blanks removed.

Exceptions
If str is not a string, an error value is returned.

Examples
RTrim("Stringtag ") = "Stringtag" "
RTrim(" Stringtag") = " Stringtag"
RTrim('Stringtag') = "Error" if the Snapshot value for the
stringtag equals "Error "

See Also
LTrim (page 104), Trim (page 149)

Second

Extract the second from a time expression.

120
 Performance Equations Functions Reference

Format
Second(time)

Arguments
time

A time expression.

Returns
The second of time, in the range 0-59.

Exceptions
None.

Examples
Second('*')
Second('y')
Second('*-1h')

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Minute (page 108), Month (page 109),
Weekday (page 151), Year (page 152), Yearday (page 152)

Sgn

Return a representation of the numerical sign of a number.

Format
Sgn(x)

Arguments
x

Must be an integer or real number.

Returns
-1 if x < 0.
0 if x = 0.
1 if x > 0.

PI Server Applications User Guide 121

PI Performance Equations Syntax and Functions Reference

Exceptions
If x is not an integer or real number, returns an error value.

Examples
Sgn('tag1')
Sgn(1)
Sgn(0)

Sin

Return the trigonometric sine of a number.

Format
Sin(x)

Arguments
x

Must be an integer or real number, which represents an angle in radians.

Returns
The sine of x.

Exceptions
If x is not a number, returns an error value.

Examples
Sin('tag1')
Sin(1)
Sin(1.1)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page
82), Sinh (page 122), Tan (page 140), Tanh (page 141)

Sinh

Return the hyperbolic sine of a number.

122
 Performance Equations Functions Reference

Format
Sinh(x)

Arguments
x

Must be an integer or real number.

Returns
The hyperbolic sine of x.

Exceptions
If x is not a number, returns an error value.

Examples
Sinh('tag1')
Sinh(1)
Sinh(0.9)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page
82), Sin (page 122), Tan (page 140), Tanh (page 141)

Sqr

Return the square root of a number.

Format
Sqr(x)

Arguments
x

Must be an integer or real number greater than or equal to zero.

Returns
The square root of x.

PI Server Applications User Guide 123

PI Performance Equations Syntax and Functions Reference

Exceptions
If x is negative, or is not a number, returns an error value.

Examples
Sqr('tag1')
Sqr(2)
Sqr(2.1)

SStDev

Return the standard deviation of two or more arguments, where those arguments represent a
sample of a larger population. The standard deviation of a sample x1...xn is equal to

Where is the sample mean; that is,

Format
SStDev(x1, x2, ..., xn)

Arguments
x1...xn

May be numbers or time expressions, but all must be the same.

Returns
The sample standard deviation of the arguments. If the arguments are numbers, the result is a
number; if they are times or time periods, the result is a time period (number of seconds).

Exceptions
Arguments whose run-time values are digital states are ignored. If there are not at least two
numeric values, SStDev returns a zero.

124
 Performance Equations Functions Reference

Usage Note
In the rare case where you have the entire population, rather than a sample, you might use the
function PstDev (page 116), rather than SStDev.

Examples
SStDev('tag1', 'tag2', TagVal('tag1', 'y'))
SStDev('y', 't', '14-Dec-97')
SStDev(1, 2, 1.1)

StateNo

Translate a digital state into its corresponding state number.

Format
StateNo(digstate)

Arguments
digstate

A digital state value.

Returns
The offset into the Digital State Set corresponding to digstate.

Exceptions
If a point is passed as digstate that is not a digital point, returns an error value.

Usage Note
A digital state may appear more than once in the digital state Table. In this case, the value
that StateNo returns may vary. If digstate is the value of a digital point, StateNo returns a
code number appropriate for that point.

Examples
StateNo('digitaltag')
StateNo(TagVal('digitaltag', '*-1h'))

PI Server Applications User Guide 125

PI Performance Equations Syntax and Functions Reference

StDev

Find the time-weighted standard deviation of a point over a given time, according to values
stored in the PI Archive.

Format
StDev(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point must represent a continuous variable.

starttime

Must be a time expression representing the beginning of the time range to search.
endtime

Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must be good.

Returns
The point's time-weighted standard deviation over the given time.

Exceptions
If the point has no good values or the PctGood minimum is not reached for the given time
range, returns an error value.

Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood (page 113) function to find out what percentage of the
values is good.

Examples
StDev('tag1', 'y', '*')
StDev('tag1', '14-Dec-97', '+1d',85)
StDev('tag1', '14-Dec-97', '15-Dec-97')

126
 Performance Equations Functions Reference

String

Convert any value to a string.

Format
String(anyvalue)

Arguments
anyvalue

Any expression. It may be of any of the normal PI System data types.

Returns
The string representing the value argument.

Exceptions
None.

Examples
String(12.23) = "12.23"
String('sinusoid')
String('pidigital')
String('*')
String("Hello, PI user!") = "Hello, PI user! "

TagAvg

Find the time-weighted average value of a point over a given time, according to values stored
in the PI Archive.

Format
TagAvg(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point must represent a continuous variable.

starttime

Must be a time expression representing the beginning of the time range to search.
endtime

PI Server Applications User Guide 127

PI Performance Equations Syntax and Functions Reference

Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must be good.

Returns
The point's time-weighted average value over the given time.

Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.

Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood (page 113) function to find out what percentage of the
values are good.

Examples
TagAvg('tag1', 'y', '*')
TagAvg('tag1', '14-Dec-97', '+1d',70)
TagAvg('tag1', '14-Dec-97', '15-Dec-97')

TagBad

Test if a point has an abnormal state at a given time. If the point's type is R or I, any digital
state is abnormal. If the point is type D, the states that are defined for that point are normal;
all others are abnormal.

Format
Tagbad(tagname [, time])

Arguments
tagname

A tagname.
time

Optional. A time expression. If omitted, the current time (*) is used.

128
 Performance Equations Functions Reference

Returns
0 if the point's state at time is normal, 1 if it is abnormal.

Exceptions
If point does not exist, or has no archived value at time, returns an error value.

Usage Note
Badval can test any value or expression; TagBad can only test a point.

Examples
TagBad('tag1', '*')
TagBad('digitaltag', '14-Dec-97')
TagBad('tag1', 'y')

See Also
Badval (page 76)

TagDesc

Get a point's descriptor from the Point Database.

Format
TagDesc(tagname)

Arguments
tagname

A tagname.

Returns
The point's descriptor.

Exceptions
If point does not exist, returns an error value.

PI Server Applications User Guide 129

PI Performance Equations Syntax and Functions Reference

Examples
TagDesc('tag1')
TagDesc('digitaltag')

TagEU

Get a point's engineering unit string from the Point Database.

Format
TagEU(tagname)

Arguments
tagname

A tagname.

Returns
The point's engineering units.

Exceptions
If point does not exist, returns an error value.

Examples
TagEU('tag1')

TagExDesc

Get a point's extended descriptor from the Point Database.

Format
TagExDesc(tagname)

Arguments
tagname

A tagname.

Returns
The point's extended descriptor.

130
 Performance Equations Functions Reference

Exceptions
If point does not exist, returns an error value.

Examples
TagExDesc('tag1')

TagMax

Find the maximum value of a point during a given time, according to values stored in the PI
Archive.

Format
TagMax(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname.
starttime

A time expression indicating the beginning of the time range to search. Relative times are
relative to endtime, if endtime is not itself a relative time. For example:
TagMax('tag1', '-1h', '*',95)

Here, the starttime is one hour before the endtime, which is now ('*').
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must be good.

Returns
The point's maximum value during the given time.

Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.

PI Server Applications User Guide 131

PI Performance Equations Syntax and Functions Reference

Caution
The OverRange digital state is not taken into account when calculating this value.

Examples
TagMax('tag1', 'y', '*')
TagMax('tag1', '-1h', '*',95)
TagMax('tag1', '14-Dec-97', '+1h')

TagMean

Find the average value of a point over a given time, according to values stored in the PI
Archive.

Format
TagMean(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point must represent a continuous variable.

starttime

Must be a time expression representing the beginning of the time range to search.
endtime

Must be a time expression, greater than starttime; representing the end of the time range to
search.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must good.

Returns
The point's average value over the given time. Notice that the average is not time-weighted.

Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value. Unlike some other summary functions, TagMean does not
interpolate any value on the boundary. Thus, if there is no Archive event between the
specified interval, an error value is returned.

132
 Performance Equations Functions Reference

Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood (page 113) function to find out what percentage of the
values is good.

Examples
TagMean('tag1', 'y', '*')
TagMean('tag1', '14-Dec-97', '+1d',70)
TagMean('tag1', '14-Dec-97', '15-Dec-97')

TagMin

Find the minimum value of a point during a given time, according to values stored in the PI
Archive.

Format
TagMin(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point should represent a continuous variable.

starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

Relative times are relative to starttime, if starttime is not itself a relative time. This time must
be after starttime.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must good.

Returns
The point's minimum value during the given time.

Exceptions
If the point has no good values or the pctgood minimum is not reached for the given time
range, returns an error value.

PI Server Applications User Guide 133

PI Performance Equations Syntax and Functions Reference

Caution
The UnderRange digital state is not taken into account when calculating this value.

Examples
TagMin('tag1', 'y', '*')
TagMin('tag1', '-1h', '*',90)
TagMin('tag1', '14-Dec-97', '+1h')

TagName

Get a point's name from the Point Database.

Format
TagName(tag)

Arguments
tagname

A tagname.

Returns
The point's name.

Exceptions
If point does not exist, returns an error value.

Examples
TagName('tag1')

TagNum

Get a point's number from the Point Database.

Format
TagNum(string)

134
 Performance Equations Functions Reference

Arguments
string

A tagname in double quotes.

Returns
The point's number.

Exceptions
If point does not exist, returns an error value.

Examples
TagNum("tag1")

TagSource

Get a point's point source string from the Point Database.

Format
TagSource(tagname)

Arguments
tagname

A tagname.

Returns
The point's point source string.

Exceptions
If point does not exist, returns an error value.

Examples
TagSource('tag1')

TagSpan

Get a point's span from the Point Database.

PI Server Applications User Guide 135

PI Performance Equations Syntax and Functions Reference

Format
TagSpan(tagname)

Arguments
tagname

A tagname.

Returns
The point's span. If the point's type is Digital this is an integer whose value is the number of
digital states defined for the point.

Examples
TagSpan('tag1')
TagSpan('digitaltag')

TagTot

Find the totalized value (time integral) of a point over a given time, according to values
stored in the PI Archive.

Format
TagTot(tagname, starttime, endtime [, pctgood])

Arguments
tagname

A tagname. This point must represent a continuous process flow.

starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time.
pctgood

Optional. Minimum time percentage over the given time range, that the point's archived
values must be good.

Returns
The point's totalized value over the given time.

136
 Performance Equations Functions Reference

Exceptions
If the point has no good values or the PctGood minimum is not reached for the given time
range, returns an error value.

Caution
If the point has few good Archive values during the time period, this function's result may not
be trustworthy. Use the PctGood (page 113) function to find out what percentage of the value
is good.

Usage Notes
• The system chooses a scale factor such that the integral is correct only if the flow is
expressed in units per day. If the flow is expressed in units per hour, or per some other
time unit, you must multiply this result by a conversion factor. The conversion factor
equals the number of actual flow time units in a day.
For instance, if you totalize a point measured in gallons per minute, multiply the result of
TagTot by 1440 to get the answer in gallons. This conversion factor is not related to the
time period you are totalizing over; it is strictly a function of the point's engineering
units.
Some PI sites have the default total period configured to be per hour rather than per day.
If you are at one of these sites, your conversion factor will differ.
• When the percentage of good data is less than 100%, TagTot determines the total based
on good data and divides the fraction of good data in the interval.

Examples
TagTot('tag1', 'y', '*')
TagTot('tag1', '-1h', '*',85)
TagTot('tag1', '14-Dec-97', '+1h')

TagType

Get a point's type character (I, R, or D) from the Point Database.

Format
TagType(tagname)

Arguments
tagname

A tagname.

PI Server Applications User Guide 137

PI Performance Equations Syntax and Functions Reference

Returns
The point's type character.

Exceptions
If point does not exist, returns an error value.

Examples
TagType('tag1')
TagType('digitaltag')

TagTypVal

Get a point's typical value from the Point Database.

Format
TagTypVal(tagname)

Arguments
tagname

A tagname.

Returns
The point's typical value. If the point's type is R or I, this is a number; if the point's type is D,
this is a digital state (character string).

Exceptions
If point does not exist, returns an error value.

Examples
TagTypVal('tag1')
TagTypVal('digitaltag')

TagVal

Find a point's Archive value at a given time.

138
 Performance Equations Functions Reference

Format
TagVal(tagname [, time])

Arguments
tagname

A tagname.
time

Optional. A time expression. If you omit this argument, '*' is used.

Returns
The archived value of tagname at time. This value is interpolated unless the point has the Step
attribute of 1 (or Resolution Code of 4 for PI2).

Exceptions
If point does not exist, or has no archived value at time, returns an error value.

Examples
TagVal('tag1')
TagVal('digitaltag')
TagVal('tag1','*')

See Also
NextEvent (page 110), NextVal (page 111), PrevEvent (page 115), PrevVal (page 115)

TagZero

Get a point's zero value from the Point Database.

Format
TagZero(tagname)

Arguments
tagname

A tagname.

PI Server Applications User Guide 139

PI Performance Equations Syntax and Functions Reference

Returns
The point's zero value. If the point's type is R or I, this is a number; if the point's type is D,
this is a digital state (character string).

Exceptions
If point does not exist, returns an error value.

Examples
TagZero('tag1')
TagZero('digitaltag')

Tan

Return the trigonometric tangent of a number.

Format
Tan(x)

Arguments
x

Must be an integer or real number, which represents an angle in radians.

Returns
The tangent of x.

Exceptions
If x is not a number, returns an error value.

Examples
Tan('tag1')
Tan(1)
Tan(1.1)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page
82), Sin (page 122), Sinh (page 122), Tanh (page 141)

140
 Performance Equations Functions Reference

Tanh

Return the hyperbolic tangent of a number.

Format
Tanh(x)

Arguments
x

Must be an integer or real number.

Returns
The hyperbolic tangent of x.

Exceptions
If x is not a number, returns an error value.

Examples
Tanh('tag1')
Tanh(1)
Tanh(1.1)

See Also
Acos (page 68), Asin (page 74), Atn (page 74), Atn2 (page 75), Cos (page 81), Cosh (page
82), Sin (page 122), Sinh (page 122), Tan (page 140)

Text

Concatenate strings representing argument values.

Format
Text(val1 [, val2, … ])

Arguments
val1, val2, …

Any expression. These may be of any of the normal PI System data types.

PI Server Applications User Guide 141

PI Performance Equations Syntax and Functions Reference

Returns
A string that is the concatenation of strings representing the argument values.

Examples
Text('sinusoid')
Text("The value for tag sinusoid is at ", '*', " is ",
'sinusoid') = "The value for tag sinusoid at 1-Jun-00 17:07:18 is
89.09"

See Also
Concat (page 81)

TimeEq

Find the total time, within a range, when a point is equal to a given value.

Format
TimeEq(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

Returns
The time period within the given range, for which the point was exactly equal to the given
value.

Exceptions
None.

142
 Performance Equations Functions Reference

Examples
TimeEq('tag1', 't', '*',40.0)
TimeEq('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeEq('digitaltag', '14-Dec-97', '*', "On")

See Also
TimeGE (page 143), TimeGT (page 144), TimeLE (page 145), TimeLT (page 146), TimeNE
(page 147)

TimeGE

Find the total time, within a range, when a point is greater than or equal to a given value.

Format
TimeGE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

Returns
The time period within the given range, for which the point was greater than or equal to the
given value.

Exceptions
None.

PI Server Applications User Guide 143

PI Performance Equations Syntax and Functions Reference

Usage Note
TimeGE interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.

Examples
TimeGE('tag1', 't', '*',40.0)
TimeGE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeGE('digitaltag', '14-Dec-97', '*', "On")

See Also
TimeEq (page 142), TimeGT (page 144), TimeLE (page 145), TimeLT (page 146), TimeNE
(page 147)

TimeGT

Find the total time, within a range, when a point is greater than a given value.

Format
TimeGT(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

Returns
The time period within the given range, for which the point was greater than the given value.

Exceptions
None.

144
 Performance Equations Functions Reference

Usage Note
TimeGT interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.

Examples
TimeGT('tag1', 't', '*',40.0)
TimeGT('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeGT('digitaltag', '14-Dec-97', '*', "On")

See Also
TimeEq (page 142), TimeGE (page 143), TimeLE (page 145), TimeLT (page 146), TimeNE
(page 147)

TimeLE

Find the total time, within a range, when a point is less than or equal to a given value.

Format
TimeLE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

Returns
The time period within the given range, for which the point was less than or equal to the
given value.

PI Server Applications User Guide 145

PI Performance Equations Syntax and Functions Reference

Exceptions
None.

Usage Note
TimeLE interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.

Examples
TimeLE('tag1', 't', '*',40.0)
TimeLE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeLE('digitaltag', '14-Dec-97', '*', "On")

See Also
TimeEq (page 142), TimeGE (page 143), TimeGT (page 144), TimeLT (page 146), TimeNE
(page 147)

TimeLT

Find the total time, within a range, when a point is less than a given value.

Format
TimeLT(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

Returns
The time period within the given range, for which the point was less than the given value.

146
 Performance Equations Functions Reference

Exceptions
None.

Usage Note
TimeLT interpolates between Archive events, if necessary, to find the times when the point
crossed the given value.

Examples
TimeLT('tag1', 't', '*',40.0)
TimeLT('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeLT'digitaltag', '14-Dec-97', '*', "On")

See Also
TimeEq (page 142), TimeGE (page 143), TimeGT (page 144), TimeLE (page 145), TimeNE
(page 147)

TimeNE

Find the total time, within a range, when a point is unequal to a given value.

Format
TimeNE(tagname, starttime, endtime, value)

Arguments
tagname

A tagname.
starttime

Beginning of the time range to search. Relative times are relative to endtime, if endtime is not
itself a relative time.
endtime

End of the time range to search. Relative times are relative to starttime, if starttime is not
itself a relative time. This time must be after starttime.
value

Must be an integer or real number or digital state (character string); the value to search for.

PI Server Applications User Guide 147

PI Performance Equations Syntax and Functions Reference

Returns
The time period within the given range, for which the point was unequal to the given value.

Exceptions
None.

Examples
TimeNE('tag1', 't', '*',40.0)
TimeNE('digitaltag', '-1d', '*',TagVal('digitaltag', '14-Dec-
97'))
TimeNE('digitaltag', '14-Dec-97', '*', "On")

See Also
TimeEq (page 142), TimeGE (page 143), TimeGT (page 144), TimeLE (page 145), TimeLT
(page 146)

Total

Return the sum of two or more arguments.

Format
Total(x1, x2, ..., xn)

Arguments
x1...xn

May be numbers or time periods, but all must be the same.

Returns
The total of the arguments. The result has the same data type as the arguments.

Exceptions
Arguments whose run-time values are digital states are not included in the total. If all values
are digital states, Total returns an error value.

Examples
Total('tag1', 'tag2', TagVal('tag1', 'y'),40.0)
Total('t'-'y', '+1h')

148
 Performance Equations Functions Reference

Trim

Trim blanks on both sides of a string.

Format
Trim(str)

Arguments
str

A string.

Returns
The source string with leading and trailing blanks removed.

Exceptions
If str is not a string, an error value is returned.

Examples
Trim(" Stringtag ") = "Stringtag"
Trim(" Stringtag is a string tag. ") = "Stringtag is a string
tag."

See Also
LTrim (page 104), RTrim (page 120)

Trunc

Truncate a number or time to the next lower unit.

Format
Trunc(x [, unit])

Arguments
x

Must be an integer or real number, time expression, or time period.

unit

Optional. The size of the unit to truncate to. If x is a number, unit must be a number. If x is a
time expression or time period, unit must be a time period. If unit is omitted, Trunc truncates
to the next lower integer (for a number) or second (for a time period).

PI Server Applications User Guide 149

PI Performance Equations Syntax and Functions Reference

Returns
The largest value smaller than x which is an integer multiple of unit. Returns the same data
type as x. For more details, see the following examples.

Exceptions
If x is a string, or if unit is of the wrong data type, returns an error value.

Examples
Expression Value Comments
Trunc(12.999) 12.0 Truncate to next lower integer
Trunc(18.75, 10) 10.0 Truncate to next lower ten
Trunc('14-Dec-97 14-Dec-97 Truncate to next lower hour
11:47','+1h') 11:00
Trunc('18:47' - 10800 Truncate period to next lower hour
'15:00','+1h') (returns period in seconds)

Note: Trunc to the next lower day results in a timestamp of the next lower day in UTC
time, not local time.

Usage Note
If x is a time, and unit is omitted, this routine has no effect, as times are only accurate to one
second.

See Also
Round (page 119)

UCase

Convert a string to an uppercase string.

Format
UCase(strexp)

Arguments
strexp

Must be a string value.

150
 Performance Equations Functions Reference

Returns
An uppercase string.

Exceptions
If the argument is not a string, returns an error value.

Examples
UCase("Stringtag") = "STRINGTAG"
UCase('Stringtag') = "ERROR" if the Snapshot value for the
stringtag equals "Error"

See Also
LCase (page 100)

Weekday

Extract the day of the week from a timestamp.

Format
Weekday(time)

Arguments
time

A time expression.

Returns
The day of the week of time, in the range 1-7, where 1 represents Sunday.

Exceptions
None.

Examples
Weekday('*')
Weekday('t')

PI Server Applications User Guide 151

PI Performance Equations Syntax and Functions Reference

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Minute (page 108), Month (page 109),
Second (page 120), Year (page 152), Yearday (page 152)

Year

Extract the year from a time expression.

Format
Year(time)

Arguments
time

A time expression.

Returns
The year of time, in the range 1970-present.

Exceptions
None.

Examples
Year('*')
Year('t')

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Minute (page 108), Month (page 109),
Second (page 120), Weekday (page 151), Yearday (page 152)

Yearday

Extract the day of the year from a time expression. The day of the year (also known as a
Julian day) is an integer ranging from 1 to 366, where 1 represents January 1.

Format
Yearday(time)

152
 Performance Equations Functions Reference

Arguments
time

A time expression.

Returns
The day of the year of time, in the range 1-366, where 1 represents January 1.

Exceptions
None.

Examples
Yearday('*')
Yearday('t')

See Also
Day (page 83), DaySec (page 84), Hour (page 96), Minute (page 108), Month (page 109),
Second (page 120), Weekday (page 151), Year (page 152)

PI Server Applications User Guide 153

Chapter 5

PI Steam Functions Reference

The PI Steam Functions module is an extension to the PI Performance Equations. Steam
Functions provide a complete set of functions for deriving the thermodynamic properties of
steam and water within Performance Equations. PI Steam Functions support both English and
SI units, and are based on the ASME (American Society of Mechanical Engineers) Steam
Tables, 6th Ed.
This chapter provides a comprehensive reference for setting up Steam calculations.

Steam Functions Overview

The PI PE Steam Functions Module (PI Steam) makes available functions that calculate the
thermodynamic properties of steam within Performance Equations. The steam functions are
also available in a COM library, PISteamTableFunctions.dll, which is distributed
by other OSIsoft products, such as ACE.
For each steam function, there are two function calls: one in English units and another in SI
units. The following tables list the engineering units for the variables in the steam functions
and the supported functions in English units.

Engineering Units

Variable English Unit SI Unit Conversion Factor (Eng to SI)

Temperature degree F degree C (T - 32) / 1.8
Pressure psia kpa 6.894757
Volume ft3/lbm cc/g 62.42796
Enthalpy BTU/lbm J/g 2.326
Entropy BTU/lbm/R J/g/K 4.1868

Supported Functions

Name Function Description

StmEng_tsatp Saturation temperature as a function of pressure.
StmEng_hsatp Saturation enthalpy as a function of pressure.
StmEng_ssatp Saturation entropy as a function of pressure.
StmEng_vsatp Saturation vapor specific volume as a function of pressure.
StmEng_psatt Saturation pressure as a function of temperature.
StmEng_hsatt Saturation enthalpy as a function of temperature.

PI Server Applications User Guide 155

PI Steam Functions Reference

Name Function Description

StmEng_ssatt Saturation entropy as a function of temperature.
StmEng_vsatt Saturation vapor specific volume as a function of temperature.
StmEng_vpt Vapor specific volume as a function of pressure and temperature. (For saturated
and super heated steam.)
StmEng_vptl Water specific volume as a function of pressure and temperature.
StmEng_vph Vapor specific volume as a function of pressure and enthalpy. (For wet and dry
steam.)
StmEng_vps Vapor specific volume as a function of pressure and entropy. (For wet and dry
steam.)
StmEng_hpt Enthalpy as a function of pressure and temperature. (For saturated and super
heated steam.)
StmEng_hptl Liquid enthalpy as a function of pressure and temperature. (For water.)
StmEng_hps Enthalpy as a function of pressure and entropy. (For wet and dry steam.)
StmEng_spt Entropy as a function of pressure and temperature. (For saturated and super
heated steam.)
StmEng_sptl Liquid entropy as a function of pressure and temperature. (For water.)
StmEng_sph Entropy as a function of pressure and enthalpy. (For wet and dry steam.)
StmEng_tph Temperature as a function of enthalpy and pressure. (For wet and dry steam.)
StmEng_tps Temperature as a function of entropy and pressure. (For wet and dry steam.)
StmEng_xph Steam quality (vapor fraction) as a function of enthalpy and pressure. (For wet
steam.)
StmEng_xps Steam quality (vapor fraction) as a function of entropy and pressure. (For wet
steam.)
StmEng_hpx Enthalpy as a function of pressure and steam quality. (For wet steam.)
StmEng_spx Entropy as a function of pressure and steam quality. (For wet steam.)

Steam Functions Naming Convention

The formulas have the same naming convention as those callable by the user program that is
STMENG_XXX for English units and STMSI_XXX for SI units. The formulas return the
steam properties values and accept real number as arguments (that is, argument type R). In
case of error, the formulas return the following digital states:
Digital State Description
INP OUTRANGE Input condition out of computation range
NOT CONVERGE Calculation failed to converge in iterative loop.

These digital states are standard and are installed with PI Server. The format for each formula
is listed in the reference section.

156
 Range of Steam Functions

Range of Steam Functions

The following table lists the valid range in English units of the input variables for each of the
steam functions. The PI Steam functions should compute the same results as the equations
given in the ASME Steam Tables, 6th Edition. Besides the accuracy quoted by the ASME
Steam Tables, you should be aware of the issues raised in Functions that use Temperature and
Pressure as Independent Variables (page 157), and Functions that use Enthalpy or Entropy as
an Independent Variable (page 158).

Functions that use Temperature and Pressure as Independent Variables

For the HPT, SPT and VPT functions, the steam has to be superheated or saturated dry. If
the temperature and pressure are on the saturated curve, the calculated entropy, enthalpy or
volume is the property of saturated vapor. If the input temperature is less than the saturated
temperature for the input pressure, an Input Out of Range error is returned (that is, digital
state INPOUTRANGE for PI formulas or error code -1 for user-callable functions). Since
measurements are not exact, these PT functions can tolerate an error margin:
if (0 > Tsat - Tin > error margin) then saturated steam

The default error margin is 0.5 degree F.

Input Range for Each Function

Function Temp (deg f) Pressure (psia) Enthalpy Entropy Quality

(btu/lb) (btu/lb/r)
StmEng_tsatp 0.088589 to 3208.2

StmEng_hsatp 0.088589 to 3208.2

StmEng_ssatp 0.088589 to 3208.2

StmEng_vsatp 0.088589 to 3208.2

StmEng_psatt 32. to 705.47

StmEng_hsatt 32. to 705.47

StmEng_ssatt 32. to 705.47

StmEng_vsatt 32. to 705.47

StmEng_vpt, 32. to 1600 0.088589 to 16000.

StmEng_vptl
StmEng_vph 0.088589 to 16000. -1 to
1860.
StmEng_vps 0.088589 to 16000. -0.1 to 3.0

PI Server Applications User Guide 157

PI Steam Functions Reference

Function Temp (deg f) Pressure (psia) Enthalpy Entropy Quality

(btu/lb) (btu/lb/r)
StmEng_hpt, 32. to 1600 0.088589 to 16000.
StmEng_hptl
StmEng_hps 0.088589 to 16000. -0.1 to 3.0

StmEng_spt, 32. to 1600 0.088589 to 16000.

StmEng_sptl
StmEng_sph 0.088589 to 16000. -1 to
1860.
StmEng_tph 0.088589 to 16000. -1 to
1860.
StmEng_tps 0.088589 to 16000. -0.1 to 3.0

StmEng_xph 0.088589 to 3208.2 -1 to

1860.
StmEng_xps 0.088589 to 3208.2 -0.1 to 3.0

StmEng_hpx 0.088589 to 3208.2 0 to 1

StmEng_spx 0.088589 to 3208.2 0 to 1

Functions that use Enthalpy or Entropy as an Independent Variable

For the VPH, VPS, HPS, SPH, TPH and TPS functions, the valid ranges cover both the
superheated and the wet steam. However, even though the ASME listed valid range for
enthalpy goes from -1 to 1860 BTU/lbm and the entropy ranges from -0.1 to 3.0
BTU/lbm/degR, there are some combination of pressure and enthalpy or entropy that
correspond to compressed water rather than steam. Hence, these input conditions generate an
error state.
For the wet steam region, the ASME routines use the Clapeyron equation and the saturated
vapor values to compute the result. For the VPH and VPS functions, the computed volume
can differ by a few percents as compared to the volume calculated from the saturated vapor
volume, saturated liquid volume and the vapor fraction. The difference in the computed
volume increases as the moisture content of the vapor mixture increases. However, since the
practical use of the steam function involves steam with vapor fraction higher than 0.5, the
ASME equation is not modified.
For the HPS and SPH functions in the wet steam region, the ASME routines use the equation
(Hvap = T*Svap) and the saturated vapor values to compute the result. The functions do not
check if the input enthalpy or entropy is less than those of the saturated liquid and the
extrapolated value is returned.
For the TPH and TPS function in the wet steam region, the ASME routines just check
whether the input enthalpy or entropy is less than that of the saturated vapor at the given
pressure. If the input enthalpy or entropy is less than the saturated vapor value, the saturated

158
 Steam Property Reference States

temperature is returned as the answer. The functions do not consider the case where the input
enthalpy or input entropy is less than that of the saturated liquid an error state.
Similarly, for the XPH and XPS functions, the ASME routines do not consider the input
enthalpy or entropy out of bound even when they are greater than saturated vapor properties
or less than saturated liquid properties. The functions return 1.0 as the vapor fraction when
the input enthalpy or entropy is greater than the saturated vapor properties. Input enthalpy or
entropy less than the saturated liquid properties results in negative vapor fraction rather than
an error state.
Though the ASME routines have inadequate checks for the wet steam region, OSIsoft did not
modify these routines because in reality, the steam functions are not used in regions where
the input checks would cause a problem.
One final feature, for pressure above the critical point (3208.2 psia), the VPH, VPS, HPS,
SPH, TPH and TPS functions compute valid results for states corresponded to temperature
greater than 682 degrees F. but less than the critical temperature, 705.47 degrees F, even
though these states are considered compressed water rather than steam.

Steam Property Reference States

The ASME establishes the following reference states:

Triple Point

Triple point of water is at 273.16 degree K or 0.01 degree C or 0.018 degree F.

Celsius Scale

The Celsius temperature is exactly Tk - 273.15.

Critical Point

Critical point of steam is at 647.3 degree K and 22,120 kpa, or 705.47 degree F and 3208.3
psia.

Reference State

The specific internal energy and specific entropy of the liquid phase were fixed at zero at the
triple point of water.

Steam Functions Reference

This section provides a detailed reference of Steam Functions.

PI Server Applications User Guide 159

PI Steam Functions Reference

StmEng_TsatP

Calculates the saturation temperature as a function of pressure—all variables expressed in

English units.

Format
StmEng_TsatP(P)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.

Returns
Computed saturation temperature in degrees F. or Error digital state.

Sample Values
Pressure Temperature
10. 193.21
100. 327.82
1000. 544.58

StmEng_HsatP

Calculates the saturated vapor specific enthalpy as a function of pressure—all variables

expressed in English units.

Format
StmEng_HsatP(P)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.

Returns
Computed specific enthalpy for saturated vapor in BTU/lbm or Error digital state.

160
 Steam Functions Reference

Sample Values
Pressure Vapor Enthalpy
10. 1143.4
100. 1187.2
1000. 1192.9

StmEng_SsatP

Calculates the saturated vapor specific entropy as a function of pressure—all variables

expressed in English units.

Format
StmEng_SsatP(P)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.

Returns
Computed saturated vapor specific entropy in BTU/lbm/R or Error digital state.

Sample Values
Pressure Entropy
10. 1.7879
100. 1.6027
1000. 1.3910

StmEng_VsatP

Calculates the saturated vapor specific volume as a function of pressure—all variables

expressed in English units.

Format
StmEng_VsatP(P)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.

PI Server Applications User Guide 161

PI Steam Functions Reference

Returns
Saturated vapor specific volume in ft3/lbm or Error digital state.

Sample Values
Pressure Volume
10. 38.42
100. 4.431
1000. 0.44596

StmEng_PsatT

Calculates the saturation pressure as a function of temperature—all variables expressed in

English units.

Format
StmEng_PsatT(T)

Arguments
T

Steam temperature in degree F. The valid range is 32 to 705.47 degree F.

Returns
Computed saturation pressure of the steam in psia or Error digital state.

Sample Values
Temperature Pressure
100. 0.9492
400. 247.26
700. 3094.33

StmEng_HsatT

Calculates the saturated vapor specific enthalpy as a function of temperature—all variables

expressed in English units.

162
 Steam Functions Reference

Format
StmEng_HsatT(T)

Arguments
T

Steam temperature in degree F. The valid range is 32 to 705.47 degree F.

Returns
Computed specific enthalpy for saturated vapor in BTU/lbm or Error digital state.

Sample Values
Temperature Vapor Enthalpy
100. 1105.1
400. 1201.0
700. 995.2

StmEng_SsatT

Calculates the saturated vapor specific entropy as a function of temperature—all variables

expressed in English units.

Format
StmEng_SsatT(T)

Arguments
T

Steam temperature in degree F. The valid range is 32 to 705.47 degree F.

Returns
Computed saturated vapor specific entropy in BTU/lbm/R or- Error digital state.

Sample Values
Temperature Entropy
100. 1.9825
400. 1.52735
700. 1.1390

PI Server Applications User Guide 163

PI Steam Functions Reference

StmEng_VsatT

Calculates the saturated vapor specific volume as a function of temperature—all variables

expressed in English units.

Format
StmEng_VsatT(T)

Arguments
T

Steam temperature in degree F. The valid range is 32 to 705.47 degree F

Returns
Computed saturated vapor specific volume in ft3/lbm or Error digital state

Sample Values
Temperature Volume
100. 350.39
400. 1.863
700. 0.0752

StmEng_VPT

Calculates the vapor specific volume as a function of pressure and temperature—all variables
expressed in English units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) returns for input temperature lower than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.

Format
StmEng_VPT(P, T)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T

Steam temperature in degree F. The valid range is 32 to 1600 degree F.

164
 Steam Functions Reference

Returns
Computed vapor specific volume in ft3/lbm or Error digital state.

Sample Values
Pressure Temperature Volume
300. 1000. 2.8585
800. 1000. 1.047
1400. 1000. 0.5809
5000. 1000. 0.13118

StmEng_VPTL

Calculates the liquid specific volume as a function of pressure and temperature—all variables
expressed in English units. Only use for liquid water condition. An error of -1 (or input out of
range digital state) returns for input temperature higher than the saturation temperature for
the input pressure. However, the function computes for the full range of temperature for input
pressure greater than the critical pressure.

Format
StmEng_VPTL(P, T)

Arguments
P

Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T

Water temperature in degree F. The valid range is 32 to 1600 degree F.

Returns
Computed liquid specific volume in ft3/lbm or Error digital state.

Sample Values
Pressure Temperature Volume
300. 100. 0.016115
800. 100. 0.016091
1400. 100. 0.016062
5000. 100. 0.015897

PI Server Applications User Guide 165

PI Steam Functions Reference

StmEng_VPH

Calculates the vapor specific volume as a function of pressure and enthalpy—all variables
expressed in English units. Use for both superheated or wet steam.

Format
StmEng_VPH(P, H)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H

Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.

Returns
Computed vapor specific volume in ft3/lbm or Error digital state.

Sample Values
Pressure Enthalpy Volume State
300. 1526.2 2.8585 Superheated
800. 1511.4 1.047 Superheated
1400. 1493.2 0.5809 Superheated
5000. 1364.6 0.13118 Superheated
300. 1122. 1.3904 90 % vapor

Note: The computed result may differ slightly from that computed using the saturated
liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.

StmEng_VPS

Calculates the vapor specific volume as a function of pressure and entropy—all variables
expressed in English units. Use for both superheated or wet steam.

Format
StmEng_VPS(P, S)

166
 Steam Functions Reference

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S

Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.

Returns
Computed vapor specific volume in ft3/lbm or Error digital state.

Sample Values
Pressure Entropy Volume State
300. 1.7964 2.8585 Superheated
800. 1.6807 1.047 Superheated
1400. 1.6096 0.5809 Superheated
5000. 1.4001 0.13118 Superheated
300. 1.4183 1.3904 90 % vapor

Note: The computed result may differ slightly from that computed using the saturated
liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.

StmEng_HPT

Calculates the vapor specific enthalpy as a function of pressure and temperature—all

variables expressed in English units. Only use for superheated or dry saturated steam. An
error of -1 (or input out of range digital state) returns for input temperature lower than the
saturation temperature for the input pressure. However, the function computes for the full
range of temperature for input pressure greater than the critical pressure.

Format
StmEng_HPT(P, T)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T

Steam temperature in degree F. The valid range is 32 to 1600 degree F.

PI Server Applications User Guide 167

PI Steam Functions Reference

Returns
Computed vapor specific enthalpy in BTU/lbm or Error digital state.

Sample Values
Pressure Temperature Enthalpy
300. 1000. 1526.2
800. 1000. 1511.4
1400. 1000. 1493.2
5000. 1000. 1364.6

StmEng_HPTL

Calculates the liquid specific enthalpy as a function of pressure and temperature—all

variables expressed in English units. Only use for compressed water. An error of -1 (or input
out of range digital state) returns for input temperature higher than the saturation temperature
for the input pressure. However, the function computes for the full range of temperature for
input pressure greater than the critical pressure.

Format
StmEng_HPTL(P, T)

Arguments
P

Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T

Water temperature in degree F. The valid range is 32 to 1600 degree F.

Returns
Computed liquid specific enthalpy in BTU/lbm or Error digital state.

Sample Values
Pressure Temperature Enthalpy
300. 100. 68.788
800. 100. 70.106
1400. 100. 71.684
5000. 100. 81.081

168
 Steam Functions Reference

StmEng_HPS

Calculates the vapor specific enthalpy as a function of pressure and entropy—all variables
expressed in English units. Use for both superheated or wet steam.

Format
StmEng_HPS(P, S)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S

Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.

Returns
Computed vapor specific enthalpy in BTU/lbm or Error digital state.

Sample Values
Pressure Entropy Enthalpy State
300. 1.7964 1526.2 Superheated
800. 1.6807 1511.4 Superheated
1400. 1.6096 1493.2 Superheated
5000. 1.4001 1364.6 Superheated
300. 1.4183 1122. 90 % vapor

Note: Even if the input entropy is less than that of the saturated liquid, the function still
computes the enthalpy by extrapolation without setting an error state.

StmEng_SPT

Calculates the vapor specific entropy as a function of pressure and temperature—all variables
expressed in English units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) returns for input temperature lower than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.

Format
StmEng_SPT(P, T)

PI Server Applications User Guide 169

PI Steam Functions Reference

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
T

Steam temperature in degree F. The valid range is 32 to 1600 degree F.

Returns
Computed vapor specific entropy in BTU/lbm/R or- Error digital state.

Sample Values
Pressure Temperature Entropy
300. 1000. 1.7964
800. 1000. 1.6807
1400. 1000. 1.6096
5000. 1000. 1.4001

StmEng_SPTL

Calculates the liquid specific entropy as a function of pressure and temperature—all variables
expressed in English units. Only use for compressed water. An error of -1 (or input out of
range digital state) returns for input temperature higher than the saturation temperature for
the input pressure. However, the function computes for the full range of temperature for input
pressure greater than the critical pressure.

Format
StmEng_SPTL(P, T)

Arguments
P

Pressure of the water in psia. The valid range is 0.088589 to 16000 psia.
T

Water temperature in degree F. The valid range is 32 to 1600 degree F.

Returns
Computed liquid specific entropy in BTU/lbm/R or- Error digital state.

170
 Steam Functions Reference

Sample Values
Pressure Temperature Entropy
300. 100. 0.12936
800. 100. 0.12905
1400. 100. 0.12868
5000. 100. 0.12645

StmEng_SPH

Calculates the vapor specific entropy as a function of pressure and enthalpy—all variables
expressed in English units. Use for both superheated or wet steam.

Format
StmEng_SPH(P, H)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H

Computed vapor specific enthalpy in BTU/lbm. The valid range is -1.0 to 1860 BTU/lbm.

Returns
Computed vapor specific entropy in BTU/lbm/R or- Error digital state.

Sample Values
Pressure Enthalpy Entropy State

300. 1526.2 1.7964 Superheated

800. 1511.4 1.6807 Superheated

1400. 1493.2 1.6096 Superheated

5000. 1364.6 1.4001 Superheated

300. 1122. 1.4183 90 % vapor

Note: Even if the input enthalpy is less than that of the saturated liquid, the function still
computes the entropy by extrapolation without setting an error state.

PI Server Applications User Guide 171

PI Steam Functions Reference

StmEng_TPH

Calculates the steam temperature as a function of pressure and enthalpy—all variables

expressed in English units. Use for both superheated or wet steam.

Format
StmEng_TPH(P, H)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
H

Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.

Returns
Computed steam temperature in degree F. or Error digital state.

Sample Values
Pressure Enthalpy Temperature State
300. 1526.2 1000. Superheated
800. 1511.4 1000. Superheated
1400. 1493.2 1000. Superheated
5000. 1364.6 1000. Superheated
300. 1122. 417.35 90 % vapor

Note: Even if the input enthalpy is less than that of the saturated liquid, the function still
returns the saturated temperature as the answer without setting an error state.

StmEng_TPS

Calculates the steam temperature as a function of pressure and entropy—all variables

expressed in English units. Use for both superheated or wet steam.

Format
StmEng_TPS(P, S)

172
 Steam Functions Reference

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 16000 psia.
S

Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R.

Returns
Computed steam temperature in degree F. or Error digital state.

Sample Values
Pressure Entropy Temperature State
300. 1.7964 1000. Superheated
800. 1.6807 1000. Superheated
1400. 1.6096 1000. Superheated
5000. 1.4001 1000. Superheated
300. 1.4183 417.35 90 % vapor

Note: Even if the input entropy is less than that of the saturated liquid, the function still
returns the saturated temperature as the answer without setting an error state.

StmEng_XPH

Calculates the steam quality (vapor fraction) as a function of pressure and enthalpy—all
variables expressed in English units. Use only for wet steam.

Format
StmEng_XPH(P, H)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
H

Specific enthalpy of the steam in BTU/lbm. The valid range is -1 to 1860 BTU/lbm.

Returns
Computed steam quality (vapor fraction) or Error digital state.

PI Server Applications User Guide 173

PI Steam Functions Reference

Sample Values
Pressure Enthalpy Steam Quality
300. 1122.0 0.9
800. 1130.4 0.9
1400. 1117.7 0.9

Note: If the input enthalpy is greater than that of the saturated vapor, the function returns
1.0 as vapor fraction. If the input enthalpy is less than that of the saturated liquid,
the function would compute negative vapor fraction without setting an error state.

StmEng_XPS

Calculates the steam quality (vapor fraction) as a function of pressure and entropy—all
variables expressed in English units. Use only for wet steam.

Format
StmEng_XPS(P, S)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
S

Specific entropy of the steam in BTU/lbm/R. The valid range is -0.1 to 3.0 BTU/lbm/R or
Error digital state.

Returns
Computed steam quality (vapor fraction).

Sample Values
Pressure Entropy Steam Quality
300. 1.4183 0.9
800. 1.3458 0.9
1400. 1.2923 0.9

Note: If the input entropy is greater than that of the saturated vapor, the function returns
1.0 as vapor fraction. If the input entropy is less than that of the saturated liquid,
the function would compute negative vapor fraction without setting an error state.

174
 Steam Functions Reference

StmEng_HPX

Calculates the steam specific enthalpy as a function of pressure and quality (vapor fraction)—
all variables expressed in English units. Use only for wet steam.

Format
StmEng_HPX(P, X)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
X

Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.

Returns
Computed specific enthalpy of the steam in BTU/lbm or Error digital state.

Sample Values
Pressure Steam Quality Enthalpy
300. 0.9 1122.0
800. 0.9 1130.4
1400. 0.9 1117.7

StmEng_SPX

Calculates the steam specific entropy as a function of pressure and quality (vapor fraction)—
all variables expressed in English units. Use only for wet steam.

Format
StmEng_SPX(P, X)

Arguments
P

Pressure of the steam in psia. The valid range is 0.088589 to 3208.2 psia.
X

Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.

PI Server Applications User Guide 175

PI Steam Functions Reference

Returns
Computed specific entropy of the steam in BTU/lbm/R or- Error digital state.

Sample Values
Pressure Steam Quality Entropy
300. 0.9 1.4183
800. 0.9 1.3458
1400. 0.9 1.2923

StmSI_TsatP

Calculates the saturation temperature as a function of pressure—all variables expressed in SI

units.

Format
StmSI_TsatP(P)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.

Returns
Computed saturation temperature in degree C. or Error digital state.

Sample Values
Pressure Temperature
50. 81.345
1000. 179.88
10000. 310.96

StmSI_HsatP

Calculates the saturated vapor specific enthalpy as a function of pressure—all variables

expressed in SI units.

Format
StmSI_HsatP(P)

176
 Steam Functions Reference

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.

Returns
Computed specific enthalpy for saturated vapor in J/g.

Sample Values
Pressure Vapor Enthalpy
50. 2646.0
1000. 2776.2
10000. 2727.7

StmSI_SsatP

Calculates the saturated vapor specific entropy as a function of pressure—all variables

expressed in SI units.

Format
StmSI_SsatP(P)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.

Returns
Computed saturated vapor specific entropy in J/g/K or Error digital state.

Sample Values
Pressure Entropy
50. 7.5947
1000. 6.5828
10000. 5.6198

PI Server Applications User Guide 177

PI Steam Functions Reference

StmSI_VsatP

Calculates the saturated vapor specific volume as a function of pressure—all variables

expressed in SI units.

Format
StmSI_VsatP(P)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.

Returns
Computed saturated vapor specific volume in cc/g or Error digital state.

Sample Values
Pressure Volume
50. 3240.2
1000. 194.29
10000. 18.041

StmSI_PsatT

Calculates the saturation pressure as a function of temperature—all variables expressed in SI

units.

Format
StmSI_PsatT(T)

Arguments
T

Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.

Returns
Computed saturation pressure of the steam in kpa or Error digital state.

178
 Steam Functions Reference

Sample Values
Temperature Pressure
50. 12.335
200. 1554.9
350. 16535.

StmSI_HsatT

Calculates the saturated vapor specific enthalpy as a function of temperature—all variables

expressed in SI units.

Format
StmSI_HsatT(T)

Arguments
T

Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.

Returns
Computed specific enthalpy for saturated vapor in J/g or Error digital state.

Sample Values
Temperature Vapor Enthalpy
50. 2592.2
200. 2790.9
350. 2567.7

StmSI_SsatT

Calculates the saturated vapor specific entropy as a function of temperature—all variables

expressed in SI units.

Format
StmSI_SsatT(T)

Arguments
T

Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C.

PI Server Applications User Guide 179

PI Steam Functions Reference

Returns
Computed saturated vapor specific entropy in J/g/K or Error digital state.

Sample Values
Temperature Entropy
50. 8.0776
200. 6.4278
350. 5.2177

StmSI_VsatT

Calculates the saturated vapor specific volume as a function of temperature—all variables

expressed in SI units.

Format
StmSI_VsatT(T)

Arguments
T

Steam temperature in degree C. The valid range is 0.0 to 374.15 degree C

Returns
Computed saturated vapor specific volume in cc/g or Error digital state.

Sample Values
Temperature Volume
50. 12046.
200. 127.16
350. 8.7991

StmSI_VPT

Calculates the vapor specific volume as a function of pressure and temperature—all variables
expressed in SI units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) returns for input temperature lower than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.

180
 Steam Functions Reference

Format
StmSI_VPT(P, T)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.

Returns
Computed vapor specific volume in cc/g or Error digital state.

Sample Values
Pressure Temperature Volume
2500. 600. 159.21
5000. 600. 78.616
10000. 600. 38.320
40000. 600. 8.0884

StmSI_VPTL

Calculates the liquid specific volume as a function of pressure and temperature—all variables
expressed in SI units. Only use for compressed water. An error of -1 (or input out of range
digital state) returns for input temperature higher than the saturation temperature for the input
pressure. However, the function computes for the full range of temperature for input pressure
greater than the critical pressure.

Format
StmSI_VPTL(P, T)

Arguments
P

Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.

Returns
Computed liquid specific volume in cc/g or Error digital state.

PI Server Applications User Guide 181

PI Steam Functions Reference

Sample Values
Pressure Temperature Volume
2500. 100. 1.04245
5000. 100. 1.04116
10000. 100. 1.03861
40000. 100. 1.02438

StmSI_VPH

Calculates the vapor specific volume as a function of pressure and enthalpy—all variables
expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_VPH(P, H)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H

Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.

Returns
Computed vapor specific volume in cc/g or Error digital state.

Sample Values
Pressure Enthalpy Volume State
2500. 3685.1 159.21 Superheated
5000. 3664.5 78.616 Superheated
10000. 3622.7 38.320 Superheated
40000. 3346.4 8.0884 Superheated
2500. 2617.0 72.04 90 % vapor

Note: The computed result may differ slightly from that computed using the saturated
liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.

182
 Steam Functions Reference

StmSI_VPS

Calculates the vapor specific volume as a function of pressure and entropy—all variables
expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_VPS(P, S)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S

Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.

Returns
Computed vapor specific volume in cc/g or Error digital state.

Sample Values
Pressure Entropy Volume State
2500. 7.5956 159.21 Superheated
5000. 7.2578 78.616 Superheated
10000. 6.9013 38.320 Superheated
40000. 6.0135 8.0884 Superheated
2500. 5.8837 72.04 90 % vapor

Note: The computed result may differ slightly from that computed using the saturated
liquid volume, saturated vapor volume and vapor fraction. The difference
increases with the moisture content of the steam.

StmSI_HPT

Calculates the vapor specific enthalpy as a function of pressure and temperature—all

variables expressed in SI units. Only use for superheated or dry saturated steam. An error of
-1 (or input out of range digital state) returns for input temperature lower than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.

PI Server Applications User Guide 183

PI Steam Functions Reference

Format
StmSI_HPT(P, T)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.

Returns
Computed vapor specific enthalpy in J/g or Error digital state.

Sample Values
Pressure Temperature Enthalpy
2500. 600. 3685.1
5000. 600. 3664.5
10000. 600. 3622.7
40000. 600. 3346.4

StmSI_HPTL

Calculates the liquid specific enthalpy as a function of pressure and temperature—all

variables expressed in SI units. Only use for compressed water. An error of -1 (or input out of
range digital state) returns for input temperature higher than the saturation temperature for
the input pressure. However, the function computes for the full range of temperature for input
pressure greater than the critical pressure.

Format
StmSI_HPTL(P, T)

Arguments
P

Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.

184
 Steam Functions Reference

Returns
Computed liquid specific enthalpy in J/g or Error digital state.

Sample Values
Pressure Temperature Enthalpy
2500. 100. 420.86
5000. 100. 422.74
10000. 100. 426.50
40000. 100. 449.22

StmSI_HPS

Calculates the vapor specific enthalpy as a function of pressure and entropy—all variables
expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_HPS(P, S)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S

Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.

Returns
Computed vapor specific enthalpy in J/g or Error digital state.

Sample Values
Pressure Entropy Enthalpy State
2500. 7.5956 3685.1 Superheated
5000. 7.2578 3664.5 Superheated
10000. 6.9013 3622.7 Superheated
40000. 6.0135 3346.4 Superheated
2500. 5.8837 2617.0 90 % vapor

Note: Even if the input entropy is less than that of the saturated liquid, the function still
computes the enthalpy by extrapolation without setting an error state.

PI Server Applications User Guide 185

PI Steam Functions Reference

StmSI_SPT

Calculates the vapor specific entropy as a function of pressure and temperature—all variables
expressed in SI units. Only use for superheated or dry saturated steam. An error of -1 (or
input out of range digital state) returns for input temperature lower than the saturation
temperature for the input pressure. However, the function computes for the full range of
temperature for input pressure greater than the critical pressure.

Format
StmSI_SPT(P, T)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Steam temperature in degree C. The valid range is 0.0 to 871.11 degree C.

Returns
Computed vapor specific entropy in J/g/K or Error digital state.

Sample Values
Pressure Temperature Entropy
2500. 600. 7.5956
5000. 600. 7.2578
10000. 600. 6.9013
40000. 600. 6.0135

StmSI_SPTL

Calculates the liquid specific entropy as a function of pressure and temperature—all variables
expressed in SI units. Only use for compressed water. An error of -1 (or input out of range
digital state) returns for input temperature higher than the saturation temperature for the input
pressure. However, the function computes for the full range of temperature for input pressure
greater than the critical pressure.

Format
StmSI_SPTL(P, T)

186
 Steam Functions Reference

Arguments
P

Pressure of the water in kpa. The valid range is 0.6108 to 110316.0 kpa.
T

Water temperature in degree C. The valid range is 0.0 to 871.11 degree C.

Returns
Computed liquid specific entropy in J/g/K or Error digital state.

Sample Values
Pressure Temperature Entropy
2500. 100. 1.305
5000. 100. 1.30304
10000. 100. 1.29919
40000. 100. 1.27714

StmSI_SPH

Calculates the vapor specific entropy as a function of pressure and enthalpy—all variables
expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_SPH(P, H)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H

Computed vapor specific enthalpy in J/g. The valid range is -2.326 to 4326.36 J/g.

Returns
Computed vapor specific entropy in J/g/K or Error digital state.

PI Server Applications User Guide 187

PI Steam Functions Reference

Sample Values
Pressure Enthalpy Entropy State
2500. 3685.1 7.5956 Superheated
5000. 3664.5 7.2578 Superheated
10000. 3622.7 6.9013 Superheated
40000. 3346.4 6.0135 Superheated
2500. 2617.0 5.8837 90 % vapor

Note: Even if the input enthalpy is less than that of the saturated liquid, the function still
computes the entropy by extrapolation without setting an error state.

StmSI_TPH

Calculates the steam temperature as a function of pressure and enthalpy—all variables

expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_TPH(P, H)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
H

Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.

Returns
Computed steam temperature in degree C. or Error digital state.

Sample Values
Pressure Enthalpy Temperature State
2500. 3685.1 600. Superheated
5000. 3664.5 600. Superheated
10000. 3622.7 600. Superheated
40000. 3346.4 600. Superheated
2500. 2617.0 223.94 90 % vapor

Note: Even if the input enthalpy is less than that of the saturated liquid, the function still
returns the saturated temperature as the answer without setting an error state.

188
 Steam Functions Reference

StmSI_TPS

Calculates the steam temperature as a function of pressure and entropy—all variables

expressed in SI units. Use for both superheated or wet steam.

Format
StmSI_TPS(P, S)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 110316.0 kpa.
S

Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.

Returns
Computed steam temperature in degree C. or Error digital state.

Sample Values
Pressure Entropy Temperature State
2500. 7.5956 600. Superheated
5000. 7.2578 600. Superheated
10000. 6.9013 600. Superheated
40000. 6.0135 600. Superheated
2500. 5.8837 223.94 90 % vapor

Note: Even if the input entropy is less than that of the saturated liquid, the function still
returns the saturated temperature as the answer without setting an error state.

StmSI_XPH

Calculates the steam quality (vapor fraction) as a function of pressure and enthalpy—all
variables expressed in SI units. Use only for wet steam.

Format
StmSI_XPH(P, H)

PI Server Applications User Guide 189

PI Steam Functions Reference

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
H

Specific enthalpy of the steam in J/g. The valid range is -2.326 to 4326.36 J/g.

Returns
Computed steam quality (vapor fraction) or Error digital state.

Sample Values
Pressure Enthalpy Steam Quality
2500. 2617.0 0.9
5000. 2630.2 0.9
10000. 2595.8 0.9

Note: If the input enthalpy is greater than that of the saturated vapor, the function returns
1.0 as vapor fraction. If the input enthalpy is less than that of the saturated liquid,
the function would compute negative vapor fraction without setting an error state.

StmSI_XPS

Calculates the steam quality (vapor fraction) as a function of pressure and entropy—all
variables expressed in SI units. Use only for wet steam.

Format
StmSI_XPS(P, S)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
S

Specific entropy of the steam in J/g/K. The valid range is -0.41868 to 12.5604 J/g/K.

Returns
Computed steam quality (vapor fraction) or Error digital state.

190
 Steam Functions Reference

Sample Values
Pressure Entropy Steam Quality
2500. 5.8837 0.9
5000. 5.6682 0.9
10000. 5.3939 0.9

Note: If the input entropy is greater than that of the saturated vapor, the function returns
1.0 as vapor fraction. If the input entropy is less than that of the saturated liquid,
the function would compute negative vapor fraction without setting an error state.

StmSI_HPX

Calculates the steam specific enthalpy as a function of pressure and quality (vapor fraction)—
all variables expressed in SI units. Use only for wet steam.

Format
StmSI_HPX(P, X)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
X

Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.

Returns
Computed specific enthalpy of the steam in J/g or Error digital state.

Sample Values
Pressure Steam Quality Enthalpy
2500. 0.9 2617.0
5000. 0.9 2630.2
10000. 0.9 2595.8

StmSI_SPX

Calculates the steam specific entropy as a function of pressure and quality (vapor fraction)—
all variables expressed in SI units. Use only for wet steam.

PI Server Applications User Guide 191

PI Steam Functions Reference

Format
StmSI_SPX(P, X)

Arguments
P

Pressure of the steam in kpa. The valid range is 0.6108 to 22119.8 kpa.
X

Steam quality (vapor fraction). Valid range is from 0.0 to 1.0.

Returns
Computed specific entropy of the steam in J/g/K or Error digital state.

Sample Values
Pressure Steam Quality Entropy
2500. 0.9 5.8837
5000. 0.9 5.6682
10000. 0.9 5.3939

192
Chapter 6

PI Batch Database
Most processes have repeatable time segments or stages. The PI Batch Subsystem maps
process or manufacturing events to slices of time and data, and stores these batch- and
process-based events hierarchically in the PI Data Archive as Batches, Unit Batches, or Sub
Batches. This capability enables powerful data and process analysis for both traditional and
non-traditional batch processes.
Many manufacturing companies find it useful to track their products in discrete batches rather
than as a time-continuous product. PI Batch can define and record sequences such as events
in discrete manufacturing, paper reels, steel coils, product or grade changes, turbine startups,
and lab runs. While industries such as chemicals and pharmaceuticals use PI Batch to track
and analyze batches, it is also widely used in non-batch applications to identify and track
process events. Along with the use of audit trail support, PI Batch and the PI System become
an integral component of a validated reporting environment in compliance with 21 CFR Part
11.
This chapter describes the functionality provided by the PI Batch Subsystem, from
configuration to interaction with the resulting batch data.

PI Batch Overview
Traditional batch applications are common in industries like chemical, food and beverage,
and pharmaceutical manufacturing. Batch processing has also been used in applications in
which a sequence of steps occurs, such as burner startup and shutdown, to determine whether
or not proper sequencing took place. Furthermore, batch processing has been used in
applications that are not typically considered pure batch processes to correlate process data
that has been generated during say an 8-hour shift or a 24-hour time period. Comparison of
various parameters during such shifts or time periods often leads to valuable insight about the
underlying process.
PI Batch is used in conjunction with its companion Client application, PI BatchView, which
allows you to search, select, trend, and compare events that have been collected by PI Batch
and stored in the PI System. Earlier versions of PI BatchView were based on the PI API, and
more recent versions are based on the PI SDK.
Batch activity is indexed on the following parameters:
• Time
• Unit
• Batch ID
• Product ID

PI Server Applications User Guide 193

PI Batch Database

Once the batch activity is recorded, specific batches or groups of batches can be searched and
retrieved. The batch search results may then be used to frame process data from the PI
Archive in the context of the selected batches.

The PI Batch Subsystem (BSS), PI Batch Database (PBD), and PI Batch

Generator (PIBaGen)

• The PI Batch Subsystem (BSS) was introduced with PI Server 3.1. It provides batch
processing functionality: configuration, monitoring, and query processing. It continues to
be installed and supported, but it is no longer the only (or preferred) technology for batch
processing.
For details about the PI Batch Subsystem, read this chapter.
• The PI Batch Database (BDB) was introduced with PI Server 3.3 and PI SDK 1.1. It
provides enhanced batch information processing support.
For details about the PI Batch Database, see the PI SDK User Manual.
• The PI Batch Generator (PIBaGen) Interface was introduced with the PI Batch
Database. It is now included with PI Server Applications. It is a PI SDK-based interface
that reads process unit configuration from the PI Module Database and writes into the PI
Batch Database. The interface monitors the PI Server for events that trigger the beginning
of a batch and then stores information about each batch, such as Batch ID and Product
ID, into the PI Data Archive.
For details about the PI Batch Generator, see the PI Batch Generator (PIBaGen) User
Manual.
• The PI Batch Database and the PI Batch Generator are independent of the PI Batch
Subsystem. All three of these system components may be used in parallel.
For a comparison of the PI Batch Subsystem and PI Batch Database see the PI Batch
Database Support of the PI Batch Subsystem. This document also explains how to access
BSS batches from the BDB, and vice versa.
To search, select, trend, and compare batches of interest, client products such as PI
BatchView are available.

Compatibility of PI API Batch Applications for PI2 (OpenVMS) Servers

PI API batch applications developed against PI BA in a PI2 Server (OpenVMS) still function
correctly when run against a PI3 Server with the PI Batch Subsystem.

194
 Installation

Glossary of Batch Terms

The following Batch terms are used in this chapter.

Term Definition
Batch A batch represents a span of time on a unit.
Unit Defines the name of the equipment set on which the batch activity takes place. Unit
definitions are not limited to a single piece of equipment. For example, a unit could
be a single reactor or a group of reactors and related equipment.
BatchID This is a name given to a batch of material. The BatchID is not required to be unique.
ProductID Describes a specific material or class of materials. This term is used in batch
applications that use equipment to produce a variety of different materials. A
ProductID is not required for a batch definition, but it does provide a useful search
index.

Installation
The PI Batch Subsystem is automatically installed on new installations or upgrades of the PI3
Server, but a valid license is required in order to use it. The pibatch.exe executable is
located in \PI\bin. The installation itself does not result in the creation of any units or
batches, but the installed piconfig script \PI\adm\pibatch.dif can be used to
configure an example unit and enable the creation of sample batches. The pibatch.dif
script is discussed in more detail in Complete Example (page 209).
The PI Batch Subsystem must start first, to configure any units or to create batches. Startup
typically occurs automatically either at boot time or when the PI Server startup script is
executed.

Configuration
All configuration for the PI Batch Subsystem must be performed with the command-line
utility piconfig. See the PI Server System Management Guide for details about using the
piconfig utility.

Unit Configuration

The starting point for all batch configurations is the unit, the piece or set of equipment where
batches occur. The fundamental rules for units are:
• The unit name must be unique.
• The unit may only process one batch at a time.

PI Server Applications User Guide 195

PI Batch Database

PI Batch Unit (PIBAUNIT) Table

The configuration for all units is stored in the data file \PI\dat\pibaunit1.nt and is
accessed exclusively via the piconfig table named PIBAUNIT. The configuration for a unit
involves several attributes of information, and the following list includes each attribute's
name, data type, default value (D:), and current value (C:):
* (Ls - ) PIconfig> @table PIBAUNIT
* (Ls - PIBAUNIT) PIconfig> @?atr
1 - UnitName String D: C:
2 - NEWUnitName String D: C:
3 - ActiveTag String D: C:
4 - ActiveType String D: pulse C:
5 - BIDExpr String D: C:
6 - DataAccess String D: o:rw g:r w:r C:
7 - DataGroup String D: piadmins C:
8 - DataOwner String D: piadmin C:
9 - Description String D: C:
10 - EvalDelay String D: 0 C:
11 - MergeConsecutive String D: 0 C:
12 - ProdExpr String D: C:
13 - UnitAccess String D: o:rw g:r w:r C:
14 - UnitGroup String D: piadmins C:
15 - UnitOwner String D: piadmin C:

The unit attributes are:

Attribute Description
UnitName Defines the unique unit name, which is the primary index of the
PIBAUNIT table. The name cannot include the backslash character (\) but
can be renamed.
NEWUnitName Used to rename an existing unit.
ActiveTag The PI tag that defines whether a batch is active or inactive on this unit.
Two different units cannot have the same batch activation tag.

196
 Configuration

Attribute Description
ActiveType Defines when a batch begins (becomes Active) or ends (becomes
Inactive) on a unit. The transition is a function of the data type and value
of the batch activation tag. The two possible types are:
 Pulse: The Inactive/Active transition occurs according to the following
table. A change in value within the same status range has no effect on
the status of the unit. This is the default type.
ActiveTag data Batch becomes Batch becomes Active
type Inactive
Integer Value = 0 Value <> 0
Digital Value = first digital Value <> first digital state
state
Float -1 < Value < 1 Value <= -1 or Value >=
1
String Value = "" Value <> ""

 Step: Units with this type are normally active: every time the ActiveTag
receives a new value, the current batch is completed and a new batch
is started. New batches cease being created for each new value when
the ActiveTag receives the Stop Value.
ActiveTag data type Stop Value
Integer Value = 0
Digital Value = first digital state
Float -1 < Value < 1
String Value = ""
BIDExpr Defines the expression consisting of PI Tags and text to generate a batch
identifier (BatchID) when a batch starts on a unit. See Rules for Defining
BIDExpr and ProdExpr (page 198) for more details.

ProdExpr Defines the expression consisting of PI tags and text to generate a

product identifier (ProductID) when the batch starts on a unit. See Rules
for Defining BIDExpr and ProdExpr (page 198) for more details.

EvalDelay Delay (default is zero), in seconds, before evaluating BIDExpr and

ProdExpr after the batch starts. If the batch duration is shorter than the
evaluation delay, the BIDExpr and ProdExpr are evaluated when the
batch ends. This attribute is useful if the BatchID and ProductID are not
defined until after the batch starts.

MergeConsecutive If the value of this attribute is non-zero (default is zero) and the
ActiveType is Pulse, consecutive batches with the same BatchID are
considered to be one batch. The first assigned ProductID is used for the
entire batch. This attribute is useful for batches that are halted temporarily
and then restarted before the actual batch completes.
Description A textual description of the unit.

PI Server Applications User Guide 197

PI Batch Database

Attribute Description
DataAccess Similar to tag security, this security attribute controls access to the batch
data for the unit for the owner, group, and world. The format is:
o:access g:access w:access
where access is either "rw" for read-write access, "w" for write-only
access, "r" for read-only access, or "" for no access. The default access
string is
o:rw g:r w:r

DataGroup Indicates which group of PI users can access batch data for the unit. The
default data group is piadmins.

DataOwner Indicates which individual PI user owns the batch data for the unit. The
default data owner is piadmin.

UnitAccess Same as DataAccess, except this controls access to the configuration for
the unit. The default access string is also o:rw g:r w:r.

UnitGroup Indicates which group of PI users can access the configuration for the
unit. The default unit group is piadmins.

UnitOwner Indicates which individual PI user owns the configuration for the unit. The
default unit owner is piadmin.

Rules for Defining BIDExpr and ProdExpr

If only one type of product is made on a given unit, a simple fixed text string will suffice for
ProdExpr. Typically, however, a given unit supports many different products, so the
ProductID must be generated from the value of one or more PI tags when the batch begins.
Similarly, a different BatchID likely must be generated even though it is not required to be
unique.
To generate multiple BatchIDs or ProductIDs requires an expression similar to the following:
" 'R1:PRODA'/4 + \"_\" + 'R1:PRODB'/5 + \"-A\" "

Note: The backslashes preceding the inner double quotes are needed; otherwise, they
would be misinterpreted to be the final double quote of the entire expression.

Such an expression combines the values of the PI tags R1:PRODA and R1:PRODB with
some additional text to generate a product name. Some example values of the PI tags and the
resulting ProductID (or BatchID) are:
R1:PRODA R1:PRODB ProductID
5 765.99 0005_00765-A
BLACK YELLOW BLAC_YELLO-A
ABC XYZ_X ABC _XYZ_X-A
12345 Shutdown ####_Digital State Set-A

The following is a complete list of the syntax rules and limitations for specifying both
BIDExpr and ProdExpr expressions:
• The entire expression must be enclosed in double quotes.

198
 Configuration

• PI points must be enclosed in single quotes.

• Static text strings must be enclosed in double quotes. Backslashes must precede the
double quotes surrounding text strings to prevent misinterpretation of the final double
quote for the entire expression.
• A number following the field size indicator, '/', indicates the number of characters the
field will occupy. A value of 0 or an unspecified field width indicates that all characters
are required.
• The values for integer tags are right-justified and zero-filled if the number of digits is less
than the field size. If the number of integer digits exceeds the field size, the field is filled
with '#'s.
• The values for float tags are truncated and then converted to integers, which means the
field size rules for integers then apply.
• The values for digital or string tags are left-justified and filled with trailing spaces if the
number of characters is less than the field size. If the number of characters exceeds the
field size, the text is truncated.
• If any tag has a bad status, the field is filled with '#'s.
• Any leading or trailing blanks in the resulting BatchID or ProductID are truncated.
• The resulting BatchID or ProductID should not contain the characters *, ?, or \. These
characters interfere with wildcard searches.

Support for Web Processes

The PI Batch Subsystem supports batches for paper machines and other web processes like
textiles and film. For these types of batches, the batch active tag should be of type Step. This
tag may be used to record the sequential batch number on a particular machine (unit), taking
on a new value when a new batch is started. The batch start time is the timestamp of the value
of the tag, and the batch end time is one second before the timestamp of the next value in the
Archive.

Configuration Differences from PI BA in PI2 (OpenVMS)

The PI Batch Subsystem configuration differs from PI BA in PI2 (OpenVMS). The
differences and the reasons for the differences are summarized in the following table.

Configuration Differences from PI BA in PI2 (OpenVMS)

Difference from PI BA in Reason

PI2
Removal of the list of TAG Tag aliases are included in the PI3 Server. Therefore, they are not
aliases for the UNIT. duplicated in the PI Batch Subsystem.
Removal of the STEP and These functions are not supported in the PI Batch Subsystem. Instead,
CYCLETIME tags. this functionality is provided by Performance Equations.

PI Server Applications User Guide 199

PI Batch Database

Difference from PI BA in Reason

PI2
Addition of the type of the The starting and stopping of a batch on a unit is indicated by the value
batch active tag of the unit's batch active tag.
 For PI BA in PI2, all of the batch active tags were of type pulse. That
is, when the value of the batch active tag is 0 (or its digital equivalent)
the unit is considered inactive. When the batch active tag is 1 (or its
digital equivalent), the unit is considered active.
 Batch active tags of type Step are not restricted to the values of 0
and 1. To support web processes, described above, the batch active
tag takes on a new value when a batch is started, ending the
previous batch.

Common Operations
The following sections demonstrate the common tasks of creating, listing, renaming, editing,
and deleting units.

Create Units
The only attributes with default values are: ActiveType, EvalDelay, MergeConsecutive, and
the security attributes (DataAccess, DataGroup, DataOwner, UnitAccess, UnitGroup,
UnitOwner). If the default values for these attributes are acceptable, then these attributes do
not have to be specified when creating new units. The following piconfig commands create
the unit TestUnit using the default attribute values:
* (Ls - ) PIconfig> @table PIBAUNIT
* (Ls - PIBAUNIT) PIconfig> @mode create
* (Cr - PIBAUNIT) PIconfig> @istr
unitname,activetag,bidexpr,prodexpr, description
* (Cr - PIBAUNIT) PIconfig>
TestUnit,TestUnitTrigger,"\"TestUnitBID\"",
"\"TestUnitPID\"","This is a test unit."
*>
TestUnit,TestUnitTrigger,"\"TestUnitBID\"","\"TestUnitPID\"","Thi
s is a test unit."

When a new unit is created, a unique PI point (such as piba36) is created to store batch data
in the Archive just for that particular unit. One easy way to determine the name of this point,
which may be needed during troubleshooting, is to examine the PI Server Message Log at the
time the unit is created for a message similar to:
0 pipoints 27-Nov-05 22:46:27
>> Point Added by User (1) piadmin, piba36, PtId: 8406, RecNo:
4283

Security
Access to the unit configuration and batch data in the PI Batch Subsystem is controlled
through the PIBATCHLEGACY entry of the PI Database Security table.

200
 Configuration

List Units
Use the following piconfig commands to list all the attributes for TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode list
* (Ls - PIBAUNIT) PIconfig> @ostr *
* (Ls - PIBAUNIT) PIconfig> @select unitname=TestUnit
* (Ls - PIBAUNIT) PIconfig> @ends
TestUnit,TestUnitTrigger,pulse,"TestBID",o:rw g:r
w:r,piadmin,piadmins, This is a test unit.,0,0,"TestPID",o:rw g:r
w:r,piadmin,piadmins

Rename Units
Renaming units requires the use of the NEWUnitName attribute in edit mode. The following
piconfig commands rename TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode edit
* (Ed - PIBAUNIT) PIconfig> @istr unitname,newunitname
* (Ed - PIBAUNIT) PIconfig> TestUnit,TestUnit1
*> TestUnit,TestUnit1

Because a unit's name is not used to store the actual batch data, renaming a unit is wholly
transparent to batch data searches and retrieval.

Edit Units
Any unit attribute except for UnitName can be edited directly using the attribute's name. The
following piconfig commands will edit the security attributes DataAccess and UnitAccess for
TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode edit
* (Ed - PIBAUNIT) PIconfig> @istr unitname,dataaccess,unitaccess
* (Ed - PIBAUNIT) PIconfig> TestUnit,"o:rw g:rw w:","o:rw g:rw
w:"
*> TestUnit,"o:rw g:rw w:","o:rw g:rw w:"

Editing a unit will also result in editing of the unique PI point (such as piba36) used to store
the unit's batch data in the archive. Examining the PI Server message log around the time of a
unit edit should yield a message similar to:
0 pipoints 27-Nov-05 23:17:22
>> Point Edited by User (1) piadmin, piba36, Point Id: 8406

Delete Units
We do not recommend deleting units, especially those that have valid batch data.
Nevertheless, the following piconfig commands will delete TestUnit:
* (Ls - ) PIconfig> @table pibaunit
* (Ls - PIBAUNIT) PIconfig> @mode delete
* (Dl - PIBAUNIT) PIconfig> @istr unitname
* (Dl - PIBAUNIT) PIconfig> TestUnit

PI Server Applications User Guide 201

PI Batch Database

*> TestUnit

In case of user error, deleting a unit does not automatically result in the deletion of the unique
PI point used to store the unit's batch data in the Archive. Instead, the batch data storage point
is simply renamed. Examining the PI Server Message Log around the time of a unit deletion
should yield a message similar to:
0 pipoints 27-Nov-05 23:30:04
>> Point Renamed by User (1) piadmin, New Tag piba36_del, Old Tag
piba36, PointId: 8406

To completely delete the unit and all of its batch data would require the second manual step
of deleting the renamed batch data storage point (such as piba36_del) for that particular unit.

Alias Configuration

PI points are often named to reflect the instrument data source in order to provide an obvious
mapping between the two. However, in practice, except possibly for the instrument or process
engineers, it is much easier to reference a particular attribute by its unit name and common
name. Furthermore, in many cases, the unit name is implied, so the common name itself is an
unambiguous reference to the physical attribute.
For example, a plant may have three very similar reactors with the same three important
attributes: level, temperature, and flow. The corresponding PI points for the attributes would
be different for each reactor.
Unit Name Common Attribute Name PI Point Name
Reactor1 Level LIC:129732.PV
Reactor1 Temperature TIC:135432.PV
Reactor1 Flow FIC:245433.PV
Reactor2 Level LIC:297324.PV
Reactor2 Temperature TIC:254326.PV
Reactor2 Flow FIC:245432.PV
Reactor3 Level LIC:397321.PV
Reactor3 Temperature TIC:354399.PV
Reactor3 Flow FIC:345439.PV

Aliases in the PI Batch Subsystem provide the mechanism to enable the more natural
reference to an attribute's common name instead of the more obscure instrument name.

PI Batch Alias (PIBAALIAS) Table

The configuration for all aliases is stored in the data file \PI\dat\pibaalias.nt and is
accessed exclusively via the piconfig table named PIBAALIAS. Compared to unit
configuration, alias configuration is simple, involving only a couple of attributes listed below.
The list includes each attribute's name, data type, default value (D:), and current value (C:).
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @?atr

202
 Configuration

1 - Alias String D: C:
2 - NEWAlias String D: C:
3 - Tag String D: C:

The alias attributes are:

Attribute Description
Alias The alias name has two components, unit name and common name. The
syntax for an alias is:
\\unit name\common name
The unit name must correspond to an existing unit in the PIBAUNIT table.
NEWAlias Used to rename an existing alias.
Tagname The name of the PI point associated with the alias. The PI point must already
exist.

Common Operations
The following sections demonstrate the common tasks of creating, listing, renaming, editing,
and deleting aliases.

Create Aliases
The following piconfig commands will create three aliases on unit Reactor1, one for each of
the attributes level, temperature, and flow:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode create
* (Cr - PIBAALIAS) PIconfig> @istr alias,tagname
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\level,LIC:129732.PV
*> \\Reactor1\level,LIC:129732.PV
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\temperature,TIC:135432.PV
*> \\Reactor1\temperature,TIC:135432.PV
* (Cr - PIBAALIAS) PIconfig> \\Reactor1\flow,FIC:245433.PV
*> \\Reactor1\flow,FIC:245433.PV

List Aliases
Because aliases include the unit name, a wildcard (default: '*') is often used to select or list
specific aliases. The following piconfig commands list all aliases defined for Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode list
* (Ls - PIBAALIAS) PIconfig> @ostr alias,tagname
* (Ls - PIBAALIAS) PIconfig> @select alias=\\Reactor1\*
* (Ls - PIBAALIAS) PIconfig> @ends
\\Reactor1\flow,FIC:245433.PV
\\Reactor1\level,LIC:129732.PV
\\Reactor1\temperature,TIC:135432.PV

The wildcard can be used to list a variety of other alias combinations. For example,
@select alias=* lists all aliases for all units; @select
alias=\\*\temperature lists all aliases with a common name of temperature.

PI Server Applications User Guide 203

PI Batch Database

Rename Aliases
Renaming of aliases is performed in edit mode using the NEWAlias attribute. The following
piconfig commands rename the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode edit
* (Ed - PIBAALIAS) PIconfig> @istr alias,newalias
* (Ed - PIBAALIAS) PIconfig>
\\Reactor1\temperature,\\Reactor1\CoreTemp
*> \\Reactor1\temperature,\\Reactor1\CoreTemp

Edit Aliases
Edit mode is also used when changing the corresponding PI point for an alias. The following
piconfig commands change the PI tag associated with the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode edit
* (Ed - PIBAALIAS) PIconfig> @istr alias,tagname
* (Ed - PIBAALIAS) PIconfig> \\Reactor1\temperature,TIC:234531.PV
*> \\Reactor1\temperature,TIC:234531.PV

Delete Aliases
The following piconfig commands delete the temperature alias of Reactor1:
* (Ls - ) PIconfig> @table PIBAALIAS
* (Ls - PIBAALIAS) PIconfig> @mode delete
* (Dl - PIBAALIAS) PIconfig> @istr alias
* (Dl - PIBAALIAS) PIconfig> \\Reactor1\temperature
*> \\Reactor1\temperature

Batch Data Information

All batch data for all units is stored in the Data Archive. When a unit is created, it is assigned
a unique Archive point named pibaN, where N is the unit's unique integer ID, for storing
batch data specific to that unit. Each completed batch consists of two events written to the
appropriate pibaN point: an event at the start time of the batch with a System Digital State of
ActiveBatch; and an event at the end time of the batch with the actual batch data stored as a
Blob object.

PI Batch Data (PIBATCH) Table

The batch data events should typically never be accessed directly from the archive. Instead,
batch data should be accessed via the piconfig table named PIBATCH. The following list
includes the name, data type, default value (D:), and current value (C:) of each of the batch
data attributes.
* (Ls - ) PIconfig> @table PIBATCH
* (Ls - PIBATCH) PIconfig> @?atr
1 - UnitName String D: C:

204
 Batch Data Information

2 - NEWUnitName String D: C:
3 - BID String D: C:
4 - BIDsearch String D: C:
5 - Count String D: 50 C:
6 - Handle String D: C:
7 - ProdID String D: C:
8 - ProdIDsearch String D: C:
9 - SearchStart String D: C:
10 - SearchStop String D: C:
11 - StartStatus String D: C:
12 - StartTime String D: C:
13 - StopStatus String D: C:
14 - StopTime String D: C:

The batch data attributes are:

Attribute Definition
UnitName The name of the unit associated with a batch. In searches, the wildcard
search string for unit names.
NEWUnitName This attribute is not supported.
BID The name or identifier of a batch. This is evaluated when a batch starts (+
evaluation delay).
BIDsearch The wild card search string for BatchIDs.
Count The maximum number of batches to retrieve in a search. If not specified, the
default number of batches returned is 50.
Handle The unique identifier for a single batch. The format is: uniqueID–StopTime in
UTC>. The unique ID is the same integer (N) used in the name pibaN of the
unit's Archive point.
ProdID The name or identifier of a batch's product. This is evaluated when a batch
starts (+ evaluation delay).

ProdIDsearch The wild card search string for ProductIDs.

SearchStart The start time of a search.

SearchStop The end time of a search.

StartStatus An integer indicating the status of a batch's start time: 0 = Not Set; 1 =
Unknown; 2 = OK.

StartTime The time a batch started.

StopStatus An integer indicating the status of a batch's end time: 0 = Not Set; 1 =
Unknown; 2 = OK.

StopTime The time a batch completed.

PI Server Applications User Guide 205

PI Batch Database

Common Operations
The following sections demonstrate the common tasks of creating, listing, editing, and
deleting batches.

Create Batches
New batches may only be created for existing units, and the start and stop times are subject to
the following conditions:
• The start time must be before the stop time.
• The time span of the batch must not overlap an existing batch on the same unit.
• There must be a registered Archive that covers the time span of the batch.
BID and ProdID are optional but typically very useful attributes. A Handle should not be
specified, for it will be generated. The following piconfig commands create a batch for
TestUnit2:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode create
* (Cr - PIBATCH) PIconfig> @istr
unitname,bid,prodid,starttime,stoptime
* (Cr - PIBATCH) PIconfig> TestUnit2,"Batch-1","Prod-1","24-Dec-
05 04:00","24-Dec-05 08:00"
*> TestUnit2,"Batch-1","Prod-1","24-Dec-05 04:00","24-Dec-05
08:00"

List Batches
The following attributes can be specified as search input to narrow the list of batches:
UnitName, BIDSearch, ProdIDSearch, SearchStart, and SearchStop. A typical search
specifies at least UnitName, SearchStart, and SearchStop. The following piconfig
commands list all batches for TestUnit2 since December 1, 2005:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode list
* (Ls - PIBATCH) PIconfig> @ostr unitname,bid,prodid,starttime,
stoptime,handle
* (Ls - PIBATCH) PIconfig> @ostr ...
* (Ls - PIBATCH) PIconfig> @istr unitname,searchstart,searchstop
* (Ls - PIBATCH) PIconfig> TestUnit2,1-dec-05,*
*> TestUnit2,1-dec-05,*
TestUnit2,Batch-1,Prod-1,24-Dec-05 04:00:00,24-Dec-05
08:00:00,35-1135440000
TestUnit2,Batch-2,Prod-2,24-Dec-05 08:01:00,24-Dec-05
12:00:00,35-1135454400
* End Repeat...

Note: The command @ostr … is required to force the output of multiple batches.
Without this command, only the first batch that matches the input criteria is output.

206
 Batch Data Information

When listing batches, the Count attribute must also be taken into consideration. If Count is
not specified in the input structure, then a maximum of 50 batches are output.
For user convenience, the installed piconfig script \PI\adm\pibalist.dif specifies the
same attributes in the input and output structures as those used in the above example, the
typical search.

Edit Batches
Any combination of the following batch attributes can be edited: StartTime, StopTime,
BID, ProdID. Modification of StartTime or StopTime is subject to the same conditions
identified in Create Batches (page 206), and if the time modification is valid, the respective
time status attribute is always set to 2 = "OK".
In addition to the attributes that will be modified, the batch Handle must also be specified to
uniquely identify the target batch for modification. Because a Handle encapsulates
StopTime, modification of StopTime renders that batch Handle obsolete after the edit.
The following piconfig commands modify the BID and StopTime of the last December
batch for TestUnit2:
* (Ls - ) PIconfig> @table pibatch
* (Ls - PIBATCH) PIconfig> @mode edit
* (Ed - PIBATCH) PIconfig> @istr handle,bid,stoptime
* (Ed - PIBATCH) PIconfig> 35-1135454400,"Batch-2Mod","24-Dec-05
14:00:00"
*> 35-1135454400,"Batch-2Mod","24-Dec-05 14:00:00"

Delete Batches
As when editing batches, the Handle must be specified when deleting batches. After a delete,
the Handle is always rendered obsolete. No other attributes need to be specified. The
following piconfig commands delete the last December batch for TestUnit2. Note that the
Handle changed after modifying StopTime in the Edit Batches (page 207) example:
* (Ls - ) PIconfig> @table PIBATCH
* (Ls - PIBATCH) PIconfig> @mode delete
* (Dl - PIBATCH) PIconfig> @istr handle
* (Dl - PIBATCH) PIconfig> 35-1135461600
*> 35-1135461600

PI Server Applications User Guide 207

PI Batch Database

Batch Subsystem Operation

The following sections describe the primary operating tasks of the Batch Subsystem.

Check for Unit Consistency

When the Batch Subsystem first starts up, it checks all defined units (stored in
\PI\dat\pibaunit1.nt) for consistency. The consistency check includes verifying the
existence of the batch activation tags as well as any tags referenced in the expressions for
generating BatchID and ProductID. Any unit indicated as active is also checked to verify that
the same batch is still running, and if there is a discrepancy, the Data Archive is updated
appropriately. Similarly, if any unit previously indicated as inactive is detected to have an
actively running batch, the Data Archive is updated accordingly as well. If any problems are
encountered, messages are sent to the PI Message Subsystem.

Monitor Activation Tags for Transitions

After startup is complete, the Batch Subsystem begins monitoring all batch activation tags for
exception reports. The Batch Subsystem remains in this state until it is shut down. If the
Batch Subsystem detects a transition for a batch activation tag from an inactive to active
state, the unit is updated to record the start of the batch. Until batch completion, all the
information for a running batch is actually stored with the unit (in
\PI\dat\pibaunit1.nt). If an active to inactive state transition is detected, the batch is
considered complete, and the Blob object containing the complete batch structure is created
and finally stored in the Data Archive.

Evaluate BIDExpr and ProdExpr

The Batch Subsystem normally evaluates the BIDExpr and ProdExpr to generate the
BatchID and ProductID, respectively, when the batch activation tag transitions from an
inactive to active state. The evaluation of these expressions can be delayed for a unit by using
the EvalDelay attribute. After the evaluation time, changes to any tags involved in a
BIDExpr and ProdExpr are ignored.

Client Access to Batch Subsystem Batches

Other than with piconfig, read-only programmatic access to the batches created by the Batch
Subsystem is available directly with the PI API. Read-only programmatic access is also
available via the PI SDK, but only if the units are first registered with the Batch Database;
this registration procedure is detailed in the document PI Batch Database Support of the PI
Batch Subsystem.
The only API-based client application is the PI BatchView add-in for Excel, but of course,
custom API applications can always be written. All other client applications such as
BatchView for PI ProcessBook or the stand-alone PI BatchView Quick Search are SDK-

208
 Complete Example

based applications, and therefore require unit registration with the Batch Database. See
corresponding user guides for more details.

Complete Example
Installation of the Batch Subsystem does not result in the creation of any units or batches. The
installed piconfig script \PI\adm\pibatch.dif creates a sample unit and enable the
automatic creation of sample batches. Of course, the actual configuration and batch data is
contrived, but the example provides a complete functional overview of the Batch Subsystem.
Before executing the script, ensure that the Batch Subsystem and all other PI Server
subsystems are fully started. To execute the script, change to the \PI\adm directory and at a
command prompt enter:
piconfig < pibatch.dif

The script first creates two digital sets to model BatchIDs and ProductIDs and two digital
tags, one assigned to each set, to be used in the BIDExpr and ProdExpr attributes of the
sample unit. These digital tags are configured to be serviced by the Random Simulator
Interface (executable name: random), a default interface distributed with all PI Servers, so
this interface also needs to be configured and started for the example to work properly.
The script then creates a single sample unit named Reactor1 using the default point
BA:Active.1 as the batch activation tag. If the default points were not created at PI Server
installation time, you can create them manually. To do this, change to the \PI\adm
directory and at a command prompt enter:
piconfig input defaultpt.dif input defaultpt.dat exit

BA:Active.1 is serviced by the Ramp Soak Simulator Interface (executable name: rmp_sk),
another default interface distributed with all PI Servers, so this interface also must be
configured and started for the example to work properly.
The script finishes with the creation of the aliases Temperature, Level, and Concentration
using other default points—BA:Temp.1, BA:Level.1, and BA:Conc.1, respectively.
If the script executed without errors and all the simulator interfaces are running, a new batch
for Reactor1 should be created approximately every 81 minutes.

PI Server Applications User Guide 209

Chapter 7

PI Totalizer Subsystem
The PI Totalizer Subsystem (Totalizer) performs common calculations such as totals,
averages, minimum and maximum values, standard deviations, and counting. Output of a
calculation is stored in a PI point. The main difference between a Performance Equations
point and a Totalizer point calculating the same summary is that Totalizer calculates based on
Snapshot events while the Performance Equation Scheduler calculates based on Archive
events. Thus, a Totalizer point may have more accurate results.

Totalizer Subsystem Overview

Totalizer allows you to perform certain calculations on a point in the Snapshot, and to store
the results in another point. The process is called postprocessing. Postprocessing includes the
following types of summary calculation:
• Total
• Average
• Minimum
• Maximum
• Range
• Standard Deviation
• Median
Additionally, Totalizer permits the counting of update events for a point. The types of
counting allowed are as follows:
• All Events
• Event Equal To a value
• Event Not Equal To a value
• Event Greater Than a value
• Event Greater Than or Equal To a value
• Event Less Than a value
• Event Less Than or Equal To a value
• Event change from Greater Than or Equal To to Less Than
• Event change from Less Than to Greater Than or Equal To

PI Server Applications User Guide 211

PI Totalizer Subsystem

The Totalizer is a dedicated subsystem, pitotal. This subsystem signs up for exceptions,
which means that it is notified when a new value is added to the Snapshot for any of the
points to be postprocessed. After postprocessing, values, for example, average, total, or time
in state, are sent back to the PI Snapshot.

Note: Since pitotal uses Snapshot events, postprocessing uses uncompressed data. Its
results are more accurate than those computed later from values in the archive.

Totalizer vs. Performance Equations

Totalizer may be more accurate because the values used in Totalizer calculations are taken
from the Snapshot, not after the application of compression as in the case of Performance
Equations. The following figure shows an interval of time for which an accumulation of a
point occurs. Within this accumulation interval, the point also undergoes exception reporting.

Exception Reporting

The values are sent to the Snapshot if they pass the exception test defined by the ExcDev,
ExcMin and ExcMax attributes. In the following figure, 10 of the 28 values fail the
exception test and are not sent to the Snapshot. The Totalizer utilizes the 18 values that are
left for the evaluation. On the other hand, the Performance Equation Scheduler uses the
compressed values (if compression is on).The following figure shows the difference in the
resultant time-weighted calculation for the Totalizer and the Performance Equation
Scheduler.

212
 Totalizer Configuration Overview

Time Weighted Calculation for Totalizer and Performance Equation

The region considered for the calculation is the area under the curve created by connecting
the 18 values left from the exception test. On the other hand, the region considered by the
Performance Equation calculation would be the area under the curve that is created by
connecting the six points that are left after the compression test. In general, the difference in
accuracy between the two calculations is about 1 to 2.5 percent.
The Totalizer may also be more efficient in many cases, especially when the summary
interval is large. Consider a year-to-day calculation. If the calculation is implemented as a
performance equation, the Archive data from the beginning of the year to the current time
needs to be retrieved to carry out the calculation. On the other hand, if the calculation is
implemented as a Totalizer point, then only the new Snapshot event is needed to do the
calculation.

Totalizer Configuration Overview

Totalizer is very flexible, offering a wide range of operating modes. The behavior of a
particular point is primarily determined by these multiple-choice parameters:
RateSampleMode CalcMode Function
Natural TimeWeighted Total
Scan1 EventWeighted Average
Scan2 AllEvents Minimum
Event EventChange Maximum
TimeTrue Range

PI Server Applications User Guide 213

PI Totalizer Subsystem

TotalCloseMode ReportMode
Clock PeriodEnd
EventChange Ramping
EventTrue Running
NSampleMoving RunEstimate
NSampleBlock RunEst2
TimeMoving
Forever

Not counting the behavior influences of the Rate Point Data Type and Step parameter, the
number of combinations of the five parameters is 12,000 (5 x 5 x 6 x 16 x 5). However, not
all of the combinations are allowed. For example, a point that is computing a total with a
TotalCloseMode option of Forever does not allow the ReportMode of PeriodEnd because
the totalization cannot stop at the end of the period. The combinations of the allowed cases
are described in the Function (page 230) and ReportMode (page 229) topics in the Totalizer
Point Class Attributes section.

Creation of a Totalizer Point

Totalization involves several steps, as follows:

1. Sample the value (RateSampleMode) from the input point called the rate point
(SourceTag).
2. Possibly exclude the value based on a filter (Filter Expression).
3. Accumulate the observed values as needed for the specified summary function (Function
and CalcMode).
4. Determine when the Totalizing period is complete and the accumulators need to be reset
(TotalCloseMode).
5. Report the result (ReportMode).
The following figure shows a flow diagram for the steps that are involved in creating a
Totalizer point.

Flow Diagram for the Creation of a Totalizer Point

214
 Totalizer Point Class Attributes

Totalizer Input Values

Each Totalizer point has a single input called the source or rate point. This is the point whose
values are summed, counted, or otherwise accumulated to produce the required summary
value. The arrival of a new rate point value triggers the accumulation and reporting functions
of each Totalizer point. Most often this process is “naturally” scheduled, that is every new
value reported to the system is processed into the ongoing accumulation.

Filtering
Each point may have one filter expression. This expression is evaluated each time that a new
update value is received for each tag referenced in the expression. The results are stored in
time order until the next rate point value is received.

Accumulation
The accumulation step takes the previous and current rate point values into account when
adding to the accumulators. If a filter is specified, the stored filter expression results are also
considered. The details of the accumulation depend on the specified functions. The available
functions are: total, average, minimum, maximum, range, standard deviation, count (of
digital states), and timer.

Accumulation Interval
The accumulation interval is the interval of time for which a postprocessing calculation
occurs. Totals are often generated for intervals specified by a period and an initial start time.
Alternatively, the interval may be defined by external events using a trigger expression using
the Performance Equation syntax.

Output
The output of the results is usually reported at the end of the accumulation interval. The
output can also be estimated before the completion of the accumulation interval. A running
result is also available.

Totalizer Point Class Attributes

The points to which the Totalizer writes its postprocessed values must be of the Totalizer
Point Class. This class has both Base and Totalizer attributes. The following table lists the
additional attributes in the Totalizer Point Class attribute set. These Totalizer-specific
parameters drive the totalization process.
The data types for the five major attributes, RateSampleMode, TotalCloseMode,
ReportMode, Function, and CalcMode as well as the SourceTag, Options, and CompVal,
are strings and are not case-sensitive. The filter and event expressions use the Performance
Equation syntax. Period, Period2, Offset and Offset2 are relative timestamps while the rest
of the attributes are real numbers.

PI Server Applications User Guide 215

PI Totalizer Subsystem

Point Attribute Default Value or Valid Options Notes

SourceTag Point to be post-processed. (See Options, in this

table, for SourceTag values.)
RateSampleMode Natural (default) Processes when new rate point value arrives.
Scan1 Time based samples based on Period2 and
Offset2, interpolated between update events.
Scan2 Time based samples based on Period2 and
Offset2, extrapolated from the value of the last
seen event.
Event Triggered only when EventExpr changes.

TotalCloseMode Clock (default) Accumulation interval based on Period and

Offset parameters.
EventChange Closes when EventExpr result changes value.

EventTrue Totalizer on while value of EventExpr is non-zero.

NSampleMoving Period based upon a fixed number of input values

that is set with the MovingCount parameter.
NSampleBlock Period based upon a block of input values. The
number of input values for the block is set with the
MovingCount parameter.
TimeMoving Moving time window based on Period.
Forever Never resets unless no previous valid point can
be found or Options attribute is settable (for total,
event counting or time only).
ReportMode PeriodEnd No output until period end.
Ramping Running result update to PI Snapshot at the time
of the update (sawtooth).
Running (default) Running result update to PI Snapshot at one
second after the period start time.
RunEstimate Projected output based on current rate value.
RunEst2 Projected output based on average value.
Function Total (default) Numeric rate points only.
Average Numeric rate points only.
Minimum Numeric rate points only.
Maximum Numeric rate points only.
Range Numeric rate points only.
StdDeviation Numeric rate points only.
Median Numeric rate points only.
Events Numeric, digital, or string points.
EventEQ Numeric or Digital points.

216
 Totalizer Point Class Attributes

EventNE Numeric rate points only.

EventGE Numeric rate points only.
EventGT Numeric rate points only.
EventLE Numeric rate points only.
EventLT Numeric rate points only.
EventGE_LT Change counter from >= to < (numeric or Digital
points).
EventLT_GE Change counter from < to >= (numeric or Digital
points).
CalcMode TimeWeighted (default) Values used in calculation weighted in proportion
to duration during period.
EventWeighted The value of each update carries the same
weight.
AllEvents Count all events matching condition.
ChangeEvents Count only events that were changes of value
from the previous update.
TimeTrue Time in seconds event condition is true.
ZeroBias 0.0 Zero is substituted for the rate point value if the
actual rate point value is less than this number.
Setting ZeroBias to exactly zero disables
ZeroBias processing entirely. To treat values less
than or equal to zero as zero-value events, set
ZeroBias to a very small positive number.
Period +1h Period of postprocessing used for
TotalCloseMode.
Offset +0m Offset from beginning of day of the start of
Totalizer.
MovingCount 2 Number of input values for NSampleMoving or
NsampleBlock.
Period2 +2m Used for RateSampleMode in Scan1 and Scan2.
Offset2 +0m Used for RateSampleMode in Scan1 and Scan2.
PctGood 85 Lower limit on the percentage of input data that
needs to be good.
Conversion 1 Conversion factor multiplies the accumulation
result.
FilterExpr Performance equation expression that filters the
rate point.
EventExpr Performance Equation expression used in
TotalCloseMode and RateSampleMode.
CompValue ON Comparison value for event counting and time
conditions expressed in the Function parameter.
Options Field contains zero or more keywords for optional Functions.
InFromTotalizer The rate point value is from an external (DCS)
Totalizer block.

PI Server Applications User Guide 217

PI Totalizer Subsystem

UnderIsBad Under range condition on rate point is bad data

(default is zero).
NoClampZero Enable output to be less than zero.
CloseAtEvent Event ends accumulation interval.
Setable TotalCloseMode of Forever can be set
externally.
OneAtStart Report is one value at 1 second into of the period
for the ReportMode of PeriodEnd.
OneAtEnd Report is one value at the end of the period for the
ReportMode of PeriodEnd.
UnderIsZero Source tag values that are UnderRange (status
code) are considered to be at the source tag zero
value.
OverIsTop Source tag values that are OverRange (status
code) are considered to be at the source tag
zero+span value.
SourceStat Use a bad source tag status in place of “Bad
Total”.
LimitBack Limits the number of totalization periods that are
reported between source tag events.

SourceTag

The SourceTag attribute specifies the rate point, which is the primary input for the
postprocessing. This rate point must already exist and must be specified when the Totalizer
point is configured. The rate point may be any numeric, digital, or string point types. The
value and timestamp used in the postprocessing calculation is taken when an update of the
rate point arrives.

RateSampleMode

The RateSampleMode attribute specifies when the individual values from the rate point are
used in the calculation or are added to the accumulation. The default option for the
RateSampleMode is Natural.

Natural (default)
Natural is the default and most common option. The following figure shows the update
values of the rate point. The values that are considered in the postprocessing calculation are
the update values that lie within the accumulation interval.

218
 Totalizer Point Class Attributes

Natural Sampling

Depending on the other attributes such as the TotalCloseMode, ReportMode, Function, and
CalcMode, the calculation of the result may or may not involve the update values of the rate
point outside the accumulation interval. These features are discussed later in the chapter.

Scan1
Scan1 uses the attributes Period2 and Offset2 to sample the rate point at evenly spaced time
intervals. Values that lie within two updates of the rate point values are linearly interpolated.
Hence, Scan1 does not compute the completed results until the rate point after the
accumulation interval end time, as shown in the following figure.

PI Server Applications User Guide 219

PI Totalizer Subsystem

Scan1 Sampling

The values used in the calculation are the interpolated values at the timestamps set using
Period2 and Offset2. Also, note that the sample rate may or may not coincide with the
postprocessing period. For digital point counting, the digital state does not change until the
update event of the rate point is a different digital state. Hence, Scan1 is similar to Scan2 in
that the digital state at a particular scan of the rate point is the last seen digital state of the rate
point.

Scan2
Scan2 is like Scan1 in that it also samples at evenly spaced time intervals using the attributes
Period2 and Offset2 except that sampled values are calculated from the last seen event. The
value is projected almost as though the Step option was set. Scan2 performs similarly to
Scan1 when counting digital states, as shown in the following figure.

220
 Totalizer Point Class Attributes

Scan2 Sampling

Event
Event uses the event expression specified in the EventExpr attribute to determine when to
sample the rate point. Sampling occurs when there is a change in the value of the event
expression, as shown in the following figure.

Event Sampling

PI Server Applications User Guide 221

PI Totalizer Subsystem

The values used in the calculation are linearly interpolated between values of the rate point
and timestamped at the time when the value of the event expression changes. Event performs
similarly to Scan1 in counting digital states.

TotalCloseMode

The option set in the TotalCloseMode attribute determines the accumulation interval. The
Totalizer functions accumulate data over the accumulation interval. The calculation is “closed
out” at the end of the accumulation interval and the “next event” occurs.

Note: “Closed out” means that the result is calculated and reported and the internal state
of the accumulation function is reset. The “next event” refers to either a value of
the rate point updating or an event from the event expression or the filter
expression for the Totalizer point being updated.

Clock (default)
In TotalCloseMode of Clock, the Totalizer runs and resets at regular time intervals. The
times are specified through two attributes, Period and Offset. Period is the length of each
accumulation interval. Offset specifies the start of the first interval. The accumulation begins
at the start of the day on which the Totalizer is started plus the amount of time given in the
Offset parameter. Period is a relative time of any length. Clock is the default setting for this
option.
The Period parameter may be specified as local time or UTC (Universal Coordinated Time).
Periods longer than one hour that have no specifier are assumed to be local time. This allows
totalization intervals to start at the same time every day even when the clocks are reset for
Daylight Savings Time.
The Offset is a relative timestamp that is less than the Period. The following figure shows an
example of the Clock option of the TotalCloseMode.

TotalCloseMode of Clock

222
 Totalizer Point Class Attributes

In this example, although the accumulation ends, the actual close of the accumulation does
not occur until the rate point updates. This event can occur well after the end of the
accumulation interval. When the update event occurs, the calculated result is written to the
Archive with timestamps of the actual totalization interval.
For the RateSampleMode of Scan2, the close out of the accumulation occurs at the first
update event at or after the end of the period. In Natural, Scan1 and Event, the closeout of the
accumulation occurs only when the rate point value updates.

EventChange
This option connects the totalization period to external events. It requires a valid event
expression be defined in the EventExpr attribute. The current accumulation ends and resets
whenever the result of the event expression is different from that of the previous event
expression calculation.
If the expression includes PI tags referencing the Snapshot, it is evaluated on a natural
schedule. That is, it is recalculated whenever there is a new update for any of the tags.
Expressions that do not reference Snapshot values are evaluated at times specified by the
period and offset parameters but only when rate tag events beyond these times have been
received. PI time functions may be used in these expressions to establish many useful
intervals.
A naturally scheduled expression is only evaluated as each update is received for the real PI
tags in the expression. The times of these events are used in the evaluation of any time
functions in the expression. Tags that come from the same source (interface or remote PI
system) as that of the rate tag should be used to assure synchronization of these critical timing
events. The Option, CloseAtEvent may be used to force prompt closing of the Totalizer at the
period end time. Time-weighted totals assume the rate tag to be constant at the last value
observed to the end of the period.
Expressions that contain no PI Snapshot references are evaluated at times specified by the
Period and Offset parameters. These calculations are only performed when new updates on
the rate tag are received. As each rate tag update arrives, its timestamp is compared with the
next time the expression is due for calculation. If the due time is prior to the event timestamp,
the expression is evaluated before the new event is fully processed.

TotalCloseMode of EventChange

PI Server Applications User Guide 223

PI Totalizer Subsystem

As shown in the figure above for Natural and Scan1, the result of the accumulation is delayed
and not sent to PI Snapshot until an update for the rate point is observed. If the event
expression does not contain a point but only a time function, it is also evaluated with the
RateSampleMode of Natural based on the rate point.

EventTrue
This option also requires a valid event expression to be defined in the EventExpr attribute. In
this case, as shown in the following figure, an accumulation interval is started when the event
expression result is evaluated to be non-zero. Accumulation continues until the event
expression is evaluated to give a zero result, at which point the Totalizer is closed out and
placed in a non-calculating state. The Totalizer point is marked with the system status
condition “Good-Off” to indicate that no postprocessing data is available for the interval.
The times at which the event expression is evaluated is different depending on whether or not
a tag is specified in the event expression. See EventExpr (page 241) for details about when
the EventExpr is evaluated.

TotalCloseMode of EventTrue

Similar to EventChange, the time at which the results are sent to PI Snapshot for
RateSampleMode of Scan2 and Event is when the event expression is equal to zero and
closes out the accumulation. The time at which RateSampleMode of Natural and Scan1
closes out the accumulation is when an update from the rate point occurs.

NSampleMoving
The accumulation interval is defined as the time required to sample the rate point a specified
number of times. The actual time is based upon the RateSampleMode and the filter
expression. The number of values used in the calculation for this TotalCloseMode option is
set in the MovingCount attribute. The NSampleMoving option only supports the
ReportMode option of Ramping.

224
 Totalizer Point Class Attributes

The following figure shows two accumulation intervals with the MovingCount set to 3. Also,
a filter expression is used to limit the values of the RateSampleMode option of Natural used
in the accumulation.

TotalCloseMode of NsampleMoving (1)

The accumulation waits for the number of inputs defined by MovingCount and then
performs the calculation and sends the results to PI Snapshot. As a new sample arrives, the
value at the beginning of the accumulation is left out to incorporate the most recent value and
a new result is calculated and posted. In the above example, the values that are used do not
include the values excluded by the filter expression. For the RateSampleMode of Scan1,
Scan2, and Event, values that are included in the accumulation are interpolated from the
values of the rate point.
The following figure shows an example of RateSampleMode of Scan1 with a filter
expression.

PI Server Applications User Guide 225

PI Totalizer Subsystem

TotalCloseMode of NSampleMoving (1)

Due to the configuration of the scan rate, the number of accumulations for the same number
of updates for the rate point doubles to four intervals. In the figure, the update values from the
rate points labeled as A and C are used to generate three interpolated values. Although the
update of the rate point C is within the time when the filter expression is true, it is used as a
reference point to generate interpolated values from update rate point values labeled as A and
C and also from C to E. Notice that the interpolated values (labeled as B and D) that occurred
when the filter expression was used, were excluded. Furthermore, in this example, the times
at which the results are sent to the Snapshot are at updates of the rate point.

NSampleBlock
The accumulation interval is defined as the time required to sample the rate point a specified
number of times. The actual time is based upon the RateSampleMode and the filter
expression. The number of values used in the calculation for this TotalCloseMode option is
set in the MovingCount attribute. With NSampleBlock, the accumulation is in blocks of
events. The NSampleBlock option only supports the ReportMode option of PeriodEnd.
The following figure shows three accumulation intervals with the MovingCount set to 3.
Also, a filter expression is used to limit the values of the RateSampleMode option of
Natural used in the accumulation.

226
 Totalizer Point Class Attributes

TotalCloseMode of NSampleBlock

The accumulation waits for the number of inputs defined by MovingCount and then
performs the calculation and sends the results to PI Snapshot. In the example above, the
values that are used do not include the values excluded by the filter expression. Accumulation
Interval #1 shows the first accumulation interval after the start of the Totalizer, the
accumulation interval starts at the time of the first event and closes at the time of the last
event. The next accumulation level starts after the end of the prior accumulation interval and
stops after three new events (which are not filtered) are processed. Notice that this second
accumulation interval and subsequent accumulation intervals all start at one second after the
close of the prior interval.

TimeMoving
This option is similar to the previous case except the time for accumulation is specified rather
than the number of samples. The accumulation time is specified in the Period attribute. As a
value for accumulation is received, the Totalizer goes back a certain amount of time that is
specified by the Period parameter and checks if the Totalizer has started and if the rate point
has been created for postprocessing. If either condition is not true, then the point is entered
into a circular queue. When conditions (start of Totalizer and point created for rate point) are
true, then the accumulation interval is set and a value for the beginning of the period is
interpolated between two update values of the rate point.
The following figure demonstrates the beginning of a TimeMoving accumulation. In this
example, the first accumulation interval does not begin until the fourth update of the rate
point because the fourth point is the first instance where the accumulation interval does not
extend to the start of the Totalizer.

PI Server Applications User Guide 227

PI Totalizer Subsystem

TotalCloseMode of TimeMoving and RateSampleMode of Natural

The shaded region represents the area under the curve for which postprocessing for the
CalcMode option of TimeWeighted is calculated. This is discussed in CalcMode (page 233).
In another example, the RateSampleMode is Scan2 whereby the value of the last update of
the rate point is used as the interpolated value.

TotalCloseMode of TimeMoving and RateSampleMode of Scan2

228
 Totalizer Point Class Attributes

Since the interpolated values of the rate point depend only on a prior update of the rate point,
the scan rate of the filter expression is also important. In the figure above, the time at which
the results for accumulation interval #1 is at the natural scan rate of the filter expression and
does not need to be delayed to the time of the update of the rate point. For this example, if the
filter expression did not exist, then both the results from accumulation interval #1 and #2
would have been sent to the Snapshot at the update of the rate point. The start of the Totalizer
is when the Totalizer Subsystem begins. If the file, pilasttot_T.dat does not exist in
the pi\dat directory, the start of the Totalizer would be at the time when the Totalizer last
started. If the file does exist, then the start of the Totalizer is at the time specified in the
pilasttot_T.dat. The only valid option for the ReportMode attribute is Ramping.

Forever
In this mode, the Totalizer never resets. When restarted, it continues from the value found in
the resultant point. This option works for total and all of the count and timing functions.
Some external force may change the Totalizer point only if the Option point attribute is set to
Setable. In this event, the new value is used as the base for the next Totalizer result. The only
valid option for ReportMode is Ramping. The only functions allowed are Total, Maximum,
Minimum and event counting functions.

ReportMode

The option set in the ReportMode attribute specifies the manner in which the Totalizer
results are sent to the PI Snapshot. The following table lists the allowed combinations of
TotalCloseMode and ReportMode where 'X' denotes the allowable option.

Allowed Combinations of TotalCloseMode and ReportMode

ReportMode (X indicates combinations that are allowed)

TotalCloseMode Period Ramping Running Run Estimate RunEst2

End
Clock X X X X X
EventChange X X X
EventTrue X X X
NSampleMoving X
NSampleBlock X
TimeMoving X
Forever X

PeriodEnd
No output is reported until the end of the accumulation period. At that time, the Totalizer
sends the calculated result twice by default. The value is sent once with a timestamp of the
start of the accumulation period plus one second, and again with a timestamp at the end of the
accumulation interval. The result on a trend display in PI ProcessBook is a horizontal line of

PI Server Applications User Guide 229

PI Totalizer Subsystem

the result value through the period of the totalization. An Archive query for the result returns
the same value any time during the period. The Option parameter may be used to change the
default to write a value only at the beginning of the period (OneAtStart) or only at the end of
the period (OneAtEnd).

Ramping
The Ramping option result is a running result that is sent to PI Snapshot when an update
event occurs. Using the Function option Total with Ramping results in a sawtooth trend on a
trend display that ramps up and then resets.

Running (default)
The Running option result is output to the PI Snapshot as each rate point event is received. It
is sent with a timestamp of one second into the current totalization period. If the Archive
compression specification CompMin is set to one second, the successive values are not
recorded in the Archive, but are available for display. Running is the default setting for
ReportMode.

RunEstimate
A new result is sent to the PI Snapshot as each rate point event is processed. The value is an
estimate of the result if the rate point were to hold steady at its current value. RunEstimate
can only be used for the Function option of Total.

RunEst2
A new result is sent to the PI Snapshot as each rate point event is processed. The value is an
estimate of the result if the rate point were to hold steady at the average observed so far in
this accumulation interval. RunEst2 can only be used for the Function option of Total.

Function

The combination of Function and CalcMode parameters defines the primary behavior of a
Totalizer point. The first seven Function options (Total, Average, Minimum, Maximum,
Range, StdDeviation, and Median) are intended for use with numerical rate points only. The
first two CalcMode options (TimeWeighted and EventWeighted) define the kind of
accumulation.
The remaining functions ("Events:" EventEQ, EventNE, … ) are for counting events and are
primarily intended for use with digital rate points. Besides the Function option of Events,
they compare the rate point value to the CompValue parameter, which is expected to be the
text of a digital state. They also work with numeric points and a valid number in
CompValue. Each is a counter for a CalcMode of AllEvents or ChangeEvent. The result is a
time when the CalcMode is TimeTrue. Internally, the time is accumulated in seconds. The
result is multiplied by the Conversion parameter before being sent to the PI Snapshot.

230
 Totalizer Point Class Attributes

The following table shows the allowed combinations of Function and CalcMode options
where X denotes the allowed combinations.
Math Counting Timing

Function Time- Event- All Change Time True

Weighted Weighted Events Events
Total X X
Average X X
Minimum X X
Maximum X X
Range X X
StdDeviation X X
Median X
Events X X
EventEQ X X X
EventNE X X X
EventGE X X X
EventGT X X X
EventLE X X X
EventLT X X X
EventGE_LT X X X
EventLT_GE X X X

Some example combinations are:

Function CalcMode Comp Value Result
EventEQ ChangeEvent Manual Number of times the rate point switched to
Manual
EventNE TimeTrue Manual Total time the rate point was in some state
other than Manual
Events AllEvents Total number of updates received by the rate
point

Total (default)
The result is the totalization of the rate point value. If CalcMode is EventWeighted, this is the
sum the values from the individual rate point value update events. TimeWeighted uses
trapezoidal integration to produce the total. Use caution in choosing the RateSampleMode
option. If the goal is for a total of the values of a rate point, use the Natural option. The other
RateSampleMode options extrapolate values from defined time points and may lead to
incorrect totals.

PI Server Applications User Guide 231

PI Totalizer Subsystem

Average
The result is the average of the rate point value. If the CalcMode is EventWeighted, the
average is the totaled individual update events and divided by the number of events. The
CalcMode option of TimeWeighted considers the time between events, dividing by the area
under the curve by the time interval.

Maximum or Minimum
The result is the maximum or minimum observed value of the input. If the CalcMode is
EventWeighted, the result is one of the input values. If there is a filter expression active and
the CalcMode is TimeWeighted, the result may be an interpolated value corresponding to the
time when the filter changed state.
For TotalCloseModes of NSampleMoving and TimeMoving, a sorted list of all of the values
seen during the period is maintained.

Range
The result is the difference between the maximum and minimum observed values of the
input. If the CalcMode is EventWeighted, the result is one of the input values. If there is a
filter expression active and the CalcMode is TimeWeighted, the result may be an interpolated
value corresponding to the time when the filter changed state.
For TotalCloseModes of NSampleMoving and TimeMoving a sorted list of all of the values
seen during the period is maintained.

StdDeviation
The result is the standard deviation of the observed data. Both time- and event-weighted
forms are available.
For TotalCloseModes of NsampleMoving, an array of intermediate results is kept.
StdDeviation is not supported for TotalCloseMode option of TimeMoving with CalcMode
option of EventWeighted.

Median
The Median value is the middle observed value of the input. If there is an even number of
values in the sample, an average of the center two is selected. Using Median with a short time
interval can be very effective as a filter for noise removal.
For TotalCloseModes of NSampleMoving and TimeMoving a sorted list of all of the values
seen during the period is maintained.

Counting and Timing Functions

The following Function options are used for counting and timing operations. The allowed
CalcMode options are AllEvents, ChangeEvents, and TimeTrue.

232
 Totalizer Point Class Attributes

Events
This Function option counts all event updates of the rate point that pass exception handling
and the filter expression. The allowed CalcMode options are AllEvents and ChangeEvents.
Use caution if the RateSampleMode option is not Natural. Using the other three options of
the RateSampleMode with Events results in counting the interpolated values as event
updates.

EventXX
The set of Function options denoted as EventXX (EventEQ, EventNE, EventGE, EventGT,
EventLE, and EventLT) is used to count the number of update events that pass exception
handling. The filter expression is used to find the time that the value of the rate point meets
the condition of the Function. As rate point events are received, they are compared to the
value in the CompValue parameter to produce a true or false result.
For CalcMode of AllEvents, true events are simply counted. ChangeEvents counts only those
events that have values different than the immediately previous event. Consecutive events
with the same value are skipped. For the TimeTrue mode, the true event starts a timer and a
false event stops it.

EventXX_XX
The set of Function options denoted as EventXX_XX (Event LT_GE and EventGE_LT) is
used as transition counters. They are used to count the number of times the update events
(that pass exception handling and the filter expression) pass through the value set in the
CompValue attribute or are used to find the time that the value of the rate point meets the
condition of the Function. As rate point events are received, they are compared to the value
in CompValue parameter to produce a true or false result.
For CalcMode of AllEvents, true events are simply counted. ChangeEvents counts only those
events that have values different than the immediately previous event. Repeat events with the
same value are skipped. For the TimeTrue mode, the true event starts a timer and a false event
stops it.

CalcMode

The value set in the CalcMode parameter modifies the Function parameter. The first two
options (TimeWeighted and EventWeighted) can only be used with math functions while the
last three (AllEvents, EventChange, and TimeTrue) can only be used with counting functions.

TimeWeighted
The time between input values is (default) considered in totalization and average functions.
This is the normal option for accumulating flow signals into totals for the period. The
following figure demonstrates a time-weighted total for both RateSampleMode options of
Natural and Scan1.

PI Server Applications User Guide 233

PI Totalizer Subsystem

TimeWeighted Total for Natural and Scan1 with Step=0

In both cases, the total is similar. The area considered for totalization is the shaded region.
Furthermore, if the Step attribute of the rate point is 0, then that indicates that the values
between the update points are interpolated. If the value of the Step attribute is 1, then the
Scan1 RateSampleMode is overwritten and the totalization would be as if Scan2 was the
intended option. The following figure shows the plots for a totalization for the
RateSampleMode options of Natural and Scan2 with the Step option set at 1.

Time-Weighted Total for Natural and Scan2 with Step=1

234
 Totalizer Point Class Attributes

When the Step attribute is “on” (equal to 1) then the value of the rate point remains the same
until a new update value is seen. This is similar to Scan2. For the example in the previous
figure, the totalization for Scan2 is shown in the shaded area. This, however, is different than
the area for Natural scanning with Step equal to 1. For this specific example, the totalization
considers both the two shaded patterned areas as well as the shaded area for Scan2. Even if
Step = 0 for Scan2, the totalization would be the same.

EventWeighted
Here each rate point value is taken to be a discrete addition to the accumulated result. Time is
not considered. Each event has the same weight. In the first example shown in the following
figure, the RateSample mode is Natural and the Function is Total.

Event-Weighted Total for Natural

In this case the accumulation interval contained two updates of the rate point labeled as A and
B. Therefore, the result is the summation of the values (XA and XB) of the rate points.
In another example shown in the following figure, the RateSampleMode is Scan1 and the
Function is Average.

PI Server Applications User Guide 235

PI Totalizer Subsystem

Event-Weighted Average for Scan1

The scan rate generated five interpolated values labeled as XA through XE, and the average
would be the sum of the values divided by the number of interpolated events. Use caution if
you want to use the Function option of Total with EventWeighted and the RateSampleMode
options of Scan1, Scan2, and Event. In the above example, since the events were interpolated,
the total from the interval would be the summation from XA through XE.

AllEvents
With the Function option of Events, the CalcMode option AllEvents counts all value
updates. For the rest of the event functions that use the CompValue attribute for comparison
with the update value, this CalcMode option counts all the events for which the comparison
is true. This means that events that repeat the same value are counted.
In the following figure, the digital states can be represented on a timeline by plotting the
digital state offsets for the two digital states “on” and “off.”

236
 Totalizer Point Class Attributes

Digital States with RateSampleMode of Natural

For the Function of Events, the count for the accumulation interval is 2. If the Function is
EventEQ and the CompValue is “on,” then the result is 1. For functions such as EventGT, the
comparison is made based on the digital state offset. Since “on” has a lower digital state
offset value than “off” for this example, using EventGT would result in counting the “off”
event that occurred within the accumulation interval.
In another example shown in the following figure, the RateSampleMode is Scan1. The value
of the digital state at the time set by the scan rate is the digital state for the last seen update
event. Hence, using Scan1 or Scan2 would be similar.

Digital States with RateSampleMode of Scan1 or Scan2

The result of Function option Events is 5 and the result of EventEQ is 3 and the result of
EventGT is 2.

PI Server Applications User Guide 237

PI Totalizer Subsystem

ChangeEvents
In the event class of functions, the count is only those updates that satisfy the condition and
that were real changes of value. Therefore, the count represents not the update events but the
changes of the update events. For the example shown in AllEvents where the
RateSampleMode could be either Scan1 or Scan2, the result of the function option Events is
2 and the result of EventGT is 1.

TimeTrue
This CalcMode option results in the duration of the conditions to be accumulated. Internally,
time is accumulated in seconds. The result is multiplied by the Conversion parameter before
being sent to the PI Snapshot. For the Function of EventEQ and CompValue of “on”,
TimeTrue finds the time within the accumulation interval that the digital state was “on”.

ZeroBias

The value of the rate point is considered to be zero if less than this value.

Note: Setting this parameter to exactly zero disables ZeroBias processing. To treat
values less than or equal to zero as zero-value events, set ZeroBias to a very
small positive number.

Period

The Period attribute is used by the TotalCloseMode option of Clock to set the accumulation
interval. It accepts relative timestamps. For example, +1h, +30m, and +1d set the
accumulation interval to one hour, 30 minutes, and one day, respectively.
Periods longer than one hour default to local wall clock scheduling. Periods of 1 hour or less
must use UTC scheduling. For periods greater than 1 hour, you can explicitly define wall
clock scheduling by appending /local or simply /l to the Period attribute; or one can
override wall clock scheduling by appending /utc or simply /u to the Period attribute. For
periods less than 1 hour, you can explicitly define UTC scheduling by appending /utc or
simply /u to the Period attribute.
Use wall clock scheduling for totals that must close at the same time every day, even across
Daylight Savings Time (DST) transitions. Frequently, wall clock scheduling is desired if the
period is evenly divisible into 24 hours. For example, if the Offset attribute is set to 0 and the
Period attribute is set to +8h /local, the total will close at Midnight, 8 AM, and 4 PM every
day. For the Midnight to 8 AM period, the actual time duration will be will be 9 hours on the
day of the Daylight to Standard transition and 7 hours on the day of the Standard to Daylight
transition. As a second example, assume that the Offset attribute is set to +150m and the
Period attribute is set to +8h /local. The total will close at 2:30 AM, 10:30 AM, and 6:30 PM
every day, except on the Standard to Daylight transition, where there is no 2:30 AM wall
clock time. The total that opens at 6:30 PM the day prior to the Standard to Daylight
transition will be 15 hours, closing at 10:30 AM.

238
 Totalizer Point Class Attributes

Use UTC scheduling for totals that always must have the same time duration, even across
DST transitions. Periods that are greater than 1 hour but do not divide evenly into 24 hours
should almost always have /utc or /u appended to the specified period. For example, a
Period of +5h uses wall clock scheduling by default, but the use case for wall clock
scheduling for a 5-hour period is difficult to envision. Even without taking DST transitions
into consideration, a 5-hour total will never close at the same wall clock time for one day to
the next. For a 5-hour period, you will almost always want to specify the Period attribute to
be +5h /UTC instead of +5h /local or +5h.

Offset

The relative timestamp set in the Offset attribute is used by the TotalCloseMode option of
Clock to determine when to begin the initial accumulation. The Offset is a relative timestamp
that must be less than the relative timestamp set in the Period attribute. For example, if
Offset is '+12h' and Period is '+1d', the Totalizer begins the accumulation calculation at
noon on the day that the Totalizer starts and accumulates data for a period of 24 hours.

MovingCount

The value in MovingCount attribute is used by the TotalCloseMode option of

NSampleMoving and NSampleBlock to determine the number of samples for the accumulation
interval.

Period2

The Period2 attribute is used by the RateSampleMode options of Scan1 and Scan2 to set the
sampling rate. It accepts relative timestamps. For example, '+1m', '+30s', and '+ 1h' set the
accumulation interval to one minute, 30 seconds, and one hour, respectively. The Period2
attribute also accepts the optional /local and /utc flags.

Offset2

The relative timestamp set in Offset attribute is used by the RateSampleMode option of
Scan1 and Scan2 to determine when to start sampling. Offset2 is a relative timestamp that
must be less than the relative timestamp set in the Period2 attribute. The Totalizer uses the
beginning of the day for which the Totalizer is started as the reference point for when to
account for Offset2 and move in intervals set by Period2 and sample at the next appropriate
beginning of a period. For example, if Offset2 is '+10s', Period2 is '+1m', and the start of the
Totalizer is at noon, the first sample is taken at noon plus 10 seconds and the next sample is
taken at 12:01:10.

PI Server Applications User Guide 239

PI Totalizer Subsystem

PctGood

PctGood is a number between 0 and 100 (in percent). If rate tag values are bad for a larger
fraction of the totalization period, the output of the Totalizer is marked bad.
Percent good is calculated based on the amount of time that the rate tag has a bad status over
the totalization period for TimeWeighted totals and for the event counting functions (Events,
EventEQ, EventNE, EventGE, EventGT, EventLE, EventLT, EventGE_LT, EventLT_GE) with
a CalcMode of TimeTrue.
Percent good is calculated based on the number of events that have a bad status for
EventWeighted totals and for the event counting functions with a CalcMode of AllEvents and
ChangeEvents.
In the case of TimeWeighted totals, the Totalizer adjusts the total to account for the missing
data. This extrapolation takes the resultant good data and divides it by the fraction of time
that the data was good. For example, if the total of the good data is 100 and the percentage of
the data that was good for the time period is 80%, then the total that is reported is 125. To
turn off extrapolation, set PctGood to 0. By setting PctGood to 0, the total that is reported
from the previous example would be 100.

Conversion

Conversion is a number that multiplies the raw Totalizer result. It is used to convert the units
of the rate tag to the proper units for the totalization.
For TimeWeighted totals, the total is computed with the assumption that the rate tag is in
units/day. If the units of the rate tag are not in units/day, then the units of the rate tag must be
converted to units/day using Conversion. For example, if the units of the rate tag are in
kilograms per hour (kg/hr) and the desired total is in grams (g), then Conversion must be set
to 24000. That is, (1 kg/hr) (24 hr/day)(1000 g/kg) = (24000 g/day).
For EventWeighted totals Conversion can be used to convert the units of the rate tag to the
desired units of the total. For example, if the units of the rate tag is in kilograms and the
desired total is in grams, then Conversion should be set to 1000.
Here are some typical conversion factors for common units.

Conversion Factors for Units

Source Units Total Units Conversion

bbl per day bbl 1.0
lbs per hour lbs 24.
gal per min gal 1440
Cubic feet per sec. acre-ft 0.504167

240
 Totalizer Point Class Attributes

FilterExpr

This is a mathematical expression in PI Performance Equation syntax. The expression is

compiled and given an initial evaluation based on the current Snapshot values of tags
referenced. It is re-evaluated whenever an update is received for any of its tags.
Rate tag point values are excluded from totalization during intervals that the expression result
is zero. That is, rate tag values for periods when the filter expression result is zero are not
included in the total. This behavior is consistent with the sense of filter expressions in PI API
and PI DataLink. For averages, the time is also excluded from the calculation.
For efficiency of evaluation, Archive access functions are not allowed in filter expressions.
Archive access functions include such functions as TagVal and TagAve.
The rate point is not filtered when the status of the filter expression is bad. The filter
expression is likely to be bad whenever some of the input points for the filter expression have
bad status.
See PI Performance Equations Scheduler (page 5) for details about the syntax of the
expressions.
Some examples of filter expressions are as follows:
'DigitalTag'= "ON"
'RateTag' > 50

EventExpr

This is a Performance Equation expression that defines event times used by EventChange
and EventTrue for the TotalCloseMode options. It also defines the times at which the rate
point is scanned for the RateSampleMode option of Event. The expression is naturally
scheduled. That is, it is evaluated whenever a new value is received for any of its input
values.
Event expressions are normally evaluated as new values are received for the tags they
reference. For TotalCloseMode of EventChange and EventTrue, an event expression that
references no Snapshot tags are evaluated at times specified by the Period and Offset
parameters. Each time a rate tag value is received, if the event expression due time has
passed, the rate tag value is evaluated prior to processing the new update value.
Some examples of event expressions are as follows:
'R-2410_mode'
'DigitalTag' = "ON"
int( ('*' - '1-jan-2001')/(7 * '+24h') )

CompValue

The value set in the CompValue attribute is used for comparison in all the event counting
functions (such as EventGE, EventLE) except the Function option Events because Events
counts all update events and does not need a comparison value. The CompValue should
match the data type of the rate tag. It may be a digital state name, string, or a number.

PI Server Applications User Guide 241

PI Totalizer Subsystem

Options

This field allows for entry of zero or more option words to select lesser-used functions.

InFromTotalizer
This option is set if the rate point is actually the integral of the flow signal to be totalized.
This is intended for use with the typical DCS accumulator block. The DCS can easily process
the flow at a very high sample rate. The updates to PI can be set for relatively large exception
deviation values with negligible loss of accuracy. These DCS blocks typically have a rollover
at some finite value. As that total is reached, the block output drops to the bottom of its range
and accumulation continues. The Totalizer observes this large value jump and calculates the
correct increment from the configured full-scale value of the rate point.

UnderIsBad
Consider values below the rate point zero level to be bad. If this option is not set, values are
considered valid. Negative values are set to zero or used if enabled by the NoClampZero
option.

NoClampZero
Do not clamp the output of the Totalizer to be greater than zero. Without this option, zero is
substituted for negative rate tag values.

CloseAtEvent
The close out of the accumulation interval is at the end of the period and the result of the
calculation is sent to the Snapshot. For time-weighted calculations, the value used at the end
of the period is the value of the last seen update of the rate point. The following figure shows
an example of a time-weighted total with Scan1 and the CloseAtEvent option.

242
 Totalizer Point Class Attributes

Time-Weighted Total with Scan1 and CloseAtEvent

This option works only on event-driven TotalCloseModes of EventChange and EventTrue.

Setable
When using a TotalCloseMode of Forever, the total can be reset only when the option field
is set to Setable. The total is reset by sending a new value to the totalizer tag itself. In this
case, the new value will be used as the base for the next totalizer result.
The timestamp of the reset value must be more recent than the timestamp of the last
SourceTag event for the total. Otherwise the reset event will be ignored. Since you may not
be able to predict when the next SourceTag event will arrive, you may want to send the reset
value with a timestamp that is 1 second in the future to avoid this potential problem.

OneAtStart
The TotalCloseMode of PeriodEnd can be modified to send a value only at the beginning of
the period (one second after the close of the last period) when the option field is set to
OneAtStart. The default behavior of PeriodEnd is to send a value at both the beginning and
the end of the period.

OneAtEnd
The TotalCloseMode of PeriodEnd can be modified to only send a value at the end of the
period when the option field is set to OneAtEnd. The default behavior of PeriodEnd is to send
a value at both the beginning and the end of the period.

PI Server Applications User Guide 243

PI Totalizer Subsystem

UnderIsZero
Some external systems have limited ranges for measured values but are able to report that the
signal is below the available range. This option causes the Totalizer to use the rate tag zero
value in place of updates with UnderRange status.

OverIsTop
Some external systems have limited ranges for measured values but are able to report that the
signal is above the available range. This option causes the Totalizer to use the rate tag top of
span value in place of updates with OverRange status.

SourceStat
When the PctGood minimum is not attained, the Totalizer normally reports “bad total” as a
status. With this option, a bad status actually received from the source tag is used instead.
This supplies some reason for the failure to someone looking only at the Totalizer results.

LimitBack
When LimitBack is set, the number of totalization periods that are reported between source
tag events is limited to twenty. This is a partial solution to the problem some systems
encounter when restarting after being down for some time. The Totalizer may attempt to
write results for all of the totalization periods for the period when the system was down.

Build Totalizer Points

Totalizer points can be created in the same manner as other point types except that Totalizer
point attributes include the Totalizer attributes as well as the point attribute for the Base point
class.

SMT Totalizer Editor Plug-in

This plug-in provides a user-friendly GUI to create a Totalizer point. Unlike

TagConfigurator (page 244), the editor strictly enforces the non-supported combinations of
options.

PI TagConfigurator

The easiest way to build many Totalizer points is using the PI TagConfigurator tool. See the
OSIsoft support Web site to download this tool.

244
 Build Totalizer Points

PI TagConfigurator Creation of Totalizer Point

Note: Under Import Tags, Export Tags, and Tag Attributes of the PI SMT drop-down
lists, the Point Class must be Totalizer.

Export Tags Dialog Box

Furthermore, the PointSource attribute must be set to T.

PI Server Applications User Guide 245

PI Totalizer Subsystem

Piconfig

Alternatively, you can use the following script in the piconfig utility to create the same
Totalizer point:
* (Ls - PIPOINT) PIconfig> @mode create,t
* (Cr - PIPOINT) PIconfig> @istr
tag, pointsource, sourcetag, ratesamplemode, totalclosemode,
reportmode,
function, calcmode
* (Cr - PIPOINT) PIconfig>
totnumtag, T, sinusoid, natural, clock, periodend, total,
eventweighted
* (Cr - PIPOINT) PIconfig> @ends

Program Operation

Startup

The pitotal program is started with the rest of the system. The program periodically writes its
internal status to the file PI\dat\pilasttot_T.dat. This file is also written during a
normal system shutdown. At startup, pitotal looks for this file. If it is not found, all Totalizer
points are initialized to start at the current time without consideration of any prior history.
If pilasttot_T.dat is found, it is read to obtain partial accumulation results to include
when restarting points. For the most part, all points with simple time-based scheduling are
able to restart. If the accumulation interval that was in progress when the file was written has
expired, an attempt is made to close that total and a shutdown event is written after it.
Otherwise, the accumulation is restarted with the assumption that no data points have been
lost. If any point appears to have shutdown events after the time of the pilasttot_T file,
then restart is canceled in favor of total cold start. Points that are event-scheduled have no
basis to know if restart is valid. Shutdown events are written and the point is cold-started.
Any point that has been reconfigured while pitotal was offline would be cold-started. Point
Database edits may result in a re-initialization of the point. This occurs when a significant
parameter change is made.

Error Messages

All significant events in the life of a Totalizer point are noted in the PI server log. These
include point additions and edits, scan status changes, and error conditions. These events can
be monitored using the pigetmsg utility in the pi\adm directory. See the PI Server System
Management Guide for details about using the pigetmsg utility.

246
 PI for OpenVMS Upgrade Considerations

Response to Scan Flag

When an operating Totalizer point is turned off-scan, the Totalizer is closed out as though
this were the end of the period and a Scan Off event is written to the Archive. Going back
on-scan is a full initialization of the point; no partial results are carried forward. A Scan On
event is written to the Archive.

PI for OpenVMS Upgrade Considerations

The Totalizer can nominally do all the operations that the PI for OpenVMS version could do
and more. Simple time-based points should port with no difficulty. However, the advanced
Totalizer algorithms depend on very specific behavior of underlying implementations that are
quite different. Any PI for OpenVMS points that use filter and event expressions will need
special attention.
The following are known differences:
• The meaning of the filter expression result has been reversed to match the logic of the PI
API. Now, input values are ignored (filtered out) when the filter expression result is zero.
• The Performance Equation syntax used in the event and filter expressions is different.
The largest difference is the absence of a formula library in PI Server. See PI
Performance Equations Scheduler (page 5) for more details.
• New functions are available for counting and timing of events. Use of these functions
may enable the elimination of many event and filter expressions.
• The use of PI for OpenVMS option of moving Totalization with event- and clock-
scheduling is not supported.

Features in PI3 versus PI for OpenVMS

The Totalizer Subsystem includes features that are not included in PI for OpenVMS.
• Totalizer points use a new point class with a new set of parameter names and meanings.
• A running account of the output.
• The event expression that can be time-scheduled.
• New event functions that can count and time values from Digital points.
• Sampling of the rate point that can be time-scheduled.
• Moving totals with several new scheduling options.
• New numeric functions that include Maximum, Minimum, Median, and Range.
• The input that may come from a typical DCS Totalizer block.

PI Server Applications User Guide 247

PI Totalizer Subsystem

Compatibility with PI for OpenVMS

The PI Server Totalizer can do all of the functions offered by PI for OpenVMS
postprocessing. Simple Totalizers can be ported easily through a translation of parameter
names. Points that use event or filter expressions must be examined for compatibility with the
PI Server syntax.
In many cases it should be possible to get the desired functionality by using the Totalizer
features rather than by re-writing expressions. These are easier to document and use less
computing resource.
The meaning of the filter operation has been redefined. A true filter result, that is non-zero,
now passes the signal. The following table lists the available postprocessing options in PI for
OpenVMS and the PI Server equivalents.
PI for OpenVMS PI Server
Postprocessing Type of Point Attribute Option to Set
Type Scheduling

Time-weighted Clock RateSampleMode Natural

TotalCloseMode Clock

ReportMode PeriodEnd

CalcMode TimeWeighted

Event RateSampleMode Natural

TotalCloseMode EventChange

ReportMode PeriodEnd

CalcMode TimeWeighted

Discrete Clock RateSampleMode Natural

TotalCloseMode Clock

ReportMode PeriodEnd

CalcMode EventWeighted

Event RateSampleMode Natural

248
 Demonstration Points

TotalCloseMode EventChange

ReportMode PeriodEnd

CalcMode EventWeighted

Moving Natural RateSampleMode Natural

TotalCloseMode NSampleMoving

ReportMode Ramping

CalcMode TimeWeighted

Clock Not Supported

Event Not Supported

Demonstration Points
Demonstration points for the Totalizer subsystem are available in the pi\adm directory in
the totalizerpts.dif file but are not automatically created when the system is
installed. These Totalizer demonstration points can be created by redirecting the file to the
piconfig utility.
$ piconfig < totalizerpts.dif

See the PI Server System Management Guide for details on the piconfig utility.

PI Server Applications User Guide 249

Chapter 8

PI Alarm Subsystem
The PI Alarm Subsystem (PI Alarm) provides the capability to establish alarms for PI
points. PI Alarm allows you to track, manage and acknowledge alarm conditions caused by
processes that exceed user-specified parameters.

Note: PI Notifications functionality replaces PI Alarm. However, OSIsoft continues to

maintain PI Alarm.

PI Alarm can monitor many variables such as temperatures, volumes, flow rates, product
quality or raw material consumption. Alarms can be triggered by the duration of an event or
deviation from norm.
PI Alarm keeps a constant eye on process conditions. PI Alarm assesses the condition as well
as the priority of an event, as you define it. Depending on the longevity and/or severity of the
event, it can notify specific personnel.
Data from PI Alarm are displayed in its companion client application, PI AlarmView. Alarm
conditions are historized together with an acknowledgment status. When Real-Time SQC
perceives an unacceptable deviation in the process, PI SQC Alarms alert the appropriate
personnel.

Alarm Subsytem Overview

A PI System often brings together information from several sources and can perform
calculations that are not easily done elsewhere. Some sites may have alarm philosophies that
enable them to take advantage of the PI System to provide alerts on these higher level
functions.
PI Alarm provides the basic server-side functions of an alarm system. The alarm package
includes the following features:
• Current and archived Alarm States.
• Alarm Groups to organize and manage alarms
• A simple alarm detection program for monitoring numeric, digital, and string points.
The alarm package is organized into two categories.
• The first part is the Alarm Point. Alarms are displayed and archived as digital points. A
monitoring program observes updates to numeric, digital, and string points and then tests
each for configured alarm conditions.
• The second part is the Alarm Group. A set of alarm points can be organized into Alarm
Groups. Statistics such as the number of alarm points and the number of unacknowledged

PI Server Applications User Guide 251

PI Alarm Subsystem

alarms can be obtained for each Alarm Group. Groups can be members of other groups to
form alarm hierarchies.

Alarm Points
An alarm point is a digital point that indicates the alarm status of a point in the PI System. PI
Alarm can monitor the values of other points and set the values of alarm points when defined
boundaries are exceeded. Numeric values exceeding limits or digital values changing to a
special state are two such boundaries.
The digital state of an alarm point may include both the priority and acknowledgment status
of the alarm condition.
• The condition of an alarm is the type of limit that the alarm is triggering. Some typical
names of conditions are “high” and “low”. For example, if a numeric point is greater than
a certain numeric constant, the condition of the alarm can be high.
• The acknowledgment status may be determined by whether a user has acknowledged the
alarm, not acknowledged the alarm, or not acknowledged the alarm condition that no
longer exists.
• The priority is level of importance given to the particular alarm.
Each alarm point has a source point, which is the tag whose value is being monitored for
special changes.The following figure shows the flow diagram of an alarm point.

Flow Diagram of Alarm Points

The alarm point is naturally scheduled and signs up for updates of the source point. This
means that the alarm point is evaluated whenever the source point produces an exception. A
series of tests are done and an alarm is triggered if any of the tests are true. The digital state
of the alarm point is then set based on the combiner logic (page 253).

252
 Alarm Point Configuration

Alarm Tests and Actions

An alarm is the result of a set of four tests on the current value of another point. Each alarm
tag has a primary source point that is the subject of these tests. Each alarm point can be
configured to perform four simple tests on new values received by the source tag. The tests
are individually configured for comparisons like "greater than," "equal," and so on. Each time
a source tag value is received, the configured tests are performed. The result of each test is a
Boolean (true/false) value. The four test results are input to combiner logic that decides the
alarm status to be set. The answer depends on the configured priority of the test conditions,
the order of detection, and the acknowledgment status of the current alarm.

Combiner Logic
Combiner logic refers to the manner in which the digital state of an alarm is set when a test or
multiple tests are true. If more than one test condition is true, the rule for which Alarm State
to set is that priorities have precedence. When two conditions of the same priority are true, it
is the first (in order of the tests) that is used to set the Alarm State. Further details of the logic
are given in the Action1, Action2, Action3, and Action4 attributes for alarm points.

Acknowledgment
Acknowledgment is accomplished by allowing the client program to write acknowledged
digital states corresponding to the Alarm Digital States directly to the alarm points. For
example, an Alarm Digital State that represents a high value in the source tag can only be
acknowledged by the corresponding high acknowledged digital state. The alarm program
overwrites the client input in case of an error. See Alarm State Sets (page 267) for details
about Alarm Digital States.
An auto-acknowledge for the alarm point is also possible. An auto-acknowledged point
continues to display the current alarm condition, but the display status is never
unacknowledged. Further details on auto-acknowledgment can be found in the AutoAck
attribute for alarm points.

Alarm Point Configuration

Alarm points have the point class of alarm. The point source is @ and the data type must be
digital.

PI Server Applications User Guide 253

PI Alarm Subsystem

Alarm Point Class Attributes

Point Attribute Valid Options Description

SourceTag Source point used to test for alarm
Test1 GT Alarm if values greater than numeric value
Test2 LT Alarm if values less than numeric value
Test3
EQ Alarm if values equal numeric value, digital state or string
Test4
NE Alarm if values not equal numeric value, digital state or string
StepGT Alarm if values stepped up more than numeric value
StepLT Alarm if values stepped down more than numeric value
RateGT Alarm if rate of change is greater than numeric value
RateLT Alarm if rate of change is less than numeric value
Is_in Alarm if value is in the digital state or string
Not_In Alarm if value is not in the digital state or string
Includes Alarm if values includes digital state or string
Change Alarm if value of point changes
CondEQ Alarm if condition is equal to string
CondNE Alarm if condition is equal to string
IsUnAck Alarm if unacknowledged
Action1 Condition nn Name of the alarm condition
Action2 nn = priority
Action3 StateName Valid name in Digital State Set.
Action4
ExDesc GroupTag Alarm Group of alarm point
DigitalSet Name of the Alarm Digital State Set for point
ReferenceTag Tagname Point that is used for comparison operators if specified.
AutoAck Yes (default) Any alarm always shows as acknowledged.
No Full acknowledge operation supported.
DeadBand 0.0 (default) Threshold for point not to be in alarm
Options RT = num Used with the RateGT and RateLT to define the period of the
rate
ControlTag Point that is used to take the alarm out of service if specified.
ControlAlg <reserved for future use>

Note: While the actual point class has the parameters, Test5 and Action5, only four
Test/Action pairs are implemented.

254
 Alarm Point Configuration

SourceTag

The point set in the SourceTag attribute is the primary source used in the testing for alarm
conditions. The point must already exist and must be specified when the Alarm Point is
configured. The point may be numeric, digital or string point types.

Test1, Test2, Test3, Test4

The set of four attributes Test1, Test2, Test3, and Test4 contains the test for the alarm
condition. The syntax for the attribute is the operator followed by an argument that is within
parenthesis, which is also followed by an optional time parameter.
Syntax: Operator ( Argument ) Time

The argument can be a numeric constant; string, digital state, or it may refer to another tag.
The following examples use the EQ (equal to) operator (page 258).
EQ ( 12 )
EQ ( ON )
EQ ( "This is a string" )

In addition, the argument can be a reference to another point that has the data type of
numeric, string, or digital. If a reference is used, the argument is the tagname of the reference
point that is enclosed in single quotes or the keyword ref. In the case where the keyword ref
is used, the ReferenceTag attribute must be the tagname of the desired reference point. An
optional numeric constant offset can also be used only in the case when the keyword ref is
used and only if the reference point is a numeric point. This adds or subtracts a numeric
constant from the value of the reference point before the test is done.
EQ ( 'tagname' )
EQ ( ref )
EQ ( ref + 12 )
EQ ( ref - 14 )

An optional time parameter can also be used to delay the triggering of the alarm until the test
comparison is true for a given amount of time. The time parameter is a relative timestamp
that is added to the comparison. The time parameter consists of a plus sign, one or more
numbers, and a letter (s, m, h, or d). There may be no spaces between these elements.
EQ ( 12 ) +14m
EQ ( 'tagname' ) +11h
EQ ( ref + 70 ) +1h
EQ ( ON ) +1d

In the examples above, the first test triggers an alarm if the source tag is equal to 12 for over
14 minutes. The second test alarms when the source point is equal to the reference point
(referenced by tagname) for over 11 hours. The third test compares the source point with the
reference point plus 70 and if they are equal for over one hour then an alarm is triggered. In
the fourth test, an alarm triggers if the source point is ON for over one day.
All numeric point comparisons are performed using floating-point operations and all string
and digital state comparisons are performed using character operations. Comparisons of a
digital or string data type with a numeric data type returns an error at the time which the point

PI Server Applications User Guide 255

PI Alarm Subsystem

is compiled. Blob data types are not supported. The following table shows some examples of
the comparisons and whether an alarm triggers.

Example Test Comparisons and the Alarm Status

Operator Source Test value Trigger an Comparison

point value alarm?
EQ 12 12 Yes numeric source and numeric test value
EQ 14 70 No numeric source and numeric test value
EQ 12 12 Error numeric source and digital test value
EQ 12 "12" Error numeric source and string test value
EQ OFF OFF Yes digital source and digital test value
EQ OFF "OFF" Yes digital source and string test value
EQ OFF "OFF " No digital source and string test value (with
trailing space)
EQ Off OFF Yes digital source and digital test value

Each of the four tests is evaluated in numeric order from Test1 through Test4 and each test is
associated with an “action” attribute numerically. For example, if the test set in Test1
becomes true, the associated “action” would be the one set in the Action1 attribute. In
general, if there is only one test that is used for the alarm point, it would be set in Test1 but
there is no rule governing the where to apply the test for the alarm point. Test1 could be left
unused and Test2, Test3, or Test4 may be used. In the case where all four attributes are
unused, the alarm point defaults to the digital state that represents “no alarm” for that point. If
more than one test is true, the digital state of the alarm is governed by the combiner logic
(page 253) rules and detailed in Action1, Action2, Action3, Action4 (page 264).
The following table shows the available options for the comparison operators with their
descriptions as well as their viable argument data types. An X in the table denotes that the
data type is allowable.

Viable Argument Data Types for Operators

Operator Description Argument Data Type

(X indicates Allowed)
Numeric Digital String
GT Greater Than X
LT Less Than X
EQ Equal To X X X
NE Not Equal To X X X
StepGT Step Greater Than X
StepLT Step Less Than X
RateGT Rate Greater Than X
RateLT Rate Less Than X
Is_In Is In the string or digital state X X
Not_In Is not in the string or digital state X X

256
 Alarm Point Configuration

Operator Description Argument Data Type

(X indicates Allowed)
Includes Includes the string or digital state X X
Change Change of State X X X
CondEQ Alarm condition equals X
CondNE Alarm condition not equal X
IsUnack Alarm condition is unacknowledged X

GT
The operator GT tests numeric constants as well as points that evaluate into numbers against
a numeric source point. An alarm is triggered if the value of the source point is greater than
the value set in the test. If a reference point is used, the tagname of the reference point is used
as the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point. A time parameter in the form of a
relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
GT ( 12 )
GT ( 'tagname' )
GT ( ref )
GT ( ref + 14 )
GT ( 70 ) +1h

LT
The operator LT tests numeric constants as well as points that evaluate into numbers against
a numeric source point. An alarm is triggered if the value of the source point is less than the
value set in the test. If a reference point is used, the tagname of the reference point is used as
the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point. A time parameter in the form of a
relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
LT ( 12 )
LT ( 'tagname' ) +14m
LT ( ref - 70 )
LT ( 11 ) +1h

PI Server Applications User Guide 257

PI Alarm Subsystem

EQ
The operator EQ tests can be performed with numeric constants, digital states, strings or a
reference to another point. An alarm is triggered if the value of the source point is equal to the
value set in the test. If a reference point is used, the tagname of the reference point is used as
the argument. If the keyword ref replaces the numeric constant as the argument and the
ReferenceTag attribute contains the tagname of the reference point, a numeric constant may
be added or subtract to the value of the reference point.
A time parameter in the form of a relative timestamp can delay the triggering of an alarm
until the comparison is true for that period of time.
EQ( 12.14 )
EQ ( OFF )
EQ ( ref )
EQ ( ref + 70 )
EQ ( "This is a string" ) +1h

NE
The operator NE tests can be performed with numeric constants, digital states, strings or a
reference to another point. An alarm is triggered if the value of the source point is not equal
to the value set in the test. If a reference point is used, the tagname of the reference point is
used as the argument. If the keyword ref replaces the numeric constant as the argument and
the ReferenceTag attribute contains the tagname of the reference point, a numeric constant
may be added or subtract to the value of the reference point. A time parameter in the form of
a relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time.
NE( 12 )
NE ( ON )
NE ( 'tagname' )
NE ( ref - 14.11 )
NE ( “This is a string” ) +70m

StepGT
The operator StepGT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point changes
more than the value set in the test. If a reference point is used, the tagname of the reference
point is used as the argument. If the keyword ref replaces the numeric constant as the
argument and the ReferenceTag attribute contains the tagname of the reference point, a
numeric constant may be added or subtract to the value of the reference point. A time
parameter in the form of a relative timestamp can delay the triggering of an alarm until the
comparison is true for that period of time.
StepGT ( 12 )
StepGT ( 'tagname' ) +14m
StepGT ( ref - 70 )
StepGT ( 11 ) +1h

258
 Alarm Point Configuration

StepLT
The operator StepLT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point changes
less than the value set in the test. If a reference point is used, the tagname of the reference
point is used as the argument. If the keyword ref replaces the numeric constant as the
argument and the ReferenceTag attribute contains the tagname of the reference point, a
numeric constant may be added or subtract to the value of the reference point. A time
parameter in the form of a relative timestamp can delay the triggering of an alarm until the
comparison is true for that period of time.
StepLT ( 12 )
StepLT ( 'tagname' )
StepLT ( ref - 14 )
StepLT ( 70 ) +1h

RateGT
The operator RateGT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the rate of change of the source point
is greater than the value set in the test. The rate of change is calculated by dividing the
difference between discrete average of two successive periods by the period. The following
figure shows an example of the calculation of the rate of change.

Calculation of Rate of Change

In the example, the average of the first period is 6.5 units and the average of the second
period is 5.0 units. Hence the rate of change is 1.5 units per minute. The values used in the
calculation are those sent to PI Snapshot as exceptions. The comparison test is made after the
second period at the time of the arrival of the next source point Snapshot value. The default
period is 10 minutes. The period can be changed by setting a new period in the options
attribute.

PI Server Applications User Guide 259

PI Alarm Subsystem

If a reference point is used, the tagname of the reference point is used as the argument. If the
keyword ref replaces the numeric constant as the argument and the ReferenceTag attribute
contains the tagname of the reference point, a numeric constant may be added or subtract to
the value of the reference point. A time parameter in the form of a relative timestamp can
delay the triggering of an alarm until the comparison is true for that period of time.
RateGT ( 12.8 )
RateGT ( 'tagname' )
RateGT ( ref + 14 )
RateGT ( 70 ) +1h

RateLT
The operator RateLT tests numeric constants as well as points that evaluate into numbers
against a numeric source point. An alarm is triggered if the value of the source point is less
than the value set in the test. If a reference point is used, the tagname of the reference point is
used as the argument. If the keyword ref replaces the numeric constant as the argument and
the ReferenceTag attribute contains the tagname of the reference point, a numeric constant
may be added or subtract to the value of the reference point. A time parameter in the form of
a relative timestamp can delay the triggering of an alarm until the comparison is true for that
period of time. The default period is 10 minutes. The period can be changed by setting a new
period in the options attribute.
RateLT ( 12.8 )
RateLT ( 'tagname' )
RateLT ( ref + 14 )
RateLT ( 70 ) +1h

Is_In
The operator Is_In tests digital states, strings, or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings, and a string-to-string comparison is performed. The Is_In operator triggers an alarm
if the source point value is in the test value. For a reference point, the tagname of the
reference point is used as the argument. If the keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time.
Is_In ( "ON OFF" )
Is_In ( 'tagname' )
Is_In ( ref )
Is_In ( "This is a string" ) +1h

Comparisons of the Is_In Operator

Operator Source Test value Trigger an Comparison

point value alarm?
Is_In Off "ON OFF" Yes digital source and string test value
Is_In "string" "This is a string" Yes string source and string test value
Is_In "str" "This is a string" Yes string source and string test value

260
 Alarm Point Configuration

Operator Source Test value Trigger an Comparison

point value alarm?
Is_In "strings" "This is a string" No string source and string test value
Is_In 100 1002 Error numeric source and digital test
value
Is_In 100 "1002" Error numeric source and string test value

Not_In
The operator Not_In tests digital states, strings, or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings and a string-to-string comparison is performed.
The Change operator triggers an alarm if the source point value is not in the test value. For a
reference point, the tagname of the reference point is used as the argument. If keyword ref is
used as the argument, the ReferenceTag attribute contains the tagname of the reference
point.
A time parameter in the form of a relative timestamp can delay the triggering of an alarm
until the comparison is true for that period of time.
Not_In ( "ON OFF" )
Not_In ( 'tagname' )
Not_In ( ref )
Not_In ( ON ) +1h

Comparisons of the Not_In Operator

Operator Source point Test value Trigger an Comparison

value alarm?
Not_In ON "OFF ON" No digital source and string test value

Not_In OF "OFF ON" No digital source and string test value

Not_In ONE "OFF ON" Yes digital source and string test value

Not_In "1" 12345678 No string source and digital test value

Not_In 9 "12345678" Yes digital source and string test value

Not_In 10 100 Error numeric source and digital test

value
Not_In 10 "100" Error numeric source and string test value

Includes
The operator Includes tests digital states, strings or points that evaluate into digital states or
strings against a digital state or string. In the comparison, all digital states are converted into
strings and a string to string comparison is performed. The Includes operator triggers an
alarm if the source point value includes the test value. For a reference point, the tagname of

PI Server Applications User Guide 261

PI Alarm Subsystem

the reference point is used as the argument. If keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time.
Includes ( HI )
Includes ( 'tagname' )
Includes ( ref )
Includes ( "This is a string" ) +1h

Comparisons of the Includes Operator

Operator Source point Test value Trigger an Comparison

value alarm?
Includes Hihi "HI" Yes digital source and string test value
Includes High HI Yes digital source and digital test value
Includes "VIN3234A" "VIN3234" Yes string source and string test value

Includes "VIN3234A" "VIN3235" No string source and string test value

Includes 1002 100 Error numeric source and digital test

value
Includes 1002 "100" Error numeric source and string test
value

Change
The operator Change tests numeric values, digital states, strings or points that evaluate into
numeric values, digital states or strings. All numeric comparisons are done as floating point
operations and comparisons of all digital states are converted into strings and a string-to-
string comparison is performed. The Change operator triggers an alarm if the source point
value is different from the previous value. A time parameter in the form of a relative
timestamp can delay the triggering of an alarm until the comparison is true for that period of
time.
Change ( )
Change ( ) +1h

CondEQ
The operator CondEQ tests alarm point conditions against alarm points. An alarm triggers if
an alarm of another alarm point is equal to the test value. For a reference point, the tagname
of the reference point is used as the argument. If keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time. The argument is an alarm condition. In the following examples, an
alarm is triggered if the condition of the source alarm point is low, the condition of the source
alarm point is equal to the condition of the reference point (ref), and the condition of the
source point is high for over one hour, respectively.
CondEQ ( low )

262
 Alarm Point Configuration

CondEQ ( 'alarmtagname' )
CondEQ ( ref )
CondEQ ( high ) +1h

The following table shows examples of the CondEQ operator using the sample Alarm Digital
State Set (page 267). The digital state for a new alarm with the condition of low is low << and
the digital state for an acknowledged alarm with the condition of low and an urgent priority is
** low.
Operator Source point Test value Trigger an Comparison
value alarm?
CondEQ Low Low Yes digital source and
digital test value
CondEQ Low << Low Yes digital source and
digital test value
CondEQ ** low Low Yes digital source and
digital test value
CondEQ Low Lolo No digital source and
digital test value

CondNE
The operator CondNE tests alarm point against an alarm point. An alarm triggers if an alarm
of another alarm point is not equal to the test value. For a reference point, the tagname of the
reference point is used as the argument. If keyword ref is used as the argument, the
ReferenceTag attribute contains the tagname of the reference point. A time parameter in the
form of a relative timestamp can delay the triggering of an alarm until the comparison is true
for that period of time. The argument is an alarm condition. In the following examples, an
alarm is triggered if the condition of the source alarm point is not low, the condition of the
source alarm point is not equal to the condition of the reference point (ref), and the condition
of the source point is not high for over one hour, respectively.
CondNE ( low )
CondNE ( 'alarmtagname' )
CondNE ( ref )
CondNE ( high ) + 1h

IsUnack
IsUnack tests an alarm point against another alarm point. This operator has no arguments and
triggers an alarm if the source alarm point is unacknowledged.
In the following examples, an alarm is triggered if the source alarm point is unacknowledged
and goes unacknowledged for over one hour, respectively.
IsUnack ( )
IsUnack ( ) +1h

PI Server Applications User Guide 263

PI Alarm Subsystem

Action1, Action2, Action3, Action4

The set of four attributes Action 1, Action 2, Action 3 and Action 4 specify the digital state
that is set when the corresponding test set in the Test1, Test2, Test3, Test4 attributes trigger
an alarm. There are two forms of the attribute and their syntax is as follows.
Syntax:
Form 1) Condition Priority
Form 2) StateName

If an Alarm State Set is the Digital State Set for the alarm point, then the first form of the
attribute is used. In this case Condition is the alarm condition to be set for the alarm point
and Priority is the numeric priority level alarm. See Alarm State Sets (page 267) for details
about conditions and priorities. The following table gives examples of the use of the first
syntax and the resulting digital state that is set using the example Alarm Digital State Set.

Examples Using First Syntax (Condition Priority)

Action1 Digital State Description

Hihi 1 __ hihi << New unacknowledged HIHI alarm with priority level 1
Hihi 2 _* hihi << New unacknowledged HIHI alarm with priority level 2
High 3 ** high << New unacknowledged HIGH alarm with priority level 3
Low 0 LOW LOW alarm with priority 0 always returns just the alarm condition

In the above examples, the digital state that is set is for a new alarm with the attribute
AutoAck set to NO. Furthermore, it is also possible to have a priority level of 0, which is
shown as the last example in the table above. In that case, only the alarm condition is returned
regardless of the acknowledgment status.
The second case is not limited to the Alarm Digital State Set and any digital state set may be
utilized. The second case only requires that the attribute contain a digital state (StateName)
that belongs to the digital state set of the alarm point.

Examples Using Second Syntax (StateName)

Action1 Digital State Description

Hihi HIHI Condition only. Similar to using the first syntax with priority 0
** high ** High Alarm Digital State
auto Auto Digital Set used is Modes {Manual, Auto, Cascade, Program, Prog-
Auto}

The first two examples given in the table above use the Alarm Digital State Set from the table
Alarm Digital State Set with Three Priorities shown in Priority (page 268). The last
example used a default digital state set, Modes, with the digital states {Manual, Auto,
Cascade, Program, Prog-Auto}.
When more than one alarm is triggered simultaneously, the combiner logic determines the
digital state that is set by using the following rules:
• Priorities have precedence.
• When two conditions of the same priority are true, it is the first (in order of the tests) that
is used to set the Alarm State.

264
 Alarm Point Configuration

The following table gives examples of which “action” is taken when more than one “action”
attribute is triggered. In these examples, it is assumed that all four tests were done and the
“actions” that were left blank are the result of alarms that were not triggered.

Combiner Logic Examples

Action1 Action2 Action3 Action4 Result

Hihi 1 High 1 Hihi 1
Hihi 2 High 1 Hihi 2
auto Manual auto

In the first combiner logic example, all the priorities are the same; hence Action1 is set
because it is the first test that is true. In the second example, even though Action4 and
Action1 are both true, Action1 is used because it has a higher priority. The last example
demonstrates the second syntax where priority is not used; hence Action1 is set because it is
the first test that is true. See Alarm State Sets (page 267) for more details about the digital
state that is set.

ExDesc

The tagname of the Alarm Group for the alarm point is set in the ExDesc. An alarm point
must belong to an Alarm Group and the Alarm Group must be created before the creation of
the alarm point. See Alarm Groups (page 271) for more details.

DigitalSet

The DigitalSet attribute specifies the name of the Alarm State Set that is to be associated
with the tag. An alarm point is required to have a digital set and the digital set must be
created before the creation of the alarm point. See Alarm State Sets (page 267) for more
details about Alarm Digital States.

ReferenceTag

The tagname defined in the ReferenceTag attribute is used in the Test1, Test2, Test3, and
Test4 attributes as a reference point to trigger alarms. In the case where a reference is used,
the argument in the test is the keyword ref. In this case, the ReferenceTag attribute must be
the tagname of the desired reference point.

AutoAck

The two options that can be set for the AutoAck attribute are yes or no. The default is yes. If
the value in AutoAck attribute is yes then an alarm is automatically acknowledged. For a
three-acknowledgment status configuration in the Alarm State Set, the new and
unacknowledged missed statuses shown in the table in Acknowledgment Status (page 267)
would never be assigned to an alarm point value.

PI Server Applications User Guide 265

PI Alarm Subsystem

DeadBand

The DeadBand attribute modifies the Test1, Test2, Test3, and Test4 attributes of GT and
LT. The DeadBand is a threshold, within the alarm limit, that the rate point must pass after
an alarm is triggered before the point is considered not to be in alarm. The default DeadBand
is 0.

Deadbands for Upper and Lower Alarm Limits

Options

The option attribute is used to modify the period associated with the RateGT and RateLT
operators in the Test1, Test2, Test3, and Test4 attributes.
Syntax: RTime = timestamp

The following examples set the period to 1 hour, 5 minutes, and 30 seconds respectively.
RTime = +1h
Rtime = +5m
Rtime = +30s

ControlTag

The tagname defined in the ControlTag attribute is used in the combiner logic to disable
alarms. The tagname specified by the ControlTag attribute must refer to a numeric (any float
or integer) or digital point type. Any other point type results in an Error state for the alarm
point. In the case where a control tag is used, the alarm can be taken out of service by setting
the value of the control tag to zero for numeric tags or the 0th state for digital tags.
Following is an example of using the ControlTag to disable an alarm when net generation
drops below a predetermined value. This could easily be applied to all alarms on a unit.
Assume that U2:NetGen.PV is the net generation on our example unit.
Configure a PE point, a digital point, with 2 states: Not Running and Running. Be sure that
Not Running is first digital state in the set. Set the point to be naturally scheduled, based on
our net generation value. The ExDesc of the Performance Equation will look similar to:

266
 Alarm State Sets

event=U2:NetGen.PV, if('U2:NetGen.PV' > 5) THEN "Running" ELSE

"Not Running"

If there are only two states in this digital set and Not Running is the first one, the following
ExDesc does the same thing.
event=U2:NetGen.PV, 'U2:NetGen.PV' > 5

Finally, enter the tagname of this Performance Equation as the ControlTag of any alarms
that should be disabled when net generation falls below 5.

ControlAlg

Reserved attribute for future implementation.

Alarm State Sets

An Alarm State Set is a Digital State Set constructed such that condition, acknowledgment,
and priority codes are all encoded in the digital states.

Condition

The condition of an alarm describes the manner in which an alarm is manifested. The
following table shows some sample descriptions of the types of alarm conditions that may be
implemented.

Sample Alarm Conditions

Condition Example Description

Lolo The value of the point is far below normal
Low The value of the point is below normal
High The value of the point is above normal
Hihi The value of the point is far above normal
Rate The rate of change of the point is abnormal
Step The change in value of the point is abnormal
Change The value of the point has changed from the previous

Acknowledgment Status

The acknowledgment shows the status or the amount of attention that has been paid to the
alarm. The acknowledgment status is a modifier to the condition of the alarm. PI Alarm
allows for 1 or 3 states of acknowledgment statuses. The three-state acknowledgment status
set consists of the New Alarm, the Acknowledged Alarm and Unacknowledged Alarm that is
missed. The one-state acknowledgment is defined by having all alarms acknowledged. The
following table shows the three-state acknowledgment status and respective descriptions.

PI Server Applications User Guide 267

PI Alarm Subsystem

Three-state acknowledgment Status

Acknowledgment Description
Status
New An alarm has been triggered and is unacknowledged.
Acknowledged The triggered alarm is acknowledged.
Unacknowledged The unacknowledged alarm was missed because the source point is no
Missed longer in alarm.

Priority

The priority describes the level of importance given to the triggered alarm or the severity
associated with the triggered alarm. The following table is an Alarm Digital State Set with a
single priority and three acknowledgment statuses.

Single Priority Alarm State Set

New Alarm Acknowledged Alarm Unacknowledged Alarm Missed

Lolo << Lolo Lolo _x
Low << Low Low _x
High << High High _x
Hihi << Hihi Hihi _x
Rate << Rate Rate _x
Step << Step Step _x
Change << Change Change _x
Dig1 << Dig1 Dig1 _x
Dig2 << Dig2 Dig2 _x

In this scheme, the acknowledgment statuses are represented by symbols. New alarms are
denoted by the symbol << at the end of the alarm conditions, while acknowledged alarms are
just denoted as the alarm conditions itself. Alarms that are missed because the source point
has gone out of an alarm condition are denoted by an underscore followed by an x (_x) after
the alarm condition.
For the case where more severity is placed on certain types of alarms as opposed to others,
the priority level can be expanded to multiple levels. The following table shows an example
of a three-priority system with their respective meanings.

Example Three-priority-level System

Priority Example Description Sample Symbol

Level
1 Alert __
2 Important _*
3 Most Urgent **

The three priorities are classified from the most severe (priority level 3) to the least severe
(priority level 1) as Most Urgent, Important, and Alert and their respective symbols which

268
 Alarm State Sets

is denoted in front of the alarm condition are “**”, “_*”, and “__” respectively. The
following table shows the same Alarm Digital State Set with the additional priorities.

Alarm Digital State Set with Three Priorities

Priority New alarm Acknowledged Alarm Unacknowledged Alarm

Missed
Most ** Lolo << ** Lolo ** Lolo _x
Urgent
** Low << ** Low ** Low _x
** High << ** High ** High _x
** Hihi << ** Hihi ** Hihi _x
** Rate << ** Rate ** Rate _x
** Step << ** Step ** Step _x
** Change << ** Change ** Change _x
** Dig1 << ** Dig1 ** Dig1 _x
** Dig2 << ** Dig2 ** Dig2 _x
Important _* Lolo << _* Lolo _* Lolo _x
_* Low << _* Low _* Low _x
_* High << _* High _* High _x
_* Hihi << _* Hihi _* Hihi _x
_* Rate << _* Rate _* Rate _x
_* Step << _* Step _* Step _x
_* Change << _* Change _* Change _x
_* Dig1 << _* Dig1 _* Dig1 _x
_* Dig2 << _* Dig2 _* Dig2 _x
Alert __ Lolo << __ Lolo __ Lolo _x
__ Low << __ Low __ Low _x
__ High << __ High __ High _x
__ Hihi << __ Hihi __ Hihi _x
__ Rate << __ Rate __ Rate _x
__ Step << __ Step __ Step _x
__ Change << __ Change __ Change _x
__ Dig1 << __ Dig1 __ Dig1 _x
__ Dig2 << __ Dig2 __ Dig2 _x
The only default Alarm State Set that is installed is the Pialarm33 State Set. Four sample
Alarm State Sets are also included in a piconfig script (two for use with numeric source tags
and two for digital). These sample Alarm State Sets are provided in Alarm State Sets (page
267). For each type, one set is simple, only showing alarm condition, and the other complete,
showing priority, condition, and acknowledge status. The sample Alarm State Sets for
numeric source points are displayed in the tables "Single Priority Alarm State Set" and

PI Server Applications User Guide 269

PI Alarm Subsystem

"Example Three-priority-level System." A second set of Alarm State Sets for digital or string
source points are provided in the following two tables.
Example Digital Alarm State Set with One Priority

New alarm Acknowledged Alarm Unacknowledged Alarm Missed

Move << Move Move _x
Fail << Fail Fail _x
Off << Off Off _x
Over << Over Over _x
Under << Under << Under <<
Change << Change Change _x
D7 << D7 D7 _x
D8 << D8 D8 _x

Example Digital Alarm Set with Three Priorities

Priority New alarm Acknowledged Alarm Unacknowledged Alarm Missed

Most Urgent ** Move << ** Move ** Move _x
** Fail << ** Fail ** Fail _x
** Off << ** Off ** Off _x
** Over << ** Over ** Over _x
** Under << ** Under ** Under _x
** Change << ** Change ** Change _x
** D7 << ** D7 ** D7 _x
** D8 << ** D8 ** D8 _x
Important _* Move << _* Move _* Move _x
_* Fail << _* Fail _* Fail _x
_* OFF << _* OFF _* OFF _x
_* Over << _* Over _* Over _x
_* Under << _* Under _* Under _x
_* Change << _* Change _* Change _x
_* D7 << _* D7 _* D7 _x
_* D8 << _* D8 _* D8 _x
Alert __ Move << __ Move __ Move _x
__ Fail << __ Fail __ Fail _x
__ OFF << __ OFF __ OFF _x
__ Over << __ Over __ Over _x
__ Under << __ Under __ Under _x
__ Change << __ Change __ Change _x
__ D7 << __ D7 __ D7 _x
__ D8 << __ D8 __ D8 _x

270
 Alarm Groups

Each site using PI Alarms needs to examine its needs for alarm display sets and establish
local standards. While state sets can be added or changed, some changes require significant
re-configuration of client programs. This can be minimized by planning.
As with all Digital State Sets, each of the digital state strings in the tables corresponds to a
digital state code. The manner in which the Alarm State Sets mentioned above are changed
into digital states is explained in Alarm State Set Encoding and Decoding (page 279).

Alarm Groups
An Alarm Group is a collection of alarm points that are grouped together using a common
group name. Furthermore, Alarm Groups may also contain other Alarm Groups, to create an
alarm hierarchy. Each alarm point is assigned to a single Alarm Group. The Alarm Group
organization should match the operational structure of the plant. This hierarchy forms the
basis for alarm system control and reporting functions.
Each Alarm Group is represented in the PI system by one or more points. A single point is
required to provide the name for the group referred to by alarm points within it. The Alarm
Group point can receive values that represent statistics about the alarms in the group.
Additional points allow the alarm subsystem to report group statistics (number of alarms,
number of unacknowledged alarms, and so on.). These additional statistical points are
optional.

Alarm Group Point Configuration

An Alarm Group is represented by one or more points in the PI System. The default point
source for Alarm Group points is G. The Alarm Group uses the point class base with a
numeric data type. The parameters that configure an Alarm Group are contained in the
ExDesc attribute.
Attribute Parameters
ExDesc GroupName PointFunc Arg

The GroupName parameter defines the name of the group. The PointFunc parameter
contains the options to be set for the group. Statistics of the Alarm Group are described in the
PointFunc table. The Arg parameter is a modifier to the PointFunc parameter. Available
statistics include the number of alarms at each priority and the highest priority of the
currently active alarms in the group. Groups can be arranged on a hierarchy.

PointFunc Options

PointFunc Description
GroupID Setting PointFunc to GroupID defines the Alarm Group. The optional Arg
parameter is the name of the group's parent group in the hierarchy (if it exists)
UnAck Displays total number of unacknowledged alarms within a group or priority.
The Arg parameter defines the priority for the unacknowledged alarms.
InAlarm Displays total number of points in alarm within a group or priority. The Arg
parameter defines the priority of the alarms.

PI Server Applications User Guide 271

PI Alarm Subsystem

In that case, the statistics at the parent level include the points in the following groups.
Groups can be arranged to any depth. There is nothing preventing both points and groups
from being assigned to the same group. The following table shows an example Alarm Group
hierarchy with two subgroups.
Example Alarm Group

TagName ExDesc Description

AlarmTop AlarmTop Name of Alarm Group for the top of alarm hierarchy and
GroupID also total number of alarm points within the hierarchy in
an Alarm State.
Tot_Unack AlarmTop Total number of unacknowledged alarms in AlarmTop
UnAck hierarchy
AlarmGrp1 AlarmGrp1 Name of Alarm Group that belongs to the AlarmTop
GroupID hierarchy and also the total number of alarm points in this
AlarmTop group that is in an Alarm State.
AlarmGrp1_Unack_1 AlarmGrp1 Number of unacknowledged alarms in AlarmGrp1 with
UnAck 1 priority 1
AlarmGrp1_InAlarm_1 AlarmGrp1 Number of alarm points in an Alarm State in AlarmGrp1
InAlarm 1 with priority 1
AlarmGrp2 AlarmGrp2 Name of Alarm Group that belongs to the AlarmTop
GroupID hierarchy and also the total number of alarm points in this
AlarmTop group that is in an Alarm State.
AlarmGrp2_InAlarm_0 AlarmGrp2 Number of alarm points in an Alarm State in AlarmGrp2
InAlarm 0 with priority 0
AlarmGrp2_Unack AlarmGrp2 Total number of unacknowledged alarms in AlarmGrp2
UnAck

This example Alarm Group contains the point AlarmTop that defines the top of the alarm
hierarchy. AlarmTop and Tot_Unack give the statistics of the total number of alarms points
that are in alarm and the total number of unacknowledged alarms in the alarm hierarchy that
are in the alarm hierarchy. AlarmGrp1 and AlarmGrp2 are the two Alarm Groups within the
hierarchy.
AlarmGrp1_Unack_1 and AlarmGrp1_InAlarm_1 are the statistics of the number of
unacknowledged alarms in Alarm Group AlarmGrp1 with priority 1 and the number of alarm
points in AlarmGrp1 that are in alarm with priority 1, respectively.
AlarmGrp2_InAlarm_0 and AlarmGrp2_Unack are the number of alarm points in an
Alarm State with priority 0 in AlarmGrp2, and the statistics of the total number of
unacknowledged alarms in AlarmGrp2, respectively. Using the modifier Arg of 'UnAck'
with the priority 0 always returns 0 because conditions are always considered acknowledged.

Build Alarm Points

Alarm points are created in the same manner as other points except that the Alarm must be of
alarm point class, which includes Base attributes. The point type must be digital and the
PointSource must be @.
To override the PointSource default values, see Override Default PointSource Values for
Alarms (page 274).

272
 Build Alarm Group Points

PI TagConfigurator

You can easily create alarm points with the PI TagConfigurator tool. See the OSIsoft
Technical Support Web site (http://techsupport.osisoft.com/) to download this tool.

PI TagConfigurator Creation of Alarm Point

Piconfig

Alternatively, you can use piconfig to create an alarm point:

@table pipoint
@ptclass alarm
@mode create, t
@istru tag, pointsource, sourcetag, exdesc, pointtype,
digitalset, test1, action1
alarmtag1, @, sinusoid, alarmgrp1, digital, pialarm33, lt (20),
lolo 2
@ends

Build Alarm Group Points

Alarm Group points are created in the same manner as other points. The point type must be
numeric and the PointSource must be G.
To override the PointSource default values, see Override Default PointSource Values for
Alarms (page 274).

PI Server Applications User Guide 273

PI Alarm Subsystem

PI TagConfigurator

Alarm Group points can be created using the PI Tag Configurator utility, which you can
obtain from the OSIsoft support Web site.

PI Tag Configurator

Piconfig

Alternatively, you can use the piconfig utility to create the same Alarm Group point.
@table pipoint
@ptclass classic
@mode create, t
@istru tag, pointsource, exdesc, pointtype
alarmgrp1, G, "alarmgrp1 GroupID", Int32
@ends

Override Default PointSource Values for Alarms

You can override the default PointSource values by setting particular values in the Windows
Registry. Under the Registry key, HKLM\SYSTEM\CurrentControlSet\Services\pialarm,
the string values AlarmPS, GroupPS, and SQCAlarmPS are present if they have been set.
For example, in the following example, the RegEdit screen shows PointSource for Alarm
points is set to A, the PointSource for group points is set to S, and the PointSource for sqc
alarmpoints is set to C. Changes take effect only when the pialarm service is restarted. The
file PI\dat\pilastalarm.dat also needs to be deleted so that points with the old point source will
no longer be updated by the PI Alarm.

274
 Build Alarm Digital State Sets

Build Alarm Digital State Sets

Alarm Digital State Sets are similar to all digital state sets in that each digital state string must
correspond to a digital state code. The Alarm State Set is special because there is a specific
structure that is required for this type of digital state set. The following piconfig script is an
example that shows how to build a simple Alarm Digital State Set with three
acknowledgment statuses, three priorities, and two conditions, low and high.
@table PIDS
@mode create,t
@istyp delim,
@istru set,
@istru oldcode ,state
@istru ...,
pialm33,
1, ----
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<
6, _* Low <<
7, ** Low <<
8, __ Low _x
9, _* Low _x
10, ** Low _x
11, __ High ^^
12, _* High ^^
13, ** High ^^
14, __ High <<
15, _* High <<
16, ** High <<
17, __ High _x

PI Server Applications User Guide 275

PI Alarm Subsystem

18, _* High _x
19, ** High _x
20, LOW
21, HIGH
22, 3 3
@ends,
In the above script, the Alarm State Set is named pialm33. There are 22 digital states. The
first digital state is the state of no alarm. In this script, the no alarm status is represented by
the symbol “----”.
1, ----
If the desired representation for no alarm is “No Alarm,” this line in the script would be:
1, No Alarm
The last digital state (22) corresponds to the number of acknowledgment statuses and the
number of priorities that exist for the Alarm State Set. In this example, it is three for both. For
only one priority, the line would read as follows:
22, 3 1
The Alarm State Set is created in a manner similar to having three nested loops, where the
outer loop is the condition, the middle loop is the acknowledgment status, and the innermost
loop is the priority. So for each condition, the innermost loop sets the priorities from least
severe to most severe, which are represented here by the symbols “__”, “_*”, “**”.
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
The middle loop then sets the acknowledgment statuses in the order of acknowledged alarm
(^^), new alarm (<<) and unacknowledged alarm missed (_x).
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<
6, _* Low <<
7, ** Low <<
8, __ Low _x
9, _* Low _x
10, ** Low _x

The outer loop finally loops around the conditions. Hence each condition has three
acknowledgment statuses and three priorities, and thus nine digital states each. Since the first
digital state code is the no alarm condition, digital state codes 2 though 19 are used for the
Alarm States. At the end of the Alarm States are the condition names themselves.
20, LOW
21, HIGH

As mentioned earlier, the last digital state code is used to tell the alarm program how many
acknowledgment statuses and priorities are in the Alarm State Set.
22, 3 3

Fore more details on encoding and decoding Alarm Digital States, see Alarm State Set
Encoding and Decoding (page 279).

276
 Program Operation

Program Operation
Startup

The Alarm Subsystem program is started with the rest of the system. The program
pialarm.exe is in the pi\bin directory. All rate calculations are reset when the PI System or
the Alarm Subsystem is restarted.

Alarm Notification

Alarm Points are standard digital points. Client programs can request to be alerted when point
values change through the standard Update Manager mechanisms. PI ProcessBook can use
alarm summary tags as the basis for the operator alert process without signing up for every
alarm point in the system.

Viewing Alarms in PI ProcessBook

The following figure shows an example of an alarm display in PI ProcessBook.

Example PI ProcessBook Display of Alarms

PI Server Applications User Guide 277

PI Alarm Subsystem

The example above is edited from the Kamyr display, from the PIDemo example included in
PI ProcessBook. It shows the alarm point values next to the values of the source tag as well as
a trend display of the statistics of the alarms for the unit (Unit5). The chart on the bottom left
corner displays the statistics of the alarms for the four other units as well as the current unit.

Error Messages

All significant events in the life of an alarm and Alarm Group point are noted in the system
Message Log, including point additions, edits and error conditions. To monitor logged events,
use PI System Management Tools or the pigetmsg utility. See the PI Server System
Management Guide for details about the pigetmsg utility.

Demonstration Points

Demonstration points for the PI Alarm Subsystem are available in the pi\adm directory in
the Alarmpts.dif file but are not automatically created when the system is installed.
These alarm demonstration points can be created by redirecting the file to the piconfig utility.
$ piconfig < alarmpts.dif

See the PI Server System Management Guide for details about using the piconfig utility.

PI for OpenVMS Upgrade Considerations

The PI Server Alarm subsystem is capable of having all the alarms of the PI for OpenVMS
version and more.
The following are known differences:
• The method of alarm messaging is not supported on the server side. The Alarm Client
program allows for the viewing of alarms and Alarm Groups as well as messaging.
• A log of the alarms is not available. The history of the alarm is contained in the alarm
points themselves.
• Acknowledgment of the alarm is accomplished by selecting the auto-acknowledgment
feature or writing an acknowledged digital state to the PI system through the PI API or PI
SDK.

New Alarm Subsystem Features in PI Server 3.4

The Alarm Subsystem includes new features that are not included in PI for OpenVMS.
• The Alarm Subsystem allows you to set Alarm priorities.
• Alarm Groups can incorporate other Alarm Groups, to form hierarchies.
• The Alarm Subsystem supports testing of string tags.

278
 Alarm State Set Encoding and Decoding

Alarm State Set Encoding and Decoding

Due to the manner in which the Alarm State Set is structured, conversion from the digital
state code or offset to the condition, acknowledgment status, and priority is not as
straightforward as it may seem.
There is a distinction between the manner in which Digital State Sets are created and the
digital state code (offset) that is returned from a client program. For example, the following is
part of the piconfig script to create an Alarm Digital State Set as explained in Build Alarm
Digital State Sets (page 275).
@table PIDS,
@mode create,t
@istyp delim,
@istru set,
@istru oldcode ,state
@istru ...,
pialm33,
1, ----
2, __ Low ^^
3, _* Low ^^
4, ** Low ^^
5, __ Low <<

In the script, the digital states are numbered starting at 1. On the contrary, the offset, which is
returned from a client program returns the digital state offset in which the number begins at 0.
Therefore, for encoding and decoding, the digital state code is the digital state offset. Hence
the offset for the digital state shown for ** Low ^^ in the script is 3 and not 4.
In order for client applications to convert from digital state codes to the condition,
acknowledgment status, and priority, and vice versa, the following algorithms should be
applied. See Build Alarm Digital State Sets (page 275) for more details.

Conversion to Digital State code

The algorithm for conversion points first needs to change the condition, C, acknowledgment
status, A, and priority, P, to numeric values. In the conversion the value for the condition is
given by where the condition is placed in the Alarm State Set. For example, in the Alarm
State Set given in the table "Alarm Digital State Set with Three Priorities," the conditions are
listed as follows.
Lolo
Low
High
Hihi
Rate
Step
Change
Dig1
Dig2

Therefore, the position for the condition Hihi within the list of conditions is 4, and the
number of conditions, MaxC, is 9. Nack is the number of acknowledgment statuses. This

PI Server Applications User Guide 279

PI Alarm Subsystem

number can only be 1 or 3. The numeric value for the acknowledgment statuses, A, for the
case when Nack is 1 is 1. The numeric values for the situation when Nack is 3, is given as
follows.
A = 0 (Acknowledged)
A = 1 (New Alarm)
A = 2 (Unacknowledged Missed)

The priority, P, is level of severity associated with the alarm. This number increases as the
severity of the alarm increases and goes from 0 to the maximum priority, MxP.
For example, an Alarm State Set with MxP equal to 3 is as follows.
P = 0 (Condition Only)
P = 1 (Alert)
P = 2 (Important)
P = 3 (Most Urgent)

P equal to 0 results in the alarm condition. The number of states per condition Pa1 is given
by multiplying the number of acknowledgeable statuses by the max numeric priority level:
Pa1 = Nack * MxP

For example, if the two conditions in the Alarm State Set are high and low, then MaxC is
equal to 2. The number of states in the Alarm State Set is Nsts.
Nsts = Pa1 * MaxC + MaxC

The digital state code, code, is then given by the following equation.
code = Pa1 * ( C - 1 ) + Mxp * A + P

Conversion from Digital State Code

Given the numeric values for the condition, C, acknowledgment status, A, and Priority, P, the
digital state code, code, is obtained using the following equations points.
C = int( ( code-1)/Pa1 ) +1
A = int( ( code-Pa1*(C-1)-1)/MxP )
P = code-Pa1*(C-1) - MxP * A

In the prior equations, the number of states per condition is Pa1 and the maximum number of
priorities is MxP. These are defined in Build Alarm Digital State Sets (page 275).

Sample Alarm Digital State Sets

The following tables list the four Alarm State Sets and their respective digital state numbers,
which are used in a piconfig session points. The only Alarm Digital State Set that is installed
(by default) is pialarm33.
These Alarm State Sets can be created in a piconfig session using the file almstate.dif.
$ piconfig < almstate.dif

280
 Alarm State Set Encoding and Decoding

One Priority Alarm Set

Offset AlarmSet
0 .
1 Lolo
2 Low
3 High
4 Hihi
5 Rate
6 Change
7 Dig1
8 Dig2
9 Lolo <<
10 Low <<
11 High <<
12 Hihi <<
13 Rate <<
14 Change <<
15 Dig1 <<
16 Dig2 <<
17 Lolo _x
18 Low _x
19 High _x
20 Hihi _x
21 Rate _x
22 Change _x
23 Dig1 _x
24 Dig2 _x
25 LOLO
26 LOW
27 HIGH
28 HIHI
29 RATE
30 CHANGE
31 DIG1
32 DIG2
33 31

PI Server Applications User Guide 281

PI Alarm Subsystem

Three Priority Alarm Set

Offset AlarmSet
0 .
1 __ Lolo
2 _* Lolo
3 ** Lolo
4 __ Lolo <<
5 _* Lolo <<
6 ** Lolo <<
7 __ Lolo _x
8 _* Lolo _x
9 ** Lolo _x
10 __ Low
11 _* Low
12 ** Low
13 __ Low <<
14 _* Low <<
15 ** Low <<
16 __ Low _x
17 _* Low _x
18 ** Low _x
19 __ High
20 _* High
21 ** High
22 __ High <<
23 _* High <<
24 ** High <<
25 __ High _x
26 _* High _x
27 ** High _x
28 __ Hihi
29 _* Hihi
30 ** Hihi
31 __ Hihi <<
32 _* Hihi <<
33 ** Hihi <<
34 __ Hihi _x
35 _* Hihi _x

282
 Alarm State Set Encoding and Decoding

Offset AlarmSet
36 ** Hihi _x
37 __ Rate
38 _* Rate
39 ** Rate
40 __ Rate <<
41 _* Rate <<
42 ** Rate <<
43 __ Rate _x
44 _* Rate _x
45 ** Rate _x
46 __ Step
47 _* Step
48 ** Step
49 __ Step <<
50 _* Step <<
51 ** Step <<
52 __ Step _x
53 _* Step _x
54 ** Step _x
55 __ Change
56 _* Change
57 ** Change
58 __ Change <<
59 _* Change <<
60 ** Change <<
61 __ Change _x
62 _* Change _x
63 ** Change _x
64 __ Dig1
65 _* Dig1
66 ** Dig1
67 __ Dig1 <<
68 _* Dig1 <<
69 ** Dig1 <<
70 __ Dig1 _x
71 _* Dig1 _x
72 ** Dig1 _x

PI Server Applications User Guide 283

PI Alarm Subsystem

Offset AlarmSet
73 __ Dig2
74 _* Dig2
75 ** Dig2
76 __ Dig2 <<
77 _* Dig2 <<
78 ** Dig2 <<
79 __ Dig2 _x
80 _* Dig2 _x
81 ** Dig2 _x
82 LOLO
83 LOW
84 HIHI
85 HIGH
86 RATE
87 STEP
88 CHANGE
89 DIG1
90 DIG2
91 3 36

Digital Base Set

Single Priority Alarm Set

Offset AlarmSet
0 .
1 Move
2 Fail
3 OFF
4 Over
5 Under
6 Change
7 Dig6
8 Dig7
9 Move <<
10 Fail <<
11 OFF <<

284
 Alarm State Set Encoding and Decoding

Offset AlarmSet
12 Over <<
13 Under <<
14 Change <<
15 Dig7 <<
16 Dig8 <<
17 Move _x
18 Fail _x
19 OFF _x
20 Over _x
21 Under _x
22 Change _x
23 Dig7 _x
24 Dig8 _x
25 MOVE
26 FAIL
27 OFF
28 OVER
29 UNDER
30 CHANGE
31 DIG7
32 DIG8
33 31

Three Priority Alarm Set

Offset AlarmSet
0 .
1 __ Move
2 _* Move
3 ** Move
4 __ Move <<
5 _* Move <<
6 ** Move <<
7 __ Move _x
8 _* Move _x
9 ** Move _x
10 __ Fail

PI Server Applications User Guide 285

PI Alarm Subsystem

Offset AlarmSet
11 _* Fail
12 ** Fail
13 __ Fail <<
14 _* Fail <<
15 ** Fail <<
16 __ Fail _x
17 _* Fail _x
18 ** Fail _x
19 __ OFF
20 _* OFF
21 ** OFF
22 __ OFF <<
23 _* OFF <<
24 ** OFF <<
25 __ OFF _x
26 _* OFF _x
27 ** OFF _x
28 __ Over
29 _* Over
30 ** Over
31 __ Over <<
32 _* Over <<
33 ** Over <<
34 __ Over _x
35 _* Over _x
36 ** Over _x
37 __ Under
38 _* Under
39 ** Under
40 __ Under <<
41 _* Under <<
42 ** Under <<
43 __ Under _x
44 _* Under _x
45 ** Under _x
46 __ Change
47 _* Change

286
 Alarm State Set Encoding and Decoding

Offset AlarmSet
48 ** Change
49 __ Change <<
50 _* Change <<
51 ** Change <<
52 __ Change _x
53 _* Change _x
54 ** Change _x
55 __ Dig7
56 _* Dig7
57 ** Dig7
58 __ Dig7 <<
59 _* Dig7 <<
60 ** Dig7 <<
61 __ Dig7 _x
62 _* Dig7 _x
63 ** Dig7 _x
64 __ Dig8
65 _* Dig8
66 ** Dig8
67 __ Dig8 <<
68 _* Dig8 <<
69 ** Dig8 <<
70 __ Dig8 _x
71 _* Dig8 _x
72 ** Dig8 _x
73 MOVE
74 FAIL
75 OFF
76 OVER
77 UNDER
78 CHANGE
79 DIG7
80 DIG8
81 33

PI Server Applications User Guide 287

Chapter 9

PI Real-Time SQC
Statistical Quality Control (SQC) is the use of numerical methods to monitor the
characteristics of a process, making sure they remain within pre-determined boundaries.
The PI Real-Time SQC (PI SQC) component allows you to apply Western Electric Pattern
Tests to all process or laboratory data collected by the PI System. PI SQC continually reviews
any SQC tests in the PI System. It stores test results, and a record of SQC control limits back
into your PI System. The results are available for viewing and analysis in PI ProcessBook.
PI SQC is a part of PI Alarm, which provides continual evaluation of SQC pattern tests and
the management of alarms generated from them. When an unacceptable deviation from test
norm occurs, PI SQC notifies the PI SQC Alarm Manager.
The chapter includes an overview of SQC fundamentals, an understanding of how PI SQC
works, an explanation of how to configure the PI points on which PI SQC functionality
depends, and instructions on how to install PI SQC.
The following books on the subject of Statistical Quality Control (SQC) were used in
developing this chapter, and may be helpful in developing your implementation of PI SQC:
• Wheeler, Donald J., Advanced Topics in Statistical Process Control: The Power of
Shewart's Charts, 1995, SPC Press, Knoxville
• Statistical Quality Control Handbook, 2nd Edition, 1958, Western Electric Company

Introduction to Statistical Quality Control

Whenever a series of observations or measurements of a process parameter are examined, the
measurements are not, in general, identical to each other. Statistical Quality Control is based
on the core premise that all processes fluctuate. The fluctuations may be natural or unnatural.
Natural fluctuations are generally small, while unnatural fluctuations are larger and
introduced by external (hopefully, definable) causes. SQC provides a set of simple tools to
identify instances of unnatural fluctuation so that causes can be assigned and corrected.
In simple terms:
• Everything Varies - People live to different ages; all patterns fluctuate.
• Individual things are unpredictable - You cannot predict exactly how long you will live;
individual points are not predictable.
• Groups of things from a constant system of causes tend to be predictable - Actuaries rely
on this to predict life expectancy for insurance companies; a series of points from a
constant process tend to follow a pattern.

PI Server Applications User Guide 289

PI Real-Time SQC

It is possible to calculate statistical control limits for any given set of data and to evaluate the
data against those limits. When the data fits within the limits its fluctuations are said to have a
natural pattern. If the data falls outside of the limits it is said to have an unnatural pattern. The
limits can either be defined in terms of a firm number, such as "centerline +/- 3 standard
deviations", or in terms of pattern tests like "4 successive points greater than 2.0 standard
deviations from the center line on the same side of the center line".
The primary method for such evaluation of the process is the Control Chart. Methods for
preparation and interpretation of control charts have been developed over the last 40 years.
Control Charts are employed by a wide range of industries and agencies as a means to
monitor and stimulate improvements in many types of processes.

Case Study for PI Real-Time SQC

The following example illustrates how PI SQC can be used and helpful in a typical setting.

Tip: If you are not familiar with the principals and practices of Real-Time SQC, read
Introduction to Statistical Quality Control (page 289)before you read this
application example.

Assume that we want to set up an SQC Alarm that evaluates data entered for a lab test. We've
already established a PI point for the manual entry of laboratory results, and we have been
entering data for some time.
Recently, we decided to apply SQC to this laboratory measurement. We used the SQC
symbol in PI ProcessBook to construct an ad-hoc SQC chart of individuals for the
measurement. By investigating data collected when the process was running within norms,
we established control limits for the chart. We entered those numeric values into the control
parameters tab for that chart. We decided to apply only the 1 of 1, Outside 3 Sigma limit to
this chart.
The ad-hoc chart served us well for a couple of months; it gave us enough information to
make process improvements. After observing the post-process improvement data for some
time, we recalculated control limits for this lab measurement and found that we could tighten
the chart control limits. Since we decided to keep a history of our control limits over time, we
created PI points into which we entered both the old and the newly calculated control limits.
We then set the control parameters for the chart to get limits from the new PI tags.
After using this chart for a while, we decided that we wanted to alert the operator when the
chart showed that a pattern test failure had occurred, so that action could be taken before we
produced off-spec product. It wasn't practical for the operator to keep the ad-hoc SQC chart
displayed in the monitor all the time, so we decided to implement an SQC Alarm in PI.
We configured an SQC alarm point to use the same lab value as the ad-hoc chart, the same
control limit tags and to evaluate the same pattern test (Individual Measurements). Now the
SQC calculations happen on the PI Server whenever the lab tester enters a new value. The
operator sees an indication on the PI ProcessBook display if the calculation results in an
alarm condition. The operator can take corrective action and acknowledge the alarm. If the
process is in an upset condition, the operator can suspend the evaluation of the alarm by

290
 Real-Time SQC Definitions and Terminology

clicking on a button on the PI ProcessBook display - and later turn the alarm evaluation back
on when the process returns to normal.
If process engineers review the SQC control limits and enter new SQC control limits lab
measurement, the PI SQC Alarm processor senses the change and begins using the new limits
for the SQC Alarm.

Real-Time SQC Definitions and Terminology

The following SQC terms and phrases are used in this chapter.
Statistical Quality Control - The use of numerical methods to help keep the
characteristics of a process within boundaries.
ο Statistical - drawing conclusions from numbers
ο Quality - the characteristics or properties of the process
ο Control - keeping something within boundaries
Process - A process is a set of conditions or causes that work together to produce a result.
In an industrial setting a process can be a single control loop, a unit operation, a
laboratory measurement, a task performed by a single person or a team, or virtually any
combination of 'actors' that work together to produce a result.
Fluctuating Measurements - All processes have parameters that can be measured.
Repeated measurement of a process's parameters will show fluctuations in the parameter's
value. Fluctuations can be classified into these types:
ο Natural Fluctuation - Small fluctuations due to the precision of measurement, the
normal small random changes in the process that cannot be assigned to a cause (Non-
definable Cause). Natural fluctuation may be due to minute variability in equipment,
measurement imprecision, or other similar causes.
ο Unnatural Fluctuation - Large, abnormal fluctuations due to some external cause.
The causes of unnatural fluctuations are generally definable to some outside
influence. For example, an unnatural fluctuation could arise from software
malfunction, field instrument failure, putting the wrong material into the product or
similar causes.
Natural Pattern - A pattern of measurements of a process parameter exhibiting natural
variability due to minute fluctuations in raw materials, equipment, measurement
precision, and so on. Obviously, natural fluctuations result in natural patterns. A natural
pattern always has the all of the following characteristics (source: Statistical Quality
Control Handbook, 1956-1984, Western Electric Company):
ο Most of the points are near the centerline.
ο A few of the points spread out and approach the control limits.
ο None of the points (or at least only a very rare and occasional point) exceeds the
control limits.
Conversely, unnatural patterns lack one or more of the three characteristics listed above.
Unnatural Pattern - A pattern of measurements of a process parameter exhibiting large
fluctuations due to a definable cause.

PI Server Applications User Guide 291

PI Real-Time SQC

Tests for Unnatural Patterns - There are two basic premises for testing the naturalness
of a pattern:
ο Test individual points versus limits.
ο Test multiple points for trend - there are several commonly accepted tests for trend
recognition (such as eight points in a row on one side of the plot center line).
Sample Grouping - Breaking a large collection of measurements into subgroups.
Evaluating subgroup averages and ranges provides a more sensitive tool for spotting
process variations with definable causes (unnatural patterns).

Example

The following example illustrates the above definitions.

Over the last couple of decades there has been an active water-sampling program in the San
Francisco Bay. The following graph depicts the salinity data collected since 1989 at a single
monitoring station at a depth of 1 meter:

San Francisco Bay Salinity

In the figure above, the process is a particular locale in San Francisco Bay. Measurements of
salinity were taken over time at that location. It is clear from the plot that the measurements
fluctuate. In order to learn whether the fluctuations are natural or unnatural we need to be
able to test for unnatural patterns and evaluate the data against those tests.
Statistical quality control can be defined as: defining tests and evaluating data (sets of
measurements) against those tests to determine if data exhibit unnatural patterns.

292
 Tests for Unnatural Patterns

Tests for Unnatural Patterns

Historically, Shewart's classic Control Chart test involved testing the samples plotted on the
Control Chart against 3 sigma limits. Over time, people applying SQC instituted additional
tests that sought to check the samples for the presence of unnatural patterns. Over the years a
number of such tests have been established. The basic set of pattern tests is known as the
Western Electric set.

Western Electric Unnatural Pattern Tests

Seven classic pattern tests from the Western Electric SQC book are implemented in PI. For
interpretation of patterns, the area between the upper and lower control limits is broken into 3
zones. Following are the zones along with their names as implemented in PI SQC.

QC Chart Zone Definition

Pattern Types and Tests

Instability
There are four tests for instability. These are the most important of the pattern tests:
1. Any single point that falls outside the 3-sigma limit fails this test.

PI Server Applications User Guide 293

PI Real-Time SQC

One Point Outside 3 Sigma Limit (Instability)

2. Two out of three successive points fall in Zone A or beyond on one side of the center
line.

Two of Three Points in Zone A or Beyond (Instability)

3. Four out of five successive points fall into Zone B or beyond on one side of the center
line.

294
 Tests for Unnatural Patterns

Four of Five Points in Zone B or Beyond (Instability)

4. Eight successive points fall on one side of the center line.

Eight Successive Points Fall on One Side of the Center Line (Instability)

Stratification
Samples whose up and down variations are very small in relation to the centerline are termed
stratified. Stratification exists when 15 or more consecutive points fall within Zone C on
either side of the centerline.

PI Server Applications User Guide 295

PI Real-Time SQC

Fifteen Consecutive Points in Zone C (Stratification)

Mixtures
The mixture pattern is one in which points fall near the limits and not near the centerline. The
test for mixture is eight consecutive points on both sides of the centerline where no point is
within Zone C. At least one crossing of the center line must occur.

Eight Points on Both Sides of Center with None in Zone C (Mixture)

Trends
Trends are indicated by a series of points that are either monotonically increasing or
decreasing.

296
 PI Real-Time SQC Configuration

PI Real-Time SQC Configuration

SQC Alarm processing is a critical part of implementing Real-Time SQC. The continual
evaluation of SQC pattern tests and the management of alarms generated from them are the
responsibility of the PI Real-Time SQC product.
Creation and maintenance of SQC Alarms is most easily performed using the PI SQC Alarm
Manager application, which includes its own user guide. The PI point that implements PI
SQC Alarm functionality is called an SQC Alarm. See PI SQC Alarm Point Configuration
(page 308) for details on configuration options for an SQC Alarm.

Required and Optional Points

An SQC Alarm requires five points in the Data Archive in addition to the alarm point itself.
Required points provide a data source for the alarm, user control over the operation of the
alarm point, and storage of the SQC control limits. Required points can be shared among
SQC Alarms, if appropriate.
There are five optional PI points that you can configure for an SQC Alarm. One of these
optional points provides detailed reporting on the status of all pattern tests when the Alarm is
set. Other optional points are used by client and user-written programs to associate
specification limits and comments with an SQC Alarm and to drive limit changes based on
the value of another PI point (such as product-based limits). See Associated Point
Configuration (page 303) for point specifications.

Pattern Tests
Each PI SQC Alarm has one or more pattern tests defined. A pattern test is in Alarm status if
some maximum number X out of a total number Y of consecutive samples meets the test
condition (for example, if 2 of 3 samples are outside two standard deviations from the
centerline). The standard Western Electric Pattern Tests are supported:
• Outside Control - This test counts the number of samples outside the control limit on
one side of the center line.
• Outside Two Sigma - This test evaluates the sample against a limit drawn 2/3 of the way
between the center line and the control limit. Do not confuse sigma in this usage with the
standard deviation of the sample (that interpretation would only be true if, as classically
defined, SQC control limits are set to 3 times the standard deviation of process
measurements; but the control limits could be set to other values depending on process
needs).
• Outside One Sigma - This test evaluates the sample against a limit drawn 1/3 of the way
between the center line and the control limit. Do not confuse sigma in this usage with the
standard deviation of the sample.
• One Side of CL - This test counts how many samples are on one side of the center line.
• Stratification - This test counts the number of samples that fall within the upper and
lower One Sigma limits on both sides of the center line.

PI Server Applications User Guide 297

PI Real-Time SQC

• Mixture - This test counts the number of samples that fall outside the upper and the
lower One Sigma limits on both sides of the center line.
• Trend - This test counts the number of samples which are monotonically increasing or
decreasing.

Limits for Pattern Tests

The following implementation options are supported for tests 1, 2, 3, and 4:

• Test evaluated only above the center line
• Test evaluated only below the center line
• Test evaluated both above and below the center line

SQC Alarm Priority and Precedence

The SQC Alarm processor uses the concepts of alarm priority and test precedence established
in the PI Alarm Subsystem. Following is a brief explanation.

Priority

SQC Alarms embody the same concept of priority that is described in PI Alarm Subsystem
(page 251). Higher priority indicates a more immediate operator concern. For example,
consider an alarm system designed with four priorities 0, 1, 2, and 3. A priority of 0 might
indicate an alert for which no action is required, while a priority of 3 indicates a severe alarm
requiring an immediate response.

298
 Create a New SQC Alarm

Each SQC Alarm can be configured to have a priority which applies to all of the alarm's
pattern tests. Selecting a priority may prove useful for incorporating SQC Alarms into Alarm
Groups for the general management of alarms. For more details, see Build Alarm Group
Points (page 273).

Precedence

The pattern tests that may be executed with PI SQC have a fixed order of precedence, as
listed:
Precedence Pattern Test
7 OutsideControl
6 OutsideOneSigma
5 OutsideTwoSigma
4 OneSideofCL
3 Stratification
2 Mixture
1 Trend

An SQC alarm point can be configured to test for any combination of these patterns. In such a
point, if more than one pattern test is in alarm status, the highest precedence test is the one
reported in the SQC alarm point.

Create a New SQC Alarm

Follow these steps to activate a new SQC Alarm:

Caution: If you perform these steps out of order, an SQC Alarm may be placed in the
Error state.

1. Start the PI Alarm Subsystem. The first time the subsystem runs, it creates the new point
class used for SQC Alarms, and the Digital State Tables used for controlling SQC Alarm
execution and reporting.
2. Create the Associated Points on the PI Server. You can use the Excel Workbooks that are
included in the distribution as templates.
3. Enter initial values for control limit points and enter Normal for the ResetTag and the
TestStatusTag (if used).
4. Create the SQC alarm point. You can use the Excel Workbooks included in the
distribution as a template.

PI Server Applications User Guide 299

PI Real-Time SQC

Start and Run the PI Alarm Subsystem

PI Real-Time SQC is handled by an enhanced version of the PI Alarm Subsystem.
• To start the PI Alarm Subsystem, use the command:
net start pialarm

• To stop the PI Alarm Subsystem, use the command:

net stop pialarm

Initial Subsystem Startup

The first time that the Alarm Subsystem with Real-Time SQC capability is run, it creates the
SQC_Alarm Point Class needed to establish Real-Time SQC Alarms. The subsystem also
creates the pisqcalarm digital state set, which contains the Alarm States used by PI SQC.
During the initial and subsequent Alarm Subsystem startups, messages are logged to the PI
System Message Log, which you can review with the pigetmsg utility.

Determine the PointSource

When the Alarm Subsystem starts up, it determines the PointSource used by SQC Alarms.
The default PointSource is Q. The subsystem finds all points on the server that have the
specified PointSource.
On Windows, you can override the default PointSource by editing the pialarm key in the
Registry. To do this, start RegEdit and select the key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\pialarm

Add a value to this key called SQCAlarmPS. Set the value equal to the string you want for
the PointSource (for example, Q).

Find all SQC Alarms

For each point found with the PointSource specified above, the Scan attribute is checked. If
the Scan attribute is On, an SQC Alarm is initialized.

Initialize each SQC Alarm

After the SQC Alarm is created, its behavior is set by interpreting the configuration
information in the SQC alarm point attributes. If the subsystem cannot interpret the
configuration information, then a value of Error is written to the point and the point is not
processed further. The following sections describe how SQC alarm point attributes are used
during the subsystem startup.

Source Data
This is the process data source to be monitored. The SourceTag attribute is read and the SQC
Alarm signs up for notification of new data events for the source point.

300
 Start and Run the PI Alarm Subsystem

Control Limits
The UCL, CL, and LCL Tag attributes are read, and the SQC Alarm signs up for notification
of data events on those points.

SQC Execution Control

The ResetTag attribute is read and the SQC Alarm signs up for notification of data events on
the reset point.

TestStatusTag
The TestStatusTag attribute is read, and if it is a valid PI point, the SQC Alarm uses it for
detailed pattern test reporting.

Pattern Tests
Each SQC Alarm contains seven pattern tests. Each pattern test is initialized by reading its
configuration text.

Event Sign Up
The SQC Alarm also signs up for data events on the SQC alarm points so it knows about
attempts to acknowledge alarms. The current value of the ResetTag is read and used to
preserve the execution state of the SQC Alarm.
An SQC Alarm can be set up to clear when the subsystem restarts. If the ClearOnStart
attribute is set to True then the alarm is cleared, and alarm calculations are started anew. If
the ClearOnStart attribute is set to False then data are retrieved from PI to the pattern test
buffer, the prior state of the SQC Alarm is retrieved from PI, and alarm calculations are
restarted.

Subsystem Startup

Control the Evaluation of SQC Alarms

The SQC Alarm ResetTag attribute controls the execution state of the SQC Alarm. The three
default execution states are Normal, Hold, and Clear:
• The Normal state allows the SQC Alarm to be evaluated. If Normal is written to the
ResetTag of an SQC Alarm which was in Hold, the System Digital State Alarm-On
(indicating that the SQC Alarm is active and awaiting a new SourceTag event to process)
is written to the SQC alarm point.
• The Hold state suspends evaluation of pattern tests. If Hold is written to the ResetTag of
an SQC Alarm the System Digital State Alarm-Off (indicating that the SQC Alarm is no
longer active) is written to the SQC alarm point.
• The Clear state clears the pattern test buffer, sets the SQC Alarm in a No Alarm State
and places the SQC Alarm in a Hold state, but the SQC Alarm values remains as Clear.

PI Server Applications User Guide 301

PI Real-Time SQC

If you need to clear and restart the SQC Alarm calculations for an SQC alarm point, you must
first set its ResetTag to Clear and then to Normal. You can do this by using the PI API in
VBA code in PI ProcessBook, Microsoft Excel or in a user-written program. An example
illustrating the technique appears in the PI ProcessBook independent display file, which is
included in the PI SQC distribution.

Evaluate New Source Data

When a new value arrives for the SourceTag of an SQC Alarm, the new value is added to the
collection of previous values used by the test evaluator. Each of the pattern tests is evaluated.
Whenever there is a change to the alarm condition of one or more of the pattern tests, the
highest precedence test in alarm is written to the SQC alarm point. The timestamp of the SQC
Alarm is the same as the source data event time.
If the optional TestStatusTag is configured, then a value corresponding to all tests in alarm
is written to the TestStatusTag with the same timestamp as the SQC Alarm event. The
TestStatusTag also includes an indication of the side of the center line of the most recent
source data event.
SQC Alarm processing is a Real-Time function; alarms are evaluated whenever new data for
source points arrive. If PI Archive data are edited, or data are inserted into the Archive before
the most recent Snapshot event (out of order data), then the SQC Alarm processor ignores
that data.

Change the Control Limits

The control limits for an SQC Alarm can be changed at any time. When control limits are
changed, new test evaluation limits are calculated for each pattern test. If the SQC Alarm's
ClearOnLimitChange attribute of the SQC alarm point is set to Yes, then the SQC Alarm is
cleared and alarm calculations are started anew.
If more than one limit is changed for an SQC Alarm, then more than one reset of the alarm
calculations occur. If you need to change more than one control limit, you can avoid the
multiple resets by first setting the SQC Alarm's ResetTag to Hold, changing the control
limits, and then setting the ResetTag to Normal. You can do this with the PI API in VBA
code in PI ProcessBook, Microsoft Excel, or in a user written program. An example
illustrating the technique is included in the PI ProcessBook independent display file included
in the PI SQC distribution.
Control limits are applied in real-time. Once a new control limit (one that is different in value
from the existing control limit) is entered, regardless of its timestamp, it is applied to the
Alarms calculated from that moment in real-time forward. If a control limit value is inserted
before the most recent snapshot event for the control limit, it is ignored.

Acknowledge SQC Alarms

SQC Alarms can be configured to either of two acknowledgment options. The point attribute
that controls acknowledgment behavior is AutoAck. The default value of the SQC Alarm's
AutoAck attribute is Yes. If the default value is used, then SQC Alarms appear just as if the

302
 Associated Point Configuration

SQC chart were drawn manually—each pattern test failure results in an Alarm event. This is
the typical manner for evaluating Shewart control charts.
If you wish to require personnel to manually acknowledge an SQC Alarm, set AutoAck to
No. An unacknowledged alarm is written for each alarm calculated by the pattern tests. The
user has the opportunity to acknowledge the alarm by writing the unacknowledged digital
state to the SQC alarm point.

Subsystem Shutdown

If only the Alarm Subsystem is shut down, SQC Alarm evaluation is simply terminated.
If the entire PI System is shut down, SQC Alarm evaluation is also terminated. All points that
were configured to receive shutdown events receive the shutdown value.

Associated Point Configuration

An SQC Alarm requires the existence or creation of several PI points in addition to the SQC
alarm point. Also, the user has the option to create several additional PI points that could be
used by user-written programs to further enhance SQC Alarm reporting. All of these points
are described in the following topics, along with the requirements for configuring these
points.

Tools to Create and Edit Associated PI Points

The SQC alarm point and its associated PI points can be configured using the PI
TagConfigurator portion of PI SMT (PI System Management Tools). The PI SMT can be
downloaded from the OSIsoft support Web site. A sample Excel workbook for use with PI
TagConfigurator is included in the distribution media.

Note: When defining a new SQC Alarm, it is important that all of the required, associated
PI points are created before the SQC alarm point is created.

In the following section, the function of each of the required PI points is described in detail.

PI Server Applications User Guide 303

PI Real-Time SQC

Summary of Associated PI Points for SQC Alarms

In addition to the SQC alarm point itself, five PI points are required to implement an SQC
Alarm. Additionally, five optional tags may also be created if desired.

Summary of Associated Points

Tag Alias Description

SourceTag The PI point on which the Alarm Calculations are performed. This point MUST
have compression turned off (compressing = 0).
Note: If compression on the source tag is not turned off, then alarms are
calculated based on snapshot events that may later be 'compressed out.' This
may lead to confusion since alarms might be generated that are not associated
with archived source-data events.
TestStatusTag Optional. The PI point whose value corresponds to all pattern tests currently in
alarm condition.
ResetTag The PI point whose value sets the execution status of the Pattern Test
evaluation.
UCLTag The PI point whose value is the upper control limit for the chart.
CLTag The PI point whose value is the center line for the chart.
LCLTag The PI point whose value is the lower control limit for the chart.
USLTag Optional. The PI point whose value is the Upper Specification limit for the chart.
LSLTag Optional. The PI point whose value is the Lower Specification limit for the chart.
ProductTag Optional. The PI point whose value represents the current product.
CommentTag Optional. The PI point for storing comments associated with the SQC Alarm.

Configure the Associated Points

Each of the following tag reference attributes of the SQC alarm point hold the TagName of
the PI point to be used in the Alarm calculation.
Although a naming convention for the points associated with the SQC alarm point is not
necessary, you may wish to implement one for ease in recognizing the purpose for the
associated points. One possible convention is to base the names of the SQC alarm point and
all of the associated points on the name of the SourceTag. If the source tag is PV1011
associated tags might be named PV1011.alarm, PV1011.status, PV1011.UCL, PV1011.LCL,
and so on.

Note: For the associated points it is usually desirable to archive every value that is input
for that point. Thus, exception reporting and compression are typically turned off
for all associated points.

SourceTag
The SourceTag contains the values from which the SQC Alarm pattern tests are evaluated.
This is also the value that would be charted if the user were generating a graphic SQC Chart.
It is possible to use the same SourceTag for multiple SQC Alarms.

304
 Associated Point Configuration

The SQC Alarm's SourceTag can be any PI point. Typically the SourceTag point is a
manually entered value for a chart of individuals, or a PI Totalizer Point for aggregated
sampled data. For example, the sampled data could be an average of a fixed number of
manually entered values or a time-weighted average of an analog measurement from a DCS.
The pointtype of the SourceTag should be a numeric data type, typically a floating point
number such as a float32 or float64.
To ensure that archive events for alarms and source tag archive events are in sync, the
SourceTag must have compression turned off.

Note: If compression on the source tag is not turned off, then alarms are calculated
based on Snapshot events that may later be 'compressed out.' This may lead to
confusion since alarms might be generated that are not associated with archived
source-data events.

TestStatusTag
The TestStatusTag can be used by customer-written programs in situations where
knowledge of all pattern tests in alarm is needed (for example, in the dynamic creation of
operator action guidelines). A TestStatusTag can only apply to one SQC Alarm.
The TestStatusTag is a point with pointtype int32, whose value is set by the Alarm
Subsystem. The value indicates all of the pattern tests currently in alarm by assigning each of
the pattern tests a bit within the 32-bit word. Whenever a pattern test is in alarm, its bit is set.
If a test is not evaluated, its bit is always zero. After the bits are set for all pattern tests in
alarm, the sign of the TestStatusTag is set to indicate whether the corresponding value of the
SourceTag was above or below the center line for the event triggering the alarm. If the value
of the SourceTag was equal to the center line, the TestStatusTag is positive.
The Alarm Subsystem assigns the values given in the following table to the TestStatusTag
based on the individual SQC pattern-test alarms.

TestStatusTag Bits Indicate SQC Alarm State

Test Value Bit #

OutsideControl 64 6

OutsideTwoSigma 32 5
OutsideOneSigma 16 4
OneSideofCL 8 3
Stratification 4 2
Mixture 2 1
Trend 1 0

A TestStatusTag value of 0 indicates no tests in alarm; a value of 64 indicates the

OutsideControl test is in alarm; a value of 24 indicates that both the OutsideOneSigma and
OneSideofCL tests are in alarm.
For values of the SourceTag below the centerline, the integer generated by the above bit
setting algorithm is then multiplied by -1.

PI Server Applications User Guide 305

PI Real-Time SQC

The following table provides more examples.

Examples of TestStatusTag values

Tests in Alarm TestStatusTag

OneSideofCL & Stratification 8+4 12
OutsideTwoSigma & Trend (SourceTag < CL) 32 + 1 -33
OutsideTwoSigma & OutsideOneSigma 32 + 16 48

For values of the SourceTag below the centerline, the TestStatusTag is negative; however,
care must be taken when analyzing the individual bits of the TestStatusTag. Before analyzing
the bits of a negative TestStatusTag, the TestStatusTag should first be multiplied by -1 to
remove the sign. Then the individual bits may be readily analyzed. For example, if the
OneSideofCL alarm has been set because the values of the SourceTag are below the
centerline, the TestStatusTag is first assigned a value of 8 and then multiplied by -1 to arrive
at -8. When viewed as a group of bits that are set, -8 is represented as
11111111111111111111111111111000, not -100.

ResetTag
The ResetTag is used by client programs to control the execution of pattern tests on an SQC
Alarm. The PI Alarm Subsystem looks for updates to the value of the ResetTag and
implements the desired actions. The allowed values of the ResetTag are listed in the
following table.

Values of the ResetTag

Value Action Digital State

Offset
Normal Pattern Tests are processed 0
Hold Pattern Tests are not processed, but buffer is preserved (no new 1
values are added to it, however)
Clear SQC alarm point set to the "no alarm" condition, buffer is cleared, 2
and the SQC Alarm behavior is the same as if it were placed in
Hold. (that is, Pattern Tests are not processed. No new values are
placed in the buffer.)
After Clearing an alarm it is necessary to set the ResetTag to
Normal to restart the processing of the SQC Alarm.

The same ResetTag PI point can be used for multiple SQC Alarm calculations if desired.
The PointType of the ResetTag must be Digital and the DigitalSet attribute should be set to
pialarmcontrol, which is the Digital State Set where the reset values are stored. This Digital
State Set is created automatically when the subsystem starts up for the first time.

UCLTag, CLTag and LCLTag

Control limits are stored in the PI points referenced by UCLTag, CLTag, and LCLTag
parameters. These PI points can be performance equations, manually entry points, or points
whose values come from a DCS or a user-written program. The SQC pattern test evaluation

306
 Associated Point Configuration

portion of the PI Alarm Subsystem monitors the values of the control limits and senses
changes in their values (such as if the user implements limits that change with product or
grade). The same UCL, CL, and LCL points can be shared among multiple SQC Alarms if
desired.
The pointtype of the control limit points must be set a numeric data type, such as a float32 or
float64.
If a control limit is changed, the pattern tests for the associated SQC Alarm are reset,
depending on the ClearOnLimitChange attribute. If ClearOnLimitChange = Yes, the SQC
Alarm is placed in the Hold state, the TestBuffer is zeroed and the alarm evaluation is then
set to the Normal state.

USLTag and LSLTag

Specification limits are stored in the PI points referenced by the optional USLTag, and
LSLTag attributes. These PI points can be performance equations, manually entry points, or
points whose values come from a DCS or a user-written program.
The pointtype of the control limit points should be set to a numeric data type, such as a
float32 or float64.
These tags are used for display and for calculation of the process capability (Cpk) by the SQC
symbol in ProcessBook. If the attributes are blank, then the specification limits are not
displayed and the Cpk is not calculated.
While specification limits are not used in SQC Alarm calculations, users may wish to
establish regular PI Alarms based on the values of the SourceTag relative to the specification
points.

ProductTag
ProductTag is an optional PI point used to designate the current product for which the SQC
Alarm is being calculated. User-written programs might use this point's value to
programmatically adjust the control and specification limits based on the product or grade of
material being manufactured.

CommentTag
CommentTag is an optional PI point for storing comments associated with the SQC Alarm.
Information regarding conditions in the plant environment at certain times may be stored in
this tag. User-written programs may be used to enter and retrieve these comments for use in
process improvements based on attributing SQC Alarms to causes such as the technique
known as Pareto analysis.

PI Server Applications User Guide 307

PI Real-Time SQC

PI SQC Alarm Point Configuration

The PI SQC Alarm Point is the central storage point for all the information needed to
implement a PI SQC Alarm. Configuration information of a SQC alarm point includes all of
the attributes needed to define the PI SQC Alarm's behavior as well as the associated points
that are referenced by the SQC Alarm.
The following topics describe how to manually configure the PI SQC alarm point. OSIsoft
recommends using PI SQC Alarm Manager to create and maintain SQC Alarms.
Later, you will find discussion of how to configure associated points, both required and
optional, that are used to define a SQC Alarm.

Methods for Configuring PI SQC Alarm Points

The order of point creation is important, because if the SQC alarm point is created before the
associated points (including setting their initial values), then the PI Alarm Subsystem does
not process the SQC Alarm; instead, it places the SQC Alarm in the Error state.
The PI SQC Alarm Manager is a utility included in the distribution media that enables you to
create and edit alarm points correctly.
Alarm points can also be configured using the PI TagConfigurator portion of PI System
Management Tools (PI SMT). PI TagConfigurator currently supports creating, editing, and
deleting SQC Alarm tags. Sample Excel workbooks for use with PI TagConfigurator are
included in the distribution media. The instructions in the workbooks step through the
creation of associated points, setting initial values for the associated points, creating the
sample aggregation point (for SQC Alarms other than for a chart of Individuals), and the
creation of the SQC alarm point itself.

SQC Alarm Point Class

SQC Alarm Definition

SQC alarm points have their own point class: SQC_Alarm. This SQC_Alarm point class
contains attributes needed to describe an SQC Alarm. The fundamental attributes that are
required to specify an SQC alarm point are given in the following table.

Note: When specifying attribute values 'Yes', 'Y', 'True', 'T', 'On' and '1' all have
equivalent meaning and may be used interchangeably. The strings are case
insensitive. The same is true of 'No', 'N', 'False', 'F', 'Off' and '0'.

SQC_Alarm Point Class Attributes

Point Attribute Default Value or Description

Valid Options
Ptclass SQC_Alarm The SQC Alarm Point Class
PointType Digital All SQC Alarms are Digital points
Digitalset pisqcalarm Contains SQC Alarm States

308
 PI SQC Alarm Point Configuration

PointSource Q Identifies SQC alarm points

Scan 1 or 0 (default=1) On (1) or Off (0). SQC Alarms are only calculated
for scan=On
Compressing 1 or 0 (default=1) On or Off. Should be set to OFF
AutoAck Yes (default) or No Automatic acknowledgment of alarms
ChartType 0-8 (0 is default) Describes type of SQC chart the SQC Alarm is
testing (Used only by the SQC symbol in
ProcessBook).
ClearOnStart Yes or No (default) Yes means restart alarm calculations on startup or
editing of the alarm point; No means seed alarm
calculations with archive values of SourceTag and
restore the alarm's prior state
ClearOnLimitChange Yes (default) or No Yes means restart alarm calculations when any
limit tag changes; No means continue evaluating
alarms using new limit values.
ExDesc Specifies Alarm Group
SQCAlarmPriority 0-n (0 is default) Integer value specifies the alarm priority assigned
to all alarms generated by this SQC Alarm
definition.
PIProductLimits <reserved for future use>
WaitOnLimitChange <reserved for future use>
Pattern Test Definitions (if left blank, the pattern test is not performed)
OutsideControl x of y [<blank>, Within y number of samples, x are outside of
above, or below] control limits. Options: specify above or below to
apply test only above or below the center line.
OutsideTwoSigma x of y [<blank>, Within y number of samples, x are outside the
above, or below] "Two Sigma" limit. Options: specify above or
below to report alarms for this test only above or
below the center line.
OutsideOneSigma x of y [<blank>, Within y number of samples, x are outside the
above, or below] "One Sigma" limit. Options: specify above or
below to report alarms for this test only above or
below the center line.
OneSideofCL x of y [<blank>, Within y number of samples, x are on one side of
above, or below] the center line. Options: specify above or below to
report alarms for this test only above or below the
center line.
Stratification x of y Within y number of samples, x are within the "One
Sigma" limit.
Mixture x of y Within y number of samples, x are not within the
"One Sigma" limit.
Trend x x consecutive values trend either up or down.
Associated-Point TagName Definitions
SourceTag TagName for PI point on which the Alarm
Calculations are performed
TestStatusTag Optional. TagName for PI point to which SQC
Alarm system writes value indicating which tests

PI Server Applications User Guide 309

PI Real-Time SQC

are in alarm

UCLTag TagName for Upper Control Limit

CLTag TagName for Center Line
LCLTag TagName for Lower Control Limit
ResetTag TagName for PI point governing Alarm Calculation
execution and reset
USLTag Optional. TagName for Upper Specification Limit
LSLTag Optional. TagName for Lower Specification Limit
ProductTag Optional. TagName for a PI point to store the
name of the current product or grade being
produced.
CommentTag Optional. TagName for a PI point to store
comments associated with the SQC Alarm.

Ptclass
This must be set to SQC_Alarm.

PointType
This must be set to digital. The SQC alarm point contains a digital state representing the
value of the highest precedence alarm currently set.

Digitalset
This must be set to pisqcalarm, which contains SQC Alarm States. The digital states in the
pisqcalarm Digital State Set are described in "Default SQC Alarm Digital States."

PointSource
The PointSource identifies points as SQC alarm points. The default PointSource for SQC
Alarms is Q, although this can be configured to a different string as described in the topic
Determine the PointSource (page 300).

Scan
Scan is used to determine when SQC Alarms are calculated. SQC Alarms are not calculated
when Scan = Off. When Scan is changed from Off to On while the SQC Alarms are running,
the ClearOnStart attribute (described below) determines the SQC Alarm's startup behavior.

Compressing
Compression defaults to On (that is, 1) for all PI points, but Compressing should be set to
OFF (that is, 0) to ensure archiving of all SQC Alarms.

Note: Exception reporting is not used for SQC alarm points.

310
 PI SQC Alarm Point Configuration

Behavior Controls

AutoAck
AutoAck is used for automatic acknowledgment of alarms. It defaults to Yes.
If AutoAck = No, the SQCAlarmPriority needs to be set to a nonzero value in order to use
acknowledgments.

ChartType
ChartType is an indicator used by the SQC symbol in PI ProcessBook. The ChartType
attribute indicates the type of SQC chart for which the SQC Alarms are being calculated.
Valid values are listed in the following table.

Note: This attribute is not used by the PI Server in its SQC calculations. The SQC Alarm
Point's SourceTag determine whether this is a chart of individuals, an x-bar chart,
and so on. The default value is 0. See PI Real-Time SQC Chart Types (page 316)
for details on how to set up SQC Alarms for the various chart types.

Valid ChartType Values

Value ChartType
0 Chart type is unspecified (default)
1 Individuals
2 X-Bar
3 Moving Average
4 Exponentially Weighted Moving Average (EWMA)
5 Standard Deviation
6 Moving Standard Deviation
7 Range
8 Moving Range

ClearOnStart
ClearOnStart=Yes is used to clear any active alarm and restart alarm calculations on startup
or after a change to the alarm point's attributes. No means to start the alarm calculations using
retrieved archive values of SourceTag and to restore the SQC Alarm's prior state. If not
specified on point creation, ClearOnStart defaults to No.

ClearOnLimitChange
ClearOnLimitChange=Yes means clear any active alarm and restart alarm calculations
when any control limit tag (UCLTag, CLTag, LCLTag) changes. No means continue
evaluating alarms using new limit values. If not specified on point creation, ClearOnStart
defaults to Yes.

PI Server Applications User Guide 311

PI Real-Time SQC

Note: If set to Yes, changing more than one limit tag may result in one reset for each
limit that is changed. This can be avoided by first setting the ResetTag to Clear,
changing the control limits, and then setting the ResetTag to Normal.

PIProductLimits
Included in Point class and reserved for future use.

WaitOnLimitChange
Included in Point class and reserved for future use.

Alarm Group Identification

ExDesc
ExDesc specifies an Alarm Group that this SQC Alarm belongs to. SQC Alarms may be
added to existing PI Alarm Groups.

Alarm Priority

SQCAlarmPriority
SQCAlarmPriority is an integer value that sets the priority of the SQC Alarm. Defaults to 0.
This affects how the SQC Alarm is reported with respect to other alarms and SQC Alarms on
your system. For a discussion of alarm priorities and precedence, see SQC Alarm Priority and
Precedence (page 298).
In addition to setting AutoAck = No, SQCAlarmPriority must be set to a nonzero value in
order to use acknowledgments.

Pattern Test Configuration

Each SQC Alarm can test for up to seven pre-set patterns. Any combination of pattern tests
may be used in a single alarm. Pattern tests that compare values of the source tag to the
control limits use values of the UCLTag, CLTag, and LCLTag. A description of each test
follows.
The general form for configuring a pattern test is to enter the text "x of y", where x and y are
positive integers. If a pattern test attribute is left blank it is not evaluated. The descriptions of
each pattern test also list the values for x of y recommended in the Western Electric
Statistical Quality Control Handbook.
In the case of the Trend pattern test only, x is specified because the test looks for x
consecutively increasing or decreasing values.
For four of the tests (OutsideControl, OutsideOneSigma, OutsideTwoSigma, and
OneSideofCL), the modifiers above and below can be added after "x of y" to restrict the

312
 PI SQC Alarm Point Configuration

alarm reporting to a single side of the center line. The following table illustrates the pattern
test configuration options.

Pattern Test Configuration Examples

Attribute Entry Pattern Test Behavior

<Blank> Test is not performed (default).
4 of 5 Test looks for 4 out of 5 consecutive values of the SourceTag that meet the
test condition. This test is evaluated for values of the SourceTag that are
both greater than and less than the value of the CLTag
2 of 3 above Test looks for 2 out of 3 consecutive values of the SourceTag that meet the
test condition. Alarms resulting from this test are only reported for values of
the SourceTag that are greater than the value of the CLTag.
8 of 8 below Test looks for 8 consecutive values of the SourceTag that meet the test
condition. Alarms resulting from this test are only reported for values of the
SourceTag that are less than the value of the CLTag.

OutsideControl
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside of
control limits. A value of the SourceTag is outside the control limits when
SourceTag > UCL or SourceTag < LCL.

The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 1
of 1 for this pattern test.

OutsideTwoSigma
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside the
"TwoSigma" limit. A value of the SourceTag is outside the "TwoSigma" limit when
SourceTag > (2/3 * (UCL-CL) + CL) or SourceTag < (CL - 2/3 * (CL-
LCL)).

The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 2
of 3 for this pattern test.

OutsideOneSigma
This pattern test fails (sets an alarm) when x of y values of the SourceTag are outside the
"OneSigma" limit. A value of the SourceTag is outside the "OneSigma" limit when
SourceTag > (1/3 * (UCL-CL) + CL) or SourceTag < (CL - 1/3 * (CL-
LCL)).

The above or below options can be used with this pattern test to restrict pattern alarm
reporting to one side of the center line. The Western Electric SQC Handbook recommends 4
of 5 for this pattern test.

PI Server Applications User Guide 313

PI Real-Time SQC

OneSideofCL
This pattern test fails (sets an alarm) when x of y values of the SourceTag are on one side of
the center line. The above or below options can be used with this pattern test to restrict
pattern alarm reporting to one side of the center line. The Western Electric SQC Handbook
recommends 8 of 8 for this pattern test.

Stratification
This pattern test fails (sets an alarm) when x of y values of the SourceTag are within the
"OneSigma" limit. A value of the SourceTag is within the "OneSigma" limit when
(CL - 1/3 * (UCL-CL)) > SourceTag > (CL + 1/3 * (CL-LCL)).

The Western Electric SQC Handbook recommends 15 of 15 for this pattern test.

Mixture
This pattern test fails (sets an alarm) when x of y values of the SourceTag are found on both
sides of the centerline and none of these values falls within "OneSigma." Each of the x values
must satisfy one of the following two conditions
SourceTag > (CL + 1/3 * (UCL-CL)) or SourceTag < (CL - 1/3 * (CL-
LCL));

and among the x values, both of these conditions must be met at least once.
The Western Electric SQC Handbook recommends 8 of 8 for this pattern test.

Trend
This pattern test fails (sets an alarm) when x consecutive values of the SourceTag trend either
up or down.
The Western Electric SQC Handbook recommends 8 for this pattern test.

Associated-Point Tagnames

There are several required and optional tags associated with each SQC Alarm. The tag names
of these points are stored in the attributes described below.

SourceTag
Tagname for PI point containing the source data on which the SQC Alarm calculations are
performed.

314
 PI SQC Alarm Point Configuration

TestStatusTag
Optional. Tagname for PI point to which SQC Alarm system writes value indicating which
tests are in alarm. When this attribute is left blank (the default) the TestStatusTag is not used.
When a TestStatusTag is used, the TestStatusTag point must be unique in each SQC Alarm
definition.

UCLTag
Tagname for Upper Control Limit. The same UCLTag can be used in more than one SQC
Alarm definition.

CLTag
Tagname for Center Line. The same CLTag can be used in more than one SQC Alarm
definition.

LCLTag
Tagname for Lower Control Limit. The same LCLTag can be used in more than one SQC
Alarm definition.

ResetTag
Tagname for PI point governing the SQC Alarm calculation's execution and reset. The same
ResetTag can be used in more than one SQC Alarm definition.

USLTag and LSLTag

Optional. Tagnames for the PI points to store the Upper Specification and Lower
Specification Limits. The same USLTag and LSLTag can be used in more than one SQC
Alarm definition. Leave these tag attributes blank (default) if you do not wish to store your
specification limits in PI points.

ProductTag
Optional. Tagname for a PI point to designate the current product for which the SQC
calculation is being made. Leave this attribute blank (default) if you do not wish to store a
product identifier in a PI point.

CommentTag
Optional. Tagname for a PI point to store comments associated with the SQC Alarm. Leave
this tag attribute blank (default) if you do not wish to store comments in a PI point.

PI Server Applications User Guide 315

PI Real-Time SQC

PI Real-Time SQC Chart Types

The type of control chart for which an SQC Alarm is established depends solely on the SQC
Alarm's SourceTag. The SourceTag can be any PI point type; creating subgroups of
measurements for use in SQC is generally done using a combination of totalizer and
performance equation points.

Charts of Individuals

The SourceTag for the SQC Alarm here is any PI point. Each new measurement is used in the
pattern test evaluation

Moving Average, Moving Range and Moving Standard Deviation

The SourceTag for these types of SQC Alarms is a Totalizer point whose source is the raw
measurement point. The Totalizer point should be configured to take the moving average, and
so on. of the raw data point based either on a number of raw data events or a time period.

X-Bar, Range and Standard Deviation

The SourceTag for these types of SQC Alarms is a Totalizer point whose source is the raw
measurement point. The Totalizer point should be configured to take the average, and so on.
of the raw data point based either on a number of raw data events (nsampleblock) or a time
period.

EWMA

The SourceTag for the Exponentially Weighted Moving Average (EWMA) SQC Alarm is a
Performance Equation that watches for events on the raw data tag and whose equation syntax
is:
'RawDataTag' +
if badval ('pe') then
Lambda * PrevVal('RawDataTag') else
Lambda * PrevVal('pe')
where:
• Lambda is the weighting factor whose magnitude you must determine
• pe is the name of the Performance Equation tag that you are creating

Default SQC Alarm Digital States

The default digital state set (pisqcalarm) for SQC Alarms is automatically installed during
the first startup of the PI Alarm Subsystem. Another Digital State Set can be created for

316
 Default SQC Alarm Digital States

custom use. The Digital State Set must contain the same seven pattern tests in the same order
as below. You may alter the number of acknowledgment states or priorities or change the text
displayed when a pattern test fails in your custom set. See Create a New SQC Alarm (page
299) for details on constructing Alarm Digital State Sets.
The zeroeth state contains the No Alarm digital state. The last digital state (71 in this case),
records the number of priorities and acknowledgment states in the digital state set.

Default DigitalSet for SQC Alarms

Offset AlarmSet
0 .
1 __ Trend
2 _* Trend
3 ** Trend
4 __ Trend <<
5 _* Trend <<
6 ** Trend <<
7 __ Trend _x
8 _* Trend _x
9 ** Trend _x
10 __ Mixture
11 _* Mixture
12 ** Mixture
13 __ Mixture <<
14 _* Mixture <<
15 ** Mixture <<
16 __ Mixture _x
17 _* Mixture _x
18 ** Mixture _x
19 __ Stratification
20 _* Stratification
21 ** Stratification
22 __ Stratification <<
23 _* Stratification <<
24 ** Stratification <<
25 __ Stratification _x
26 _* Stratification _x
27 ** Stratification _x
28 __ OneSideofCL
29 _* OneSideofCL

PI Server Applications User Guide 317

PI Real-Time SQC

Offset AlarmSet
30 ** OneSideofCL
31 __ OneSideofCL <<
32 _* OneSideofCL <<
33 ** OneSideofCL <<
34 __ OneSideofCL _x
35 _* OneSideofCL _x
36 ** OneSideofCL _x
37 __ OutsideTwoSigma
38 _* OutsideTwoSigma
39 ** OutsideTwoSigma
40 __ OutsideTwoSigma <<
41 _* OutsideTwoSigma <<
42 ** OutsideTwoSigma <<
43 __ OutsideTwoSigma _x
44 _* OutsideTwoSigma _x
45 ** OutsideTwoSigma _x
46 __ OutsideOneSigma
47 _* OutsideOneSigma
48 ** OutsideOneSigma
49 __ OutsideOneSigma <<
50 _* OutsideOneSigma <<
51 ** OutsideOneSigma <<
52 __ OutsideOneSigma _x
53 _* OutsideOneSigma _x
54 ** OutsideOneSigma _x
55 __ OutsideControl
56 _* OutsideControl
57 ** OutsideControl
58 __ OutsideControl <<
59 _* OutsideControl <<
60 ** OutsideControl <<
61 __ OutsideControl _x
62 _* OutsideControl _x
63 ** OutsideControl _x
64 Trend
65 Mixture
66 Stratification

318
 Log Messages

Offset AlarmSet
67 OneSideofCL
68 OutsideTwoSigma
69 OutsideOneSigma
70 OutsideControl
71 33

Log Messages
Errors in configuration of SQC alarm points and errors encountered in the operation of the
subsystem are written to the PI System Message Log. The following section explains how to
view those error messages using the PIGetMsg utility. The error messages are listed along
with hints on how to correct the error condition.

View Log Messages

The PIGetMsg utility provides the means to view all SQC-related messages written to the PI
System Message Log. Use the following command to view them:
pigetmsg -st "pitimestring" -et "pitimestring" -pn "pialarm" -msg
"mask"

Substitute a valid time string in PI format for the start and end pitimestring and substitute the
string mask you are interested in for mask. The mask could be a tagname.

Log Message Reference

Wherever you see <SQC_Alarm_Point> in this list, you will see the name of your SQC alarm
point within the braces in the message log.
The following table lists the messages that occur under normal operating conditions.
Message Explanation
Created the state set The subsystem created one of the digital state sets it needs
to function. Only seen if the state set does not exist at the
time of subsystem startup.
SQC alarm point class OK The subsystem created the SQC Alarm point class. Only
seen if the point class does not exist when the subsystem
starts up. The subsystem successfully created the point
class.
Adding SQC Alarm A new SQC alarm point has been created on the PI Server
<SQC_Alarm_Point> and it is being picked up by the subsystem.
Previously deleted SQC Alarm The SQC Alarm was previously established. PI point was
<SQC_Alarm_Point> is being deleted and then re-created. Now it is being picked up by
added again. the subsystem.
Editing SQC Alarm The SQC alarm point has been edited and the subsystem is
<SQC_Alarm_Point> picking up the changes.

PI Server Applications User Guide 319

PI Real-Time SQC

Message Explanation
An existing PI point is being The PI point's PointSource was edited to the one used by
changed to an SQC Alarm the subsystem for SQC Alarms and is being picked up by
<SQC_Alarm_Point> the subsystem.
PointSource edit, deleting alarm The PI point's PointSource was edited to one not used by
<SQC_Alarm_Point> the subsystem, and the subsystem will no longer process
the point.
PI Point Deleted, deleting alarm The PI point was deleted so the subsystem will no longer
<SQC_Alarm_Point> process it.
<SQC_Alarm_Point> Scan set to The SQC Alarm's Scan attribute was set to OFF, so the
off subsystem will no longer process it.
<SQC_Alarm_Point> Scan-off at The subsystem tried to establish the SQC Alarm, but the
initialization - not added point's scan attribute is set to OFF. If this is not what you
want, edit the point using PI SMT and change the scan
attribute to ON.
<SQC_Alarm_Point> Scan-on ... SQC alarm point was edited and the Scan parameter was
re-initializing. changed from OFF to ON. The Alarm is being put back on
line.

Error Messages
The following table lists messages that indicate that a serious error has occurred at some point
in the running of PI Real-Time SQC or in the initialization of a Real-Time SQC Alarm.
Error Message Explanation
Failed to create SQC alarm The subsystem had trouble creating the point class. Possible
point class ... retrying solution to problem: Open a command window and change
directory to the pi\adm directory. Then enter net stop pialarm.
After the services are stopped, enter net start pialarm. Now look
in the message log for the message SQC alarm point class
created.
<SQC_Alarm_Point> failed to The digital set specified for the SQC Alarm is not valid. Check
setup digital set that you have used a valid digital state set and that it conforms to
the requirements as listed in this chapter.
<SQC_Alarm_Point> being Subsystem can't get attributes for point during an attempt to edit
edited but unable to retrieve the SQC Alarm.
attributes
<SQC_Alarm_Point> is wrong The SQC Alarm was not created as a digital point. Change the
point type for alarm point SQC alarm point's pointtype to digital.
<SQC_Alarm_Point> failed to Unable to retrieve the SQC Alarm's SourceTag attribute.
get sourcetag attribute.Status-
<SQC_Alarm_Point> update For some reason the subsystem was not able to sign up for data
signup for _sourcetag failed events on the tag.
<SQC_Alarm_Point> The SourceTag was not a recognized type, change the
sourcetag _sourcetag SourceTag pointtype.
pointtype is not valid
<SQC_Alarm_Point> failed to Unable to retrieve the TestStatusTag attribute.
get teststatustag attribute
<SQC_Alarm_Point> failed to Unable to get the SQCAlarmPriority attribute.
get SQCAlarmPriority attribute

320
 Log Messages

Error Message Explanation

<SQC_Alarm_Point> update Unable to sign up for data events on the SQC alarm point
signup for
<SQC_Alarm_Point> failed
<SQC_Alarm_Point> Status of The current value of the ResetTag for the SQC Alarm is not
ResetTag is bad at start NORMAL, HOLD or CLEAR. Enter an initial value of NORMAL for
the reset tag.
<SQC_Alarm_Point> Status of One or more limit points for this SQC Alarm has a bad status
one or more Limits is bad at (includes Pt Created, Shutdown, and so on). Enter initial values
start for all three limit tags.
<SQC_Alarm_Point> One or One or more of the pattern test attributes was not properly
more pattern tests failed to defined. Check that all pattern tests are properly configured
initialize according to this chapter.

PI Server Applications User Guide 321

Appendix A

Technical Support and Resources

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

Before You Call or Write for Help

When you contact OSIsoft Technical Support, please provide:

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

Help Desk and Telephone Support

You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location Access Number Local Language Options
San Leandro, CA, USA 1 510 297 5828 English
Philadelphia, PA, USA 1 215 606 0705 English
Johnson City, TN, USA 1 423 610 3800 English
Montreal, QC, Canada 1 514 493 0663 English, French
São Paulo, Brazil 55 11 3053 5040 English, Portuguese
Altenstadt, Germany 49 6047 9890 English, German
Manama, Bahrain 973 1758 4429 English, Arabic
Singapore 65 6391 1811 English, Mandarin
86 021 2327 8686 Mandarin
Perth, WA, Australia 61 8 9282 9220 English

PI Server Applications User Guide 323

Technical Support and Resources

Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail
will be treated as a regular phone call and will be directed to the first TSE who becomes
available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.

Search Support

From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site's Support Solutions,
Documentation, and Support Bulletins using the advanced MS SharePoint search engine.

Email-based Technical Support

techsupport@osisoft.com
When contacting OSIsoft Technical Support by email, it is helpful to send the following
information:
• Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue
• Message logs: See documentation for your PI System for information on obtaining
message logs pertinent to the situation.

Online Technical Support

From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft's Online Technical Support, you can:
• Enter a new call directly into OSIsoft's database (monitored 24 hours a day)
• View or edit existing OSIsoft calls that you entered
• View any of the calls entered by your organization or site, if enabled
• See your licensed software and dates of your Service Reliance Program agreements

324
 Remote Access

From the OSIsoft Technical Support Web site, click Contact Us > Remote Support
Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Access page for details on the various
methods you can use.

On-site service

From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service
Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.

Knowledge Center

From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
• The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
• System Manager Resources include tools and instructions that help you manage: Archive
sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server
security, PI System sizing and configuration, PI trusts for Interface Nodes, and more.

Upgrades

From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.

PI Server Applications User Guide 325

Index
in Alarms • 264
Actions
Alarms • 253
- operator • 51
Activation tag • 196, 208
Alarm Digital State Sets
*
Building • 275
* operator • 51 Alarm Group • 251, 271
Alarm Statistics • 271
/ for SQC alarms • 312
/ operator • 51 hierarchy • 271
Identification • 312
^ Alarm Group Points
Building with PI TagConfigurator • 274
^ operator • 51 Building with piconfig • 274
Alarm Notification • 277
+ Alarm Points • 251, 252
+ operator • 51 Building with piconfig • 273
Alarm Set
< Single Priority • 284
< operator • 51 Three Priority • 282, 285
<= operator • 51 Alarm State Set • 267
<> operator • 51 Encoding and Decoding • 279
Alarm States • 251
= Alarm Subsystem
Acknowledgment • 252, 253
= operator • 51 Acknowledgment Status • 267
actions • 253
> Alarm Group • 271
> operator • 51 Alarm State Set • 267
>= operator • 51 AutoAck • 265
Building Alarm Group Points • 271, 273
A Building Alarm Points • 272
Combiner Logic • 253
Abs
Condition • 252, 267
function in PEs • 67
ControlTag • 266
Absolute time expressions • 48
Conversion to digital state code • 279
Absolute Timestamp
Converstion from digital state code • 280
Recalculator Subsystem • 20
DeadBand • 266
Accumulation
Demonstration Points • 278
Interval, Totalizer • 215
Digital state sets • 316
output • 215 DigitalSet attribute • 265
Totalizer • 215 Error messages • 278, 319
Acknowledgment ExDesc • 265
Alarms • 252, 253, 267 IsUnack • 263
Acos new features • 278
function in PEs • 68 Notification • 277
Action 1 point attribute Options • 266

PI Server Applications User Guide 327

Index

Overview • 251 Archive • 90

Point Configuration • 253 retrieval • 60
Points • 252 search • 60
Priority • 252, 268 Archive and Time Functions
Program Operation • 277 Recalculator Subsystem Subsystem • 33
ReferenceTag • 265 Archiving flag
Sample Alarm State Sets • 280 Recalculator Subsystem • 23
shutdown • 303 Arg Alarm Group • 271
sign up for data events • 301 Argument
SourceTag • 255 Data type • 255
Start • 277 for built-in functions • 59
startup • 300 Arithmetic operations
test • 253 on Times • 52
Test1 • 255 Arithmetic Operators • 51, 52
Change • 262 Arma
CondEQ • 262 function in PEs • 71
Ascii
CondNE • 263
function in PEs • 73
EQ • 258 Asin
GT • 257 function in PEs • 74
Includes • 261 Associated Points • 304
Is_In • 260 Atn
LT • 257 function in PEs • 74
Atn2
NE • 258
function in PEs • 75
Not_In • 261
Attributes • 60
RateGT • 259 exdesc character limits • 14
RateLT • 260 PE Subsystem • 11
StepGT • 258 setting for PEs • 11
StepLT • 259 Totalizer • 215
AutoAck • 302, 311
Upgrading from PI for OpenVMS • 278
Alarms • 265
Alarms
Average
Number of alarms • 271
Totalizer • 232
Number of unacknowledged alarms • 271
Avg
Alias
Deleting • 203 function in PEs • 76
Renaming a batch alias • 203
B
Alias Table
Batch Subsystem • 202 Badval
AllEvents function in PEs • 76
Totalizer • 236 Basis time
AlmAckStat Recalculator Subsystem • 20
function in PEs • 69 Batch Subsystem
Almconditon Alias Table • 202
function in PEs • 69 Batch Deletes • 206
AlmCondText Batch Edits • 206
function in PEs • 70 configuration • 195
AlmPriority Operation • 208
function in PEs • 71 Pibaunit name table • 208
And operator • 51 Batch tags in Data Archive • 204

328
BATCHACTIVETYPE • 196 scheduling problems • 17
BATCHEXPR • 196 setting scan classes • 12
BATCHID shutdown attribute • 14
Defining • 198 switching calculations on or off • 14
Defining for Web Processes • 199 tips for creating • 16
definition of • 195 Calculated tags
Evaluation • 208 inconsistent data types • 17
Behavior Controls setting attributes • 11
PI SQC • 311 Calculation expressions • 12
BID about • 12
Batch Subsystem • 204 examples • 14
Blob Calculation intervals
Data types • 255 PEs • 10
Recalculator Subsystem Subsystem • 33 Celsius scale • 159
Bod ChangeEvents
function in PEs • 77 Totalizer • 238
Bom Char
function in PEs • 78 function in PEs • 79
Bonm Character limits on PEs • 13, 14
function in PEs • 79 ChartType • 311
Check a Point's exDesc Parameter • 59
C Clapeyron equation • 158
Calc Failed message • 58 ClearOnLimitChange • 306, 311
CalcMode • 215 ClearOnStart • 301, 311
AllEvents • 236 Clock Scheduling
ChangeEvents • 238 for PEs • 10
EventWeighted • 235 Recalculator Subsystem • 22
TimeTrue • 238 Clock TotalCloseMode
TimeWeighted • 233 Totalizer • 222
Totalizer • 233 Clock-scheduled points
Calculated expressions setting scan class • 12
character limits • 13, 14 CloseAtEvent
Calculated Points • 5 Totalizer • 242
about • 5 CLTag • 304, 306, 315
adding scan classes • 10 Coercion, data type • 17
calculation expressions • 12 Combination Time • 20
creating • 7 Combined time expressions • 48
exDesc attribute • 13, 14 Combiner Logic
finding scan classes • 10 Alarms • 253
finding the PointSource • 8 CommentTag • 304, 307, 315
location3 attribute • 12 Comparing
location4 attribute • 12 Point Values to Strings • 51
PointSource attribute • 12 Comparisons
scan attribute • 14 Compare
scan class offset • 9 function in PEs • 80
scan class period • 9 in PEs • 54, 58
scan class, UTC time flag • 9 Compressing • 308
scan classes • 9 CompValue • 215
scheduling • 10 Totalizer • 241

PI Server Applications User Guide 329

Index

Concat Alarms • 266

function in PEs • 81 Default
CondEQ point source for alarm group points • 271
Alarms • 262 Delay
Condition function in PEs • 85
Alarms • 252, 267 Delete
CondNE an Alias • 203
Alarms • 263 Demonstration Points
Configuration Alarm • 278
Batch • 195 Totalizer • 249
Totalizer • 213 Dependent Point
Conjunction Operators • 51 Recalculator Subsystem • 20
Control chart • 289 Digital Base Set • 284
Control limits • 289 Digital Set • 308
changing • 302 Alarms • 265
reset of alarm calculations • 302 Digital State Set
initializing on startup • 300 SQC custom • 316
Real-Time application • 302 SQC default • 316
ControlAlg • 267 Digital States
ControlTag • 266 numbers and strings as • 51
Alarms • 266 Steam Tables • 156
Conversion Digstate
Totalizer • 240 function in PEs • 86
Conversion factor DigText
TagTot function • 137 function in PEs • 86
Conversion, data type • 17 Disjunction Operators • 51
Cos Dynamic Functions
function in PEs • 81 Recalculator Subsystem Subsystem • 33
Cosh Dynamic Response • 60
function in PEs • 82
Count E
Batch Subsystem • 204 Encoding and Decoding
Counting Functions Alarm State Set • 279
Totalizer • 211, 232 Engineering units, Steam Tables • 155
Cpk • 307 Enthalpy
Critical point of steam • 159 as independent variable • 158
Curve Entropy
function in PEs • 83 as independent variable • 158
CYCLETIME tag • 199 EQ
Alarms • 258
D Error Messages
Data types Alarm • 278
checking, in PEs • 58 PI SQC • 319
inconsistent, in PEs • 17 Totalizer • 246
DataLink • 5 Errors
Day Checking • 57
function in PEs • 83 in PEs • 16, 58
DaySec EvalDelay
function in PEs • 84 Batch Subsystem • 196, 208
DeadBand Event

330
 Totalizer • 233 FindGE
Event expression function in PEs • 90
Totalizer • 223 FindGT
Event RateSampleMode function in PEs • 91
Totalizer • 221 FindLE
Event Scheduling function in PEs • 91
for PEs • 10 FindLT
Recalculator Subsystem • 22 function in PEs • 92
EventChange TotalCloseMode FindNE
Totalizer • 223 function in PEs • 93
EventCount Float
function in PEs • 87 function in PEs • 94
EventExpression Fluctuation
Totalizer • 241 natural • 291
EventTag • 11 unnatural • 291
EventTrue TotalCloseMode Forever TotalCloseMode
Totalizer • 224 Totalizer • 229
EventWeighted Format
Totalizer • 235 function in PEs • 95
EventXX of PEs • 45
Totalizer • 233 Frac
EventXX_XX function in PEs • 95
Totalizer • 233 Functions
Examples aggregate • 60
calculation expressions • 14 as PE operands • 46, 50
Exception reporting • 308 Attributes
ExDesc • 312 Totalizer • 230
Alarms • 265 Average • 232
ExDesc attribute Events • 233
Checking an • 59 EventXX • 233
create calculated point • 5 EventXX_XX • 233
for PEs • 13, 14 math • 60
Execution control • 300 Maximum • 232
Exp Minimum • 232
function in PEs • 88 Range • 232
Expressions StdDeviation • 232
absolute time • 48 Time • 60
combined time • 48 Total • 231
relative time • 48 Totalizer • 215
tagnames in • 47 transcendental • 60
time, tips for • 48
Extended descriptor G
character limits • 14
GroupID
F Alarm Group • 271
GroupName
Filter Expression Alarm Group • 271
Totalizer • 215, 241 GroupTag
FindEq alarms • 253
function in PEs • 89 GT

PI Server Applications User Guide 331

Index

Alarms • 257 Left

function in PEs • 101
H Len
Handle function in PEs • 102
Batch Subsystem • 204 Limits
Hierarchy on characters in PEs • 13, 14
Alarm Groups • 271 List
Hour aliases
function in PEs • 96 Batch Subsystem • 203
location1 attribute
I Recalculator Subsystem • 23
location3 attribute
If-then-else expressions • 51
for PEs • 12
If-then-else operator • 56
PEs • 10
Impulse
location4 attribute
function in PEs • 97
for PEs • 10, 12
in ( ) operator • 51
Log
in .. operator • 51
function in PEs • 102
InAlarm
Log10
Alarm Group • 271
function in PEs • 103
Includes
Lower Control Limit tag • 315
Alarms • 261
Lower Specification Limit tag • 315
Inclusion Operators • 51
LSLTag • 304, 307, 315
Independent Variables • 157, 158
LT
InFromTotalizer
Alarms • 257
Totalizer • 242
LTrim
Instability tests • 293
function in PEs • 104
InStr
function in PEs • 98
M
InstrumentTag • 11
Int Max
function in PEs • 98 function in PEs • 105
Interfaces Maximum
PE Subsystem • 6 Totalizer • 232
Intervals between PE calculations • 10 Median
Inversion function in PEs • 105
Recalculator Subsystem • 20 MedianFilt
Is_In function in PEs • 106
Alarms • 260 Mid
IsDST function in PEs • 107
function in PEs • 99 Min
IsSet function in PEs • 108
function in PEs • 100 Minimum
IsUnack Totalizer • 232
Alarms • 263 Minute
function in PEs • 108
L Mixture pattern • 296
test algorithm • 314
LCase
Mod operator • 51
function in PEs • 100
Month
LCLTag • 304, 306, 315
function in PEs • 109

332
MovingCount in PEs • 46
Totalizer • 224, 226 numbers as • 46
strings • 48
N tagnames as • 47
Naming convention • 156 time expressions • 48
Natural fluctuation • 291 Operation
Natural pattern • 289, 291 Alarm • 277
Natural RateSampleMode Totalizer • 246
Totalizer • 218 Operations on times • 52
NE -operator • 51
Alarms • 258 Operators
NEWUnitName • 196 Arithmetic • 52
NextEvent in PEs
function in PEs • 110 priority • 56
NextVal List of • 51
function in PEs • 111 Prefix • 55
NoClampZero Option
Totalizer • 242 Alarms • 266
Noon CloseAtEvent • 242
function in PEs • 111 OneAtEnd • 243
Not OneAtStart • 243
operator • 51 Options field
Not_In Totalizer • 242
Alarms • 261 Setable • 229, 243
NsampleBlock TotalCloseMode Or operator • 51
Totalizer • 226 Out-of-order data
NsampleMovin TotalCloseMode g PI SQC • 302
Totalizer • 224 OutsideControl
NSampleMoving test algorithm • 313
Totalizer • 224 OutsideOneSigma
Numbers test algorithm • 313
as digital states • 51 OutsideTwoSigma
as PE operands • 46 test algorithm • 313
OverIsTop
O Totalizer • 244
Offset Overloading PE Subsystem • 17
scan class • 9
scheduling problems • 17 P
Totalizer • 239 Parameters
Offset2 Totalizer • 213
Totalizer • 239 Pareto analysis
OneAtEnd comment tag • 307
Totalizer • 243 Parsetime
OneAtStart function in PEs • 112
Totalizer • 243 Recalculator Subsystem • 31
OneSideofCL • 297 Pattern
test algorithm • 314 natural • 289, 291
Operands unnatural • 289, 291
functions • 50 Pattern tests

PI Server Applications User Guide 333

Index

additional options for • 297 scan class period • 9

as used in PI Real Time SQC scan class,UTC time flag • 9
definitions • 297 scan classes • 9
configuration of • 312 Scheduler • 5, 6
definition of • 291 scheduling • 10
evaluation of • 302 scheduling problems • 17
initializing • 300 setting attributes • 11
precedence • 298 setting scan classes • 12
shutdown attribute • 14
order of • 299
string operands • 48
zones • 293 switching calculations on or off • 14
Pattern types • 293 syntax • 45
instability • 293 tagnames as operands • 47
mixture • 296 tagnames in expressions • 47
stratification • 295 time expressions • 48
trend • 296 time expressions as operands • 48
PctGood time-based or event-based, definition • 5
PEs • 113 times as strings • 48
Totalizer • 240 tips • 16
PE OperatorsSee Operators • 51 tips for time expressions • 48
PE Subsystem troubleshooting • 16
about • 6 Period
executable • 6 MovingCount • 239
overloading • 17 scan class • 9
skipped calculations • 17 Totalizer • 238
starting and stopping • 6 Period2
Performance Equations Totalizer • 239
about calculated points • 5 PeriodEnd ReportMode
adding scan classes • 10 Totalizer • 229
Built-in functions table • 60, 64 PEs
calculation expressions • 12 about calculated points • 5
changing the PointSource • 8 calculation expressions • 12
character limits • 13, 14 changing the PointSource • 8
creating • 7 character limits • 14
errors in • 16 creating • 7
examples • 14 errors in • 16
exDesc attribute • 13, 14 examples • 14
finding scan classes • 10 exDesc attribute • 13, 14
finding the PointSource • 8 finding the PointSource • 8
How they're used • 5 inconsistent data types • 17
inconsistent data types • 17 location3 attribute • 12
location3 attribute • 12 location4 attribute • 12
location4 attribute • 12 number operands • 46
number operands • 46 operands • 46
operands • 46 PointSource attribute • 12
Operators • 51 scan attribute • 14
Parentheses • 56 Scan class offset • 9
Pipetest Utility • 58 Scan class period • 9
PointSource attribute • 12 scan class,UTC time flag • 9
scan attribute • 14 scan classes • 9
scan class offset • 9

334
 adding for PEs • 10 Pilasttotal_T.dat • 246
configuring for PEs • 9 pipeschd file
finding for PEs • 10 adding scan classes • 10
changing the point source • 8
setting for PEs • 12
finding scan classes • 10
Scheduler • 6 PointSource • 8
scheduling • 10 scan classes • 9
scheduling problems • 17 pipeschd.bat • 7
setting attributes • 11 pipeschd.exe • 6
Shutdown attribute • 14 pipeschd.sh • 7
string operands • 48 Pipetest Utility • 58
switching calculations on or off • 14 Pisqcalarm digital set • 308
syntax • 45 PItotal • 211
tagnames as operands • 47 Program • 246
tagnames in expressions • 47 Point
time expressions • 48 dependent PE points • 21
time expressions as operands • 48 Point Attributes
times as strings • 48 RateSampleMode
Tips for creating • 16
in Totalizer • 218
tips for time expressions • 48
PI ReportMode
Performance Equation Scheduler • 6 in Totalizer • 229
PI BA for OpenVMS • 199 SourceTag
PI DataLink • 5 in Totalizer • 218
PI Message Log • 319 TotalCloseMode
PI Message subsystem • 300
in Totalizer • 222
PI PE Steam module
definition • 155 Point Class
naming convention • 156 SQC • 308
supported functions • 155 Point Configuration
PI ProcessBook • 5, 277 Alarms • 253
PI SDK • 5 Recalculator Subsystem • 33
PI SMT • 303, 308 Totalizer Points • 214
PI SQC Subsystem Point restart
Multiple resets event-scheduled points • 246
PointFunc
how to avoid • 302
Alarm Group • 271
Running the subsystem • 301 Points
Sample Grouping • 291 creating PEs • 7
Zones • 293 PointSource • 308
PI System alarm group points • 271
shut down configuring for PEs • 8
impact on SQC • 303 determining • 300
PI System Management Tools • 303, 308 how to set default • 300
PI TagConfigurator • 303, 308 overriding defaults • 274
Alarm Group Points • 274 PEs, changing • 8
Building Totalizer Points • 244 PointSource attribute
Piconfig for PEs • 8, 11, 12
Building Totalizer Points • 246 PointType • 308
PIGetMsg utility • 319 Poly

PI Server Applications User Guide 335

Index

function in PEs • 114 Point attribute in Totalizer • 218

Postprocessing • 211 Scan1 • 219
Prefix Operators • 51, 55 Scan2 • 220
Pressure Recalculation
as independent variable • 157 Absolute Time Reference Point Relationship • 30
PrevEvent Multi-level Dependency Point Relationship • 27
function in PEs • 115 Multi-level Time Point Relationship • 30
PrevVal Recursive Point Relationship • 27
function in PEs • 115 Relative Point Relationship • 28
Priorities Relative Time Point Relationship • 28
Alarms • 252, 268 Simple Point Relationship • 24
Priority Special Event Point Relationship • 28
PI SQC • 298 Time Range Point Relationship • 29
Process Time Shift Point Relationship • 28
definition of • 291 Recalculator Subsystem
Process capability • 307 Archive and Time Functions • 33
ProcessBook • 5 Archive retrieval & search functions • 31
PRODEXPR • 196 Compression exception • 22
ProdIDsearch compression, calculated values • 24
Batch Subsystem • 204 configuration • 36
Product Dynamic Functions • 33
Defining Name • 198 error and information messages • 44
Product Batch Subsystem • 195 exception reporting • 24
ProductTag • 304, 307 Extract from Timestamp • 31
Program Operation functionality • 20
Alarm • 277 glossary • 20, 195
Totalizer • 246 Incomplete Timestamps • 33
PStDev installation • 36
function in PEs • 116 Limitations • 32
Ptclass • 308 manual use for one point • 42
ptClassName multiple instances of • 41
for PEs • 11 options • 38
Overview • 19
Q point configuration • 33
Quotes starting • 38
around strings • 48 step attribute • 24
time functions • 31
R time range considerations • 21
tuning • 44
Ramping ReportMode Reference State
Totalizer • 230 Steam Functions • 159
Range ReferenceTag
function in PEs • 117 Alarms • 265
Totalizer • 232 Registry
RateGT Recalculator Subsystem • 40
Alarms • 259 Relational Operators • 51
RateLT Relative time
Alarms • 260 expressions • 48
RateSampleMode • 215, 222, 224 Relative Timestamp
Event • 221 Recalculator Subsystem • 20
Natural • 218

336
ReportMode • 215 Totalizer • 215
PeriodEnd • 229 Scheduling PEs • 10
Point Attribute problems • 17
in Totalizer • 229 SDK • 5
Ramping • 230 SearchStart
RunEst2 • 230 Batch Subsystem • 204
RunEstimate • 230 Second
Running • 230 function in PEs • 120
Totalizer • 229 Sequencing PEs • 17
ResetTag • 304, 306, 315 Server Application
digitalset • 306 PE Syntax and Functions Reference • 1
functions of • 301 Performance Equations Calculator • 1
initializing • 300 Performance Equations Scheduler • 1, 5
pointtype • 306 PI Alarm Subsystem • 3
Right PI Batch Subsystem • 2
function in PEs • 118 PI Totalizer Subsystem • 2
Round Real-Time SQC • 3
function in PEs • 119 Recalculator • 19
RTrim Steam Tables, Syntax and Functions Reference •
2
function in PEs • 120
Totalizer • 211
RunEst2 ReportMode
Server Applications
Totalizer • 230
Overview • 1
RunEstimate ReportMode
Totalizer • 230 Setable
Running ReportMode Totalizer • 243
Sgn
Totalizer • 230
function in PEs • 121
S Shutdown
Alarm subsystem • 303
Sample Grouping Shutdown attribute
PI SQC • 291 for PEs • 14
Scan attribute • 308 Sin
checking on subsystem startup • 300 function in PEs • 122
for PEs • 14 Single Priority Alarm Set • 284
Recalculator Subsystem • 23 Sinh
Scan class function in PEs • 122
definition • 9 SMT • 303, 308
offset • 9 Source data
period • 9 obtaining on startup • 300
scheduling problems • 17 SourcePoint
UTC time flag • 9 Recalculator Subsystem • 20
Scan Flag SourceStat
Response to • 247 Totalizer • 244
Scan1 RateSampleMode SourceTag • 304
Totalizer • 219 Point attribute
Scan2 RateSampleMode in Alarms • 255
Totalizer • 220
Totalizer • 218
Scheduling
Specification limits • 307
clock, for PEs • 10
SQC alarm • 297
event, for PEs • 10

PI Server Applications User Guide 337

Index

acknowledgment options • 302 function in PEs • 125

Behavior on control limit change • 302 States
Finding all • 300 numbers and strings as • 51
How to change control limits • 302 Statistical Quality Control
How to clear and restart alarm calculations • 301 definition of • 291
How to control execution of • 301 introduction to • 289
initialization,clearing on subsystem startup • 301 reference sources • 289
initialization,control limits • 300 StdDeviation
initialization,execution control • 300 Totalizer • 232
initialization,pattern tests • 300 StDev
initialization,signing up for events • 301 function in PEs • 126
initialization,source data • 300 Steam Functions
Initialization,subsystem error handling • 300 Reference • 2, 160
initialization,test status indicator • 300 valid range • 157
manual acknowledgment • 302 Step attribute
point class • 308 Recalculator Subsystem • 22
PointSource,determining • 300 Recalculator Subsystem • 24
PointSource,how to set default • 300 STEP tag • 199
priority of • 298 StepGT
required and optional points for • 297 Alarms • 258
SourceTag • 314 StepLT
TestStatusTag Alarms • 259
values • 305 StmEng_HPS • 169
TestStatusTag,use of • 302 StmEng_HPT • 167
SQC Alarm point StmEng_HPTL • 168
attributes • 308 StmEng_HPX • 175
configuring • 308 StmEng_HsatP • 160
SQC Chart types StmEng_HsatT • 162
exponentially weighted moving average • 316 StmEng_PsatT • 162
individuals • 316 StmEng_SPH • 171
moving average • 316 StmEng_SPT • 169
moving standard deviation • 316 StmEng_SPTL • 170
range • 316 StmEng_SPX • 175
standard deviation • 316 StmEng_SsatP • 161
x-bar • 316 StmEng_SsatT • 163
SQC_Alarm Point Class StmEng_TPH • 172
creation of • 300 StmEng_TPS • 172
SQCAlarmPriority • 312 StmEng_TsatP • 160
Sqr StmEng_VPS • 166
function in PEs • 123 StmEng_VPT • 164
SquareRoot • 11 StmEng_VPTL • 165
SStDev StmEng_VsatP • 161
function in PEs • 124 StmEng_VsatT • 164
Start StmEng_XPH • 173
Alarm • 277 StmEng_XPS • 174
Recalculator Subsystem • 36 StmSI_HPS • 185
Totalizer • 246 StmSI_HPT • 183
Startup StmSI_HPTL • 184
of alarm subsystem • 300 StmSI_HPX • 191
StateNo StmSI_HsatP • 176

338
StmSI_HsatT • 179 function in PEs • 128
StmSI_PsatT • 178 TagDesc
StmSI_SPH • 187 function in PEs • 129
StmSI_SPT • 186 TagEU
StmSI_SPTL • 186 function in PEs • 130
StmSI_SPX • 191 TagExDesc
StmSI_SsatP • 177 function in PEs • 130
StmSI_SsatT • 179 TagMax
StmSI_TPH • 188 function in PEs • 131
StmSI_TPS • 189 TagMax vs. Max Example
StmSI_TsatP • 176 Performance Equations • 15
StmSI_VPH • 182 TagMean
StmSI_VPS • 183 function in PEs • 132
StmSI_VPT • 180 TagMin
StmSI_VPTL • 181 function in PEs • 133
StmSI_VsatP • 178 TAGnames
StmSI_VsatT • 180 as PE operands • 46, 47
StmSI_XPH • 189 Batch Subsystem, renaming • 203
StmSI_XPS • 190 in arguments • 59
Stop in expressions • 47
Recalculator Subsystem • 44 in PEs • 134
Stratification TagNum
pattern test • 295 in PEs • 134
test algorithm • 314 TagSource
String function in PEs • 135
function in PEs • 127 TagSpan
String functions • 60 function in PEs • 135
Strings TagTot
as digital states • 51 Example, Performance Equations • 15
as PE operands • 46, 48 function in PEs • 136
Comparing Point Values to • 51 TagTot function
times as • 48 conversion factor • 137
using quotes with • 48 TagType
Subgroups • 291 function in PEs • 137
Subsystems TagTypVal
PE, about • 6 function in PEs • 138
PE, executable • 6 TagVal
Syntax function in PEs • 138
PEs • 45 TagZero
function in PEs • 139
T Tan
Table function in PEs • 140
Pibaunit name • 208 Tanh
Tag function in PEs • 141
Aliases • 199 Temperature
Tag Configurator • 303, 308 as independent variable • 157
TagAvg Test1 point attribute
function in PEs • 127 in Alarms • 255
TagBad Testing alarms • 253
TestStatusTag • 304, 305, 315

PI Server Applications User Guide 339

Index

initializing • 300 NSampleBlock • 226

pointtype • 305 NSampleMoving • 224
use of • 302 TimeMoving • 227
values • 305 Totalizer • 222
Text Totalization of Digital Tag Example
function in PEs • 141 Performance Equations • 14
Three Priority Alarm Set • 282, 285 Totalizer Subsystem
Time expressions Building Totalizer Points • 244
absolute time • 48 CalcMode • 233
and strings • 48 Compatibility with PI for OpenVMS • 248
Arithmetic operations on • 52 CompValue • 241
as PE operands • 48 Configuration • 213
combined time • 48 Conversion • 240
relative time • 48 Demonstration Points • 249
tips • 48 Error Messages • 246
Time Functions EventExpression • 241
Extract from Timestamp • 31 Filter Expression • 241
Recalculator Subsystem • 31 InFromTotalizer • 242
TimeEq MovingCount • 239
function in PEs • 142 new features • 247
TimeGE Offset • 239
function in PEs • 143 Offset2 • 239
TimeGT Options field • 242
function in PEs • 144 OverIsTop • 244
TimeLE Overview • 211
function in PEs • 145 PctGood • 240
TimeLT Period • 238
function in PEs • 146 Period2 • 239
TimeMoving TotalCloseMode Point Class Attributes • 215
Totalizer • 227 Points
TimeNE Building • 244
function in PEs • 147 RateSampleMode • 218
Timestamps ReportMode • 229
modifying through Recalculator • 31 Scheduling • 215
setting for PEs • 12 SourceStat • 244
TimeTrue SourceTag • 218
Totalizer • 238 TotalCloseMode • 222
TimeWeighted UnderIsZero • 244
Totalizer • 233 upgrading from PI for OpenVMS • 247
Timing Functions ZeroBias • 238
Totalizer • 232 Trend pattern test • 296, 314
Tips for creating PEs • 16 algorithm • 314
Total Triggering events, PEs • 10
function in PEs • 148 Trim
Totalizer • 231 function in PEs • 149
TotalCloseMode • 215, 222 Triple point of water • 159
Clock • 222 Troubleshooting
EventChange • 223 PEs • 16
EventTrue • 224 Recalculator Subsystem • 44
Forever • 229 Trunc

340
 function in PEs • 149 function in PEs • 152
Type Yearday
checking, in PEs • 58 function in PEs • 152
Type coercion
in PEs • 17 Z
ZeroBias • 215
U Totalizer • 238
UCase
function in PEs • 150
UCLTag • 304, 306, 315
UnAck
Alarm Group • 271
UnderIsBad
Totalizer • 242
UnderIsZero
Totalizer • 244
Unit Batch Subsystem • 195
UnitName, Batch Subsystem • 196, 202, 204
Universal Coordinate Time • 52
in PEs • 9, 291
Unnatural fluctuation • 291
Unnatural Pattern • 293
Western Electric tests • 293
Update events, PEs • 10
Upgrade from PI for OpenVMS
Alarm • 278
Totalizer • 247
Upper Control Limit tag • 315
Upper Specification Limit tag • 315
UserInt1 • 11
UserReal1 • 11
USLTag • 304, 307, 315
UTC • 52
UTC time flag, scan class • 9
Utility
pipetest • 58

V
Values of the TestStatusTag • 305

W
Web processes • 199
Weekday
function in PEs • 151
Wildcards • 203

Y
Year

PI Server Applications User Guide 341