PI DataLink 2013 User Guide

PI DataLink 2013
User Guide
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia Perth, Australia

OSIsoft Europe GmbH Frankfurt, Germany
OSIsoft Asia Pte Ltd. Singapore
OSIsoft Canada ULC Montreal & Calgary, Canada
OSIsoft, LLC Representative Office Shanghai, Peoples Republic of China
OSIsoft Japan KK Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil
OSIsoft France EURL Paris, France
PI DataLink 2013 User Guide

Copyright: 1992-2013 OSIsoft, LLC. 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, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework (PI AF), IT
Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Coresight, PI Data Services, PI Event
Frames, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and
RtWebParts are all trademarks of OSIsoft, LLC. 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, LLC license agreement and as
provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Version: 5.0.0
Published: 11-Feb-2013
Table of Contents
Chapter 1 Introduction .................................................................................................................. 1

PI DataLink overview.......................................................................................................... 1
About this release ............................................................................................................... 2
PI DataLink setup process ................................................................................................. 4
Microsoft Excel add-in configuration .................................................................................. 6
About this document........................................................................................................... 8
Chapter 2 Basics............................................................................................................................ 9
User interface ..................................................................................................................... 9
Overview of PI DataLink functions ...................................................................................11
Search for data items .......................................................................................................15
Manage preference settings .............................................................................................19
Manage connections to servers .......................................................................................21
Worksheet construction ....................................................................................................22
Chapter 3 PI DataLink functions ................................................................................................27

Current Value function......................................................................................................27
Archive Value function......................................................................................................28
Compressed Data function ...............................................................................................30
Sampled Data function .....................................................................................................34
Timed Data function .........................................................................................................36
Calculated Data function ..................................................................................................37
Time Filtered function .......................................................................................................42
Properties function ...........................................................................................................44
Chapter 4 Worksheets .................................................................................................................47

Function arrays .................................................................................................................47
Calculation frequency .......................................................................................................50
Worksheet sharing ...........................................................................................................52
Chapter 5 Advanced topics ........................................................................................................55

PI time ..............................................................................................................................55
Expressions ......................................................................................................................58
Manual function entry .......................................................................................................61
Functions to write data .....................................................................................................64
PI DataLink 2013 User Guide iii

Table of Contents
Chapter 6 Tag functions .............................................................................................................65

Point ID to Tag function ....................................................................................................65
Attribute Mask to Tag function .........................................................................................66
Search for tags .................................................................................................................67
Chapter 7 Trends .........................................................................................................................69

Create a trend ..................................................................................................................69
Trend right-click menu ......................................................................................................72
Chapter 8 PI Module Database objects .....................................................................................73

PI Module Database and worksheets ..............................................................................73
Insert PI Module Database objects into your worksheet ..................................................74
Module database functions ..............................................................................................75
Chapter 9 Notifications ...............................................................................................................77

Search and insert notifications .........................................................................................77
Inserted notifications ........................................................................................................81
Notification display settings ..............................................................................................81
Appendix A Function reference .................................................................................................83

Single-value functions ......................................................................................................83
Multiple-value functions ....................................................................................................86
Calculation functions ........................................................................................................96
Tag functions ..................................................................................................................111
Module Database functions ............................................................................................113
Input functions ................................................................................................................114
Appendix B Troubleshooting ...................................................................................................117

Log files ..........................................................................................................................117
PI DataLink tab not available .........................................................................................117
Array and cell limits ........................................................................................................117
Data retrieval limits .........................................................................................................118
Data item not supported by function ..............................................................................118
Security ..........................................................................................................................118
PI Server connection issues ...........................................................................................119
Cannot connect to PI OLEDB Enterprise Agent ............................................................120
Timeout exception ..........................................................................................................121
Appendix C Technical support and other resources .............................................................123
Index ............................................................................................................................................125
iv
Chapter 1
Introduction
Welcome to PI DataLink! This section provides an overview of PI DataLink, describes
features of this release, and discusses installation and configuration.
PI DataLink overview
PI DataLink is a Microsoft Excel add-in that enables you to retrieve information from your PI
System directly into a worksheet. Combined with the computational, graphic, and formatting
capabilities of Microsoft Excel, PI DataLink offers powerful tools for gathering, monitoring,
analyzing, and reporting PI System data.
With PI DataLink, you can:
Retrieve PI point values from a PI Server
Retrieve attribute values from a PI Asset Framework (PI AF) server
Retrieve system metadata to create a structured view of PI System data:
PI point names and attributes
PI Module Database paths, aliases, and properties
PI AF attributes and elements
Reference these items using PI DataLink functions to calculate and filter data
Update retrieved values when the worksheet recalculates
Retrieve notifications that you subscribed to with PI Notifications
PI DataLink includes a user interface to help you build functions and retrieve data. PI
DataLink embeds functions in worksheet cells and can provide active updates of real-time
data from your PI System.
You can also use the rich calculation and formatting capabilities of Excel to organize and
present PI System data to fit your purpose or audience.
There are two ways to work with PI DataLink functions in Excel worksheets:
Install a stand-alone version of PI DataLink on a local PC.
Use a web browser to view the worksheet with PI DataLink Server (page 2), a separate
product that lets you view worksheets created with PI DataLink.
Contact your OSIsoft sales representative for more information.
PI DataLink 2013 User Guide 1

Introduction
PI DataLink Server (DLS)
PI DataLink Server is a server version of PI DataLink for use with Microsoft SharePoint
Server 2007 or later. PI DataLink Server supports all PI DataLink and PI BatchView
functions provided by Excel add-ins in a typical PI client configuration.
With PI DataLink Server, you can use a web browser to retrieve and view PI Server data
contained in a Microsoft Excel worksheet. You can expand access to real-time PI System data
to many different consumers, regardless of location, or familiarity with either Microsoft
Excel or PI DataLink functions.
This server version of PI DataLink uses Microsoft SharePoint technologies including Excel
Services and the Excel Web Access web part. Together, these Microsoft components support
a majority of standard worksheet features. PI DataLink Server augments these services,
adding connectivity and support for PI DataLink functions.
Excel workbooks published to SharePoint document libraries can be accessed independently,
or added to web part pages. The Excel Web Access web part supports connections that allow
parameters to be exchanged between a workbook and other web parts, integrating worksheets
with PI DataLink functions into the PI WebParts environment.
Contact your OSIsoft sales representative for more information about PI DataLink Server.
About this release

This release of PI DataLink installs an add-in for Microsoft Excel 2007 SP3 or later. This
add-in cannot run in earlier versions of Excel. Topics in this section describe system
requirements, upgrade compatibility with previous releases, and supported data types.
System requirements
For up-to-date system requirements, see the OSIsoft Tech Support site:
http://techsupport.osisoft.com/Products.htm (http://techsupport.osisoft.com/Products.htm)
Upgrade compatibility
PI DataLink is backwards compatible. This version of PI DataLink can read workbooks

created in older versions without any conversion. However, the reverse is not necessarily
true. Once you modify a worksheet in the current version, it may no longer work in older
versions of PI DataLink.
PI DataLink 2013 uses PI AF SDK whereas previous releases used either PI SDK or PI API.
Different behaviors might require you to change existing worksheets:
Returned error messages might differ. You might need to change worksheets that look for
certain strings (for example, in Excel VBA code or macros).
2
PI DataLink setup process
PI DataLink does not create connections to PI SDK or PI API. You might need to change
VBA code in workbooks that depend on an existing PI SDK or PI API connection to
create a new, explicit connection to PI SDK or PI API.
Some time formats, such as 10:, are no longer supported. You need to change any time
inputs that use unsupported formats.
Default user connections to PI Server are no longer supported. If prompted, you can enter
a user name and password. However, OSIsoft recommends that you configure PI
mappings to connect to PI Server.
The 64-bit version of PI DataLink 2013 does not let you create an ActiveX trend object. The
64-bit version will only show an image of the last trend in an existing worksheet, and will not
update those trends.
Supported data types
PI DataLink supports the following PI point data types:

Digital (defined states)
Int (16 and 32)
Float (16, 32 and 64)
String (text)
Timestamp
PI DataLink does not support the blob type.
PI DataLink supports the following PI AF attribute value types:
Byte
Int (16, 32, and 64)
Single
Double
String*
DateTime*
Boolean*
Enumeration*
*Not supported by Calculated Data function
PI DataLink does not support the PI AF attribute value types Guid, Attribute, Element, File,
or Array.

Introduction

To prepare your computer to use PI DataLink, you must install PI DataLink from a
distribution CD or a setup kit downloaded from OSIsoft. If desired, you can use a silent
installation. You can also install the language pack to enable support for other languages. In
addition, you need to consider your PI Server configuration and ensure that you have proper
access to PI points.
Install PI DataLink
Launch the setup program to install PI DataLink. On 64-bit operating systems, the setup
program automatically installs both the 32-bit and 64-bit version of PI DataLink. You can
modify the setup.ini file if you want to install only one version. If you have a previous
version of PI DataLink installed on your computer, the setup program automatically upgrades
your installation and retains the preference settings from previous versions.
Before you begin

Find the setup kit. You can:
Download the kit from http://techsupport.osisoft.com.
Insert the distribution CD.
Procedure
1. Extract the files to your computer.
2. If you only want to install one version (32-bit or 64-bit), modify the setup.ini file.
3. Run the setup.exe program.
The setup program installs PI DataLink under the root directory PIPC, typically in:
C:\Program Files\PIPC\Excel
The program installs the online Help file in the appropriate language directory under the
../PIPC/Help directory. You can download the PDF version and release notes from
http://techsupport.osisoft.com.
After you finish

Install the PI DataLink MUI Language Pack if you want to view PI DataLink in a
language other than English. See View PI DataLink in a supported language (page 5).
Manually activate the PI DataLink (Legacy) add-in if you need to use tag functions,
module database functions, or trends. See Microsoft Excel add-in configuration (page 6).
4
Silent installation
You can install PI DataLink with the Windows silent installation feature. Sometimes called
an unattended installation, silent installation requires no feedback during the setup process.
System administrators with an automated software distribution application might use silent
installation to deploy software automatically to large numbers of corporate desktops.
To launch a silent install, type:
Setup.exe f silent.ini
The silent.ini file is included in the setup kit. You can make site-specific alterations to
the file as needed. See the PI SDK setup.ini file for further information and descriptions
of available arguments.
View PI DataLink in a supported language
PI DataLink supports multiple languages. Install the PI DataLink MUI (multilingual user
interface) language pack to view the PI DataLink user interface in the same language as
Microsoft Excel. If PI DataLink does not support a language, the PI DataLink user interface
appears in English.
Procedure
1. Set the desired language in Microsoft Excel:
a. Install the Microsoft Office language pack.
a. Use the Microsoft Office language setting tool to change the language of Microsoft
Excel.
2. Download the PI DataLink MUI language pack from http://techsupport.osisoft.com.
3. Install the PI DataLink MUI language pack.
Connection preferences to PI Server collectives
If PI DataLink connects to a PI Server collective, PI DataLink sets a connection preference

upon the first connection to the collective. The preference depends on the component that
initiates the connection:
PI DataLink functions set the preference to Any.
Search sets the preference to Any.
Connection Manager (accessed from the Settings window) sets the preference to Any.
Trend control legacy objects set the preference to Prefer Primary.
Tag Search (accessed from the legacy tag functions) sets the preference to Prefer
Primary.
PI Connection Manager (accessed from the legacy Tag Search) sets the preference to
Prefer Primary.

Introduction
See the High Availability Administrator Guide for more information about client connections
to PI Server.
PI Server configuration
PI DataLink can retrieve data from PI Server 3.4.370.76 and later. However, PI DataLink
must connect to PI Server and have proper access to points. This might require configuration
changes for:
Firewall database. The firewall database on each PI Server computer must be configured
to allow access from client computers that run PI DataLink.
Authentication and authorization. Those using PI DataLink must be able to authenticate
their identity with PI Server and have access to PI Server. OSIsoft recommends that you
use PI mappings (available in PI Server version 3.4.380 and later). You can also use PI
trusts or PI password authentication. OSIsoft does not recommend PI password
authentication as that method is less secure.
Point definitions. Points must be defined to give authorized users read access, and write
access, if necessary.
For more information, consult the PI Server documentation, including the Configuring PI
Server Security guide. You can download documentation from the OSIsoft Technical Support
site (http://techsupport.osisoft.com/downloadcenter.aspx).
Microsoft Excel add-in configuration

PI DataLink has three application add-ins to Microsoft Excel.
Name Location Type
PI DataLink ..\PIPC\Excel\OSIsoft.PIDataLink.UI.vsto COM Add-in

PI DataLink (Legacy) ..\PIPC\Excel\OSIsoft.PIDataLink.UI(Legacy).vsto COM Add-in
PI DataLink Notifications ..\PIPC\Excel\OSIsoft.PIDataLink.Notifications2007.UI.vsto COM Add-in
To use all PI DataLink features, these application add-ins must be active. The setup program
installs all the add-ins, and activates the PI DataLink add-in. If PI Notifications is installed on
your machine, the setup program also activates the PI DataLink Notifications add-in. If not,
you must activate that add-in after you install PI Notifications. The setup program does not
activate the PI DataLink (Legacy) add-in. You must activate the add-in if you want to use tag
functions, Module Database objects, or trends.
In rare cases, Microsoft Excel might disable an add-in. You must enable an add-in before you
can activate it.
Note: To activate an application add-in, you must have administrator privileges on the
computer. If you are not an administrator, right-click Excel.exe in Windows
Explorer, and then click Run as administrator to run Microsoft Excel as an
administrator.
6
Microsoft Excel add-in configuration
See also
Tag functions (page 65)
Module Database objects (page 73)
Trends (page 69)
Notifications (page 77)
View add-in status
Check the status of an add-in to learn whether it is active, inactive, or disabled.
Procedure
1. Click the File tab and then click Options. (In Microsoft Excel 2007, click the Microsoft
Office Button, and then click Excel Options.)
2. On the Excel Options window, click Add-Ins.
3. Search the list of add-ins to find the current status of an add-in.
Each add-in will be listed under either:
Active Application Add-ins
Inactive Application Add-ins
Disabled Application Add-ins.
Enable a disabled add-in
If an add-in is disabled, you must enable the add-in before you can make it active.
Procedure
3. From the Manage list, select Disabled Items, and then click Go.
4. Select the check box next to the add-in.
5. Click Enable.

Introduction
Activate an inactive add-in
Activate an inactive add-in to make the add-in available in Microsoft Excel.
Note: To activate an application add-in, you must have administrator privileges on the
computer. If you are not an administrator, right-click Excel.exe in Windows
Explorer, and then click Run as administrator to run Microsoft Excel as an
administrator.
Procedure
3. From the Manage list, select Com Add-ins, and then click Go.
4. Select the check box next to the add-in.
5. Click OK.
About this document

The PI DataLink User Guide provides a detailed description of product features and a
complete reference to PI DataLink functions. The content of the PDF and Help versions of
the guide is identical.
This document assumes that you have knowledge about PI System concepts. Consult the PI
Server and PI AF documentation for more information about those products. Knowledge of
PI Server and PI AF will help you understand terms used in PI DataLink.
You might also find the training materials helpful. These include the exercises that OSIsoft
uses in PI DataLink training courses.
You can download the training materials and documentation for other OSIsoft products from
the OSIsoft Technical Support site (http://techsupport.osisoft.com/downloadcenter.aspx).
8
Chapter 2
Basics
When you use PI DataLink, you define PI DataLink functions that extract PI System data into
function arrays in an Excel worksheet. A function array is a cluster of cells that contain the
output from a single PI DataLink function. The following sections introduce basic PI
DataLink concepts and features. Familiarize yourself with these sections before using PI
DataLink to build a worksheet and retrieve PI System data.
These sections describe:
User interface features
Core features for working with PI DataLink
Different approaches to build a PI DataLink worksheet, depending on your goals, needs,
and resources
User interface
PI DataLink adds specific menu commands, windows, and task panes to Microsoft Excel.
The following sections describe core elements of the PI DataLink interface.
PI DataLink tab
PI DataLink inserts the PI DataLink tab in the Microsoft Excel ribbon.
Click the PI DataLink tab to access the PI DataLink commands.

Click a command to open the corresponding task pane or window.
Place the cursor over a command to display a descriptive tooltip.
Function task panes
Use function task panes to define PI DataLink functions.

Basics
A task pane is a panel of controls that you can move and dock. You can continue to work on a
worksheet while a task pane is open.
To open a function task pane:
Click the desired output cell, and then click a function command on the PI DataLink tab
to add a function.
Click a cell in an existing function array to open the corresponding task pane and edit the
function inputs.
Note: You can turn off automatic display (page 19) of task panes if you prefer.
Right-click a function-array cell, and then click the function name to manually open the
task pane.
In an open function task pane:
Enter or change input values, and then:
Click OK to save the input values, write the resulting function array, and close the
task pane.
Click Apply to save the input values and write the resulting function array without
closing the task pane.
Click the X button in the task pane title bar to close the task pane without saving changes.
Click the arrow button to select the Move, Size, or Close commands.
Drag the title bar to undock the task pane.
Double-click the title bar to dock the task pane.
Place your cursor at the edge and drag to resize the pane.
10
Overview of PI DataLink functions
Right-click menu
PI DataLink adds several commands to the standard Microsoft Excel right-click menu. You
can use these commands to manage function arrays in a worksheet.
To open the right-click menu with the PI DataLink commands, right-click anywhere in a PI
DataLink function array.
PI DataLink adds the following commands to the right-click menu:
Select DataLink Function
Selects the entire function array.
You should select an array before you copy, cut, or paste it to a new worksheet location.
Recalculate (Resize) Function
Rewrites the entire function array: PI DataLink retrieves new values from PI Server or PI
AF and automatically resizes the array to fit the returned data.
Function Name
Opens the corresponding function task pane and shows inputs for the function array.
Trends offer an alternative right-click menu.
See also
Trend right-click menu (page 72)
Function task panes (page 9)

PI DataLink functions extract PI System data into Excel. You can use a function task pane to
easily enter the inputs that define the function. Alternatively, as you become more
experienced you might enter a function directly into the Excel formula bar.
The following sections describe:
Common features in PI DataLink function task panes
How real-time data is acquired and presented
How PI DataLink functions can be used within a worksheet
See also
Manual function entry (page 61)

Basics
Data items
PI DataLink functions return data about specified PI System data items, either PI points or PI
AF attributes. Functions might return recorded values from a database or computed values
based on specified criteria or a specified expression.
When you define a function, you specify the paths to data items with the Data item,
Expression, and Filter expression fields along with the optional Root path field. You can
specify:
Fully qualified paths in the Data item, Expression, or Filter expression fields. A fully
qualified path begins with two backslashes (\\) and evaluates to either a PI point or a PI
AF attribute.
Partial paths in the Data item, Expression, or Filter expression fields and the common
base path in the Root path field. PI point names or PI AF attribute names are examples
of partial paths. PI DataLink combines the common base path with the partial path to set
the full path that evalues to either a PI point or PI AF attribute.
PI DataLink requires a full path to find the data item. To find a PI point, PI DataLink must
know the PI Server to search and the point name. To find a PI AF attribute, PI DataLink must
know the PI AF server, the database, the element, and any subelements or parent attributes.
Use a pipe (|) to separate attributes from elements or parent attributes.
You can leave the Root path field blank if the Data item, Expression, and Filter expression
fields contain a fully qualified path or a PI point on the default PI Server.
If specified, the Root path field indicates the common path to the specified data items.
Type of data item Content of root-path field
PI point PI Server that stores the point or a blank to indicate the default PI
Server. Valid entries include:
PIServer
\\PIServer
PI AF attribute PI AF server and database along with any elements, subelements, and
parent attributes not specified in Data item. Valid entries include:
\\PIAFserver\database
\\PIAFserver\database\element
\\PIAFserver\database\element\subelement
\\PIAFserver\database\element|ParentAttribute
\\PIAFserver\database\element|ParentAttribute1|ParentAttribute2
Note: The PI AF server and database must be in the same field. You
cannot specify the PI AF server in the Root path field and the
database in the Data item field.
See also
Expressions (page 58)
12
Input entry
Labeled inputs on function task panes accept appropriate values for the function. For many
inputs, you can enter either a value or a reference to a worksheet cell that contains the value.
Some inputs have a default value shown when the task pane opens. Inputs marked (optional)
are optional, and do not require a value.
For inputs with edit fields , you can:

Enter text directly in the edit field, such as a PI AF attribute name or the address of an
output cell.
Click the edit field, and then click a worksheet cell or range that contains appropriate
values, such as PI AF attribute names, time stamps, or output cell locations.
Click to open the Search tool, and then select data items found in a search of a
connected PI Server or PI AF server.
For inputs with lists , you can:

Select a choice from the list, such as a calculation or a sampling method.
Click and then click a worksheet cell or range that contains appropriate values, such
as a mode, time unit, boundary type, or property.
Note: In edit fields, enter strings without any quotes. However, in worksheet cells, enter
strings with a leading quote (') to force Excel to interpret the contents as a string.
For example, to specify a PI point in the Data item(s) field, you can:
Enter the string for the point name.
Click to open the Search tool, and search PI Server for the point.
Enter a reference to a worksheet cell that contains the point name:
a. Click the Data item(s) field.
b. Click the cell on the worksheet.
PI DataLink automatically enters the cell reference into the edit field.
Time inputs
Many PI DataLink functions require Start time and End time inputs to retrieve an array of
event values over a specific time period. Other PI DataLink functions require a Time stamp
input to retrieve values at a specific time. Follow these guidelines when specifying time
inputs:
Enter either a fixed time, such as 10-Dec-99 19:12, or a PI time expression that
specifies a relative time, such as -3h. For example, you might enter a fixed time to
define a time period in the past, or you might enter a relative time expression to define a
time period that includes the current time.

Basics
If the start time is more recent than the end time, PI DataLink displays results in reverse
chronological order.
Precede time expressions entered in worksheet cells with a single quote to indicate a
string (for example, '10-Dec-99 19:12 or '-3h).
Cell references may also use the absolute Excel time format (such as 39299.6146,
equivalent to 8/5/2007 2:45:00 PM). Excel stores time stamps in this format,
which represents the cumulative number of days since 1900. Excel can display the same
time stamps using any date-time format assigned to the cell.
Some time entries, such as 9:45, can represent both a valid time and a valid range of
worksheet rows. In a task pane field, precede such entries with a single quote, such as
'9:45, to force PI DataLink to interpret as a time.
Some PI DataLink functions require a Time interval input, which you specify with a single
value:
Enter a value and time unit, such as a 1d or 30m; never include a reference time. For
example, to specify an interval of 32 minutes, enter 32m or reference a cell containing
that string.
To enter intervals in terms of frequency, convert the frequency to equivalent seconds. For
example, enter a frequency of 25 Hz as a 0.04s interval (=1/25 of a second).
Note: PI DataLink supports only the default 1900 date system supported by Excel. PI
DataLink does not support Excel's 1904 date system, and returns incorrect time
stamps if this system is used.
See also
Time-stamp specification (page 56)
Time-interval specification (page 58)
Appended data
PI DataLink can append information about the values retrieved. This appended data can
provide context to retrieved values. Appended data can include:
Event time stamps
Time stamps that show the start and end times of an interval
Time stamps that show when the minimum and maximum values occurred
The percentage of good values over a sampling interval
Value attributes
Manually entered event annotations
Source server names
14
Search for data items
PI DataLink displays the specified appended data in the columns (or rows) adjacent to the
primary values that the function returns:
Time data are displayed in columns to the left of (or rows above) primary values.
Other related data are displayed in columns to the right of (or rows below) primary
values.
Display formats
Use the Settings window (page 19) to specify the time and number formats that PI DataLink
uses to format data in function arrays. There are two settings:
Number format
The format for numbers in function output. The default setting, General, formats
numbers (and all non-time stamp data) to match the formatting of the General category
in the Excel Format Cells window.
Time format
The format for time stamps in function output. The default setting, dd-mmm-yy
hh:mm:ss, matches the standard PI time stamp format. You can add :000 to the end of
the string (dd-mmm-yy hh:mm:ss:000) to display subsecond time stamps. Note that
Excel does not support microsecond precision formats.
You can customize these format strings using any valid Excel format codes from the Format
Cells window in Excel.
You can also apply individual time and date formatting to any worksheet cell, including those
containing PI DataLink functions, with the Format Cells window. See your Excel
documentation for more information on formatting dates and times.

Use the Search tool to search any specified PI Server or PI AF server for data items. You can
insert data items into your worksheet and later reference these data items in PI DataLink
functions. You can also insert a data item directly into a function task pane.
Before you begin

Connect to any PI Server or PI AF server that you want to search. See Manage connections to
servers (page 21).

Basics
Procedure
1. Open the Search tool:
To insert one or more items into a worksheet, select the upper leftmost cell of the
range in the worksheet where you want to insert the data items, and then on the PI
DataLink tab, in the Search group, click Search.
To insert one or more items into a function task pane, click the button next to the
Data item(s) field.
2. Set the search scope, shown in the path at the top.
Initially, the tool sets the search scope to Home, which is all the PI Servers (indicated by
) and PI AF servers (indicated by ) listed in Connection Manager. You can limit the
search to a single PI Server or single PI AF server, and even further to a single database
on a PI AF server, and then to specific elements and parent attributes. You can:
Use the browse pane to limit the search (page 18)
Use the scope path to limit the search (page 19)
If you set the search scope to an element or attribute, the results pane lists that element's
or attribute's immediate child attributes.
3. As necessary, search for data items in the scope to list in the results pane.
a. In the field at the top of the tool, type text that identifies data items you want to find
in the selected scope.
The tool adds implicit wildcard characters after the text that you type. For example:
Type sin to find all data items that start with "sin," such as sinusoid or
sinusoidu.
Type * to find all data items
b. If your search scope is a PI Server, set the fields under Filters to specify any
additional criteria the retrieved PI points must match:
Point source
The string that associates a PI point with an interface; corresponds to the
PointSource point attribute.
Point type
The type of value stored by the PI point; corresponds to the PointType point
attribute.
Engineering units
The string that describes the units of measurement; corresponds to the EngUnits
point attribute.
Extended descriptor
A string that provides additional information about the PI point; corresponds to
the ExDesc point attribute.
Instrument tag
For some interfaces, the string that contains the tag in the external system;
corresponds to the InstrumentTag point attribute.
16
c. Click Search to initiate the search.

The tool searches within the specified scope for data items that match the text you
typed and returns the found data items in the results pane. The tool searches the entire
hierarchy below the search scope. (In contrast, when you browse the hierarchy, the
results pane only shows the immediate child attributes of the search scope.) The tool
finds:
PI points with names or descriptors that match.
PI AF attributes with names or descriptions that match.
PI AF attributes that have parent elements with names or descriptions that match.
Note: Searches of PI Server return no more than 100,000 PI points. To be certain

that you see all results, constrain your search to return fewer PI points.
4. If desired, change columns displayed in the results pane:

Right-click the results pane, and then click a column name to add it or clear it from
the displayed columns.
Drag column headers to change the order of the displayed columns.
5. If desired, move the Root path length slider to split the data-item path between the Root
path and Data item columns:
Select Minimum to specify a full path in the Data item column.
Select Maximum to specify only the attribute or point name in the Data item
column, with the rest of the path in the Root path column.
Select intermediate positions for other content splits between the columns.
The content of these columns determines the content added to the task-pane fields or the
worksheet columns.
6. If inserting data items in a worksheet, specify how to insert the Root path content:
Select Column or row to insert the content from the Root path and Data item
columns into the designated worksheet cells. If both columns contain data, PI
DataLink always inserts the Root path content in the first worksheet column and the
Data item content in the second worksheet column. If only the Data Item column
contains content (that is, a full path), then PI DataLink only inserts that column into
the worksheet.
Select Drop-down list to insert a drop-down list of paths (from the Root path
column) followed by the data items (from the Data item column) into the designated
worksheet cells.
If you reference the inserted drop-down list and data items in a PI DataLink function,
the worksheet will dynamically update the retrieved values when you select a
different path in the list.
Note: PI DataLink inserts the list of root paths in column EZ of your worksheet. If
that column contains data, PI DataLink inserts the paths in the next available column
to the right.
7. Select the items that you want to insert and click OK.

Basics
See also
Create an asset-relative display (page 23)
Use the browse pane to limit the search
The browse pane is on the left side of the Search tool. The browse pane shows what the
current search scope includes (the top of the window shows the corresponding scope path).
For scopes in a PI AF server, the browse pane only shows databases, elements, or attributes
that contain attributes in the hierarchy beneath them. Therefore, the browse pane will never
list elements or attributes with no child attributes.
You can use the browse pane to limit the scope of a search (and set the scope path). For
example, you can limit a search to a particular PI AF server or a particular database on that
server, or a particular element within that database. As you navigate a PI AF server hierarchy
in the browse pane, the results pane updates to show any attributes directly under the
currently selected scope path.
Procedure
In the browse pane:
Click a server to limit the search to that server.
The tool updates the scope path at the top of the window to list the selected server and
updates the browse pane. If you clicked a PI AF server (indicated by ), the browse
pane shows all the databases on that server. If you clicked a PI Server (indicated by ),
the browse pane shows a list of filter fields that you can use to limit retrieved PI points.
Click a database (indicated by ) to limit the search to that database.
The tool updates the browse pane to show all the top-level elements in the selected
database, and updates the scope path at the top of the window to list the selected
database.
Click an element (indicated by ) to limit the search to that element.
The tool updates the browse pane to show all the parent elements and parent attributes
under the selected element, updates the scope path at the top of the window to list the
selected element, and lists any attributes under the selected element in the results pane.
Note that the browse pane only shows attributes that are parent attributes, whereas the
results pane shows both parent and non-parent attributes under the selected element.
Click an attribute (indicated by ) to limit the search to that attribute.
The tool updates the browse pane to show any parent attributes under the selected
attribute, updates the scope path at the top of the window to list the selected attribute, and
lists any attributes under the selected attribute in the results pane.
18
Manage preference settings
Use the scope path to limit the search
The scope path is at the top of the Search tool.
The scope path shows where the Search tool looks for data items. You can use the scope path
to limit the scope of a search. For example, you can limit a search to a particular PI AF server
or a particular database on that server, or a particular element within that database. As you
navigate a PI AF server hierarchy in the scope path, the results pane updates to show any
attributes directly under the currently selected scope path.
Procedure
In the scope path:
Click Home to reset the scope to all the PI Servers and PI AF servers listed in
Connection Manager.
Click the arrow next to Home, and then click a particular server to reset the scope to that
server.
Click the server to reset the scope to that entire server.
Click the arrow next to a PI AF server, and then click a particular database to reset the
scope to that database.
Click the database to reset the scope to the entire database.
Click the arrow next to the database, and then click a particular element to reset the scope
to that element.
Click an element to reset the scope to the entire element.
Click the arrow next to an element, and then click a subelement or attribute to reset the
scope to that subelement or attribute.
Click a parent attribute to reset the scope to all its subattributes.
Click the arrow next to a parent attribute and select a particular subattribute to reset the
scope to that subattribute.
Manage preference settings

Use the Settings window to specify global preferences and default formatting for the output
of PI DataLink functions. These settings apply to a particular user on a particular computer.
Procedure
1. On the PI DataLink tab, in the Resources group, click Settings.
2. Set the preferred setting and click OK.
Setting Description
In a row Select to paste multiple results from a search into a row
of values in the worksheet.

Basics
Setting Description
In a column Select to paste multiple results from a search into a
column of values in the worksheet. Default value.
Copy PI Server name (Legacy add-in Select to paste the name of the PI Server data source
only) into an adjacent worksheet cell when you insert PI point
names from tag functions into a worksheet.
Use PI Server time zone Select to have PI DataLink interpret the input and output
time stamps as being in the PI Server time zone for data
items or expressions that contain either a PI point or a PI
AF attribute that is a PI point data reference.
If not selected, or the data item or expression contains a
PI AF attribute that is not a PI point data reference, PI
DataLink interprets the input and output time stamps as
being in the client-workstation time zone.
This option is relevant only if a PI Server has a time zone
setting different from the client workstation.
Display #N/A instead of blanks Select to show #N/A (not applicable) rather than blanks
in cells without values when a recalculation returns fewer
values than a function array can show.
This feature is particularly useful if you use the Excel
charting package to plot function results.
Locale independent Select to have PI DataLink interpret input time strings
according to PI time format rules, regardless of the locale
settings of the client workstation. PI time assumes all
strings are English and use the date-time format dd-
mmm-yyyy hh:mm:ss.
Clear the check box to parse date-time formats according
to regional settings on the client workstation, falling back
to PI time format rules only if necessary.
Disable automatic task pane display Select to turn off the automatic opening of the function
on click task pane upon a click of a function cell.
Disable "Resize to show all values" Select to display no warning message when a
message recalculation returns more values than a function array
can show.
Number format Enter the format for numbers in function output. The
format string may be any valid number format code from
the Excel Format window (see "Display formats" on
page 15).
During installation, PI DataLink enters the default number
format from Excel in this field, unless you have set a
different format preference previously in PI DataLink on
this computer. If your version of Excel runs a different
locale, this format includes correct syntax to reflect the
locale. For example:
35.03
would appear as
35,03
in French Excel.
20
Manage connections to servers
Setting Description
Time format Enter the format for time stamps in function output. The
time format string may be any valid date-time format
code from the Excel Format window.
During installation, PI DataLink enters the standard PI
time stamp format in this field, unless you have set a
different format preference previously in PI DataLink on
this computer. If your version of Excel runs a different
locale, this format includes correct syntax to reflect the
locale. For example:
dd-mmm-yy hh:mm:ss
would appear as
jj-mmm-aa hh:mm:ss
in French Excel.
Calculate (F9) Select to recalculate all volatile functions (and any
functions that reference them) during each recalculation
that the Automatic Update feature initiates. The Current
Value function is the only volatile PI DataLink function.
Full calculate (Ctrl+Alt+Shift+F9) Select to recalculate all functions, regardless of volatility,
during each recalculation that the Automatic Update
feature initiates.
Interval (seconds) Enter the number of seconds between each recalculation
that the Automatic Update feature initiates. The minimum
value is five seconds. Enter 0 to have PI DataLink
compute an automatic interval based on the duration of
previous calculation times.
Manage connections to servers

Use Connection Manager to manage connections to any PI Server or PI AF server, including
the selection of the default PI Server and PI AF server.
Procedure
1. On the PI DataLink tab, in the Resources group, click Settings to open the Settings
window.
2. Click Connection Manager to open the Servers window, which shows defined server
connections and the current status of those connections, including the default servers.
3. Modify connections, as desired:
Click Add AF Server to open the AF Server Properties window, where you can
define a connection to a PI AF server.
Click Add PI Server to open the PI Server Properties window, where you can
define a connection to a PI Server.
Select a server not currently connected, and click Connect to connect to that server.

Basics
To connect with PI AF servers, PI DataLink uses the Windows credentials of the

logged-in user. To connect with PI Servers, PI DataLink can use a PI trust or a
default user in addition to the Windows credentials of the logged-in user.
Select a server not currently the default connection, and click Set as Default to make
that server the default connection (either PI Server or PI AF server).
Select a server and click Properties to view the connection properties for that server.
Right-click a server and choose Remove to remove the connection definition to that
server.
Worksheet construction
Once you are familiar with the basic tools and concepts of PI DataLink, you are ready to
build a worksheet that uses PI DataLink functions.
Consider your goals

Ask yourself:
What data do you want to display in a worksheet in order to monitor performance or
answer a business question?
Where does the data reside?
How can you most effectively display the information, both to communicate essential
points and provide needed background context?
The answers will help you to determine which PI DataLink functions can return the data most
relevant to your task.
Select an approach
Techniques you might use to build your worksheet include:
Function-based
Add functions (page 27) to the worksheet, and build the display around the functions as
needed. For example, you might add point information to help clarify what the data
represents. This approach is useful if you are still exploring your requirements or learning
how PI DataLink works.
Structure-based
Add structure as you build a worksheet. Use the Search tool (see "Search for data items"
on page 15) to insert data items that frame the subject in your worksheet, and then add
functions that retrieve the corresponding data. This approach requires a bit more planning
and familiarity with PI DataLink, but once you add data items to the worksheet, you can
use them to build functions more easily through cell references. You can easily reuse
worksheets built this way.
Report-based
Place PI DataLink functions on the second worksheet in your workbook, and reference
the results from those functions on the first worksheet. Use Excel security features to hide
and protect the function syntax and business logic in the second worksheet from most
22
users. This approach is useful if you are a system administrator or build worksheets for
other users. This strategy also works well for documents distributed through PI Data Link
Server (page 2).
Asset-relative displays
An asset-relative display shows the values for a set of PI AF attributes along with the
corresponding asset (a PI AF element). You can select a different asset to show the values for
that asset.
Asset-relative display for React1 element
Asset-relative display for React2 element
Asset-relative displays require a common set of attribute names for assets. For example, to
create an asset-relative display you can use PI AF elements based on the same element and
attribute templates.
Create an asset-relative display
To create an asset-relative display, insert a set of data items that have a common structure
into your worksheet with a root-path drop-down list, and then add a PI DataLink function that
references these cells. After you create the asset-relative display, you can select a different
asset from the list to see the attribute values for that asset.
Procedure
1. Insert a set of data items with a common structure into your worksheet (page 24).
2. Configure a PI DataLink function to retrieve data about the inserted data items (page 25)
See also
Asset-relative displays (page 23)
Search for data items (page 15)

Basics
Insert a set of data items with a common structure into your worksheet
Asset-relative displays require the worksheet to contain set of data items (PI AF attributes)
that have a common structure along with a root-path drop-down list for those data items.
Procedure
1. Select a cell in the worksheet where you will insert the data items.
2. On the PI DataLink tab, click Search to open the Search tool.
3. Set the search scope, specify the data items you want to find, and click Search .
For asset-relative displays, you want to find PI AF attributes that have a common parent
element and the same attribute structure. These attributes might have the same attribute
template. For example, you might find all the reactors at your facility.
4. Split the data-item path such that the assets for the display appear in the Root path
column.
Move the Root path length slider until the Root path column shows the unique elements
for the listed attributes. Typically this will be at or near the Maximum setting.
5. Select the data items that you want to insert into the worksheet.
6. Under Insert root paths in, select Drop-down list.
7. Click OK.
PI DataLink inserts the unique data items into the worksheet below a drop-down list that
contains the unique assets (from the root-path column).
24
Note: PI DataLink inserts the list of root paths in column EZ of your worksheet. If that
column contains data, PI DataLink inserts the paths in the next available
column to the right.
Configure a PI DataLink function to retrieve data about the inserted data items
Asset-relative displays require you to configure a PI DataLink function to retrieve data for the
data items and root path you inserted in your worksheet: a set of data items with a common
structure and the root-path for that structure.
Procedure
1. Click the worksheet cell next to the first data item in the range that you inserted.
2. On the PI DataLink tab, click the function that you want to use to retrieve values.
The function task pane opens with the clicked cell specified in Output cell.
3. In the function task pane, click the Data item(s) field and then select the worksheet range
that contains the data items you just inserted.
PI DataLink inserts the cell range into the field.
4. In the function task pane, click the Root path field and then select the worksheet cell that
contains the root-path drop-down list.
PI DataLink inserts a cell reference into the field.
5. Specify other function inputs, as desired.
6. Click OK to insert the function array into the worksheet.
You can select a different asset from the list to see attribute values for that asset.

Chapter 3
PI DataLink functions
With PI DataLink functions, you can query any PI Server or PI AF server, apply calculations
to retrieved results, and return values to worksheet cells. Like other Excel functions, PI
DataLink functions return results in function arrays, which you can recalculate to update
values as needed. Use function task panes to define inputs for PI DataLink functions and
paste them into a worksheet.
The function descriptions in this section describe inputs specific to each function.
See also
Function arrays (page 47)
Function reference (page 83)
Current Value function

The Current Value function returns the current or most recent value of a PI point or PI AF
attribute.
Current Value is a volatile function: the function recalculates and updates values whenever
Excel calculates or recalculates any cell in the worksheet. To force an immediate
recalculation, press F9.
Input Description
Root path The common path to specified data items. Valid entries include:
PI Server name if the data item is a PI point.
PI AF server and database if the data item is a PI AF attribute.
Blank if the data item is a PI point on the default PI Server.
See Data items (page 12).
Data item(s) One or more PI point names or PI AF attribute names, for which the
function returns values.
Reference a range of cells that contain PI point names or PI AF
attribute names to return values for each.
Required.

Input Description
Output cell The worksheet cell where the function writes the resulting function
array. If you select a cell before you open the function task pane, PI
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. PI DataLink expands
the range downward and to the right of the output cell, as necessary to
return specified data. PI DataLink might overwrite adjacent cells.
If you specify a multi-cell array in the Output cell field and the specified
array is larger than the resulting function array, PI DataLink pastes the
function formula in the unneeded cells of the specified array.
No time stamp Click this option to return only values. The function returns values in a
column for a column of referenced data items, or returns values in a
row for a row of referenced data items.
Time at left Click this option to return two columns: the time stamp in the left
column and the value in the right column.
Time on top Click this option to return two rows: the time stamp in the top row and
the value in the bottom row.
RELATED TOPICS
PICurrVal() (page 83)
Current Value example
To see the current value of the PI point sinusoid, set the following inputs for the Current
Value function:
Input Value
Data item(s) sinusoid
Time at left Selected
The function returns the following array:
Archive Value function

If you select the Data item option, the Archive Value function returns the value of a PI
point or PI AF attribute at a specified time stamp.
If you select the Expression option, the Archive Value function returns the computed
value of a performance equation at a specified time stamp.
28
Archive Value function
Input Description
Root path The common path to specified data items, including those in
expressions. Valid entries include:
Reference a range of cells that contain PI point names or PI AF attribute
names to return values for each.
Required if you select the Data item option.
Expression(s) One or more performance equations that the function computes a value
for. See Expressions (page 58).
Reference a range of cells that contain expressions to return values for
each.
Required if you select the Expression option.
Time stamp The time stamp for which the function returns values. Specify either a
fixed time or a time expression relative to the current time. See Time
inputs (page 13). Required.
Retrieval mode The method the function uses to determine returned values. Choices
include:
previous
Returns the value that exactly matches or precedes the specified time
stamp.
previous only
Returns the value that precedes the specified time stamp.
interpolated
Returns the interpolated value at the specified time.
auto
Returns the interpolated value at the specified time, or follows the
previous method. (Uses the previous method for data items with step
attributes.)
next
Returns the value that exactly matches or follows the specified time
stamp.
next only
Returns the value that follows the specified time stamp.
exact time
Returns only a value that exactly matches the time stamp, or returns
No events found if no value exists at that time stamp.
Available if you select the Data item option.
Output cell The worksheet cell where the function writes the resulting function array.
If you select a cell before you open the function task pane, PI DataLink
inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. PI DataLink expands the
range downward and to the right of the output cell, as necessary to return
specified data. PI DataLink might overwrite adjacent cells.

Input Description
No time stamp Click this option to return only values. The function returns values in a
column for a column of referenced data items or expressions, or returns
values in a row for a row of referenced data items or expressions.
Time at left Click this option to return two columns: the time stamp in the left column
and the value in the right column.
Time on top Click this option to return two rows: the time stamp in the top row and the
value in the bottom row.
RELATED TOPICS
PIArcVal() (page 84)
Specify data items.
PIExpVal() (page 85)
Specify an expression.
Archive Value example
To see the value of the PI point sinusoid at a specific time, set the following inputs for
the Archive Value function:
Input Value
Time stamp 30-Sep-07 15:13
Retrieval mode previous

Time at left Selected
Compressed Data function

If you select the Time range option, the Compressed Data function returns all the values
of a PI point or PI AF attribute along with a count of values that occur during a specified
time period.
If you select the Number of values option, the Compressed Data function returns a
specific number of point values or attribute values beginning at a certain time.
30
Note: Values stored in the PI Server archive undergo a compression algorithm that
removes all values that represent the same slope. Values stored in the PI Server
snapshot have not undergone this compression algorithm. If you specify the
current time in the time period of the Compressed Data function, the function
retrieves a snapshot value for that time. That snapshot value might not be
subsequently stored in the archive due to compression.
Input Description
Root path The common path to specified data items, including those in
expressions. Valid entries include:
Reference a range of cells that contain PI point names or PI AF
attribute names to return values for each.
Required.
Start time The start of the time period for which the function returns values.
See Time inputs (page 13). Required.
End time The end of the time period for which the function returns values.
Required if you select the Time range option.
Number of values The number of values that the function returns, beginning at Start
time. Required if you select the Number of values option.
Backwards in time Select this check box to return values recorded at Start time and
earlier. Available if you select the Number of values option and
enter a value in the Number of values field.
If you enter a cell reference in the Number of values field, this
check box is disabled. Instead, enter a negative number in the
referenced cell to have the same effect.
Filter expression A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 60).
Mark as filtered Select this check box to insert the label Filtered in place of a
value or block of values that the function filtered from the output
based on Filter expression.

Input Description
Boundary type The method that the function uses to determine which values to
return near the start time or end time:
inside (default)
Returns values at start and end times, if they exist, or the nearest
values that occur within the range.
outside
Returns the nearest values that occur immediately outside the
range.
interpolated
Returns interpolated values at the start and end times.
auto
Returns interpolated values, but uses the inside method for data
items with step attributes.
Output cell The worksheet cell where the function writes the resulting function
array. If you select a cell before you open the function task pane, PI
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. PI DataLink
expands the range downward and to the right of the output cell, as
necessary to return specified data. PI DataLink might overwrite
adjacent cells.
If you specify a multi-cell array in the Output cell field and the
specified array is larger than the resulting function array, PI
DataLink pastes the function formula in the unneeded cells of the
specified array.
Hide count Select this check box to hide the count of returned values and show
only returned values. Available if you select the Time range option.
Show time stamps Select this check box to show the time stamp that corresponds to
each returned value. PI DataLink shows time stamps to the left of
values displayed in a column or above values displayed in a row.
Show value attributes Select this check box to show the extended status bits associated
with returned values. Possible status bits include:
A
Annotated, indicates a comment has been added to the event
S
Substituted, indicates the event value has been changed from its
original value
Q
Questionable, indicates that there is some reason to doubt the
accuracy of the value
PI DataLink shows value attributes in a column to the right of event
values.
Show annotations Select this check box to show annotations associated with returned
values. Annotations contain notes or comments that describe a data
value. PI DataLink shows annotations in a column to the right of the
value.
Column Click this option to return values in a column.
Row Click this option to return values in a row.
Note: If you specify a range of items in Data item(s), PI DataLink
automatically selects Column or Row to match the orientation of
the items.
32
RELATED TOPICS
PICompDat() (page 88)
Specify a time range without a filter expression.
PICompFilDat() (page 89)
Specify a time range with a filter expression.
PINCompDat() (page 86)
Specify a number of values without a filter expression.
PINCompFilDat() (page 87)
Specify a number of values with a filter expression.
Compressed Data example
To see the most recent 10 values of the PI point sinusoid, set the following inputs for the
Compressed Data function:
Input Value
Number of values Selected
Start time $A$10 (assuming cell A-10 has the current time)
Number of values 10
Backwards in time Selected
Boundary type inside
Show time stamps Selected
Column Selected
Note that you could select the Time range option and specify the appropriate Start time and
End time to return the same values.

Sampled Data function

If you select the Data item option, the Sampled Data function returns evenly-spaced,
interpolated values for a PI point or PI AF attribute over a regular interval.
If you select the Expression option, the Sampled Data function returns evenly-spaced,
interpolated values of a performance equation over a regular interval.
Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
Expression(s) One or more performance equations that the function computes a value for.
See Expressions (page 58).
Reference a range of cells that contain expressions to return values for
each.
Start time The start of the time period for which the function returns values. See Time
End time The end of the time period for which the function returns values. Required.
Time interval The sampling frequency used to calculate values during the time period.
Enter a value and time unit. For example, enter 15m (15 minutes) to return
a value for every 15-minute interval in the time period. See Time-interval
specification (page 58). Required.
Filter expression A Boolean performance equation that the function uses to filter values.
When the expression evaluates to false, the function excludes
corresponding values. See Filter expressions (page 60).
Mark as filtered Select this check box to insert the label Filtered in place of a value or
block of values that the function filtered from the output based on Filter
expression.
Output cell The worksheet cell where the function writes the resulting function array. If
you select a cell before you open the function task pane, PI DataLink
inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. PI DataLink expands the
range downward and to the right of the output cell, as necessary to return
specified data. PI DataLink might overwrite adjacent cells.
Show time stamps Select this check box to show the time stamp that corresponds to each
returned value. PI DataLink shows time stamps to the left of values
displayed in a column or above values displayed in a row.
34
Sampled Data function
Input Description
Note: If you specify a range of items in Data item(s) or a range of
expressions in Expression(s), PI DataLink automatically selects Column
or Row to match the orientation of the specified range.
RELATED TOPICS
PISampDat() (page 91)
Specify a data item with a filter expression.
PISampFilDat() (page 91)
Specify a data item without a filter expression.
PIExpDat() (page 93)
Sampled Data example
To see periodic, interpolated values over the previous 24 hours for the PI point sinusoid,
set the following inputs for the Sampled Data function:
Input Value

Start time -1d
End time $A$10 (assuming cell A-10 has the current time)
Time interval 3h
Show time stamps Selected
Column Selected
The array contains a value for each 3-hour interval.

Timed Data function

If you select the Data item option, the Timed Data function returns actual or interpolated
sample values for a PI point or PI AF attribute at specified time stamps.
If you select the Expression option, the Timed Data function returns values of a
performance equation computed at specified time stamps.
Input Description
Root path The common path to specified data items, including those in expressions. Valid
entries include:
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
Reference a range of cells that contain PI point names or PI AF attribute names
to return values for each.
Reference a range of cells that contain expressions to return values for each.
Time stamp(s) The time stamps for which the function returns values. Enter a time stamp or a
reference to one or more worksheet cells that contain time stamp values.
Required.
Retrieval mode The method the function uses to retrieve data:
interpolated
Returns interpolated values that correspond to specified time stamps. For
data items with the step attributes, retrieves the value preceding the specified
time stamp.
exact time
Returns only values that exactly match specified time stamps; returns No
events found if no value exists.
Output cell The worksheet cell where the function writes the resulting function array. If you
select a cell before you open the function task pane, PI DataLink inserts the
selected cell into the Output cell field.
Specify the top-left corner of the function array. PI DataLink expands the range
downward and to the right of the output cell, as necessary to return specified
data. PI DataLink might overwrite adjacent cells.
If you specify a multi-cell array in the Output cell field and the specified array is
larger than the resulting function array, PI DataLink pastes the function formula
in the unneeded cells of the specified array.
RELATED TOPICS
PITimeDat() (page 94)
Specify a data item.
36
Calculated Data function
PITimeExpDat() (page 95)

Timed Data example
To see values that correspond to an array of time stamps for the PI point sinusoidu, set the
following inputs for the Timed Data function:
Input Value
Data items(s) sinusoidu
Time stamps $A$3..$A$12 (cells A-3 through A-12 contain the time stamps for an array of
compressed data)
Retrieval mode interpolated
The function returns the following timed-data array in the column to the right:
The time-data array is based on time stamps in the first column.

If you select the Data item option, the Calculated Data function returns one or more
evenly-spaced, calculated values based on PI point or PI AF attribute values and specified
calculation preferences.
If you select the Expression option, the Calculated Data function returns one or more
evenly-spaced, calculated values based on an evaluated performance equation and
specified calculation preferences.
Note: Click the + sign next to Advanced to access all function inputs.

Input Description
entries include:
returns values.
Time interval The sampling frequency used to calculate values during the time period. Enter
a value and time unit. For example, enter 15m (15 minutes) to return a value for
every 15-minute interval in the time period. See Time-interval specification
(page 58).
Filter expression A Boolean performance equation that the function uses to filter values. When
the expression evaluates to false, the function excludes corresponding values.
See Filter expressions (page 60).
Conversion factor A factor that the function applies to returned values. Enter 1 if a conversion
factor is not needed. For time-weighted total calculations, specify a factor that
converts recorded rate values to the server default time unit (units per day).
Required.
For example, common conversion factors include:
1.0 for values that store units/day
24 for values that store units/hour
1440 for values that store units/minute
86400 for values that store units/second
38
Input Description
Calculation mode The type of calculation that the function performs:
total
Sums values during the interval.
minimum
Finds the minimum value during the interval.
maximum
Finds the maximum value during the interval.
standard deviation
Computes the standard deviation of values during the interval.
range
Computes the maximum value minus the minimum value during the interval.
average
Computes the average of values during the interval.
count
Counts the number of values stored during the interval.
mean
Computes the event-weighted version of the average calculation.
Calculation basis The calculation method:
time-weighted
Default. The function weights each event value by the length of time that the
event applies.
event-weighted
The function weights each event equally. Select this option for batch values.
This method requires at least one event in a time period (two events for
standard deviation calculations).
Expression The method that the function uses to determine when to evaluate an
sampling expression:
compressed
The function evaluates the expression during the time period at time stamps
where PI points or PI AF attributes in the expression have stored events.
interpolated
The function evaluates the expression at evenly spaced sampling intervals,
determined by Expression sampling frequency.
Available if you select Expression or if you specify a Filter expression.
Expression The frequency that the function evaluates an expression. Required if you set
sampling Expression sampling to interpolated.
frequency For example, set to 10m (10 minutes) to return an interpolated value for every
10-minute interval.
Minimum percent The minimum percentage of good data required in each time interval to
good calculate and return a value for that interval. The function returns the label
Insufficient good data for an interval that does not meet this
percentage.
If you specify a multi-cell array in the Output cell field and the specified array
is larger than the resulting function array, PI DataLink pastes the function
formula in the unneeded cells of the specified array.

Input Description
Show start time Select this check box to show the start time of the time interval used to
calculate the returned value. PI DataLink shows the start time in a column to
the left or in a row above returned values. Only available if you specify Time
interval.
Show end time Select this check box to show the end time of the time interval used to
calculate the returned value. PI DataLink shows the end time in a column to the
left or in a row above returned values. Only available if you specify Time
interval.
Show min/max Select this check box to show the time stamp that corresponds to the minimum
time or maximum value during the interval used to calculate the value. Only
available for three values of Calculation mode:
maximum
Shows the time stamp of the maximum value.
minimum
Shows the time stamp of the minimum value.
range
Shows the time stamps of the minimum value and the maximum value.
Show percent good Select this check box to show the percentage of time that good values were
returned during the array time period. PI DataLink shows the percent-good
values in a column to the right or in a row below returned values.
Good values are event values that PI Server determined were valid, and not in
an error state. You might use the percentage of good values to assess the
reliability of calculations built on PI point values, particularly if you use
calculated values in further calculations.
For example, if a time period includes bad data, the resulting time-weighted
total equals the total divided by the fraction of the interval where good data is
available. This normalization assumes that the average over the time period
with bad data is equivalent to the average value over the entire period. Thus,
the average becomes less reliable if a large fraction of the time period contains
bad data.
Note: If you specify a range of items in Data item(s) or a range of expressions
in Expression(s), PI DataLink automatically selects Column or Row to match
the orientation of the specified range.
RELATED TOPICS
PIAdvCalcVal() (page 96)
Specify a data item to retrieve a single value
PIAdvCalcFilVal() (page 97)
Specify a data item and filter expression to retrieve a single value
PIAdvCalcExpVal() (page 99)
Specify an expression to retrieve a single value
PIAdvCalcExpFilVal() (page 100)
Specify an expression and a filter expression to retrieve a single value
40
PIAdvCalcDat() (page 102)

Specify a data item and time interval to retrieve multiple values
PIAdvCalcFilDat() (page 103)
Specify a data item, time interval, and filter expression to retrieve multiple values
PIAdvCalcExpDat() (page 105)
Specify an expression and time interval to retrieve multiple values
PIAdvCalcExpFilDat() (page 107)
Specify an expression, time interval, and filter expression to retrieve multiple values
Calculated Data example
To see the hourly range of values from midnight today until the present time for the PI point
sinusoid, set the following inputs for the Calculated Data function:
Input Value
Start time t
End time *
Time interval 1h
Calculation mode range
Calculation basis time-weighted
Show start time selected
Show end time selected
Column selected
In this example, the function calculates the range for each one-hour interval. You can specify
any available calculation over any interval.

Time Filtered function

The Time Filtered function returns the amount of time that a performance equation evaluates
to true during a specified time period.
Note: Results from the Time Filtered function vary slightly depending on your PI Server
version.
Input Description
entries include:
Expression(s) A Boolean performance equation that the function evaluates. See Expressions
(page 58).
Required.
Time interval The sampling frequency used to calculate values during the time period. Enter
a value and time unit. For example, enter 15m (15 minutes) to return a value for
every 15-minute interval in the time period. See Time-interval specification
(page 58).
Time units The units of time in which the function returns the result. Required.
Show start time Select this check box to show the start time of the time interval used to
calculate the returned value. PI DataLink shows the start time in a column to
the left or in a row above returned values. Only available if you specify Time
interval.
Show end time Select this check box to show the end time of the time interval used to
calculate the returned value. PI DataLink shows the end time in a column to the
left or in a row above returned values. Only available if you specify Time
interval.
42
Time Filtered function
Input Description
Show percent good Select this check box to show the percentage of time that good values were
returned during the array time period. PI DataLink shows the percent-good
values in a column to the right or in a row below returned values.
Good values are event values that PI Server determined were valid, and not in
an error state. You might use the percentage of good values to assess the
reliability of calculations built on PI point values, particularly if you use
calculated values in further calculations.
For example, if a time period includes bad data, the resulting time-weighted
total equals the total divided by the fraction of the interval where good data is
available. This normalization assumes that the average over the time period
with bad data is equivalent to the average value over the entire period. Thus,
the average becomes less reliable if a large fraction of the time period contains
bad data.
Note: If you specify a range of items in Expression(s), PI DataLink
automatically selects Column or Row to match the orientation of the items.
RELATED TOPICS
PITimeFilterVal() (page 110)
Return a single value
PITimeFilter() (page 109)
Specify a time interval and return multiple values
Time Filtered example
To see the number of hours that the value of the PI point sinusoid exceeded 75 during the
previous seven days, set the following inputs for the Time Filtered function:
Input Value
Expression 'sinusoid' > 75
Start time -7d
End time *
Time units h
Show percent good selected

Column selected

In this example, the function calculates that the value of sinusoid exceeded 75 for 7.85 hours
over the previous 7 days, and 100 percent of the values were good during this period.
Properties function
The Properties function returns the property value of a specified data item.
Input Description
Root path The common path to specified data items. Valid entries include:
returns property values.
names to display values for each. By default, PI DataLink writes values in rows
for a column of referenced data items, and in columns for a row of referenced
data items.
Property The property for which the function returns values. The listed properties
depend on the entered data item:
Single PI point. The list contains the point attributes from the point class of
the entered point.
Note: This list substitutes uom for engunits. Select uom if you want to see
the value of the engunits point attribute.
Single PI AF attribute. The list contains three PI AF attribute properties:
categories, description, and uom.
Reference to multiple cells. The list depends on the type of data item in the
first referenced cell:
PI point. The list contains the point attributes from the point class of that
point.
PI AF attribute. The list contains three PI AF attribute properties:
categories, description, and uom.
If the list is blank, PI DataLink could not find the data item.
Select the desired property or specify a cell reference to a cell that contains the
property.
RELATED TOPICS
PITagAtt() (page 85)
44
Properties function
Properties example
To see attribute values of some PI points listed in your worksheet, set the following inputs for
the Properties function:
Input Value
Data item B3..B5 (cell array containing points)
Property description
In this case, the point names are in a column to the left. You could use a separate Properties
function to show additional attributes in subsequent columns.

Chapter 4
Worksheets
This section discusses how PI DataLink functions work within a worksheet and how to
manage and maintain your worksheet over time.
Function arrays
A function array is the cluster of cells that contains the output from a single PI DataLink
function. When you add a function to a worksheet, PI DataLink enters the function formula
into the specified output cells. The function queries PI Server or PI AF server and returns
values in a function array. The size of the array depends on the function, the number of
matching values available, the number of values requested, and the output requested.
The worksheet shows the returned values in the cells of a function array. However, these cells
actually contain the function formula. You can view the function formula in the Excel
formula bar when you click a cell.
1 Function formula in formula bar

2 Returned values in function array
Common function array tasks
Function arrays can be moved within, copied, or removed from a worksheet.

To select an array, do one of the following:
Click and drag to select every cell in the array. Keep in mind that the array may have
empty values, which must also be selected.
Right-click any part of the array and then click Select DataLink Function to select all
cells in the array.

Worksheets
Once selected, you can easily manage the array:

Manually remove initial $ characters in the formula bar to make cell references relative.
Note: After you make a change in the formula bar, press Ctrl + Alt + Shift to apply
that change.
Right-click any cell in the array and then click the desired Cut, Copy, Delete, Clear, or
Format command.
Right-click a new cell and then click Paste to reinsert a cut or copied array.
Place the pointer at the edge of the selected array, and when the pointer becomes a
movement pointer, drag the array to a new cell to move it.
Note: You must move or clear an entire function array, including all cells, or PI
DataLink returns an error message: You cannot change part of an
array.
Open the function task pane and update the Output cell field to place the array in a new
location. See Update inputs to a function array (page 48).
You can also copy the values from a function array if you want to use them elsewhere in a
worksheet. After you copy and paste the values, they are no longer part of a function array;
they are simply cell values and are not updated. To copy array values:
Select the function values you want, copy them, and use the Paste Special command to
paste values in the desired location.
You do not need to select the entire array column or row to copy values.
Update inputs to a function array
Use the function task pane to update a function array with new input values.
Procedure
1. Open the function task pane for an array:
With the automatic-task-pane display enabled, click a cell or multiple cells.
With the automatic-task-pane display disabled, select a cell or multiple cells, right-
click, and choose the function name.
The function task pane shows the current inputs for the selected function array.
If you selected a single cell, PI DataLink automatically detects adjacent function arrays
that differ only by source (that is, by data item or expression) and selects those arrays for
editing.
If you selected multiple cells, PI DataLink only selects the arrays with the same source
(that is, the same values for data item or expression) as the selected cells.
48
Function arrays
2. Change input values as desired to update the selected arrays, and click OK or Apply.
If you changed the Output cell field, the results depend on the location of the new cell
reference:
If the new cell reference is part of the original array, then PI DataLink moves the
entire array, placing the upper-leftmost cell of the array in the newly referenced cell.
If the new cell reference is not part of the original array, then PI DataLink copies the
array and pastes the copy, locating the upper-leftmost cell in the newly referenced
cell. The original array remains in its original location.
Array size
When a PI DataLink function writes a function array, it automatically sizes the array to fit the
returned data. Functions write the function array when you click OK or Apply on a task pane
or when you click Recalculate (Resize) Function on the shortcut menu.
Other methods that recalculate or update a function do not write a new function array. These
methods only update array values; the array size remains unchanged. For example, if you
specify function inputs with cell references and change the value in a cell, the function will
update returned values but the size of the array remains the same. The update might return
more or fewer values than the function array on the worksheet can show. Settings control
what PI DataLink returns:
If the update returns fewer values, PI DataLink either returns blanks or #N/A in the cells
without values.
If the update returns more values than the function array can show, PI DataLink returns
the text Resize to show all values at the bottom of the array unless the
preference settings disable the message.
Empty values can change the appearance of a worksheet. To maintain a constant size,
consider setting function inputs to limit returned data. For example, in the Compressed Data
function, you can specify the number of values to retrieve rather than a time period during
which you retrieve all values.
See also
Calculation frequency (page 50)
Resize arrays (page 49)
Manage preference settings (page 19)
Resize arrays
An update or recalculation of a PI DataLink function might return more or fewer values than
a function array can show. Use the Recalculate (Resize) Function command to rewrite the
entire function array: PI DataLink retrieves new values from PI Server or PI AF and
automatically resizes the array to fit the returned data.

Worksheets
Procedure
Right-click a cell in the function array and then click Recalculate (Resize) Function.
The function rewrites the function array, using current inputs, and automatically resizes
the array to fit the returned data.
Calculation frequency
PI DataLink writes a function array and calculates the current values for the function
whenever you click OK or Apply on the function task pane. To keep the data current, you
must recalculate the function array. Subsequent sections discuss approaches to recalculate a
function array.
For detailed information on how Excel manages calculation, see the Excel Recalculation
(http://msdn.microsoft.com/en-us/library/bb687891.aspx) topic in the MSDN library.
Automatic Update feature
The Automatic Update feature automatically initiates a recalculation of functions and trends
at a specified interval. Automatic Update applies to any workbook opened by the same Excel
session. Automatic Update pauses when you open a menu, task pane, or window, or you have
the current worksheet in edit mode. Automatic Update cannot update protected workbooks,
which are read-only.
Your preference settings affect Automatic Update:
Type of update
A preference setting determines which functions update during Automatic Update. There
are two choices:
Calculate (F9)
Select this option to recalculate all volatile functions and any functions that reference
them during each recalculation.
Full Calculate (Ctrl+Alt+Shift+F9)
Select this option to recalculate all functions, regardless of volatility, during each
recalculation.
Frequency of update
In the Interval field, enter the number of seconds between automatic recalculation. The
minimum value is five seconds. Enter 0 to have PI DataLink automatically set the
interval to twice the calculation duration, with a minimum interval of five seconds.
OSIsoft recommends you use the automatic interval to ensure that Excel remains
responsive 50% of the time.
If the recalculation takes longer than the specified interval, a message prompts you to
switch to the automatic interval or to turn off Automatic Update.
50
Calculation frequency
See also
Activate Automatic Update (page 51)
Cancel Automatic Update (page 51)
Activate Automatic Update

Activate the Automatic Update feature to recalculate PI DataLink functions automatically at a
specified interval.
Procedure
On the PI DataLink tab, click the Update button.
Excel immediately recalculates all PI DataLink functions in any workbooks opened in the
current Excel session. Then, Excel automatically recalculates these functions at the
interval specified in your preference settings.
When the Automatic Update feature is enabled, the Update button is highlighted and the
status bar shows an indicator message.
See also
Cancel Automatic Update

Cancel the Automatic Update feature to stop automatic recalculation of PI DataLink
functions.
Procedure
On the PI DataLink tab, click the highlighted Update button to clear the selection.
Click ESC to cancel a recalculation in progress. PI DataLink finishes the calculation for
the currently-processing function, writes Calculation aborted in unprocessed
function array cells, and turns off Automatic Update.
Triggered recalculation
Excel recalculates volatile functions and any function that references a volatile function
whenever you edit any worksheet cell or press F9. Volatile functions include the Excel time
functions, now() and today(). The Current Value function is a volatile function; other PI
DataLink functions are not. You can trigger recalculation of non-volatile PI DataLink
functions by referencing a volatile function within the non-volatile PI DataLink functions.

Worksheets
Base PI DataLink functions on volatile Excel functions

If you do not use the Automatic Update feature, you can maximize the refresh frequency and
keep function arrays current by basing your PI DataLink functions on a volatile Excel
function.
Procedure
1. Use the Excel formula bar to enter a volatile function in a worksheet cell.
For example, you can use (today()+1/3) to represent 8 a.m. the same day, or
now()as a cell reference to replace the current PI time, *.
To create an absolute time stamp that triggers updates, add and subtract now(), such as
2-feb-12 00:30:30 + now() - now().
2. Reference the cell when you define the Start time or End time inputs of a PI DataLink
function.
Note: To maximize the frequency of updates when Automatic Update is not in use,
check your Excel calculation preferences to ensure that both the worksheet and
application are set to Automatic rather than Manual calculation. Keep in mind that
this may impact performance and make large worksheets difficult to use.
Manual recalculation
You can also manually recalculate PI DataLink functions:

Press F9 to force all volatile functions (and any functions that reference them) to
recalculate.
Press Ctrl+Alt+Shift+F9 to force all functions to recalculate.
Right-click any part of a function array and then click Recalculate (Resize) Function.
This command will write the entire array and automatically size the array to fit the
returned data.
Worksheet sharing
To share PI System data with others, you can share worksheets created with PI DataLink. To
determine the best way to share your worksheets, consider the following:
You can send a PI DataLink workbook to another Microsoft Excel user. The user must
have PI DataLink installed and an active connection to the same PI Server and PI AF
server in order to recalculate functions and see dynamically updated PI point and PI AF
attribute values.
Those who do not have PI DataLink installed can still see the last data saved in the
worksheet provided the Excel Workbook Calculation option is set to Manual before
they open the worksheet in Excel. See Set Workbook Calculation option to manual (page
53).
52
Worksheet sharing
You can also save a worksheet as a web page or PDF file to share a static version of the
worksheet.
You can copy and paste (page 47) values from function arrays to new locations on a
worksheet using the Paste Special command. Although the worksheet data can no longer
be recalculated once copied, this method allows you to distribute a customized snapshot
of data to anyone who has a copy of Excel.
If you have Microsoft SharePoint Server in your computing environment, you can
publish a PI DataLink worksheet to a SharePoint site and use PI DataLink Server (page
2) to display and recalculate data from PI DataLink functions.
Set Workbook Calculation option to manual
To let those without PI DataLink view the last data saved in the workbook, set the Excel
Workbook Calculation option to Manual before you save a workbook.
Procedure
1. Click the File tab and select Options. (In Excel 2007, click the Microsoft Office Button,
and then click Excel Options.)
2. In the Excel Options window, click Formulas.
3. Under Calculation options, set Workbook Calculation to Manual, and then click OK.

Chapter 5
Advanced topics
Topics in this discussion provide more in-depth information useful for work with PI DataLink
functions.
PI time
You can use a special syntax, called PI time, to specify inputs for time stamps and time
intervals. PI time uses specific abbreviations, which you combine to create time expressions.
PI time abbreviations
When specifying PI time, you can use specific abbreviations that represent time units and
reference times.
Time-unit abbreviations
Abbreviation Time unit

s second
m minute
h hour
d day
mo month
y year
w week
To specify time units, you can specify the abbreviation, the full time unit, or the plural
version of the time unit, such as s, second, or seconds. You must include a valid value
with any time unit. If specifying seconds, minutes, or hours, you can specify a fractional
value, such as 1.25h. You cannot specify fractional values for other time units.
Reference-time abbreviations
Abbreviation Full version Reference time
* Current time
t today 00:00:00 (midnight) of the current day
y yesterday 00:00:00 (midnight) of the previous day

Advanced topics
Abbreviation Full version Reference time
sun1 sunday 00:00:00 (midnight) on the most recent Sunday
jun2 june 00:00:00 (midnight) on the current day in June of the

current year
dec DD december DD 00:00:00 (midnight) on the DDth day of December in
the current year
YYYY 00:00:00 (midnight) on the current day and month in
year YYYY
M-D or M/D 00:00:00 (midnight) on the Dth day of month M in the
current year
DD 00:00:00 (midnight) on the DDth day of the current
month
1
Use the first three letters as an abbreviation for any day of the week: sun, mon, tue, wed, thu,
fri, or sat.
Use the first three letters as an abbreviation for any month of the year: jan, feb, mar, apr,
2
may, jun, jul, aug, sep, oct, nov, or dec.
PI time expressions
PI time expressions can include a reference time and a time offset, indicated by a direction
(either + or -) and a time unit with a value. PI time expressions might include:
Only a reference time, such as t
Only a time offset, such as +3h
A reference time with a time offset, such as t+3h
A reference time can be a fixed time, such as 24-aug-2012 09:50:00, or a valid
reference-time abbreviation, such as t.
You can only include one time offset in an expression. Including multiple offsets can lead to
unpredictable results. For example, the following time expressions are not valid:
*+1d+4h
t-1d+12h
Time-stamp specification
To specify inputs for time stamps, you can enter time expressions that contain:
Fixed times
A fixed time always represents the same time, regardless of the field or the current time.
Input Meaning
23-aug-12 15:00:00 3:00 p.m. on August 23, 2012
25-sep-12 00:00:00 (midnight) on September 25, 2012
56
PI time
Reference-time abbreviations
A reference-time abbreviation represents a time relative to the current time.
Input Meaning
* Current time (now)
3-1 or 3/1 00:00:00 (midnight) on March 1 of the current year
2011 00:00:00 (midnight) on the current month and day in the
year 2011
25 00:00:00 (midnight) on the 25th of the current month
t 00:00:00 (midnight) on the current date (today)
y 00:00:00 (midnight) on the previous date (yesterday)
tue 00:00:00 (midnight) on the most recent Tuesday
Reference-time abbreviations or fixed times with a time offset

When included with a fixed time or a reference-time abbreviation, a time offset adds or
subtracts from the specified time.
Input Meaning
*-1h One hour ago
t+8h 08:00:00 (8:00 a.m.) today
y-8h 16:00:00 (4:00 p.m.) the day before yesterday
mon+14.5h 14:30:00 (2:30 p.m.) last Monday
sat-1m 23:59:00 (11:59 p.m.) last Friday
1-jan-11-1d 00:00:00 (12:00 a.m.) 31 December 2010
Time offsets
Entered alone in a time field, time offsets specify a time relative to an implied reference
time. The implied reference time depends on the field where you enter the expression:
For a start time, the reference time is the current clock time.
For an end time, the reference time is the start time.
For a single time stamp, the reference time is the current clock time.
Time field Input Meaning
Start time -1d One day before the current clock time (24
hours before the current clock time)
End time +6h Six hours after the start time
End time -30m 30 minutes before the start time
Time stamp -15s 15 seconds before the current clock time

Advanced topics
Time-interval specification
Time-interval inputs define intervals for collecting or calculating values during a time period.
For example, you might specify a 60-minute interval to compute an hourly average over a 12-
hour period. To specify time-interval inputs, enter a valid value and time unit:
Positive values define intervals that begin at the earlier time in the period and that finish
at or before the later time in the period.
Examples with positive time-interval value
Start time 2:00:00 3:15:00

End time 3:15:00 2:00:00
Time interval 30m 30m

Returned intervals 2:00:00 to 2:30:00 2:30:00 to 3:00:00
2:30:00 to 3:00:00 2:00:00 to 2:30:00
Negative values define intervals that finish at the later time in the period and that begin at
or after the earlier time in the period.
Examples with negative time-interval value
Start time 2:00:00 3:15:00

End time 3:15:00 2:00:00
Time interval -30m -30m
Returned intervals 2:15:00 to 2:45:00 2:45:00 to 3:15:00
2:45:00 to 3:15:00 2:15:00 to 2:45:00
Expressions
In PI DataLink, expressions are performance equations that you can use in functions to
incorporate mathematical operations and calculations based on PI System data items. For
example, you might use an expression in a PI DataLink function to calculate values as they
are retrieved from PI Server.
Note: PI DataLink restricts data items that you can include in expressions. See
Restrictions on data items in expressions (page 60).
Some PI DataLink functions accept either a data item or an expression as input. These
functions have Data item and Expression options at the top of the task pane. Some PI
DataLink functions also have a Filter Expression field. Specify a filter expression to limit
the values that a function returns.
PI DataLink functions that can use expressions include:
Archive Value (page 28)
Compressed Data (page 30)
58
Expressions
Sampled Data (page 34)

Timed Data (page 36)
Calculated Data (page 37)
Time Filtered (page 42)
Subsequent sections describe basic information about expressions. PI DataLink supports all
the syntax, operators, and functions that PI Server supports.
For a full description of performance equations and examples, see the PI Server Applications
User Guide or the PI 3 Performance Equations Help File. You can download these
documents from the OSIsoft Technical Support site
(http://techsupport.osisoft.com/downloadcenter.aspx).
Use expressions in PI DataLink functions
Use expressions in PI DataLink functions to incorporate mathematical operations and

calculations based on PI System data items. Functions that accept either a data item or an
expression have Data item and Expression options at the top of the task pane.
Before you begin

Open the function task pane.
Procedure
1. Click the Expression option at the top of the function task pane.
The Data item(s) field becomes an Expression(s) field. The availability of other fields
might change.
2. Enter the expression directly in the Expression(s) field, or enter a reference to a cell that
contains an expression.
Use cell references to specify multiple expressions for a function. Remember that an
expression in a referenced cell is a string, and should be preceded by a single quote.
Expression syntax
Follow these guidelines when writing expressions:

Enclose any PI point or PI AF attribute names in the expression in single quotes.
If entering an expression in an Excel cell, begin the expression with a single quote to
force Excel to interpret the expression as a string.
If entering an expression in an Excel cell and the expression starts with a PI point or PI
AF attribute name, begin the expression with two single quotes.
If entering a value to compare to a digital PI point, specify the negative value of the
digital state code number.

Advanced topics
Restrictions on data items in expressions
PI DataLink permits the following data items in expressions:

PI points
PI AF attributes that store data references to PI points
PI AF attributes that store constant values
Furthermore, a PI DataLink function can only return data from a single PI Server. Therefore,
any PI points in an expression, including those referred to by PI AF attributes, must be stored
on the same PI Server. Similarly, PI points in a filter expression must be stored on the same
PI Server as any PI points specified by the Data item or Expression fields.
Expression examples
The following expression computes the sum of the value of the PI point sinusoid cubed
and the value of the PI point cdf144 divided by 10:
(('sinusoid')^3 + 'cdf144'/10)
The following expression evaluates to true (non-zero) if the absolute value of the PI point
mytag is at least 14.65:
(abs('mytag') >= 14.65)
The following expression evaluates to true if the value of the PI AF attribute Manufacturer
is ACME:
('\\Server\Database\Element|Manufacturer' = "Manual")
The following expression evaluates to true if the value of the PI point sinusoid is less
than 45 and the square root of the value of the PI point vdf1002 is greater than 2:
('sinusoid' < 45 and sqr('vdf1002') > 2)
Filter expressions
Use a filter expression in a PI DataLink function to filter returned event values with a
Boolean performance equation. PI DataLink removes data for which the expression evaluates
as false.
PI DataLink applies the filter expression to the raw data retrieved (and not values that result
from the calculation itself). For example, adding the simple filter expression 'sinusoid'
< 70 to the Calculated Data function would remove all values over 70 from the calculation.
Filter expressions can contain any valid Boolean performance equation; however, data items
in filter expressions must reference a PI point. You can build complex expressions. For
example, you might use filter expressions to remove atypical peaks in data values.
If available, select the Mark as filtered check box to insert the label Filtered in place of
a value or block of values that the function filtered from the output based on the filter
expression.
60
Manual function entry
See also
Expression syntax (page 59)
Restrictions on data items in expressions (page 60)

Though you can use the PI DataLink interface to build any PI DataLink function, experienced
users might prefer to enter functions directly in the Excel formula bar.
The following topics apply to PI DataLink functions entered directly in the formula bar.
Define functions manually
If you do not want to use the function task pane, you can define PI DataLink functions
manually.
Procedure
1. Select an appropriate range in the worksheet for the output array based on the number of
expected values.
2. Enter the PI DataLink function and its arguments into the Excel formula bar.
3. Press Ctrl+Shift+Enter to place the PI DataLink function into the selected output cells.
Refer to the online Help for Microsoft Excel for more information on array formulas.
Guidelines for entering arguments manually
The following table lists types of data you might enter as arguments to PI DataLink functions,
and provides guidelines for entering them.
Data entered as argument Guideline
Standard functions You can include various functions in arguments that accept
expressions. See the PI Server Applications User Guide or the
PI 3 Performance Equations Help File for a list of functions.
Strings Surround string arguments with double quotes.
For example, to retrieve the snapshot time and value for the PI
point sinusoid from the PI Server named casaba, select a
1 x 2 output array and enter:
=PICurrVal("sinusoid", 1, "casaba")

Advanced topics
Data entered as argument Guideline

Cell references You can use cell references for any PI DataLink function
arguments.
For example, suppose the worksheet cells have the following
values:
A1 "sinusoid"
A2 1
A3 "casaba"
Then, entering the following function in the formula bar:
=PICurrVal(A1, A2, A3)
is equivalent to entering:
=PICurrVal("sinusoid", 1, "casaba")
Root path Surround an entry with double quotes. For example, to retrieve
the current value for the PI AF attributes specified in cells B3
through B5 and stored in the PI AF server DLAFPI, database
MyTest, and element Reactor, enter:
=PICurrVal(B3:B5,0,"\\DLAFPI\MyTest\Reactor")
See Data items (page 12) for information about valid entries.
Output codes Determines what appended data the function returns and how
the function orients output. See Output codes (page 62).
Output codes
PI DataLink function syntax contains an integer OutCode argument. This argument takes an
output code that determines which appended data (page 14) the function returns and the
orientation of output cells.
PI DataLink task panes generate output code values automatically. However, if you enter a
function manually in the Excel formula bar, you need to calculate and include an appropriate
output code value.
An output code is an integer representation of binary bits. In PI DataLink, bit meaning
depends on the function:
Bit meaning for Current Value and Archive Value functions
Bit Purpose
1st Show time stamp in column to left of value
2nd Show time stamp in row above value
Bit meaning for other PI DataLink functions
Bit Purpose
1st Show time stamps

2nd Orient data in rows rather than columns
62
Bit Purpose
3rd Show percent good

4th Hide count
5th Show extended status
6th Show annotations
7th1 Show start time
8th1 Show end time
9th1 Show min/max time
1
Requires that the 1st bit be enabled also
With an OutCode argument of 0, a function returns the value in a column orientation with
no appended data. To compute the OutCode argument, use the following formula:
For example, with an OutCode argument of 0, the PISampDat() function returns the
sampled values in the designated output cell. With an OutCode argument of 1, the function
returns time stamps in column one and sampled values in column two of an n x 2 array. With
an OutCode argument of 3, the function returns time stamps in row one and the sampled
values in row two of a 2 x n array. (In these results, n is the number of sampled events.)
Note: Functions support different bits and therefore OutCode argument values. Those
valid for one function are not necessarily valid for another function. See the
function reference (page 83) for the bits that each function supports in its
OutCode specification.
EXAMPLE
Suppose you want the Calculated Data function to display percent good, start time, and
min/max time. To display the start time and min/max time, you must enable the show-time-
stamps bit. To calculate the OutCode argument:

Advanced topics
In the Excel formula bar, enter:

=PICalcDat("sinusoid","y","t","1h","minimum", 1, 325,"piserver")
Note: If an OutCode argument specifies the display of multiple columns or rows but the
worksheet does not show them, right-click the function array and choose
Recalculate/Resize to rewrite the function array.
Functions to write data

Unlike standard PI DataLink functions, which retrieve data from a PI Server or PI AF server,
the PIPutVal() and PIPutValX() (page 114) functions write a value from a worksheet
to a PI Server or PI AF server. These functions can replace existing values with new user-
supplied values that have matching time stamps.
The PIPutVal() and PIPutValX() functions are Excel macro functions. You can run
the PIPutVal() or PIPutValX() function from an Excel 4.0 macro sheet, or in VBA
using the application.run method. See the putval_code module in the
piexam32.xls file distributed with PI DataLink for 32-bit Excel and in the
piexam64.xls file distributed with PI DataLink for 64-bit Excel. In particular, see the tags
marked PutVal and the VBA module PutVal_code for an example of a VBA module
used to enter PI DataLink functions in a worksheet.
Note that VBA does not recognize PI DataLink functions, but you can formulate a function as
a text string, and then set the formula array property of a range of cells to the text string
value. The VBA code can then check the cell values for the PI DataLink function results.
This yields the same results as manual entry of PI DataLink functions in the same range of
cells.
64
Chapter 6
Tag functions
A PI point is a stream of real-time data from a defined source. Point attributes, including the
tag (that is, the PI point name) and point source, describe a PI point.
Use PI DataLink tag functions to find tags that correspond to PI point IDs or other point
attributes. You can find tag functions on the PI DataLink tab in the Tag Functions group.
Note: You must activate the PI DataLink (Legacy) add-in to use these functions (see
Microsoft Excel add-in configuration (page 6)).
See also
Overview of PI DataLink functions (page 11)
Properties function (page 44)
Trends (page 69)
Point ID to Tag function

The Point ID to Tag function returns the tag that corresponds to a specific PI point ID.
Input Description
PI Server The PI Server that the function returns data from. If you do not select a server
or leave the field blank, the function searches the default PI Server.
Point ID(s) One or more point IDs for which you want the function to return tags. Required.
RELATED TOPICS
PIPointIDToTag() (page 111)

Tag functions
Point ID to Tag example
To see the tag that corresponds to a PI point ID, set the following inputs for the Point ID to
Tag function:
Input Value
Point ID A5 (a cell that contains a point ID)
In this case, 1 is the point ID and SINUSOID is the returned tag.
Attribute Mask to Tag function

The Attribute Mask to Tag function returns tags that match one or more specified PI point
attribute values.
Input Description
Tagname(s) PI point attribute value for which the function finds the corresponding tag. You
must enter a value in at least one input. Use the wildcard character (*) to find
Descriptor all matches or matches limited to specified characters. For example, enter S* in
Point source Point source to find any tag with a point source of "S" or a point source that
begins with "S."
Point type
Point class
Engineering units
66
Search for tags
RELATED TOPICS
PIAttributeMaskToTag () (page 112)
Attribute Mask to Tag example
To see the tags that have a name that starts with "BA" and type "Float32," set the following
inputs for the Attribute Mask to Tag function:
Input Value
Tagname BA*
Point type Float32
Note that attribute strings must match attribute values in PI Server, and wildcards can be
used.
Search for tags

For tag-information functions, use the Tag Search window to query PI Server for point IDs
or tags to insert in the task pane.
Procedure
1. On the task pane, click next to the Point ID(s) or Tagname(s) field.
2. In the Tag Search window, click the appropriate tab for your search:
Basic Search
Use to create a mask from specified PI point attributes and search for tags that have
matching attribute values.
Advanced Search
Use to build a query for a complex search that involves more point attributes than the
basic search.
Alias Search
Use to select tags by their descriptive aliases in the PI Module Database.

Tag functions
3. Enter the search criteria.

Use '*' or '?' as wildcard characters, as appropriate. For example, the Tag Mask Tem*
returns all point names that start with Tem, but Tem? returns only points that start with
Tem and end with another single character. All search fields are case insensitive.
4. If desired, click Favorites to access previous searches.
5. Click Search to find tags that match the specified criteria.
6. Select the desired tag in the Results panel, and click OK to insert the value in the task
pane.
If you select multiple tags, PI DataLink only pastes the first tag in the task pane.
68
Chapter 7
Trends
The PI DataLink version for 32-bit Microsoft Office includes an ActiveX trend object. You
can insert a trend into a worksheet to visually depict changes in event values over time.
Trends can depict data in the worksheet or from selected PI points.
Note: You must activate the PI DataLink (Legacy) add-in to insert or edit trends (see
Create a trend
A trend includes one or more traces, which visually depict a set of values. Use the Trend
Add-in Wizard to insert and configure trends.
Procedure
1. In a worksheet, click the cell where you want to place the top left corner of the trend.
When selecting the cell, remember that by default a trend requires approximately 14 by 8
standard cells.
2. On the PI DataLink tab, in the Tag Functions group, click Insert Trend to open the
Trend Add-in Wizard.

Trends
3. Define one or more traces to include in the trend. You can:

Create a trace of values in the worksheet (page 71).
Create a trace of PI point values retrieved from a PI Server (page 71).
4. Adjust the appearance of the traces in the trend. You can:
Select the check box in the Markers column to include markers that indicate the
location of archived data points.
Note: Traces are drawn in different colors. By default a trend also includes color-
blind markers to differentiate traces on monochrome screens. Color-blind markers are
evenly spaced along a trace and do not indicate archived data points.
Select a trace and then use the arrow buttons to move the trace up or down in the
legend.
Select a trace and then click X to remove the trace.
Click X All to remove all the traces.
Select a trace and then click Rename to rename the trace.
5. Click Next.
6. If any of the traces in the trend contains PI point values retrieved from a PI Server,
specify the time period to retrieve values:
a. Specify the start of the period in the Start Time field and the end of the period in the
End Time field. You can:
Select a time string from the list.
Type a time value in the field.
Click to change the field to a data-reference field, and then click the work-
sheet cell that contains a time string or type the address of that worksheet cell.
See PI time (page 55) for a discussion of valid time strings.
b. Select the Enable Updates check box to refresh the trend with new PI Server data if
the time range changes or extends to the present.
7. Click Next.
8. Specify the title and placement of the trend:
a. In the Trend title field, type a title for the trend.
b. Clear the Show Value Attributes check box if you do not want value attributes to
appear on trend traces.
The icons appear when the data contains events that have the Questionable,
Substituted, or Annotated bits set.
c. If desired, specify a different location for the trend. You can select:
New worksheet to place the trend at the top left corner of a blank worksheet.
Existing worksheet to place the trend in the current worksheet beginning in the
specified cell.
If you change the cell, make sure the new cell does not contain data.
9. Click Finish.
70
Create a trend
Create a trace of values in the worksheet
When creating a trend with the Trend Add-in Wizard, you can define a trace for the trend
from values in a worksheet.
Procedure
1. In the Trend Add-in Wizard, click Data on worksheet.
2. Click the Cell Range containing data field, and then select the worksheet cells that
contain the values.
3. Specify options appropriate to the specified cell range:
Select the First element is trace name check box to use the value of an adjacent cell
as the name of the trace. (If the cell range is a column, then the name of the trace is in
the cell above the first value; if the cell range is a row, then the name of the trace is in
the cell to the left of the first value.)
Select the Include all cells in array check box to include all the cells in a function
array in the cell range. If you select this check box, the Cell Range containing data
field only needs to specify one cell in a function array.
Select the Stepped check box to plot a stepped trend instead of a continuous trace.
You might select this check box for PI points that store discrete values.
4. Click Add to insert the trace in the trend.
Create a trace of PI point values retrieved from a PI Server
When creating a trend with the Trend Add-in Wizard, you can define a trace for the trend
from values retrieved from a PI Server.
Procedure
1. In the Trend Add-in Wizard, click Data from PI.
2. In the Tag name field, specify the PI point name you want to retrieve values for. You
can:
Type the name of the point.
Click the field and then select the worksheet cells that contain names of points.
Click to open the Tag Search window, which you can use to search for tags
(page 67).
3. In the Server name field, specify the PI Server that stores values for the point. You can:
Select the server from the list.
Click to change the field to a data reference field, and then click the worksheet
cell that contains a server or type the address of that worksheet cell.
4. Click Add to insert the trace in the trend.

Trends
Trend right-click menu

Use the trend right-click menu to update, edit, or manage a trend inserted in a worksheet.
Right-click a trend to open a menu with several commands:
Change Scale
Open the Change Scale window to change the y-axis scale or the x-axis time range.
Revert
Undo any changes and revert to the original trend settings defined in the Trend Add-in
Wizard.
Scroll Bar
Enable a scroll bar at the bottom of the trend to scroll the display through adjacent time
periods.
Format
Open the PI Trend Control Properties window to edit the appearance of individual
traces or the trend as a whole. You can change the color or line thickness of a trace, or
add legend items to the trend.
Define Trend
Open the trace definition page of the trend wizard to update or change the traces.
Define Trend Time Range
Open the time range definition page of the trend wizard to update the time range.
Delete Trend
Remove the trend from the worksheet.
Note: You cannot restore a deleted trend; you can only recreate.
Export Data
Open the Export Data window to paste the values in the trend into rows or columns of
the worksheet. You can also export trace names as headings.
Move/Resize
Open the Move/Resize window to move the upper left corner of the trend to a specified
cell. Enter a cell range to resize the trend.
Copy/Paste
Open the Copy/Paste window to paste a copy of the trend to a specified cell.
72
Chapter 8
PI Module Database objects

The topics in this section describe the tools that PI DataLink provides to access PI Module
Database objects. You can find these tools on the PI DataLink tab in the Module Database
group. See the PI Server documentation for more information about module databases and
configuration.
Note: You must activate the PI DataLink (Legacy) add-in to use these tools (see
PI Module Database and worksheets

The PI Module Database is a hierarchical tree structure based on the contents of a PI Server.
The PI Module Database provides an entirely different way to build the infrastructure of a
worksheet. If your PI Server's module database is configured and includes objects that
represent the tags you want to use, your worksheets can be easier to build and provide more
flexibility and potential for re-use.
The PI Module Database is typically configured by your system or PI administrator, and
stores aliases and properties that refer to PI points and their attributes, respectively. The
hierarchical structure of these objects provides a relational context between points.
For example, you may have five PI points that represent the levels of five individual, identical
tanks. Each point has a different tag name and represents a different physical object, but their
usage and monitoring requirements are the same.
By retrieving objects from the module database, you can create a single worksheet built on
the aliases and properties that represent all five tanks. Module database functions resolve
these objects into tag names and attribute values. Parallel module paths for each tank provide
a different context for the alias references.
With this type of structure, you can use the same worksheet to alternate between views of
multiple assets. For instance, when you select the name of any of the five tanks in a
worksheet cell, the alias mapping to the matching PI point allows PI DataLink functions to
retrieve values for the appropriate tank.

Insert PI Module Database objects into your worksheet

Use the Module Browse window to browse PI aliases, properties, and module paths in the PI
Module Database. You can select these items and copy them directly into a worksheet.
Note: Aliases and properties corresponding to PI points must be configured in your PI

Module Database to use the Module Database functions in PI DataLink.
Procedure
1. Select a cell, and then on the PI DataLink tab click Module Browse to open the Module
Browse window.
2. Select the type of object you are looking for:
Alias
Property
Module
3. From the PI Server list, select the connected PI Server that contains the module database
you want to browse.
4. From the Query date list, specify the effective date and time of the module database
hierarchy that you want to see.
5. Browse the tree hierarchy to find the desired item.
6. Select an item or a parent collection object that you want to copy to the worksheet:
Select an item to copy it to the worksheet.
Select a parent object (either Aliases or Properties) in a module to copy all the
aliases or properties of that module to the worksheet.
7. Select the Copy module path check box to copy the full module path of the alias or
property to the adjacent worksheet cell.
The module path provides the context for the selected object
Note: If the Copy PI Server name setting (see "Manage preference settings" on
page 19) is enabled, PI DataLink also copies the corresponding PI Server
name.
8. Click OK to copy the selected items to the worksheet and close the window.
74
Module database functions
Module database functions

Use PI DataLink module database functions to find the tags that correspond to aliases and
properties in a module database tree. These functions use the module path. You can enter a
module path as a function argument or reference it from a worksheet cell. You can find
module database functions on the PI DataLink tab in the Module Database group.
Note: The function cannot resolve an alias or property object into a tag without a module
path. The path provides a context that maps the alias to a specific PI point.
Also see Overview of PI DataLink functions (page 11).
Alias to Tag function
The Alias to Tag function returns the PI tag that corresponds to a specified PI alias.
Option Description
Alias(s) An alias in PI Module Database. Required.
Module path The module path from the PI Module Database where the specified alias can
be found. If you specify Alias by browsing the Module Database, then PI
DataLink enters Module path automatically. Required.
Query date An effective date of the alias. PI DataLink returns the tag that corresponds to
the specified alias on this date. Required.
No server Choose to return only the PI tag.
Server at right Choose to display the PI Server that stores the tag in the cell to the right of the
tag.
Server at bottom Choose to display the PI Server that stores the tag in the cell below the tag.
RELATED TOPICS
PIAliasToTag() (page 113)

Property to Value function
The Property To Value function returns the value or values corresponding to a specified PI
property.
PI DataLink can return values for Boolean, Date, Double, Integer, Long, Null, Single, and
String property types, or for Double, Integer, Long, and Single array property types.
Option Description
Property(s) A PI property in PI Module Database. Required.
Module path The module path from the PI Module Database where the specified property
can be found. If you specify Property by browsing the Module Database, then
PI DataLink enters Module Path automatically. Required.
Query date An effective date of the PI property. PI DataLink returns the tag that
corresponds to the specified property on this date. Required.
RELATED TOPICS
PIPropertyToValue() (page 114)
76
Chapter 9
Notifications
PI DataLink includes the PI DataLink Notifications add-in. When activated, this add-in adds
the Notification Search function to the PI DataLink tab. Use the Notification Search function
to retrieve PI System notifications that you subscribe to and to insert those notifications into
worksheets.
The PI DataLink Notifications add-in runs on Windows XP and later operating systems, and
requires Excel 2007 SP3 or later versions. PI Notifications must be installed on the computer
to activate the add-in (see Microsoft Excel add-in configuration (page 6)).
Note: You must have an account on at least one PI AF 2.0 server with PI Notifications
1.0, and be subscribed to at least one notification rule to receive notifications. For
further information on PI Notifications, see the PI Notifications User Guide.
To access the Notification Search function, click the desired output cell in the worksheet, and
then on the PI DataLink tab (in the Notifications group), click Notification Search to open
the Notification Search window.
Search and insert notifications

Use the Notification Search window to search for notifications that you subscribed to from a
particular PI AF server and then insert them into your worksheet. The PI AF server contains a
database of structural elements and notification events that help you work with data in your
PI Server.

Notifications
Procedure
1. On the PI DataLink tab, in the Notifications group, click Notification Search to open
the Notification Search window.
2. On the Search tab, select the PI AF server you will search for notifications:
From the PI Systems list, select a PI AF server and click Connect to connect to that
server.
If necessary, click Show List to open the AF Servers window, where you can
add a PI AF server (see "Add a PI AF server to the Notification Search function" on
page 78) to the list.
Click and then click a worksheet cell that contains the name of a PI AF server.
Click the button again to show the PI Systems list.
3. From the View Notifications list, select the option to filter returned notifications:
Select Active to return all currently-active notifications.
Select Timerange and enter Start Time and End Time values to return notifications
that occurred over a specific time range.
Select Recent and enter a value and a time interval to return the most recent
notifications over a specific time period.
4. In the Output Cell field, specify the worksheet cell where you want to insert the
notifications.
5. Click Search to retrieve the notifications that match the specified criteria into the results
area at the bottom of the tab.
6. Examine the retrieved notifications. You can:
Adjust display of retrieved notifications (page 80)
Manage retrieved notifications (page 80)
7. Click OK to insert the displayed notifications into the worksheet and close the window.
PI DataLink inserts the notification query into the worksheet as a function array at the
designated location. Like other PI DataLink functions, the Notification Search function
updates data when the worksheet recalculates (see "Triggered recalculation" on page
51).
Add a PI AF server to the Notification Search function
Your PI System might have multiple PI AF servers, each of which might have PI
Notifications installed and be a source of relevant notifications. For example, you might
subscribe to notifications from PI AF servers that run in different facilities or that represent
different business units.
Before you can view the notifications from a particular PI AF server in Excel, you must add
that PI AF server to the PI Systems list that the Notification Search function maintains.
78
Search and insert notifications
Before you begin

Subscribe to the notifications in PI System Explorer.
Procedure
1. On the Search tab of the Notification Search window, click Show List next to the
PI Systems list to open the AF Servers window.
2. Click Add AF Server to open the AF Server Properties window.

3. Enter the relevant network information to locate the PI AF server and to authenticate your
computer to that server:
In the Name field, enter the name that will identify the PI AF server in the
Notification Search function.
Click Configure Active Directory to configure access to Active Directory to acquire
login information.
4. Click OK to save the properties and add to list of PI AF servers.
5. Click OK to close the AF Servers window.
The PI AF server appears in the PI Systems list.
For more information about PI AF servers, see the PI AF documentation.

Notifications
Adjust display of retrieved notifications
On the Notification Search window, the results area at the bottom of the Search tab shows
the notifications that match the specified search criteria. You can adjust the display of these
notifications.
Procedure
Click column headings to sort notifications by a particular attribute.
Right-click the results to show and hide columns:
Click Expand All or Collapse All to expand or collapse a notification grouping.
Click Show Contact Events to toggle the display of contact events for each
notification.
Manage retrieved notifications
On the Notification Search window, the results area at the bottom of the Search tab shows
the notifications that match the specified search criteria. Before you insert retrieved
notifications into your worksheet, you can assess, manage, and respond to these notifications.
Procedure
Right-click a notification and choose a command:
Acknowledge Instance
Acknowledge that action has been taken regarding the notification, and that no further
escalation is needed. If desired, enter a comment, and click OK.
Acknowledge Subscription
Acknowledge receipt of a notification you are subscribed to. If desired, enter a comment
and click OK.
Add Comment
Comment on a notification.
View Notification Rule Summary
Display the properties of the notification rule that triggered a selected notification.
80
Inserted notifications
Inserted notifications
PI DataLink functions can reference notifications data in worksheet cells. For example, you
might use the Start Time value from a retrieved notification to retrieve sampled data that
indicates the progress of a batch process.
If your notifications are set to display acknowledgments, these columns include links to PI
Notifications web pages where you can acknowledge or comment on a notification.
For more information on notifications, subscriptions, and acknowledgments, see the PI
Notifications User Guide.
Notification display settings

Use the Display Format tab on the Notification Search window to specify the appearance of
notifications inserted into worksheet cells. You can select the columns displayed and change
their organization and formatting.

Notifications
Columns
Select columns from the Available columns list and click Add to move them to the
Column order list, which specifies the data inserted into the worksheet.
Note: Include the Acknowledge column to add a link in the worksheet to

acknowledge receipt of a notification, and include the Acknowledge With
Comment column to add a link in the worksheet to make a comment on a
notification.
Click Add All to move all columns to the Column order list.
Select columns from the Column order list and click the arrow buttons above the list to
change column order.
Select columns from the Column order list and click Remove to remove the selected
columns from the list.
Click Clear to remove all columns from the Column order list.
Contact events
Select the Display contact events check box to include contact events related to each
notification, such as sending to each recipient, comments and acknowledgments.
Select the Indent contacts check box to indent contact events in the worksheet. This can
help you identify them.
Select Using separate columns to add a second column for contact events.
Select Formatting cells to indent contact events in the same column as notification
events.
Select the Group notifications with Excel grouping check box to use Excel's grouping
functionality to nest contact events beneath individual parent notifications that spawned
them.
Note: PI DataLink Server (page 2) does not support Excel grouping.
Display and orientation

Select the Display column headers check box to add headers to the notifications data.
Select the Display count check box to add a row or column that contains the count of
notifications before the notifications data.
Under Orient results in, select Columns to display notifications data in columns or
select Rows to display notifications data in rows.
82
Appendix A
Function reference
You can generate PI DataLink functions from PI DataLink task panes (page 11). The
resulting function array depends on the inputs. You can also enter these same functions
directly (page 61) in the Excel formula bar.
This section contains a reference to supported PI DataLink functions. Each topic describes
the function syntax and arguments; most topics also include an example. Subsequent sections
group functions by type.
Single-value functions
Single-value functions retrieve the value of a data item at a specific time. They return exactly
one value per data item.
PICurrVal()
Returns the current value of a PI point from the snapshot or a PI AF attribute from the
database.
SYNTAX
PICurrVal(DataItem, OutCode, RootPath)
ARGUMENTS
Argument Description
DataItem The PI point name or PI AF attribute name for which the function returns
(string) a value. Specify a range of cells that contain PI point names or PI AF
attribute names to return a value for each.
OutCode An output code that determines what appended data the function
(integer) returns and how the function orients output. See Output Codes (page
62) for information on how to compute the code. This function supports
bits 1 and 2.
RootPath The path to the data item. See Data items (page 12).
(string)
EXAMPLE
The following function returns the current value and corresponding time stamp for the PI
point let439 from the PI Server named holden and places the time stamp in the column
to the left of the value:

Function reference
=PICurrVal("let439",1,"holden")
RELATED TOPICS
Current Value function (page 27)
Define functions manually (page 61)
Guidelines for entering arguments manually (page 61)
PIArcVal()
Returns the value of a PI point or PI AF attribute at a specified time stamp.
SYNTAX
PIArcVal(DataItem, TimeStamp, OutCode, RootPath, Mode)
ARGUMENTS
DataItem (string) The PI point name or PI AF attribute name for which the function
returns a value. Specify a range of cells that contain PI point
names or PI AF attribute names to return a value for each.
TimeStamp (string) The time stamp for which the function returns values. See Time
inputs (page 13).
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes
(page 62) for information on how to compute the code. This
function supports bits 1 and 2.
RootPath (string) The path to the data item. See Data items (page 12).
Mode (string) The method the function uses to retrieve values:
previous
previous only
interpolated
auto
next
next only
exact time
EXAMPLE
The following function returns the interpolated value of the PI point cdep158 at 7:20 p.m.
on December 11, 1992 from the PI Server named casaba:
=PIArcVal("cdep158","11-dec-92 19:20",0, "casaba","interpolated")
RELATED TOPICS
Archive Value function (page 28)
84
Single-value functions
PIExpVal()
Returns the computed value of a performance equation at a specified time stamp.
SYNTAX
PIExpVal(Expression, TimeStamp, OutCode, RootPath)
ARGUMENTS
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 58).
Reference a range of cells that contain expressions to return
values for each.
TimeStamp (string) The time stamp for which the function returns values. See Time
inputs (page 13).
OutCode (string) An output code that determines what appended data the function
function supports bits 1 and 2.
RootPath (string) The path to the data item referenced by the expression. See Data
items (page 12).
EXAMPLE
The following function calculates the square root of the value of the PI point sinusoid
from the PI Server named thevax at midnight yesterday:
=PIExpVal("sqr('sinusoid')","y",0,"thevax")
RELATED TOPICS
Archive Value function (page 28)
PITagAtt()
Returns a property value associated with a specified data item.
SYNTAX
PITagAtt(DataItem, Property, RootPath)

Function reference
ARGUMENTS
returns a value. Specify a range of cells that contain PI point
names or PI AF attribute names to return a value for each.
Property (string) The PI point attribute or PI AF attribute property for which the
function returns the value.
EXAMPLE
The following function returns the engineering units for the PI point specified in cell D1 from
the default PI Server:
=PITagAtt(d1,"uom",)
RELATED TOPICS
Properties function (page 44)
Multiple-value functions
Multiple-value functions associate a PI point or PI AF attribute with a time period over which
there can be one or many corresponding values.
PINCompDat()
Returns a specific number of PI point values or PI AF attribute values beginning at a certain

time.
SYNTAX
PINCompDat(DataItem, STime, NumVals, OutCode, RootPath, Mode)
ARGUMENTS
returns values. Specify a range of cells that contain PI point names
or PI AF attribute names to return values for each.
STime (string) The start of the time period for which the function returns values.
See Time inputs (page 13).
NumVals (integer) The number of values that the function returns, beginning at
STime (specify a negative number to retrieve values backward in
time).
function supports bits 1, 2, 5, and 6.
86
Mode (string) The method that the function uses to determine which values to
retrieve near the start time (boundary type):
inside
outside
interpolated
auto
EXAMPLE
The following function returns ten values and the corresponding time stamps from the default
PI Server for the PI point cdf144 starting from 1:00 a.m. this morning, using boundary type
"inside":
=PINCompDat("cdf144","1:00:00",10,1,,"inside")
RELATED TOPICS
Compressed Data function (page 30)
PINCompFilDat()
Returns a specific number of filtered PI point values or filtered PI AF attribute values

beginning at a certain time.
SYNTAX
PINCompFilDat(DataItem, STime, NumVals, FiltExp, FiltCode,
OutCode, RootPath, Mode)
ARGUMENTS
STime (string) The start of the time period for which the function returns values. See
Time inputs (page 13).
NumVals (integer) The number of values that the function returns, beginning at STime
(specify a negative number to retrieve values backward in time).
FiltExp (string) A Boolean performance equation that the function uses to filter

Function reference
FiltCode (integer) A code that indicates whether to label filtered values:
1
Insert the label Filtered in place of a value or block of values
that the function filtered from the output based on FiltExp.
0
Do not label filtered values.
returns and how the function orients output. See Output Codes (page
62) for information on how to compute the code. This function
supports bits 1, 2, 5, and 6.
retrieve near the start time (boundary type):
inside
outside
interpolated
auto
EXAMPLE
The following function returns ten values and the corresponding time stamps from the default
PI Server for the PI point cdf144 starting from 2:00 a.m. this morning, when the tag
cdep158 is greater than 38, using boundary type "inside":
=PINCompFilDat("cdf144","2:00:00",10,"'cdep158'>38",1,1,,)
The output contains the label Filtered between any values where the filter condition was
false.
RELATED TOPICS
Filter expressions (page 60)
PICompDat()
Returns PI point values or PI AF attribute values stored during a specified time period.
SYNTAX
PICompDat(DataItem, STime, ETime, OutCode, RootPath, Mode)
88
ARGUMENTS
returns values. Specify a range of cells that contain PI point
names or PI AF attribute names to return values for each.
ETime (string) The end of the time period for which the function returns values.
function supports bits 1, 2, 4, 5, and 6.
RootPath(string) The path to the data item. See Data items (page 12).
retrieve near STime or ETime (boundary type):
inside
outside
interpolated
auto
EXAMPLE
The following function returns values and corresponding time stamps from the default PI
Server for the PI point cdf144 from 1:00 a.m. to 3:00 a.m. this morning using boundary
type "inside":
=PICompDat("cdf144","1:00:00","3:00:00",1,,"inside")
RELATED TOPICS
PICompFilDat()
Returns filtered PI point values or filtered PI AF attribute values stored during a specified
time period.
SYNTAX
PICompFilDat(DataItem, STime, ETime, FiltExp, FiltCode, OutCode,
RootPath, Mode)

Function reference
ARGUMENTS
returns values. Specify a range of cells that contain PI point names or
PI AF attribute names to return values for each.
FiltExp (string) A Boolean performance equation that the function uses to filter values.
When the expression evaluates to false, the function excludes
corresponding values. See Filter expressions (page 60).
FiltCode A code that indicates whether to label filtered values:
(integer) 1
Insert the label Filtered in place of a value or block of values that
the function filtered from the output based on FiltExp.
0
supports bits 1, 2, 4, 5, and 6.
retrieve near STime or ETime (boundary type):
inside
outside
interpolated
auto
EXAMPLE
The following function returns values and the corresponding time stamps for the PI point
cdf144 from the default PI Server, starting at 2:00 a.m. and ending at 10:00 a.m., when the
PI point cdep158 is greater than 38, using boundary type "inside":
=PICompFilDat("cdf144","2:00:00","10:00:00","'cdep158'>38",1,1,,)
The output contains the label Filtered between any values where the filter condition was
false.
RELATED TOPICS
90
PISampDat()
Returns evenly-spaced, interpolated values for a PI point or PI AF attribute stored over a

specified time period.
SYNTAX
PISampDat(DataItem, STime, ETime, Interval, OutCode, RootPath)
ARGUMENTS
DataItem(string) The PI point name or PI AF attribute name for which the function
returns values. Specify a range of cells that contain PI point names or
PI AF attribute names to return values for each.
Interval The interval between returned values. Enter a value and time unit that
(string) specifies the length of the interval. For example, enter 15m (15 minutes)
to return a value for every 15-minute interval during the time period.
See Time-interval specification (page 58).
OutCode An output code that determines what appended data the function
(integer) returns and how the function orients output. See Output Codes (page
62) for information on how to compute the code. This function supports
bits 1 and 2.
RootPath The path to the data item. See Data items (page 12).
(string)
EXAMPLE
The following function returns sampled data and the corresponding time stamps for the PI
point sinusoid from the default PI Server, beginning at midnight yesterday and ending at
midnight today, reporting values in 3-hour intervals:
=PISampDat("sinusoid","y","t","3h",1,)
RELATED TOPICS
Sampled Data function (page 34)
PISampFilDat()
Returns evenly-spaced, interpolated and filtered values for a PI point or PI AF attribute stored
over a specified time period.
SYNTAX
PISampFilDat(DataItem, STime, ETime, Interval, FiltExp, FiltCode,
OutCode, RootPath)

Function reference
ARGUMENTS
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m (15
minutes) to return a value for every 15-minute interval during the
time period. See Time-interval specification (page 58).
FiltCode (integer) A code that indicates whether to label filtered values:
1
Insert the label Filtered in place of a value or block of values
that the function filtered from the output based on FiltExp.
0
(page 62) for information on how to compute the code. This function
supports bits 1 and 2.
EXAMPLE
The following function returns sampled data for the PI point sinusoid from the default PI
Server. The function retrieves values at midnight 11-Jan-97, 1:00 a.m. on 11-Jan-97, 2:00
a.m. on 11-Jan-97, and 3:00 a.m. on 11-Jan-97. If the condition in cell A1 is not satisfied at
any of those times, the function returns the label Filtered at that time. The function shows
time stamps in the first column and values in the second column.
=PISampFilDat("sinusoid","11-Jan-97","+3h","1h",A1,1,1,)
RELATED TOPICS
92
PIExpDat()
Returns evenly-spaced, computed values of a performance equation over a specified time

period.
SYNTAX
PIExpDat(Expression, STime, ETime, Interval, OutCode, RootPath)
ARGUMENTS
Reference a range of cells that contain expressions to return values
for each.
STime (string) The start of the time period for which the function calculates a value.
ETime (string) The end of the time period for which the function calculates a value.
minutes) to return a value for every 15-minute interval during the
time period. See Time-interval specification (page 58).
EXAMPLE
The following function calculates the square root of the value of the PI point sinusoid
retrieved from the PI Server named thevax at one-hour intervals, starting from midnight
yesterday to midnight today:
=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax")
The function displays the time stamp for each value in the column to the left of the calculated
value.
RELATED TOPICS

Function reference
PITimeDat()
Returns actual or interpolated sample values of a PI point or PI AF attribute at specified time

stamps.
SYNTAX
PITimeDat(DataItem, TimeStamps, RootPath, Mode)
ARGUMENTS
DataItem(string) The PI point name or PI AF attribute name for which the
function returns values. Specify a range of cells that contain PI
point names or PI AF attribute names to return values for each.
TimeStamps (reference) A reference to one or more worksheet cells that contain time
stamps for which the function returns values. See Time inputs
(page 13).
Mode (string) The method the function uses to retrieve data:
interpolated
exact time
RETURNS
Values at the specified time stamps, presented in the same orientation as the time stamp
reference. If the time stamp reference is a row, the function presents values in a row. If the
time stamp reference is a column, the function presents values in a column. The orientation of
the output array must match the orientation of the time stamp reference.
EXAMPLE
The following function retrieves interpolated values at the time stamps located in cells B1
through B12 for the PI point mytag on the default PI Server:
=PITimeDat("mytag",b1:b12,,"interpolated")
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
RELATED TOPICS
Timed Data function (page 36)
94
PITimeExpDat()
Returns values of a performance equation calculated at specified time stamps.
SYNTAX
PITimeExpDat(Expression, TimeStamps, RootPath)
ARGUMENTS
Expression (string) One or more performance equations that the function computes
a value for. See Expressions (page 58).
values for each.
TimeStamps (reference) A reference to one or more worksheet cells that contain time
stamps for which the function returns values. See Time inputs
(page 13).
RETURNS
Values at the specified time stamps, presented in the same orientation as the time stamp
reference. If the time stamp reference is a row, the function presents values in a row. If the
time stamp reference is a column, the function presents values in a column. The orientation of
the output array must match the orientation of the time stamp reference.
EXAMPLE
The following function calculates the square root of the value of the PI tag sinusoid
retrieved from the default PI Server at the times specified in cells B1 through B12:
=PITimeExpDat("sqr('sinusoid')",b1:b12,)
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
RELATED TOPICS
Timed Data function (page 36)

Function reference
Calculation functions
Calculation functions compute values from PI point values, PI AF attributes, or performance
equation evaluations during a specific time period.
PIAdvCalcVal()
Returns a value calculated from PI point or PI AF attribute values during a specified time
period.
SYNTAX
PIAdvCalcVal(DataItem, STime, ETime, Mode, CalcBasis, MinPctGood,
CFactor, OutCode, RootPath)
ARGUMENTS
calculates a value. Specify a range of cells that contain PI point
names or PI AF attribute names to calculate a value for each.
Mode (string) The type of calculation that the function performs:
total
minimum
maximum
stdev
range
average
count
mean
CalcBasis (string) The calculation method:
time-weighted
event-weighted
MinPctGood The minimum percentage of good data required during the time
(number) period to calculate and return a value.
CFactor (number) A factor that the function applies to the returned value. Enter 1 if a
conversion factor is not needed. For time-weighted total calculations,
specify a factor that converts recorded rate values to the server
default time unit (units per day).
96
supports bits 2, 3, and 9 (if Mode is set to minimum, maximum, or
range).
EXAMPLE
The following function returns a time-weighted total of the PI point cdf144 calculated from
the values on the default PI Server from yesterday to today:
=PIAdvCalcVal("cdf144","y","t","total","time-weighted",50,1,4,)
The function multiplies the result by 1, and only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of the calculated total.
RELATED TOPICS
Calculated Data function (page 37)
PIAdvCalcFilVal()
Returns a value calculated from filtered PI point or PI AF attribute values during a specified
time period.
SYNTAX
PIAdvCalcFilVal(DataItem, STime, ETime, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)
ARGUMENTS
calculates a value. Specify a range of cells that contain PI point
names or PI AF attribute names to calculate a value for each.
STime (string) The start of the time period for which the function calculates a
value. See Time inputs (page 13).
ETime (string) The end of the time period for which the function calculates a
value.

Function reference
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
SampMode (string) The sampling method the function uses to determine when to
evaluate FiltExp:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates FiltExp if SampMode
is set to interpolated. Enter a relative PI time expression
(page 56). For example, set to 10m (10 minutes) to return an
interpolated value for every 10-minute interval.
MinPctGood (number) The minimum percentage of good data required during the time
period to calculate and return a value.
conversion factor is not needed. For time-weighted total
calculations, specify a factor that converts recorded rate values to
the server default time unit (units per day).
function supports bits 2, 3, and 9 (if Mode is set to minimum,
maximum, or range).
EXAMPLE
The following function returns the time-weighted total for the PI point cdf144 calculated
from the values on the default PI Server, summing values from yesterday to today during the
time periods when the PI point cdm158 is set to Manual:
=PIAdvCalcFilVal("cdf144","y","t","'cdm158'=""Manual""","total","t
ime-weighted","compressed","10m",50,1,4,)
The function multiplies the result by 1. Because the sampling mode is compressed, the
function ignores the sampling frequency and samples the filter expression at the compressed
events of the point cdf144. The function only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of the calculated total.
98
RELATED TOPICS
PIAdvCalcExpVal()
Returns a value calculated from a performance equation during a specified time period.
SYNTAX
PIAdvCalcExpVal(Expression, STime, ETime, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)
ARGUMENTS
values for each.
value.
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
evaluate Expression:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates Expression if
SampMode is set to interpolated. Enter a relative PI time
expression (page 56). For example, set to 10m (10 minutes) to
return an interpolated value for every 10-minute interval.

Function reference
maximum, or range).
RootPath(string) The path to the data item referenced by the expression. See Data
items (page 12).
EXAMPLE
The following function returns the time-weighted total for the expression
'cdf144'+'cdt158' calculated from the values on the default PI Server, using values from
yesterday to today:
=PIAdvCalcExpVal("'cdf144'+'cdt158'","y","t","total","time-
weighted","compressed","10m",50,1,4,)
function ignores the sampling frequency and samples the filter expression at the combined
compressed events of cdf144 and cdt158. The function only returns a result if at least 50
percent of the data is good. The function returns the percent good to the right of the
calculated total.
RELATED TOPICS
PIAdvCalcExpFilVal()
Returns a filtered, calculated PI point value based on a performance equation.
SYNTAX
PIAdvCalcExpFilVal(Expression, STime, ETime, FiltExp, Mode,
CalcBasis, SampMode, SampFreq, MinPctGood, CFactor, OutCode,
RootPath)
100
ARGUMENTS
values for each.
value.
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
evaluate Expression and FiltExp:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates Expression and
FiltExp if SampMode is set to interpolated. Enter a value
and time unit. For example, set to 10m (10 minutes) to return an
interpolated value for every 10-minute interval. See Time-interval
specification (page 58).
maximum, or range).
items (page 12).

Function reference
EXAMPLE
The following function returns the time-weighted total for the expression
'cdf144'+'cdt158' calculated from the values on the default PI Server when 'productid'
= "Product2" using values from yesterday to today:
=PIAdvCalcExpFilVal("'cdf144'+'cdt158'","y","t","'productid'=
"Product2"","total","time-weighted","compressed","10m",50,1,4,)
function ignores the sampling frequency and samples the filter expression at the combined
compressed events of cdf144 and cdt158. The function only returns a result if at least 50
percent of the data is good. The function returns the percent good to the right of the
calculated total.
RELATED TOPICS
PIAdvCalcDat()
Returns evenly spaced values calculated from PI point or PI AF attribute values during a
SYNTAX
PIAdvCalcDat(DataItem, STime, ETime, Interval, Mode, CalcBasis,
MinPctGood, CFactor, OutCode, RootPath)
ARGUMENTS
calculates values. Specify a range of cells that contain PI point
names or PI AF attribute names to calculate values for each.
STime (string) The start of the time period for which the function calculates values.
ETime (string) The end of the time period for which the function calculates values.
minutes) to return a value for every 15-minute interval during the time
period. See Time-interval specification (page 58).
102
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
MinPctGood The minimum percentage of good data required during the time
(number) period to calculate and return a value.
conversion factor is not needed. For time-weighted total calculations,
specify a factor that converts recorded rate values to the server
default time unit (units per day).
supports bits 2, 3, 7, 8, and 9 (if Mode is set to minimum, maximum,
or range).
EXAMPLE
The following function returns the time-weighted total for the PI point cdf144 calculated
from the values on the default PI Server for three-hour intervals from midnight yesterday to
midnight today:
=PIAdvCalcDat("cdf144","y","t","3h","total","time-weighted",50,
1,4,)
The function multiplies the result by 1, and only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of each calculated total.
RELATED TOPICS
PIAdvCalcFilDat()
Returns evenly spaced values calculated from filtered PI point or PI AF attribute values
during a specified time period.

Function reference
SYNTAX
PIAdvCalcFilDat(DataItem, STime, ETime, Interval, FiltExp, Mode,
RootPath)
ARGUMENTS
calculates values. Specify a range of cells that contain PI point
names or PI AF attribute names to calculate values for each.
STime (string) The start of the time period for which the function calculates
values. See Time inputs (page 13).
ETime (string) The end of the time period for which the function calculates
values.
that specifies the length of the interval. For example, enter 15m
(15 minutes) to return a value for every 15-minute interval during
the time period. See Time-interval specification (page 58).
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
evaluate FiltExp:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates FiltExp if SampMode
is set to interpolated. Enter a relative PI time expression
(page 56). For example, set to 10m (10 minutes) to return an
interpolated value for every 10-minute interval.
104
function supports bits 2, 3, 7, 8, and 9 (if Mode is set to
minimum, maximum, or range).
EXAMPLE
The following function returns the time-weighted total for the PI point cdf144, calculated
from the values on the default PI Server for three-hour intervals from midnight yesterday to
midnight today when PI point cdf144 is set to Manual:
=PIAdvCalcFilDat("cdf144","y","t","3h","'cdm158'=""Manual""",
"total","time-weighted","compressed","10m",50,1,4,)
function ignores the sampling frequency and samples the filter expression at the compressed
events of cdf144. The function only returns a result if at least 50 percent of the data is good.
The function returns the percent good to the right of the calculated total.
RELATED TOPICS
PIAdvCalcExpDat()
Returns evenly spaced values calculated from a performance equation during a specified time
period.
SYNTAX
PIAdvCalcExpDat(Expression, STime, ETime, Interval, Mode,
RootPath)
ARGUMENTS
values for each.

Function reference
values.
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
evaluate Expression:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates Expression if
SampMode is set to interpolated. Enter a relative PI time
expression (page 56). For example, set to 10m (10 minutes) to
return an interpolated value for every 10-minute interval.
items (page 12).
EXAMPLE
The following function computes the expression 'cdf144'+'cdt158' at any time stamp
between midnight yesterday and midnight today with an event stored at the default PI Server,
and then calculates the time-weighted total of the computed values in three-hour intervals:
=PIAdvCalcExpDat("'cdf144'+'cdt158'","y","t","3h","total", "time-
weighted","compressed", "10m",50,1,4,)
106
The function multiplies each calculated total by 1 and returns a value when the percent of
good values is at least 50 percent during the three-hour interval. The function returns the
percent good to the right of the calculated total. Note that because the sampling mode is
compressed, the function ignores the sampling frequency, and samples values whenever a
cdf144 or cdt158 event is stored.
RELATED TOPICS
PIAdvCalcExpFilDat()
Returns evenly spaced values calculated from a filtered performance equation during a
SYNTAX
PIAdvCalcExpFilDat(Expression, STime, ETime, Interval, FiltExp,
Mode, CalcBasis, SampMode, SampFreq, MinPctGood, CFactor, OutCode,
RootPath)
ARGUMENTS
values for each.
values.

Function reference
total
minimum
maximum
stdev
range
average
count
mean
time-weighted
event-weighted
evaluate Expression and FiltExp:
compressed
interpolated
SampFreq (string) The frequency that the function evaluates Expression and
FiltExp if SampMode is set to interpolated. Enter a value
and time unit. For example, set to 10m (10 minutes) to return an
interpolated value for every 10-minute interval. See Time-interval
specification (page 58).
items (page 12).
EXAMPLE
The following function calculates a time-weighted total for the expression 'cdf144'+'
cdt158' when 'productid' = "Product2" at three-hour intervals from yesterday to
today from the default PI Server:
=PIAdvCalcExpFilDat("'cdf144'+'cdt158'","y","t","3h","'productid'=
"Product2"","total","time-weighted","compressed","10m",50,1,4,)
The function multiplies each calculated total by 1 and returns a value when the percent of
good values is at least 50 percent during the three-hour interval. The function returns the
percent good to the right of the calculated total. Note that because the sampling mode is
compressed, the function ignores the sampling frequency, and samples values whenever a
108
cdf144 or cdt158 event is stored or the value of productid changes to or from

Product2.
RELATED TOPICS
PITimeFilter()
Returns the amount of time that a performance equation evaluates to true during evenly
spaced intervals in a specified time period.
SYNTAX
PITimeFilter(Expression, STime, ETime, Interval, TimeUnit,
OutCode, RootPath)
ARGUMENTS
Expression (string) A Boolean performance equation that the function evaluates.
values for each.
values.
Interval (string) The interval between returned values. Enter a value and time
unit that specifies the length of the interval. For example, enter
15m (15 minutes) to return a value for every 15-minute interval
during the time period. See Time-interval specification (page 58).
TimeUnit (string) Time unit of the calculated result:
seconds
minutes
hours
days
function supports bits 2, 3, 7, and 8.
RootPath (string) The path to the data item referenced by the expression. See
Data items (page 12).

Function reference
EXAMPLE
The following function returns the number of seconds that the expression in cell A1 is true on
the PI Server named thevax during one-hour intervals, starting from midnight yesterday to
midnight today:
=PITimeFilter($A$1,"y","t","1h","seconds",65,"thevax")
The function shows the time stamp of the start of each calculation interval to the left of the
value.
RELATED TOPICS
Time Filtered function (page 42)
PITimeFilterVal()
Returns the amount of time that a performance equation evaluates to true during a specified
time period.
SYNTAX
PITimeFilterVal(Expression, STime, ETime, TimeUnit, OutCode,
RootPath)
ARGUMENTS
Expression (string) A Boolean performance equation that the function evaluates. See
Expressions (page 58).
Reference a range of cells that contain expressions to return values
for each.
TimeUnit (string) Time unit of the calculated result:
seconds
minutes
hours
days
items (page 12).
110
Tag functions
EXAMPLE
The following function returns the number of seconds that the expression in cell A1 is true on
the PI Server named thevax from midnight yesterday to midnight today:
=PITimeFilterVal($A$1,"y","t","seconds",0,"thevax")
RELATED TOPICS
Time Filtered function (page 42)
Tag functions
Tag functions help you work with PI tags.
PIPointIDToTag()
Returns the tag that corresponds to a specific PI point ID.
SYNTAX
PIPointIDToTag(PointID, PIServer)
ARGUMENTS
PointID (string) A PI point ID, which is a unique internal ID not reused upon deletion
of a point
PIServer (string) The PI Server that the function returns data from. If you do not select
a server or leave the field blank, the function searches the default PI
Server.
EXAMPLE
The following function searches the PI Server named thevax for point ID 123, and returns
that point's tag:
=PIPointIDToTag("123","thevax")
RELATED TOPICS
Point ID to Tag function (page 65)

Function reference
PIAttributeMaskToTag ()
Returns tags that match one or more specified PI point attribute values.
SYNTAX
PIAttributeMaskToTag(TagName, Descriptor, PointSource, PointType,
PointClass, EngUnits, OutCode, PIServer)
ARGUMENTS
TagName (string) Name of returned tags.1
Descriptor (string) Descriptor of returned tags.1
PointSource (string) Point source of returned tags.1
PointType (string) Point type of returned tags.1
PointClass (string) Point class of returned tags.1
EngUnits (string) Engineering units of returned tags.1
OutCode (integer) An output code that determines how the function orients output:
0
Write values in a column.
2
Write values in a row.
PIServer (string) The PI Server that the function returns data from. If you do not
select a server or leave the field blank, the function searches
the default PI Server.
1
Use wildcard character (*) to find all matches or matches limited to specified characters.
EXAMPLE
The following function returns the tags that start with "sin" from the PI Server named
thevax:
=PIAttributeMaskToTag("sin*","*","*","*","*","*",0,"thevax")
RELATED TOPICS
Attribute Mask to Tag function (page 66)
112
Module Database functions
Module Database functions
PIAliasToTag()
Returns the PI tag that corresponds to a specified PI alias.
SYNTAX
PIAliasToTag(Alias, ModulePath, QueryDate, OutCode, PIServer)
ARGUMENTS
Alias (string) The module database alias that corresponds to the PI tag to return.
ModulePath The full module path to the alias
(string)
QueryDate An effective date of the alias. The function returns the tag that
(integer) corresponds to the specified alias on this date.
OutCode (integer) An output code that determines whether to append the server name
to the result:
0
Returns only tag.
1
Returns the PI Server that stores the tag in the cell to the right of
the tag.
2
Returns the PI Server that stores the tag in the cell below the tag.
PIServer (string) The PI Server that the function returns data from. If you do not
select a server or leave the field blank, the function searches the
default PI Server.
EXAMPLE
The following function returns the tag that corresponds to the Temperature alias of
module Reactor1, which is a submodule of Unit1. Unit1 is at the root of the module
database for a PI Server named thevax. The module database is queried at the current time.
=PIAliasToTag("Temperature","\Unit1\Reactor1","*",0,"thevax")
RELATED TOPICS
Alias to Tag function (page 75)

Function reference
PIPropertyToValue()
Returns the value or values corresponding to a specified PI property.
SYNTAX
PIPropertyToValue(Property, ModulePath, QueryDate, PIServer,
OutCode)
ARGUMENTS
Property (string) The module database property that corresponds to the PI point for
which the function retrieves values.
ModulePath The full module path to the property.
(string)
QueryDate An effective date of the PI property value. The function returns the
(integer) values that correspond to the specified property on this date.
PIServer (string) The PI Server that the function returns data from. If you do not select
a server or leave the field blank, the function searches the default PI
Server.
OutCode (integer) An output code that determines how to orient the result:
0
Returns values in a column.
2
Returns values in a row.
EXAMPLE
The following function returns the value corresponding to the Implementer property of
module Reactor1 which is a submodule of Unit1. Unit1 is at the root of the module
database for a PI Server named thevax. The module database is queried at the current time.
=PIPropertyToValue("Implementer","\Unit1\Reactor1","*","thevax")
RELATED TOPICS
Property to Value function (page 76)
Input functions
PIPutVal() and PIPutValX()
Writes a value to PI Server or PI AF server and returns a string that indicates the status.
SYNTAX
PIPutVal(DataItem, Value, TimeStamp, RootPath, OutCell)
PIPutValX(DataItem, Value, TimeStamp, RootPath, OutCell)
114
Input functions
ARGUMENTS
DataItem (string) The name of the PI point or PI AF attribute to which the function
writes a value.
Value (reference) A reference to the cell that contains the value to be written, either
a string or a number.
TimeStamp (string) The time stamp for the value. See Time inputs (page 13).
OutCell (reference) A reference to the cell where PI DataLink writes the string that
macro function returns.
The returned string varies:
If the write succeeds, the PIPutVal function returns xxx
Written where xxx is either Real Value, Integer,
Digital State, or Value, depending on the value type
written; the PIPutValX function returns Value Written.
If the write fails, the function returns an error code such as [-
5] Tag not found.
NOTES
The PIPutVal and PIPutValX functions cannot write to PI AF attributes that are
configuration attributes. These functions can only write to a PI AF attribute for which the
Configuration Item check box is not selected. You can check the status of the check box on
the Attributes tab in PI System Explorer.
The PIPutVal and PIPutValX functions support all PI Server data types, including
string input to string tags and subsecond data. The functions interpret time stamps using client
machine time zone information for PI Server unless the Use PI Server Time Zone setting is
enabled.
The functions do not verify the user-specified range for a point before writing the value. The
range is defined as zero to zero + span, where zero and span are point attributes
specified during point creation. The function returns a value written string even if Over
Range or Under Range is stored in PI Server.
EXAMPLE
The following function writes the value located in the cell A5 in the PI Server archive on the
default PI Server for the PI point testtag with a time stamp of midnight today:
=PIPutVal("testtag",a5,"t",,e5)
The function writes the result of the macro function in cell E5 on the worksheet.

Appendix B
Troubleshooting
Consult the topics in this section if you experience difficulty using PI DataLink. If these
topics do not address or solve the problem, see Technical support and other resources (page
123) for details on contacting Technical Support.
Log files
PI DataLink does not generate a generic log file. You can use error messages in worksheets to
diagnose issues. However, some specific processes do generate log files:
Installation
The ../pipc/dat directory contains the installation log files,
SetupPIDataLink_x64.log and SetupPIDataLink_x86.log.
PI Server connectivity
Examine the PI Server log file in PI SMT for PI Server connectivity issues.
PI DataLink tab not available

If the PI DataLink tab does not appear after you install PI DataLink, you may need to
manually configure (page 6) the add-in for Excel, or reduce security settings (page 118) for
add-ins.
Some user-written VBA scripts in Excel worksheets (or add-ins) reset the main Excel ribbon.
In such cases, the PI DataLink tab may disappear even though the PI DataLink add-in is still
loaded, and embedded PI DataLink functions may work even though the PI DataLink tab
itself is not available. Restarting Excel usually fixes this problem.
Array and cell limits

PI DataLink is subject to an Excel limitation on the number of elements in a calculation array.
A single PI DataLink function can return no more than 1,048,576 values per retrieval.
The Excel SDK used by PI DataLink limits strings to 255 characters in length. Input strings
for PI DataLink expressions in a referenced cell may not exceed this 255-character limit.
Similarly, PI DataLink might truncate string output, such as PI tag strings, to 255 characters.

Troubleshooting
Data retrieval limits

Error code -11091 indicates that a single query initiated by a PI DataLink function attempted
to retrieve more events from PI Server than allowed by the ArcMaxCollect tuning
parameter.
Because this limit applies to events retrieved from the PI Server archive, even functions that
return small numbers of values can exceed the limit posed by this tuning parameter. For
example, the value of the PI point sinusoid constantly varies between 0 and 100. You
might create a function that returns sampled values of sinusoid every 30 seconds over a
year with a filter to exclude values less than 95. This function might return a relatively small
number of values, but will retrieve many more events from the archives to process the query.
If you receive this error, consider modifying your search criteria to reduce the data retrieved.
For example, you might reduce the time period over which the function retrieves data.
Data item not supported by function

The returned message "Data item not supported by function" can indicate:
A PI AF attribute uses a custom data reference that does not allow calculations. To use in
PI DataLink, change the custom-data-reference code to permit use of data-access
methods. This is disabled by default.
The Calculated Data function attempted a summary calculation on a PI AF attribute of
type PI Point Array.
Security
Excel security features for add-ins, ActiveX controls, and macros control the types of
components that can run inside Excel. The security settings either disable, enable with
prompting, or completely enable these types of objects.
Excel security settings may conflict with certain PI DataLink features:
PI DataLink is an Excel add-in. Security settings that disable add-ins prevent PI DataLink
from loading in Excel.
Trends use a signed ActiveX control marked safe for initialization and require that
ActiveX controls be enabled.
Worksheets that contain the PIPutVal or PIPutValX (page 114) function use macros and
require that macros be enabled.
If you regularly apply Excel security to worksheets, or encounter problems using these PI
DataLink features, you may need to reduce or eliminate Excel security settings depending on
how you plan to use PI DataLink.
For further information on Excel security, consult Microsoft Excel online Help and online
resources.
118
PI Server connection issues
PI Server connection issues

This version of PI DataLink uses tighter security settings for connecting to PI Server. The
new settings reduce exposure to security weaknesses associated with PI password
authentication. See the support bulletin, Security Alert: PI Authentication Weakness
(http://techsupport.osisoft.com/Bulletins/4/224a5434-ba62-41d1-83eb-244ba60da193.htm),
for more information.
The new security settings can result in errors if PI DataLink uses:
PI user names and passwords to connect to PI Server
Default user to connect to PI Server
Specifically, these settings might generate error -10407 "No Access - Secure Object" with
information about insufficient privilege to access PI Server. The settings might also generate
a message about a disabled explicit login prompt.
To resolve these errors, you can:
Configure PI mappings for users who connect to PI Server. OSIsoft recommends this
approach (available in PI Server version 3.4.380 and later). This is the most secure
connection method. See the Configuring PI Server Security guide for information on
creating PI mappings. To use PI mappings, you must also enable the Windows Security
authentication protocol on each computer that runs PI DataLink.
Configure PI trusts for users who connect to PI Server. This is the next-best approach.
See the Configuring PI Server Security guide for information on creating PI trusts. To use
PI trusts, you must also enable the PI Trust authentication protocol on each computer that
runs PI DataLink.
Configure each computer to allow an explicit login prompt when a PI mapping or PI trust
is not available. OSIsoft does not recommend this approach. Explicit logins are not
secure.
Note: Entering an incorrect password at a login prompt can result in the same error
message.
See also
Configure a computer to allow explicit login prompts (page 119)
Enable an authentication protocol (page 120)
Configure a computer to allow explicit login prompts
To connect to PI Server by logging in as a PI user, use PI SDK Utility to allow explicit login
prompts on your computer. You must configure each computer where you connect to PI
Server by logging in as a PI user.
Caution: OSIsoft recommends that you select an alternative, more secure method to
connect to PI Server.

Troubleshooting
Procedure
1. Click Start > All Programs > PI System > PISDKUtility to open PI SDK Utility.
2. Under PI-SDK, click Connections to show available PI Servers and update the utility
menus.
3. Click Connections > Options to open the Connection Options window.
4. Select the Allow login prompt (if all configured protocols fail) check box.
5. Click OK.
After you finish

A prompt will ask you for a user name and password each time you initiate a new connection
to PI Server.
Enable an authentication protocol
To connect to PI Server with a defined PI mapping or PI trust, use PI SDK Utility to enable
the corresponding protocol on your computer. You must configure each computer where you
connect to PI Server with a PI mapping or PI trust.
Procedure
1. Click Start > All Programs > PI System > PISDKUtility to open PI SDK Utility.
2. Under PI-SDK, click Connections to show available PI Servers and update the utility
menus.
3. Click Connections > Options to open the Connection Options window.
4. Under Specify Authentication Procedure, use the arrow keys to move and sort the
enabled protocols listed under Protocol order. List the needed protocols:
To use PI mappings, Windows Security must be listed. This should be the first
protocol in the Protocol order list.
To use PI trusts, PI Trust must be listed.
5. Click OK.
Cannot connect to PI OLEDB Enterprise Agent

The search error message, "Cannot connect to PI OLEDB Enterprise Agent," indicates that
the Windows service, PI OLEDB Enterprise Agent, is not running.
To clear the error, open the Services panel (such as through Administrative Tools from
Control Panel), and start the PI OLEDB Enterprise Agent service.
120
Timeout exception
Timeout exception
Searches of PI Servers with large point databases might reach the data timeout before PI
Server returns all results. You will receive the following error:
OSIsoft.PI.Net.PITimeoutException: [-10722] PINET: Timeout on
PI RPC or System Call.
To eliminate the error, use Connection Manager to increase the data timeout value:
1. On the PI DataLink tab, in the Resources group, click Settings to open the Settings
window.
2. Click Connection Manager to open the Servers window.
3. Right-click the PI Server that returned the error, and then click Properties to open the PI
Server Properties window.
4. Increase the value of the Data Timeout field, and then click OK.

Appendix C
Technical support and other resources

For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or
[email protected]. The OSIsoft Technical Support (http://techsupport.osisoft.com)
website offers additional contact options
(http://techsupport.osisoft.com/Contact+Us/Contact+Methods/Contact+Methods.htm) for
customers outside of the United States.
When you contact OSIsoft Technical Support, be prepared to provide this information:
Product name, version, and build numbers
Computer platform (CPU type, operating system, and version number)
Time that the difficulty started
Log files at that time
Details of any environment changes prior to the start of the issue
Summary of the issue, including any relevant log files during the time the issue occurred
The OSIsoft Virtual Campus (vCampus) (http://vCampus.osisoft.com) website has
subscription-based resources to help you with the programming and integration of OSIsoft
products.

Index
A D
add-ins, Excel data access 6
activating 8 data items
configuration 6 description 12
enabling 7 restrictions in expressions 60
viewing status 7 searching for 15
Advanced Calculated Data function 37 unsupported by function 118
Alias to Tag function 75 data types 3
annotations 30, 62 display formats
appended data 14 notifications 81
Archive Value function 28 number 15
arrays time 15
common tasks 47 trends 72
function 47
size 49 E
updating inputs 48 errors 117
asset-relative displays expression sampling frequency 37
creating 23 expression sampling mode 37
description 23 expressions
Attribute Mask to Tag function 66 calculation 58
automatic update data item restrictions 60
activating 51 examples 60
canceling 51 filter 60
description 50 syntax 59
average 37
F
B
filter expressions 60
backwards in time 30 functions
boundary type 30 calculation frequency 50
defining 9, 61
C descriptions 27
Calculated Data function 37 manual entry 61
calculation basis 37 modifying 48
calculation expressions 58 module database 75
calculation mode 37 overview 11
cell references 13 reference 83
cells, worksheet tag 65
function values 47 task panes 9
references 13
Compressed Data function 30 H
connections 21 high availability 5
conversion factor 37
Current Value function 27 I
inputs

Index
task pane 13 PI calculation expressions 59

time 13 PI DataLink Server 2
time interval 58 PI DataLink tab
time stamp 56 description 9
interface features 9 not available 117
PI Module Database
L accessing objects in 73
languages, alternative 5 browsing 74
legacy functions building worksheets with 73
add-in for 6 inserting objects in worksheet 74
module database 73 PI Notifications 77
tag functions 65 PI point attributes
trends 69 limiting searches with 15
returning tags for 66
M returning values of 44
PI points
Microsoft Excel search limits 15
add-in configuration 6 specifying as data item 12
security settings 118 supported data types 3
minimum percent good 37 PI SDK 2
Module Database, browse 73, 74 PI Server
move function arrays 47 collective connection preferences 5
configuration for PI DataLink 6
N limiting search to 15
notifications managing connections to 21
add-in configuration 6 PI time
add-in description 77 abbreviations 55
display format 81 description 55
inserting into worksheet 77 specifying time intervals 58
searching for 77 specifying time stamps 56
working with in worksheet 81 PIAdvCalcDat 102
number formats 15 PIAdvCalcExpDat 105
PIAdvCalcExpFilDat 107
O PIAdvCalcExpFilVal 100
PIAdvCalcExpVal 99
outcode argument 62
PIAdvCalcFilDat 103
PIAdvCalcFilVal 97
P
PIAdvCalcVal 96
percent good 37, 42, 62 PIAliasToTag 113
performance equations 58 PIArcVal 84
PI AF attributes PICompDat 88
showing values for elements 23 PICompFilDat 89
specifying as data item 12 PICurrVal 83
supported data types 3 PIExpDat 93
PI AF SDK 2 PIExpVal 85
PI AF server PINCompDat 86
adding to Notification Search function 78 PINCompFilDat 87
connections to 21 PIPropertyValue 114
limiting search to 15 PIPutVal 114
PI API 2 PISampDat 91
126
PISampFilDat 91 show annotations 30, 62
PITagAtt 85 show end time 37, 42, 62
PITimeDat 94 show min/max time 37
PITimeExpDat 95 show percent good 37, 42, 62
PITimeFilter 109 show start time 37, 42, 62
PITimeFilterVal 110 show time stamps 27, 28, 30, 34, 62
Point Access 6 show value attributes 30
Point ID to Tag function 65 silent installation 5
Property to Value function 76 single quotes
expressions 59
Q time inputs 13
quotes worksheet cells 13
arguments in function formulas 61 standard deviation 37
expressions 59 system requirements 2
time inputs 13
worksheet cells 13
T
tag functions 65
R Tag Search window 67
refresh data task panes 9
automatic 51 time display formats 15
manual 52 Time Filtered function 42
retrieval mode 28, 36 time inputs 13
right-click menu time interval 34, 37, 42, 58
trend 72 time stamps 13, 14, 56
worksheet cell 11 Timed Data function 36
root paths totals 37
drop-down list 23 trends
root paths 12 commands for 72
specifying from search 15 creating 69
description 69
S right-click menu 72
troubleshooting 117
Sampled Data function 34
search V
data items 15
limiting by browsing server 18 value attributes, show 30
limiting with path 19 volatile functions
tags in legacy functions 67 basing PI DataLink functions on 52
security Current Value function 27
Excel settings 118 triggered recalculation 51
PI Server configuration for 6
settings 19
W
setup worksheets
alternative languages 5 constructing for PI DataLink 22
Excel add-in configuration 6 PI DataLink functions in 47
installation steps 4 sharing with others 52
process overview 4
silent installation 5
system requirements 2

PI DataLink 2013 User Guide

Uploaded by

Copyright:

Available Formats

PI DataLink 2013 User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PI DataLink 2013 User Guide

Uploaded by

Copyright:

Available Formats

PI DataLink 2013

OSIsoft Australia Perth, Australia

PI DataLink 2013 User Guide

U.S. GOVERNMENT RIGHTS

Chapter 1 Introduction .................................................................................................................. 1

Chapter 3 PI DataLink functions ................................................................................................27

Chapter 4 Worksheets .................................................................................................................47

Chapter 5 Advanced topics ........................................................................................................55

PI DataLink 2013 User Guide iii

Chapter 6 Tag functions .............................................................................................................65

Chapter 7 Trends .........................................................................................................................69

Chapter 8 PI Module Database objects .....................................................................................73

Chapter 9 Notifications ...............................................................................................................77

Appendix A Function reference .................................................................................................83

Appendix B Troubleshooting ...................................................................................................117

Appendix C Technical support and other resources .............................................................123

PI DataLink 2013 User Guide 1

PI DataLink Server (DLS)

About this release

PI DataLink is backwards compatible. This version of PI DataLink can read workbooks

Supported data types

PI DataLink supports the following PI point data types:

PI DataLink 2013 User Guide 3

PI DataLink setup process

Before you begin

After you finish

View PI DataLink in a supported language

Connection preferences to PI Server collectives

If PI DataLink connects to a PI Server collective, PI DataLink sets a connection preference

PI DataLink 2013 User Guide 5

Microsoft Excel add-in configuration

PI DataLink ..\PIPC\Excel\OSIsoft.PIDataLink.UI.vsto COM Add-in

View add-in status

Check the status of an add-in to learn whether it is active, inactive, or disabled.

Enable a disabled add-in

PI DataLink 2013 User Guide 7

Activate an inactive add-in

Activate an inactive add-in to make the add-in available in Microsoft Excel.

About this document

PI DataLink inserts the PI DataLink tab in the Microsoft Excel ribbon.

Click the PI DataLink tab to access the PI DataLink commands.

Function task panes

Use function task panes to define PI DataLink functions.

PI DataLink 2013 User Guide 9

Overview of PI DataLink functions

PI DataLink 2013 User Guide 11

For inputs with edit fields , you can:

For inputs with lists , you can:

PI DataLink 2013 User Guide 13

Search for data items

Before you begin

PI DataLink 2013 User Guide 15

c. Click Search to initiate the search.

Note: Searches of PI Server return no more than 100,000 PI points. To be certain

4. If desired, change columns displayed in the results pane:

PI DataLink 2013 User Guide 17

Use the browse pane to limit the search

Use the scope path to limit the search

The scope path is at the top of the Search tool.

Manage preference settings