PI DataLink 2019

User Guide
OSIsoft, LLC
1600 Alvarado Street
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com

PI DataLink 2019 User Guide

© 1992-2019 by 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, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services,
OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API,
PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive,
PI DataLink, PI DataLink Server, PI Developers Club, PI Integrator for Business Analytics, PI Interfaces,
PI JDBC Driver, PI Manual Logger, PI Notifications, PI ODBC Driver, PI OLEDB Enterprise,
PI OLEDB Provider, PI OPC DA Server, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square,
PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services,
RLINK, and RtReports 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-19, or their successors, as applicable. OSIsoft, LLC.
Version: 5.5.0
Published: 30 January 2019
Contents

Introduction.............................................................................................................. 1
PI DataLink overview.......................................................................................................................................1
PI DataLink Server (DLS)............................................................................................................................. 2
About this release........................................................................................................................................... 2
System requirements for PI DataLink.......................................................................................................... 2
Upgrade compatibility.................................................................................................................................2
Supported data types.................................................................................................................................. 3
PI DataLink installation................................................................................................................................... 4
Install PI DataLink....................................................................................................................................... 4
Silent installation.........................................................................................................................................5
View PI DataLink in a supported language................................................................................................... 5
Connection preferences to PI Data Archive collectives.................................................................................6
PI Data Archive configuration...................................................................................................................... 6
Microsoft Excel add-in configuration............................................................................................................... 6
View add-in status....................................................................................................................................... 7
Enable a disabled add-in..............................................................................................................................8
Activate an inactive add-in.......................................................................................................................... 8
Security recommendations............................................................................................................................. 8
Excel file security......................................................................................................................................... 9
Excel add-in security.................................................................................................................................. 10
Account privileges..................................................................................................................................... 10
Organizational security practices............................................................................................................... 10
Strategies for logging................................................................................................................................ 11
About this document..................................................................................................................................... 12

Basics...................................................................................................................... 13
User interface................................................................................................................................................ 13
PI DataLink tab.......................................................................................................................................... 13
Function task panes................................................................................................................................... 14
Right-click menu........................................................................................................................................ 15
Overview of PI DataLink functions................................................................................................................. 15
Data items................................................................................................................................................. 16
Input entry................................................................................................................................................. 17
Time inputs................................................................................................................................................18
Appended data.......................................................................................................................................... 19
Display formats......................................................................................................................................... 19
Interpolated values.................................................................................................................................... 20
Searches....................................................................................................................................................... 20
Search for data items.................................................................................................................................21
Search for assets by filtering...................................................................................................................... 25
PI DataLink settings.......................................................................................................................................27
Manage PI DataLink settings from Excel.................................................................................................... 27
Time-zone-setting limitations....................................................................................................................30
Change PI DataLink settings for all users on a computer............................................................................ 30
Delete PI DataLink settings for all users on a computer.............................................................................. 31
Manage connections to servers..................................................................................................................... 32

Worksheet creation.................................................................................................. 33

PI DataLink 2019 User Guide iii

Contents

Process of creating worksheets......................................................................................................................33

Retrieval of large amounts of data................................................................................................................. 34
Asset-relative displays................................................................................................................................... 34
Create an asset-relative display..................................................................................................................35
Events in worksheets..................................................................................................................................... 37
Explore events related to an element.........................................................................................................39
Explore events with child events................................................................................................................ 42
Compare events by including child events................................................................................................. 44
Compare events by including parent events...............................................................................................50
Search for events of a specific parent event............................................................................................... 52
Reserved attribute names.......................................................................................................................... 53

PI DataLink functions............................................................................................... 55
Current Value function...................................................................................................................................55
Current Value example.............................................................................................................................. 56
Archive Value function...................................................................................................................................57
Archive Value example.............................................................................................................................. 59
Compressed Data function............................................................................................................................ 59
Compressed Data example........................................................................................................................ 62
Sampled Data function..................................................................................................................................62
Sampled Data example............................................................................................................................. 64
Timed Data function......................................................................................................................................65
Timed Data example................................................................................................................................. 66
Calculated Data function............................................................................................................................... 67
Calculated Data example........................................................................................................................... 71
Time Filtered function................................................................................................................................... 72
Time Filtered example............................................................................................................................... 74
Explore Events function................................................................................................................................. 74
Explore Events task-pane reference........................................................................................................... 75
Explore Events example.............................................................................................................................79
Compare Events function.............................................................................................................................. 79
Compare Events task-pane reference........................................................................................................ 80
Path notation for Compare Events function...............................................................................................84
Compare Events example.......................................................................................................................... 84
Asset Filter Search function........................................................................................................................... 85
Properties function........................................................................................................................................85
Properties example.................................................................................................................................... 87

Worksheet usage and maintenance........................................................................... 89

Function arrays............................................................................................................................................. 89
Common function array tasks....................................................................................................................90
Update inputs to a function array.............................................................................................................. 90
Array size...................................................................................................................................................91
Resize arrays..............................................................................................................................................91
Calculation frequency....................................................................................................................................92
Automatic Update feature.........................................................................................................................92
Triggered recalculation.............................................................................................................................. 93
Recalculate manually.................................................................................................................................94
Worksheet sharing........................................................................................................................................ 94
Set Workbook Calculation option to manual..............................................................................................95

Advanced topics...................................................................................................... 97
PI time........................................................................................................................................................... 97

iv PI DataLink 2019 User Guide

 Contents

PI time abbreviations................................................................................................................................. 97
PI time expressions....................................................................................................................................98
Time-stamp specification.......................................................................................................................... 98
Time-interval specification........................................................................................................................ 99
Expressions................................................................................................................................................. 100
Use expressions in PI DataLink functions..................................................................................................101
Expression syntax.................................................................................................................................... 101
Expressions in Excel cells..........................................................................................................................102
Cell references in expressions.................................................................................................................. 102
Restrictions on data items in expressions................................................................................................. 104
Expression examples................................................................................................................................104
Filter expressions..................................................................................................................................... 105
Manual function entry..................................................................................................................................105
Define functions manually....................................................................................................................... 105
Guidelines for entering arguments manually............................................................................................105
Output codes........................................................................................................................................... 106
Functions to write data................................................................................................................................ 108
Write data to PI Data Archive or PI AF......................................................................................................108

Tag functions......................................................................................................... 111

Point ID to Tag function................................................................................................................................111
Point ID to Tag example........................................................................................................................... 112
Attribute Mask to Tag function.................................................................................................................... 112
Attribute Mask to Tag example.................................................................................................................113
Search for PI points...................................................................................................................................... 113

Trends................................................................................................................... 115
Create a trend.............................................................................................................................................. 115
Create a trace of values in the worksheet..................................................................................................117
Create a trace of PI point values retrieved from PI Data Archive............................................................... 117
Trend right-click menu................................................................................................................................. 118

PI Module Database objects.................................................................................... 119

PI Module Database and worksheets........................................................................................................... 119
Insert PI Module Database objects into your worksheet............................................................................... 119
Module database functions..........................................................................................................................120
Alias to Tag function................................................................................................................................ 121
Property to Value function....................................................................................................................... 121

Function reference.................................................................................................. 123

Single-value functions..................................................................................................................................123
PICurrVal()............................................................................................................................................... 123
PIArcVal()................................................................................................................................................ 124
PIExpVal()................................................................................................................................................ 125
PITagAtt()................................................................................................................................................ 126
Multiple-value functions.............................................................................................................................. 127
PINCompDat()......................................................................................................................................... 127
PINCompFilDat()..................................................................................................................................... 128
PICompDat()............................................................................................................................................129
PICompFilDat()........................................................................................................................................ 130
PISampDat()............................................................................................................................................ 132
PISampFilDat()......................................................................................................................................... 133

PI DataLink 2019 User Guide v

Contents

PIExpDat()................................................................................................................................................134
PITimeDat()............................................................................................................................................. 135
PITimeExpDat()....................................................................................................................................... 136
Calculation functions................................................................................................................................... 136
PIAdvCalcVal()..........................................................................................................................................137
PIAdvCalcFilVal()......................................................................................................................................138
PIAdvCalcExpVal()................................................................................................................................... 140
PIAdvCalcExpFilVal()................................................................................................................................141
PIAdvCalcDat()........................................................................................................................................ 143
PIAdvCalcFilDat().....................................................................................................................................145
PIAdvCalcExpDat().................................................................................................................................. 146
PIAdvCalcExpFilDat()...............................................................................................................................148
PITimeFilter()........................................................................................................................................... 150
PITimeFilterVal()...................................................................................................................................... 151
Tag functions reference............................................................................................................................... 152
PIPointIDToTag()......................................................................................................................................152
PIAttributeMaskToTag ().......................................................................................................................... 153
Module database functions reference.......................................................................................................... 154
PIAliasToTag()..........................................................................................................................................154
PIPropertyToValue().................................................................................................................................155
Input functions.............................................................................................................................................155
PIPutVal() and PIPutValX()....................................................................................................................... 156
Deprecated functions...................................................................................................................................157

Troubleshooting..................................................................................................... 159
Log files....................................................................................................................................................... 159
PI DataLink tab not available....................................................................................................................... 159
Array and cell limits..................................................................................................................................... 160
Data retrieval limits..................................................................................................................................... 160
Data item not supported by function........................................................................................................... 160
Duplicate event exists..................................................................................................................................160
Security....................................................................................................................................................... 161
PI Data Archive connection issues................................................................................................................ 161
Enable an authentication protocol........................................................................................................... 162
Configure a computer to allow explicit login prompts.............................................................................. 162
Enter login credentials from Connection Manager................................................................................... 163
Eliminate timeout exception error............................................................................................................... 163
Data does not update.................................................................................................................................. 164

Technical support and other resources..................................................................... 165

vi PI DataLink 2019 User Guide

Introduction
Welcome to PI DataLink! This section provides an overview of PI DataLink, describes features
of this release, and discusses installation and configuration.

Topics in this section

• PI DataLink overview
• About this release
• PI DataLink installation
• Microsoft Excel add-in configuration
• Security recommendations
• About this document

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 Data Archive 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
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 (DLS), a separate product
that lets you view worksheets created with PI DataLink.
Contact your OSIsoft sales representative for more information.

PI DataLink 2019 User Guide 1

Introduction

PI DataLink Server (DLS)

PI DataLink Server is a server version of PI DataLink. 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 Data Archive 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

Topics in this section describe system requirements, upgrade compatibility with previous
releases, and supported data types.

Topics in this section

• System requirements for PI DataLink
• Upgrade compatibility
• Supported data types

System requirements for PI DataLink

For up-to-date system requirements, see the OSIsoft Tech Support page PI DataLink System
Requirements (https://techsupport.osisoft.com/Products/PI-Visualization/PI-DataLink/
System-Requirements).

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.
This version of PI DataLink uses PI AF SDK. PI DataLink 2010 and earlier versions used either
PI SDK or PI API. Different behaviors might require you to change existing worksheets that you
created with PI DataLink 2010 or earlier versions:

2 PI DataLink 2019 User Guide

 Introduction

• Returned error messages might differ. You might need to change worksheets that look for
certain strings (for example, in Excel VBA code or macros).
• 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 Data Archive 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 Data Archive.
The 64-bit version of PI DataLink 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.

PI DataLink 2019 User Guide 3

Introduction

PI DataLink installation
Before you 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 languages other than English. In addition, you need to
consider your PI Data Archive configuration and ensure that you have proper access to PI
points.

Topics in this section

• Install PI DataLink
• Silent installation
• View PI DataLink in a supported language
• Connection preferences to PI Data Archive collectives
• PI Data Archive configuration

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. The setup
program does not install the PI DataLink (Legacy) add-in, even when upgrading from a
previous installation that had the add-in enabled, unless you modify the setup.ini file.

Procedure
1. Find the setup kit. You can:
◦ Download the kit from the OSIsoft Tech Support Downloads page (https://
techsupport.osisoft.com/Downloads/All-Downloads/).
You can filter the Downloads page to show installation kits.
◦ Insert the distribution CD.
2. Extract the files to your computer.
3. If needed, modify the setup.ini file to do the following:
◦ Install one version of PI DataLink (32-bit or 64-bit).
◦ Install and activate the PI DataLink (Legacy) add-in (for the 32-bit version of PI DataLink
in 32-bit Microsoft Office). The PI DataLink (Legacy) add-in is required to use tag
functions, module database functions, or trends.
Caution:
The PI DataLink (Legacy) add-in uses older technologies, such as ActiveX, that have
known security risks. ActiveX controls can have unrestricted access to your
computer and therefore can access your local file system and change your
operating-system-registry settings. If a hacker uses an ActiveX control to take over
your computer, the damage can be significant.

4 PI DataLink 2019 User Guide

 Introduction

To modify the setup.ini file, follow the example in the file.

4. 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 the
OSIsoft Tech Support Downloads page (https://techsupport.osisoft.com/Downloads/All-
Downloads/).

After you finish

• To change the default PI DataLink settings, see Change PI DataLink settings for all users on a
computer.
• To view PI DataLink in a language other than English, install the PI DataLink MUI Language
Pack. See View PI DataLink in a supported language.

Silent installation
You can install this software 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 installation, 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 silent.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.
b. Use the Microsoft Office language setting tool to change the language of Microsoft Excel.
2. Download the PI DataLink MUI language pack from the OSIsoft Tech Support Downloads
page (https://techsupport.osisoft.com/Downloads/All-Downloads/).
3. Install the PI DataLink MUI language pack.

PI DataLink 2019 User Guide 5

Introduction

Connection preferences to PI Data Archive collectives

If PI DataLink connects to a PI Data Archive 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 Prefer
Primary or to the setting in PI System Explorer, if set differently. For information on setting
the preference in PI System Explorer, see the PI Server topic "Manage connection
preferences for PI System Explorer" in Live Library (https://livelibrary.osisoft.com).
• 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.

PI Data Archive configuration

PI DataLink can retrieve data from PI Data Archive 3.4.380 and later. However, PI DataLink
must be able to connect to the proper PI Data Archive server and users must have proper
access to points. This might require configuration changes for:

• Firewall database
The firewall database on each PI Data Archive 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 Data Archive
and have access to PI Data Archive. Assign users the least-privileged access possible, such as
read-only permissions. For authentication, OSIsoft recommends that you use PI mappings
(available in PI Data Archive 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 Data Archive documentation, including the PI Server topic
"PI Data Archive security" in Live Library (https://livelibrary.osisoft.com).

Microsoft Excel add-in configuration

PI DataLink has application add-ins to Microsoft Excel.

6 PI DataLink 2019 User Guide

 Introduction

Note:
The procedures in this add-in section refer to configuring a local copy of the Microsoft Excel
application.

Name Location Type

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

The setup program always installs the PI DataLink add-ins. To have the setup program also
install the PI DataLink (Legacy) add-in, modify the setup.ini file, following the example in
the file.
To use all PI DataLink features, these application add-ins must be active. The setup program
always activates the PI DataLink add-in.
The setup program installs and activates the PI DataLink (Legacy) add-in if you modified the
setup.ini file to do so. The add-in must be active 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.

See also
Tag functions
PI Module Database objects
Trends

Topics in this section

• View add-in status
Check the status of add-ins to learn whether they are active, inactive, or disabled.
• Enable a disabled add-in
You must enable disabled add-ins before you can make them active.
• Activate an inactive add-in
Activate inactive add-ins to make them available in Microsoft Excel.

View add-in status

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

PI DataLink 2019 User Guide 7

Introduction

Procedure
1. Click the File tab and then click 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 one of the following:
◦ 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
1. Click the File tab and then click Options.
2. On the Excel Options window, click Add-Ins.
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.

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
1. Click the File tab and then click Options.
2. On the Excel Options window, click Add-Ins.
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.

Security recommendations
Your PI System might store sensitive data that you want to protect. OSIsoft designs its products
to minimize the risk of unauthorized access. Topics in this section describe the recommended
practices to maximize data security when working with PI DataLink.

8 PI DataLink 2019 User Guide

 Introduction

Topics in this section

• Excel file security
• Excel add-in security
• Account privileges
• Organizational security practices
• Strategies for logging

Excel file security

Excel workbooks can contain sensitive data that must be protected when residing on a client
computer. The underlying security offered by the PI System is not applicable after retrieving
the information into a worksheet. Therefore, OSIsoft recommends that you secure each
workbook file. You can:
• Secure your Excel workbook files with passwords. Passwords will allow only authorized
users to view or modify any data in the workbook. For more information, see the Microsoft
Office article Protect a workbook (https://support.office.com/en-us/article/Protect-a-
workbook-7e365a4d-3e89-4616-84ca-1931257c1517).
• Use the most secure practices for setting workbook passwords:
◦ Set a password to open the workbook and a password to modify the workbook.
◦ Use a mix of uppercase and lowercase letters, numbers, and symbols in your passwords.
◦ Select the Encrypt document properties check box to prevent unauthorized users from
viewing summary and custom file properties of the workbook.
• Enable Information Rights Management (IRM) on your Excel workbooks. IRM lets
individuals and administrators specify workbook access permissions, which can help to
prevent unauthorized people from printing, forwarding, or copying sensitive PI System data.
After you restrict the permission for a file with IRM, the access and usage restrictions are
enforced regardless of where the information is because the access permission is stored in
the file itself. For more information, see the Microsoft Office article Information Rights
Management in Office 2010 (http://office.microsoft.com/en-us/excel-help/information-
rights-management-in-office-2010-HA010354260.aspx). If required, you can set an
expiration date for the data in the Excel file. In the Microsoft Office article, see the procedure
Set an expiration date for a file (http://office.microsoft.com/en-us/excel-help/information-
rights-management-in-office-2010-HA010354260.aspx#BMexpire).
• Use Internet Protocol Security (IPSec) encryption on the link between computers that host
PI DataLink and file stores that contain Excel workbooks if storing Excel workbooks on
remote drives. For more information, see the Microsoft TechNet article What Is IPSec
(https://technet.microsoft.com/library/cc776369.aspx).
• Apply secure file permissions on your Excel workbooks to ensure that unauthorized users
do not have access to the contents of the files. For more information, see the Microsoft
TechNet article File and Folder Permissions (http://technet.microsoft.com/en-us/library/
bb727008.aspx).
• Apply a digital signature to the Excel workbook file. For more information, see the Microsoft
Support article Description of digital signatures and code signing in workbooks in Excel
(http://support.microsoft.com/kb/820738).

PI DataLink 2019 User Guide 9

Introduction

Excel add-in security

You use the Excel Trust Center to control the behavior of add-ins. To prevent unauthorized
software from acting on your Microsoft Excel worksheets, OSIsoft recommends that you
require add-ins to be signed by trusted publishers. Specifically, in the Trust Center, use the Add-
ins page to do the following:
• Require application add-ins to be signed by trusted publishers.
• Disable notification for unsigned add-ins.
If you install PI DataLink outside of the standard C:\Program Files directory and you
require add-ins to be signed by trusted publishers, then you must manually add the PI
DataLink certificate to the store of trusted certificates. See Add PI DataLink certificate to store
of trusted certificates.
For more information, see the Microsoft Office article View, manage, and install add-ins in
Office programs (http://office.microsoft.com/en-us/excel-help/view-manage-and-install-add-
ins-in-office-programs-HA010354315.aspx).

Add PI DataLink certificate to store of trusted certificates

If you configure Microsoft Excel to require add-ins to be signed by a trusted publisher and you
install PI DataLink outside of the standard C:\Program Files directory, then you must
manually add the PI DataLink certificate to the store of trusted certificates.

Procedure
1. Open a command window as administrator.
2. From a command prompt, navigate to the directory that contains the PI DataLink certificate
(pidlcert.cer).
You can find the certificate in the Excel subfolder of the installation folder (defined by the
PIHOME environment variable).
3. Enter the following command:
C:\Windows\System32\certutil.exe -addstore TrustedPublisher
pidlcert.cer

Account privileges
To avoid damage from malicious users, assign users the least-privileged access possible, such
as read-only permissions.

Organizational security practices

To prevent attackers from gaining access to the system, OSIsoft recommends that your
organization adopt thorough security practices:

10 PI DataLink 2019 User Guide

 Introduction

• Physically secure your computers. Attackers who gain access to computers that run PI
DataLink could gain access to all PI System data retrieved and stored in Excel files on that
computer.
• Restrict computer access to authorized employees and guests. Procedures should prevent
lost or stolen computers from accessing the company network.
• Apply the most recent security updates to all computers. Subscribe to the Security
Notification service to stay informed about new security updates for operating systems and
other components. For more information, see the Microsoft TechNet article Microsoft
Technical Security Notifications (http://technet.microsoft.com/en-us/security/dd252948).
• Protect against unauthorized administrators. Unauthorized administrators can launch
numerous attacks. For example, they might do the following:
◦ Install and run malicious software.
◦ Configure remote access to take remote control of a computer.
• Audit all administrative activity and routinely review the audit logs. Require all
administrators to undergo a background check before hiring and periodic rechecks as a
condition of employment.
• Provide multiple layers of security. Relying solely on perimeter security, such as firewalls,
increases risks if the firewall is compromised. You can provide another layer of defense by
designing your network to isolate less secure clients from more secure clients. Personal
firewalls on client computers add an additional layer. Enhance security further with
intrusion-detection software and host-based intrusion-detection software that helps filter
out suspicious activity; running antivirus software is essential. Finally, educating users
about computer security is a critical part of a network security strategy.
• Create and maintain secure baselines for all systems. Specify each baseline with a detailed
description of how to configure and administer the computer. The description must include
all relevant configuration settings for a secure computer. To create a secure baseline, use the
most secure operating system possible. More recent operating systems are more likely to be
designed with security in mind and to contain features that make the operating system
secure. Keep the operating system and applications up-to-date by applying security updates
as they become available.
• Use strong passwords or passphrases. Never use blank passwords. For more information
about password concepts, see the Microsoft TechNet article Account Policies (https://
technet.microsoft.com/en-us/library/dd349793(v=ws.10).aspx).
• Control access to PI DataLink Excel files. Implement access-control procedures to ensure
that all Excel files are stored securely and that attackers cannot modify the file contents or
search for information within the file.

Strategies for logging

Organizations need to develop an appropriate strategy for logging. You can use log files for:
• Tracking. You might use log files to provide statistical data about transactions.
• Verification. You might use log files to provide a full record of transactions to recreate the
transactions.
• Proving the validity of a transaction.

PI DataLink 2019 User Guide 11

Introduction

PI DataLink sends all data requests through the PI AF SDK. Though PI DataLink maintains no
separate log files, you can use PI AF SDK and PI Data Archive log files to get information about
PI DataLink transactions. Consult the PI AF SDK and PI Data Archive documentation for more
information.

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
Data Archive and PI AF documentation for more information about those products. Knowledge
of PI Data Archive 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 Tech Support Downloads page (https://techsupport.osisoft.com/Downloads/All-
Downloads/). You can also view documentation in Live Library (https://
livelibrary.osisoft.com).

Terminology change
OSIsoft is revising its terminology to reflect the growth of the PI System from its original single-
server architecture. In the revised terminology, PI Data Archive refers to the component that
stores time-series data (formerly called PI Server), and PI Server refers to both PI Data Archive
and PI Asset Framework. This document uses the revised terminology.

12 PI DataLink 2019 User Guide

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

Videos
To learn about PI DataLink, you can also watch the PI DataLink playlist on the OSIsoft Learning
YouTube channel:
https://www.youtube.com/playlist?list=PLMcG1Hs2Jbcs_qbRKOvGo9T5xWc0oBlF_

Topics in this section

• User interface
• Overview of PI DataLink functions
• Searches
• PI DataLink settings
• Manage connections to servers

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.

Topics in this section

• PI DataLink tab
• Function task panes
• Right-click menu

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

PI DataLink 2019 User Guide 13

Basics

• 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.

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 of task panes if you prefer. See Manage PI DataLink
settings from Excel.
• 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:

14 PI DataLink 2019 User Guide

 Basics

◦ 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 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.

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 Data Archive 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
Function task panes

Overview of PI DataLink functions

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

PI DataLink 2019 User Guide 15

Basics

See also
Function task panes
Manual function entry

Topics in this section

• Data items
• Input entry
• Time inputs
• Appended data
• Display formats
• Interpolated values

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 evaluates 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 Data Archive 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 Data Archive 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 Data Archive server that stores the point or a blank to indicate the default
PI Data Archive server. Valid entries include:
• MyPIDataArchiveServer
• \\MyPIDataArchiveServer

16 PI DataLink 2019 User Guide

 Basics

Type of data item Content of root-path field

PI AF attribute PI AF server and database along with any elements, subelements, and parent
attributes not specified in Data item. Valid entries include:
• \\MyPIAFServer\MyDatabase
• \\MyPIAFServer\MyDatabase\MyElement
• \\MyPIAFServer\MyDatabase\MyElement\MySubElement
• \\MyPIAFServer\MyDatabase\MyElement|MyParentAttribute
• \\MyPIAFServer\MyDatabase\MyElement|MyParentAttribute1|
MyParentAttribute2
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

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)
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 the edit field to open a list of valid values that you can select from (only available for
the Root path and Database fields).
• Click to open the Search tool, and then select data items found in a search of a
connected PI Data Archive 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:

PI DataLink 2019 User Guide 17

Basics

• Enter the string for the point name.

• Click to open the Search tool, and search the PI Data Archive 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
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 a valid PI time expression. Expressions can include fixed times, reference-time
abbreviations, and time offsets. Use fixed times, such as 10-Dec-16 19:12 to always
retrieve data from a certain date, and use reference-time abbreviations and time offsets,
such as t and -3h, to retrieve data relative to the current time.
• A time offset entered alone in an End time input specifies a time relative to the Start time
input.
• A time offset entered alone in a Start time or Time stamp input specifies a time relative to
the current time.
• 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.

18 PI DataLink 2019 User Guide

 Basics

See also
Time-stamp specification
Time-interval specification

Appended data
PI DataLink can append information about the values retrieved. This appended data can
provide context to retrieved values. Appended data can include:
• Time stamps that show when values were recorded
• 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 annotations
• Source server names
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 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.
For details on the Settings window, see Manage PI DataLink settings from Excel.
You can also apply individual number and time formats to any worksheet cell, including those
containing PI DataLink functions, with the Format Cells window. See your Excel documentation
for more information on formatting numbers and times. PI DataLink overwrites or applies
individual cell formats as follows:

PI DataLink 2019 User Guide 19

Basics

• When writing a function array after you click OK or Apply on a task pane, PI DataLink
overwrites any individual number or time formats applied to a cell in the function array
with the settings from the Settings window.
• When writing a function array after you right-click a function array and then click
Recalculate (Resize) function, PI DataLink finds the top-left cell in the array with a number
format and applies that format, either an individual format or the format from the Settings
window, to all array cells with number formatting. Similarly, PI DataLink finds the top-left
cell in the array with a time format and applies that format, either an individual format or
the format from the Settings window, to all array cells with time formatting.

Interpolated values
Many PI DataLink functions can return interpolated values, useful for PI points associated with
time stamps. For example, you might request that the Archive Value function return an
interpolated value at a particular time stamp rather than the last recorded value that precedes
the time stamp. The interpolated value depends on the time stamps of the recorded values and
possibly on the type of PI point:
• For time stamps before the first recorded value, the function returns either Pt Created or
No Data.
• For time stamps between two recorded values, the function determines the value at the
time stamp using linear interpolation between the recorded values. For points that store
discrete values, such as digital state points or step points, the function returns the last
recorded value that precedes the time stamp.
• For time stamps after the last recorded value, the returned value depends on the point type:
◦ For historical PI points, the function returns the most recent value.
◦ For future PI points, the function returns No Data.

Searches
PI DataLink offers two ways for you to search for data items:

• Search tool
With the Search tool, you can find PI points or PI AF attributes, either by searching for
matching text or by exploring a PI Data Archive or a PI AF database. Depending on how you
open the tool, it inserts the found points or attributes into your worksheet or into a function
task pane.

• Asset Filter Search function

With the Asset Filter Search function, you can find PI AF elements that match a criteria, and
filter those elements based on attribute values. The function can return the filtered
elements or selected attributes of the filtered elements. The function can paste the filtered
assets into your worksheet as values or as a function array.

Topics in this section

• Search for data items
• Search for assets by filtering

20 PI DataLink 2019 User Guide

 Basics

Search for data items

Use the Search tool to search any specified PI Data Archive 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 start

Connect to any PI Data Archive server or PI AF server that you want to search. See Manage
connections to servers.

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.
Upon first use, the tool starts at the Home node, which shows all the PI Data Archive servers
(indicated by ) and PI AF servers (indicated by ) listed in Connection Manager. You
must limit the search to a single PI Data Archive server or single PI AF server, and can limit
the search further to a single database on a PI AF server, and then to specific elements and
parent attributes.
Upon subsequent uses, the tool starts each session with the search scope set to the last PI
Data Archive server, PI AF server, or PI AF database that you searched.
You can:
◦ Use the browse pane to limit the search
◦ Use the scope path to limit the search
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.
You can use wildcard characters to augment your search. For example:
▪ Type sinusoid to find all data items named sinusoid.
▪ Type sinusoid* to find any data items that start with "sinusoid" such as sinusoid or
sinusoidu.
▪ Type *u to find any data items that end with "u" such as sinusoidu.
▪ Type * to find all data items.
b. If your search scope is a PI Data Archive server, set the lists and fields under Filters to
specify any additional criteria the retrieved PI points must match.

PI DataLink 2019 User Guide 21

Basics

The Quick Filters list at the upper-right corner of the pane contains predefined common
searches. You can select a predefined search, and the Search tool automatically populates
the lists and fields for that search.
The pane has six lists that contain built-in and system-assigned point attributes,
attributes from the base and classic point classes, and virtual attributes for the point
value, time stamp, and status (Is good). Select an attribute from a list and specify criteria
for that attribute. You can enter wildcard characters; the search does not add any implicit
wildcard characters.
The final list contains point types. Select the type of stored value you want to find.
For example, select Descriptor and then enter *vapor* to return only PI points that
contain the word vapor anywhere in the descriptor point attribute
For more information about PI point attributes, see the PI Server topic "Point classes and
attributes" in Live Library (https://livelibrary.osisoft.com).
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 that match.
▪ PI AF attributes with names that match.
▪ PI AF attributes with descriptions that match (if you are using PI AF Server 2015 or
later)
▪ PI AF attributes that have parent elements with names, descriptions, categories, or
templates that match.
Note:
Searches of PI Data Archive 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 Data item length slider to split the path of the data item between the
Root path and Data item columns:
◦ Select Full path to specify a full path in the Data item column.
◦ Select Name only 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 PI AF attributes into the worksheet and you split the data-item content, specify
how to insert the Root path content into the worksheet:

22 PI DataLink 2019 User Guide

 Basics

◦ 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 ALL of your worksheet. If that
column contains data, PI DataLink inserts the paths in the next available column to
the right.
◦ Select Column or row to insert the content from the Root path and Data item columns
into the designated worksheet cells.
In this case, PI DataLink always inserts the Root path content in the first worksheet
column and the Data item content in the second worksheet column.
7. Select the items that you want to insert and click OK.

See also
Create an asset-relative display

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 Data Archive server
(indicated by ), the browse pane shows filters that you can use to limit retrieved PI
points based on attribute values.
◦ 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.

PI DataLink 2019 User Guide 23

Basics

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.

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 navigate to the Home node. At the Home node, the browse pane shows all
the PI Data Archive servers and PI AF servers listed in Connection Manager. You cannot
search at the Home node. The broadest scope for searching is either a single PI Data
Archive server or single PI AF server.
◦ 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.

24 PI DataLink 2019 User Guide

 Basics

Search for assets by filtering

Use the Asset Filter Search function to search a PI AF database for elements and to filter the
returned elements by attribute value. You can choose to output either the filtered elements or
selected attributes of the filtered elements. You can also choose whether to paste the output
into the worksheet as static values or as a function array, which can update automatically.

Procedure
1. Select the upper leftmost cell of the range in the worksheet where you want to insert
retrieved assets.
2. On the PI DataLink tab, in the Search group, click Asset Filter to open the Asset Filter Search
task pane.
3. In the Root path field, enter the common path to the elements you want to find.
The common path must contain the server and database, and can contain any parent
elements. Specify in the format \\ServerName\DatabaseName\ParentElementName.
For example, to find elements at the root level of the database MyDatabase on the server
MyPIAFServer, enter \\MyPIAFServer\MyDatabase; to find elements under the Boilers
element in that same database, enter \\MyPIAFServer\MyDatabase\Boilers.
4. Specify the PI AF elements to retrieve:
a. From the Element template list, select the template of retrieved elements.
You must select a template to filter elements based on attribute values. Note that if you
select a base template, the function also retrieves elements from derived templates.
b. In the Element name field, enter the name of elements to retrieve. Use wildcard
characters to specify part of the name.
c. From the Element category list, select the category of elements to retrieve.
d. In the Element description field, enter text found in the description of all elements to
retrieve. Use wildcard characters to specify part of the description.
e. Select the Limit to root level check box to only retrieve elements at the level specified in
the Root path field. Clear the check box to retrieve child elements as well.
f. Optional: In the Attribute value filters table, specify conditions for the attribute values of
elements to retrieve.
You must select an element template before specifying any attribute-value condition. You
can only filter using values of attributes defined in the selected element template or in a
base template of the selected element template.
You can specify up to five conditions. For each condition, set three fields:
▪ From the Attribute list, select an attribute found in elements based on the selected
element template.
▪ From the Operator list, select the relational operator, such as =, <, or >. For attributes
that store string, Boolean, or enumerated values, the only valid operators are = and <>.
▪ In the Value field, enter the value to filter for. You can use wildcard characters for
string attributes.

PI DataLink 2019 User Guide 25

Basics

For example, to retrieve elements that have the Manufacturer attribute that starts with
ABC and a ZipCode attribute between and including 94102 and 94188, enter three
conditions:
Manufacturer = ABC*
ZipCode >= 94102
ZipCode <= 94188
For best performance, limit attributes to those that have values stored in the PI AF
database (that is, omit attributes with data references). If you specify an attribute with a
data reference, the function uses the preference setting for maximum filter search count
to limit the number of elements searched for matching attribute values. See Manage PI
DataLink settings from Excel.
5. Specify the worksheet output:
a. From the Attributes to display list, select the attributes to include and set the order to
display the attributes.
If you select no attributes, the Asset Filter Search function only returns the matching
elements. If you select at least one attribute, the function returns the selected attributes
for each element.
By default, the list includes the attributes in the selected element template. You can:
▪ Select the Select all check box to include all the listed attributes.
▪ Select a check box to include an attribute, or clear a check box to exclude an attribute.
▪ Type the name of an attribute next to the blank check box at the bottom of the list.
▪ Select an attribute and click to move the attribute up in the list of displayed
attributes.
▪ Select an attribute and click to move the attribute down in the list of displayed
attributes.
▪ Select an attribute and click to remove the attribute from the list of displayed
attributes.
b. Indicate how to paste the matching elements or attributes into the worksheet:
▪ Click Column to insert the full path to the elements or attributes into the designated
worksheet cells.
▪ Click Drop-down list to insert a drop-down list that contains the paths to the
attributes (that is, the unique server, database, and parent elements) followed by the
selected attributes into the designated worksheet cells.
Only select Drop-down list if you have selected at least one attribute.
From another PI DataLink function, you can reference the inserted drop-down list
from a Root path field and the attributes from a Data item field to create an asset-
relative display: the worksheet will dynamically update the retrieved values when you
select a different path in the list. See Asset-relative displays.
c. Indicate the output format:

26 PI DataLink 2019 User Guide

 Basics

▪ Click Function array to paste a function array. This is the output format of other PI
DataLink functions. With a function array, you can easily update the inputs from the
task pane and recalculate the output.
▪ Click Values to paste the output as values. You can easily copy values for use
elsewhere.
Tip:
Function arrays are particularly useful when the function results change frequently.
However, function-array recalculation, which occurs each time you open a
worksheet, can be slow. By contrast, values are useful when you do not expect
results to change and do not want to wait for function-array recalculation.
d. Verify that the Output cell field contains the upper leftmost cell of the range in the
worksheet where you want to insert returned assets.
6. Click OK to insert the matching elements or attributes into the worksheet and close the task
pane.

PI DataLink settings
Settings control many PI DataLink behaviors, including the time and number formats, the time
zones returned, the strings that functions return, when the task pane opens, and how search
results are pasted. Each person on a computer has individually saved settings. Users can view
and change these settings directly from Excel.
PI DataLink retrieves the settings from the OSIsoft.PIDataLink.xml file, saved in each
user's AppData directory:
%UserProfile%\AppData\Local\OSIsoft,_Inc\PIDataLink
Administrators can change the settings for all users on a particular computer or delete the
settings for all users on a particular computer.

Topics in this section

• Manage PI DataLink settings from Excel
• Time-zone-setting limitations
• Change PI DataLink settings for all users on a computer
• Delete PI DataLink settings for all users on a computer

Manage PI DataLink settings from Excel

Use the Settings window to specify global preferences and default output formatting for PI
DataLink functions. These settings apply to a particular user on a particular computer. From
this window, you can also clear the cache of configuration data for PI points and non-time-
based data from PI AF.

Procedure
1. On the PI DataLink tab, in the Resources group, click Settings.
2. To clear the PI DataLink cache manually, click Clear Cache.

PI DataLink 2019 User Guide 27

Basics

By default, PI DataLink caches configuration data for PI points and non-time-based data
from PI AF (that is, data other than PI point data references and events). This cache
improves performance. Before calculating a function, PI DataLink checks when the cache
was last cleared; if the cache has not been cleared within the last six hours, PI DataLink
automatically clears the cache. To clear the cache and obtain updated data sooner, clear the
cache manually.
3. To update settings, enter the preferred setting and click OK.
Setting Description
Copy PI Data Archive name Select to paste the name of the PI Data Archive data source into an
(Legacy add-in only) adjacent worksheet cell when you insert PI point names from tag
functions into a worksheet.
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 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 Select to turn off the automatic opening of the function task pane
display on click when you click a function cell.
Disable "Resize to show all Select to display no warning message when a recalculation returns
values" message more values than a function array can show.
Client time zone Select to interpret the input time stamps and display output time
stamps in the client-workstation time zone. Some functions will
display certain time stamps in the PI Data Archive server time
zone. See Time-zone-setting limitations for these exceptions.
PI Data Archive time zone Select to interpret the input time stamps and display output time
stamps in the PI Data Archive server time zone. This setting only
applies to data items or expressions that contain either a PI point
or a PI AF attribute that is a PI point data reference. If 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 Data Archive server has a time-
zone setting different from the client workstation.
UTC time zone Select to interpret the input time stamps and display output time
stamps in coordinated universal time (UTC). Some functions do
not support this setting. See Time-zone-setting limitations for
details about these exceptions.
In a row Select to paste multiple results from a search into a row of values
in the worksheet.
In a column Select to paste multiple results from a search into a column of
values in the worksheet. Default value.

28 PI DataLink 2019 User Guide

 Basics

Setting Description
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).
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.
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.
Maximum event count Enter the maximum number of events that the Explore Events and
Compare Events functions return to the preview and to the
worksheet.
Maximum filter search count Enter the maximum number of elements that the Asset Filter
Search function returns to the worksheet, except when you specify
an attribute-value filter for an attribute with a data reference. In
this case, enter the total number of elements among which you
want to search for an attribute with a data reference; note that if
you set this number too low, the function might return fewer
results than expected.
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 Select to recalculate all functions, regardless of volatility, during
+F9) 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.

PI DataLink 2019 User Guide 29

Basics

Time-zone-setting limitations
Certain limitations apply to the time-zone setting:
• If an annotation contains a time stamp, the Compressed Data function always displays that
time stamp in the PI Data Archive server time zone.
• The Properties function always displays values of PI point attributes that contain time
stamps (such as creation date and change date) in the PI Data Archive server time zone.
• Trends created with the PI DataLink (Legacy) add-in always display data in the PI Data
Archive server time zone.
• The PI DataLink module database functions (Alias to Tag function and Property to Value
function) do not support the UTC time-zone setting. These functions use the client time
zone when the UTC time zone is selected.

Change PI DataLink settings for all users on a computer

Administrators can use a batch file to change the PI DataLink settings for all users on a
computer.

Procedure
1. Create the OSIsoft.PIDataLink.xml file that contains the preferred settings for all users.
You might copy the file from a user account folder (%UserProfile%\AppData\Local
\OSIsoft,_Inc\PIDataLink), or you can create one starting with the following default
file:
<Settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CTPDockWidth>200</CTPDockWidth>
<CTPFloatLeft>-1</CTPFloatLeft>
<CTPFloatTop>-1</CTPFloatTop>
<CTPFloatWidth>200</CTPFloatWidth>
<CTPFloatHeight>-1</CTPFloatHeight>
<CTPDockPosition>right</CTPDockPosition>
<CopyItemsInRow>0</CopyItemsInRow>
<CopyServerName>0</CopyServerName>
<UseServerTime>0</UseServerTime>
<DisplayEndTime>0</DisplayEndTime>
<DisplayNA>0</DisplayNA>
<LocaleIndependent>0</LocaleIndependent>
<DisableAutoReinit>0</DisableAutoReinit>
<DisableResizeMessage>0</DisableResizeMessage>
<NFormat>General</NFormat>
<TFormat>dd-mmm-yy hh:mm:ss</TFormat>
<AutoUpdateCalculateMode>0</AutoUpdateCalculateMode>
<AutoUpdateInterval>0</AutoUpdateInterval>
<LastSearchFullPath>false</LastSearchFullPath>
<LastSearchPath> </LastSearchPath>
<LastEFDatabase> </LastEFDatabase>
<MaxEFCount>1000</MaxEFCount>
<MaxAFSearchCount>10000</MaxAFSearchCount>
</Settings>
2. Create a batch file to distribute the preferred settings file to all users.
For example, you might create a batch file called deploySettings.bat:

30 PI DataLink 2019 User Guide

 Basics

@echo off

IF NOT EXIST "%CD%\OSIsoft.PIDataLink.xml" (

ECHO OSIsoft.PIDataLink.xml file not found in this directory.
EXIT /B 2
)

SET ProfileBase=%SystemDrive%\Users
SET AppDir=APPDATA\Local
SET DefaultUsername=Default

ECHO Deploying XML settings to all users.

for /f "tokens=*" %%a in ('dir /b /ad-h "%ProfileBase%"') do if 1==1 (

REM No need to copy to Public and All Users folders

ECHO %%a | findstr /i "all.users public" >nul 2> nul
if errorlevel 1 (
mkdir "%ProfileBase%\%%a\%AppDir%\OSIsoft,_Inc"
mkdir "%ProfileBase%\%%a\%AppDir%\OSIsoft,_Inc\PIDataLink"
xcopy /f /y "%CD%\OSIsoft.PIDataLink.xml" "%ProfileBase%\%%a\%AppDir%
\OSIsoft,_Inc\PIDataLink\"
)

REM Apply to default user

mkdir "%ProfileBase%\%DefaultUsername%\%AppDir%\OSIsoft,_Inc"
mkdir "%ProfileBase%\%DefaultUsername%\%AppDir%\OSIsoft,_Inc\PIDataLink"
xcopy /f /y "%CD%\OSIsoft.PIDataLink.xml" "%ProfileBase%\%DefaultUsername%\
%AppDir%\OSIsoft,_Inc\PIDataLink\"
3. Save the batch file in the same directory as the OSIsoft.PIDataLink.xml file that
contains the preferred settings.
4. From Windows Explorer, right-click the batch file and then click Run as administrator.
The script irreversibly overwrites any existing settings for all users on this computer and
replaces the settings with the preferred settings. New users on this computer will have the
same settings.
5. If you do not want new accounts (created after running this script) to have these preferred
settings, remove the OSIsoft.PIDataLink.xml file from the Default user account (found
in C:\Users\Default\AppData\Local\OSIsoft,_Inc\PIDataLink).

Delete PI DataLink settings for all users on a computer

Administrators can delete the PI DataLink settings for all users on a computer. The next time
users open PI DataLink, they will have the default settings from a new installation.

Procedure
1. Create a batch file that deletes the OSIsoft.PIDataLink.xml file.
@echo off

SET ProfileBase=%SystemDrive%\Users
SET AppDir=APPDATA\Local
SET DefaultUsername=Default

ECHO Deleting XML settings file from all users.

for /f "tokens=*" %%a in ('dir /b /ad-h "%ProfileBase%"') do if 1==1 (
ECHO Deleting "%ProfileBase%\%%a\%AppDir%\OSIsoft,_Inc".
rmdir "%ProfileBase%\%%a\%AppDir%\OSIsoft,_Inc" /s /q

PI DataLink 2019 User Guide 31

Basics

ECHO Deleting "%ProfileBase%\%DefaultUsername%\%AppDir%\OSIsoft,_Inc".

rmdir "%ProfileBase%\%DefaultUsername%\%AppDir%\OSIsoft,_Inc" /s /q
2. From Windows Explorer, right-click the batch file and then click Run as administrator.

Manage connections to servers

Use Connection Manager to manage connections to any PI Data Archive server or PI AF server,
including the selection of the default PI Data Archive 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 Asset Server to open the PI AF Server Properties window, where you can define
a connection to a PI AF server.
◦ Click Add Data Server to open the PI Data Archive Properties window, where you can
define a connection to a PI Data Archive server.
◦ Select a server not currently connected, and click Connect to connect to that server.
To connect with PI AF servers, PI DataLink uses the Windows credentials of the logged-in
user. To connect with PI Data Archive 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 Data Archive server or PI AF server).
◦ Select a server and click Properties to view the connection properties for that server.
◦ Right-click a server and then click Remove to remove the connection definition to that
server.

32 PI DataLink 2019 User Guide

Worksheet creation
This section discusses the process you might use to create worksheets with PI DataLink and
some specific types of displays you can create with PI DataLink. The topics about displays
include procedures to create those displays.

Topics in this section

• Process of creating worksheets
• Retrieval of large amounts of data
• Asset-relative displays
• Events in worksheets

Process of creating worksheets

When 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 PI DataLink function 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 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

PI DataLink 2019 User Guide 33

Worksheet creation

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 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 DataLink Server.

See also
PI DataLink functions
Search for data items
PI DataLink Server (DLS)

Retrieval of large amounts of data

For each data item in a function, PI DataLink must make a call to either PI Data Archive or PI
Asset Framework to retrieve values. When PI DataLink retrieves values for large numbers of
data items, processing each call separately can result in a long retrieval time. To reduce this
time, PI DataLink makes bulk calls for certain functions under certain conditions.
The following conditions must be satisfied to make a bulk call:
• Function inputs specify data items, and not expressions or filter expressions
• Function input specifies data items with a reference to a cell range
• PI DataLink settings specify time stamps in client time zone
With the above conditions satisfied, the following functions make bulk calls:
• Current Value
• Archive Value
• Calculated Data (without time interval specified)
PI DataLink returns values from a bulk call in a single function array.
Bulk calls result in performance improvements when functions retrieve values for more than
1,000 data items or in environments with latency between PI DataLink and data sources. When
functions retrieve values for more than 10,000 data items, bulk calls reduce retrieval time by
an order of magnitude. Therefore, when creating worksheets that retrieve values for large
numbers of data items, consider using these functions under the required conditions.

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.

34 PI DataLink 2019 User Guide

 Worksheet creation

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.
2. Configure a PI DataLink function that references the inserted data items.

See also
Search for data items

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 .

PI DataLink 2019 User Guide 35

Worksheet creation

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 paths of the data items such that the assets for the display appear in the Root path
column.
Move the Data item length slider until the Root path column shows the unique elements for
the listed attributes. Typically this will be at or near the Name only 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).

Note:
PI DataLink inserts the list of root paths in column ALL of your worksheet. If that
column contains data, PI DataLink inserts the paths in the next available column to the
right.

36 PI DataLink 2019 User Guide

 Worksheet creation

Configure a PI DataLink function that references 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.

You can select a different asset from the list to see attribute values for that asset.

Events in worksheets
You can use PI DataLink to create displays for viewing, understanding, and analyzing events
stored in PI AF. Your system configuration and the type of data collected determine which
events your system stores. For example, your system might have events that store information
about batch processes or events created from calculations.
You can use two PI DataLink functions to retrieve events:

• Explore Events function

Useful for exploring events anywhere in your event hierarchy, the Explore Events function
returns one event per row. You can use the Explore Events function to examine the data in a
simple hierarchy, such as to analyze the events for a particular element. For example, you
might examine the downtime of a particular boiler.

PI DataLink 2019 User Guide 37

Worksheet creation

Exploring events related to an element

You can also use the Explore Events function to examine the events in a full hierarchy, such
as to analyze the child events for a type of event. (The event template often indicates the
type of event.) For example, you might examine the startup phases of turbines.

Exploring events with child events

• Compare Events function

Useful for comparing hierarchical events, the Compare Events function can return attributes
from related events in a single row. In displays created from the Compare Events function,
each row can show a retrieved event along with information from that event's child events
and parent events. Including this information can help you compare the retrieved events.
For example, including information about a startup event's phase events can help you
compare multiple startup events.
The Compare Events function identifies attributes by path. Therefore, attribute names and
hierarchical location affect the display. The capabilities of the function differ depending on
the structure of the events and their attributes:

◦ Events that have child events with identical names

If you have a set of events that have identically named child events, then you can
compare those events by including child-event information and parent-event
information. Specify the criteria to find the events with identically named child events.
The Compare Events function can then include information about child events in the
same row as each matched event. For example, you might compare turbine-startup
events that have identically named phase events, such as Phase1, Phase2, and Phase3.

Comparing events by including child-event information

The Compare Events function can also include information about parent events in the
same row as a matched event. You might include information from the parent event to

38 PI DataLink 2019 User Guide

 Worksheet creation

provide more information about the matched events. For example, for the matched
turbine-startup events, information about the parent process event might enhance your
comparison.

Comparing events by including child-event and parent-event information

◦ Events that have child events with different names

If you have a set of events that have child events with different names, then you can only
compare events by including parent-event information. Specify the criteria to find the
lowest-level events in the hierarchy. The Compare Events function can then include
information from parent events in the same row as each matched event. For example,
suppose you have first-phase events with different names, such as Phase1, P1, PhaseX,
and PhaseA. You can compare the phase events and include information about the
parent startup event.

Comparing events by including parent-event information

Topics in this section

• Explore events related to an element
• Explore events with child events
• Compare events by including child events
• Compare events by including parent events
• Search for events of a specific parent event
• Reserved attribute names

Explore events related to an element

You can use the Explore Events function to explore and analyze events related to a particular PI
AF element. For example, suppose you want to analyze the downtime of a particular boiler. You
can retrieve all the downtime events for that boiler into Microsoft Excel and create a chart to
analyze the data. In this case, you might find events that match an element name and event
name.

PI DataLink 2019 User Guide 39

Worksheet creation

Procedure
1. Select a cell in the worksheet where you want PI DataLink to start inserting the function
array that contains the events.
2. On the PI DataLink tab, in the Events group, click Explore to open the Explore Events task
pane.
3. Specify the criteria to find the events you are interested in. As you enter criteria, the Preview
list updates to show the events that match the entered criteria.
a. In the Database field, enter the PI AF database that stores the events.
Specify in the format \\ServerName\DatabaseName. Click the field to open a list of
databases that contain event templates in connected PI AF servers.
b. In the Search start and Search end fields specify the time period that you want to search
for active events.
Enter a PI time expression. For example, to retrieve events that were active during the
last month, enter *-1mo in the Search start field and * in the Search end field.
Tip:
To find events with a more specific relationship to this time period, such as events
that started or ended during this time period, expand More search options and
select an alternative method from the Search mode list.
c. As necessary, specify additional criteria to refine the events that the function returns
(shown in the Preview list).
See Explore Events task-pane reference for a complete list of available fields.
For example, use the Event name field to limit returned events to those with a particular
name. You might enter *shut* to find all events that contain shut in their name, such as
shutdown and BoilerShutdown. If you leave the default entry, *, the function will find
events with any name.
Similarly, use the Element name field to limit returned events to those associated with
particular elements. You might enter Boiler5 to analyze events associated with that
boiler.
4. Specify the worksheet output:
a. From the Columns to display list, select the columns to include in the function array and
set the column order.
The list contains the names of attributes. By default, the list includes the virtual
attributes generated for all events and the event attributes from the selected event
template. You can:
▪ Select the Select all check box to include all the listed attributes as columns in the
returned function array.
▪ Select a check box to include the attribute, or clear a check box to exclude an attribute
as a column in the returned function array.
▪ Click to open the Add Attributes window where you can select additional
attributes to include as columns in the function array. See Add attribute columns to
the Explore Events task pane.

40 PI DataLink 2019 User Guide

 Worksheet creation

▪ Type the name of an event attribute next to the blank check box at the bottom of the
list.
▪ Right-click an attribute, click Insert attribute to insert a blank attribute above the
selected attribute, and then type the name of an event attribute.
▪ Select an attribute and click to move the attribute up in the list.

▪ Select an attribute and click to move the attribute down in the list.

▪ Select an attribute and click to remove the attribute from the list.

▪ Right-click an attribute and then click Delete attribute to remove the attribute from
the list.
If the length of the selected column names exceeds 759 characters, the function cannot
process columns individually. In this case, the task pane prompts you to specify all
columns as a group. With columns specified as a group, the list says All event attributes
and template attributes, and the returned function array includes all the default
attributes and their children attributes, but no additional attributes that you specified.
b. Verify that the Output cell field contains the worksheet cell where you want to insert the
top-left corner of the function array.
If you clicked a cell before opening the task pane, PI DataLink automatically inserts that
cell into this field.
5. Click OK to insert the function array into the worksheet.

After you finish

Use Excel features to analyze your data. For example, you might create a chart.

Add attribute columns to the Explore Events task pane

Use the Add Attributes window to add event attributes to the Columns to display list in the
Explore Events task pane. You can then include those attributes in the function array inserted
into the worksheet.

Before you start

Open the Explore Events task pane and specify events to retrieve into the worksheet.

Procedure
1. Next to the Columns to display list in the task pane, click to open the Add Attributes
window.
The window lists the events that match the criteria currently specified in the task pane.
2. Expand an event to see the event attributes stored for that event.

PI DataLink 2019 User Guide 41

Worksheet creation

You can include any event attribute as a column in the function array. When included in the
function array, an attribute column shows values stored for an event.
3. Select the check box next to any attribute that you want to add to the Columns to display list
in the task pane.
The Explore Events function identifies attributes by name. An event and attribute name
uniquely define a value. Therefore, you only need to add a particular attribute one time.
When you select an attribute, the window automatically selects that attribute everywhere it
appears in the event hierarchy.
Note:
PI DataLink does not synchronize selections in this window with the Columns to
display list in the task pane. In this window, you can select an attribute already
available or selected in the column list in the task pane; doing so adds the same
attribute more than once to the column list in the task pane.
4. Click OK to insert the attribute into the Columns to display list and select that column.

Explore events with child events

You can use the Explore Events function to analyze events with child events by examining them
in a hierarchical format. For example, suppose you want to analyze the startup phases of
turbines, and you have configured each phase as a child event of an overall startup event. You
can retrieve all the turbine startup events along with their child events (the phase events) into
Microsoft Excel, and then analyze that data. In this case, you might retrieve events by event
template.

Procedure
1. Select a cell in the worksheet where you want PI DataLink to start inserting the function
array that contains the events.
2. On the PI DataLink tab, in the Events group, click Explore to open the Explore Events task
pane.
3. Specify the criteria to find the events you are interested in. As you enter criteria, the Preview
list updates to show the events that match the entered criteria.
a. In the Database field, enter the PI AF database that stores the events.
Specify in the format \\ServerName\DatabaseName. Click the field to open a list of
databases that contain event templates in connected PI AF servers.
b. In the Search start and Search end fields specify the time period that you want to search
for active events.
Enter a PI time expression. For example, to retrieve events that were active during the
last month, enter *-1mo in the Search start field and * in the Search end field.
Tip:
To find events with a more specific relationship to this time period, such as events
that started or ended during this time period, expand More search options and
select an alternative method from the Search mode list.
c. As necessary, specify additional criteria to refine the events that the function returns
(shown in the Preview list).
See Explore Events task-pane reference for a complete list of available fields.

42 PI DataLink 2019 User Guide

 Worksheet creation

For example, use the Event template list to limit returned events to those based on a
particular event template. You might select the template named TurbineStartUp to
analyze turbine startup events.
4. Specify the worksheet output:
a. From the Columns to display list, select the columns to include in the function array and
set the column order.
The list contains the names of attributes. By default, the list includes the virtual
attributes generated for all events and the event attributes from the selected event
template. You can:
▪ Select the Select all check box to include all the listed attributes as columns in the
returned function array.
▪ Select a check box to include the attribute, or clear a check box to exclude an attribute
as a column in the returned function array.
▪ Click to open the Add Attributes window where you can select additional
attributes to include as columns in the function array. See Add attribute columns to
the Explore Events task pane.
▪ Type the name of an event attribute next to the blank check box at the bottom of the
list.
▪ Right-click an attribute, click Insert attribute to insert a blank attribute above the
selected attribute, and then type the name of an event attribute.
▪ Select an attribute and click to move the attribute up in the list.

▪ Select an attribute and click to move the attribute down in the list.

▪ Select an attribute and click to remove the attribute from the list.

▪ Right-click an attribute and then click Delete attribute to remove the attribute from
the list.
If the length of the selected column names exceeds 759 characters, the function cannot
process columns individually. In this case, the task pane prompts you to specify all
columns as a group. With columns specified as a group, the list says All event attributes
and template attributes, and the returned function array includes all the default
attributes and their children attributes, but no additional attributes that you specified.
b. From the Number of child event levels list, select the number of child-event levels to
include in the function array.
Select 0 to retrieve no child events, select 1 to retrieve child events from the first level
(that is, events immediately below the matched events), and so on. You can identify
events with child events in the Preview list by a + next to the event name. Child events do
not need to match the specified criteria.
The function adds a column for each level retrieved. When retrieving child events, the
function inserts each child event into a separate row. In rows containing child events, the
added column contains the child event name.
c. Verify that the Output cell field contains the worksheet cell where you want to insert the
top-left corner of the function array.

PI DataLink 2019 User Guide 43

Worksheet creation

If you clicked a cell before opening the task pane, PI DataLink automatically inserts that
cell into this field.
5. Click OK to insert the function array into the worksheet.

Compare events by including child events

You can use the Compare Events function to compare events that have child events with the
same names. The Compare Events function identifies attributes by path. Therefore, the
function can return attributes from related events in a single row. For example, suppose you
have turbine startup events that have phase events (child events that occur during the startup
event). The Compare Events function can present a row for each startup event and show values
from the corresponding phases in separate columns within each row. You can use this returned
function array to easily compare the startup events.

Procedure
1. Select a cell in the worksheet where you want PI DataLink to start inserting the function
array that contains the events.
2. On the PI DataLink tab, in the Events group, click Compare to open the Compare Events task
pane.
3. Specify the criteria to find the events you are interested in. As you enter criteria, the Preview
list updates to show the events that match the entered criteria.
a. In the Database field, enter the PI AF database that stores the events.
Specify in the format \\ServerName\DatabaseName. Click the field to open a list of
databases that contain event templates in connected PI AF servers.
b. In the Search start and Search end fields specify the time period that you want to search
for active events.
Enter a PI time expression. For example, to retrieve events that were active during the
last month, enter *-1mo in the Search start field and * in the Search end field.
Tip:
To find events with a more specific relationship to this time period, such as events
that started or ended during this time period, expand More search options and
select an alternative method from the Search mode list.
c. As necessary, specify additional criteria to refine the events that the function returns
(shown in the Preview list).
See Compare Events task-pane reference for a complete list of available fields.
For example, use the Event template list to limit returned events to those based on a
particular event template. You might select the template named TurbineStartUp to
analyze turbine startup events.

44 PI DataLink 2019 User Guide

 Worksheet creation

4. Use the Columns to display list to specify the columns in the returned function array.
The list contains the names of attributes. By default, the list includes the virtual attributes
generated for all events and the event attributes from the selected event template. The
function identifies attributes by path. See Path notation for Compare Events function for
information about supported path notations.

a. Click to open the Add Attributes window and select the child-event attributes that
you want to compare among parent events.
See Add child-event attributes as columns in the Compare Events task pane.
b. Insert any parent-event attributes that you want included in the function array.
See Add parent-event attributes as columns in the Compare Events task pane.
c. Select the columns to include in the function array and set the column order.
You can:
▪ Select the Select all check box to include all the listed attributes as columns in the
returned function array.
▪ Select a check box to include the attribute, or clear a check box to exclude an attribute
as a column in the returned function array.
▪ Type the name of an event attribute next to the blank check box at the bottom of the
list.
▪ Select an attribute and click to move the attribute up in the list.

▪ Select an attribute and click to move the attribute down in the list.

▪ Select an attribute and click to remove the attribute from the list.

▪ Right-click an attribute and then click Delete attribute to remove the attribute from
the list.
5. Verify that the Output cell field contains the worksheet cell where you want to insert the
top-left corner of the function array.
If you clicked a cell before opening the task pane, PI DataLink automatically inserts that cell
into this field.
6. Click OK to insert the function array into the worksheet.

Add child-event attributes as columns in the Compare Events task pane

Use the Add Attributes window to add child-event attributes to the Columns to display list in
the Compare Events task pane. (Then you can include those columns in the function array
inserted into the worksheet.) After you specify criteria for events in the task pane, this window
lists the matched events and their child events. You can use this window to add any event

PI DataLink 2019 User Guide 45

Worksheet creation

attribute from these events. Most commonly, you use this window to add child-event attributes
that will help you compare the matched events.

Before you start

Open the Compare Events task pane and specify events to retrieve into the worksheet.

Procedure
1. Next to the Columns to display list in the task pane, click to open the Add Attributes
window.
The window lists the events that match the criteria currently specified in the task pane.
2. Expand an event to see the event attributes stored for that event along with any child
events.
If two or more child events have the same name, PI DataLink automatically adds an index to
the child-event name. To create the index, PI DataLink sorts those events by ascending start
time, then ascending end time, and then ascending identifier.

Event with two child events named Phase1

You can include any event attribute as a column in the function array. When included in the
function array, that column will show values stored for the event attribute.
3. Select the check box next to any attribute that you want to add to the Columns to display list
in the task pane.
The Compare Events function identifies attributes by name and path relative to the matched
event. For example, suppose you select the Start time attribute under both a matched
event and its child event.

46 PI DataLink 2019 User Guide

 Worksheet creation

Select start-time attribute of matched and child event

This adds two columns:

◦ .|Start time
In the worksheet, this column contains the start time of the matched event listed in each
row.
◦ .\Phase1|Start time
In the worksheet, this column contains the start time of the Phase1 child event of the
matched event listed in each row.

Worksheet with child-attribute column

You can add attributes from anywhere in the hierarchy. The window does not synchronize
selections: if the path and attribute name are the same, you can add the same attribute more
than once.
When events have inconsistent event hierarchies, use care when selecting attributes of child
events. If any event contains multiple child events with the same name, then select
attributes under a duplicated child event (that is, an indexed child event) to ensure that you
can view data for all events. For example, suppose you select the Start time attribute
under a duplicated child event (the Phase1[1] child event of the TurbineStartUp.1.2
event) and a nonduplicated child event (the Phase1 child event of the TurbineStartUp.
3.2 event).

PI DataLink 2019 User Guide 47

Worksheet creation

Select start-time attribute of duplicated child event and nonduplicated child event

This adds two columns that return different results:

◦ .\Phase1[1]|Start time
In the worksheet, this column contains the start time of the first Phase1 child event of
the matched event listed in each row. If the matched event has only one child event with
this name, then the column lists the start time of that event in this column.
◦ .\Phase1|Start time
In the worksheet, this column contains the start time of the only Phase1 child event of
the matched event listed in each row. If the matched event has more than one child event
with this name, the column reports Duplicate event exists: specify index for
Phase1.

48 PI DataLink 2019 User Guide

 Worksheet creation

Worksheet with indexed and nonindexed child attribute

The indexed attribute ensures that you return the desired data.
4. Click OK to insert the attribute into the Columns to display list and select that column.

Add parent-event attributes as columns in the Compare Events task

pane
To help compare events in a worksheet, you can include columns that contain information
about the parent events of matched events. Use the Columns to display list in the Compare
Events task pane to insert attributes of parent events (and their parent events or any higher
level event in the hierarchy).
Note:
The Compare Events function does not retrieve data from parent-event attributes for
events with relationships defined through event-frame references.

Before you start

Open the Compare Events task pane and specify events to retrieve into the worksheet.

Procedure
1. From the Columns to display list in the Compare Events task pane, add parent-event
attributes using the method appropriate for the attribute:
To insert: Do this:
Same attribute name at a. Right-click the attribute and then click Clone for parent event.
parent level
PI DataLink inserts the parent-event attribute of the same name
above the selected attribute.
For example if you right-click the .|Event name attribute (the Event
name attribute of the matched event) and click Clone for parent
event, PI DataLink inserts the ..|Event name attribute (the Event
name attribute of the parent event).

You can repeat to add the same attribute from events higher up the
hierarchy. For example, if you right-click the ..|Event name attribute
and click Clone for parent event, PI DataLink inserts the ..\..|Event
name attribute (the Eventname attribute of the grandparent event).

PI DataLink 2019 User Guide 49

Worksheet creation

To insert: Do this:
Unique attribute name a. Right-click the attribute above which you want to insert the parent-
event attribute, and then click Insert attribute.
PI DataLink inserts a blank attribute at the primary event level (.|).
b. Enter the correct path and name of the parent-event attribute.
For example, to include the Type attribute of the parent event,
enter ..|Type.

For information on path syntax, see Path notation for Compare Events function.

Compare events by including parent events

You can use the Compare Events function to present information about parent events in the
same row as an event. You can use this capability to compare any events from matching
hierarchies, including events with different names. For example, suppose you have turbine
startup events that have phase events, but some phase events have different names. With the
Compare Events function, you can return a row for each phase event and show values from the
parent event in separate columns within each phase-event row. The returned information can
help you compare phase events.

Procedure
1. Select a cell in the worksheet where you want PI DataLink to start inserting the function
array that contains the events.
2. On the PI DataLink tab, in the Events group, click Compare to open the Compare Events task
pane.
3. Specify the criteria to find the events you are interested in. As you enter criteria, the Preview
list updates to show the events that match the entered criteria.
a. In the Database field, enter the PI AF database that stores the events.
Specify in the format \\ServerName\DatabaseName. Click the field to open a list of
databases that contain event templates in connected PI AF servers.
b. In the Search start and Search end fields specify the time period that you want to search
for active events.
Enter a PI time expression. For example, to retrieve events that were active during the
last month, enter *-1mo in the Search start field and * in the Search end field.
Tip:
To find events with a more specific relationship to this time period, such as events
that started or ended during this time period, expand More search options and
select an alternative method from the Search mode list.
c. As necessary, specify additional criteria to refine the events that the function returns
(shown in the Preview list).
See Compare Events task-pane reference for a complete list of available fields.

50 PI DataLink 2019 User Guide

 Worksheet creation

For example, use the Event template list to limit returned events to those based on a
particular event template. You might select the template named StartUpPhase1 to
analyze first-phase startup events.
4. Use the Columns to display list to specify the columns in the returned function array.
The list contains the names of attributes. By default, the list includes the virtual attributes
generated for all events and the event attributes from the selected event template. The
function identifies attributes by path. See Path notation for Compare Events function for
information about supported path notations.

a. Insert the parent-event attributes that you want included in the function array.
See Add parent-event attributes as columns in the Compare Events task pane.
For example, you might right-click some of the virtual attributes and then click Clone for
parent event to insert the corresponding parent-event attributes, such as:
..|Event name
..|Start time
..|Primary element
b. Select the attributes to include as columns in the function array and set the column
order.
You can:
▪ Select the Select all check box to include all the listed attributes as columns in the
returned function array.
▪ Select a check box to include the attribute, or clear a check box to exclude an attribute
as a column in the returned function array.
▪ Type the name of an event attribute next to the blank check box at the bottom of the
list.
▪ Select an attribute and click to move the attribute up in the list.

▪ Select an attribute and click to move the attribute down in the list.

▪ Select an attribute and click to remove the attribute from the list.

▪ Right-click an attribute and then click Delete attribute to remove the attribute from
the list.
5. Verify that the Output cell field contains the worksheet cell where you want to insert the
top-left corner of the function array.
If you clicked a cell before opening the task pane, PI DataLink automatically inserts that cell
into this field.
6. Click OK to insert the function array into the worksheet.

PI DataLink 2019 User Guide 51

Worksheet creation

Search for events of a specific parent event

You can use the Explore Events and Compare Events functions to show information only about
events with a specific parent event. To limit retrieved events to a particular parent event, open
the function task pane and specify the path to the parent event in the Database field. You can
specify the path using a cell reference.

Procedure
1. Retrieve the event path to the parent event into a worksheet.
a. Use the Explore Events function to find the parent event.
b. From the Columns to display list, select the Event path check box to include the column
in the output.
You can also include other columns.
c. Click OK to retrieve the data into the worksheet.

2. Reference the parent event path in the Explore Events or Compare Events function.
a. In the same worksheet or another worksheet, click the cell where you want PI DataLink
to start inserting the function array that contains the child events.
Remember that the new array must not overlap any other function array.
b. On the PI DataLink tab, in the Events group, click either Explore or Compare to open the
corresponding function task pane.
c. In the Database field, clear the existing entry to the current database, and then click the
cell in Event path column that corresponds to the parent event for which you want to
find events.
PI DataLink inserts a cell reference to the worksheet cell into the task pane.

3. Specify any other criteria to find the desired child events and the columns to display, and
then click OK to insert the function array into the worksheet.

52 PI DataLink 2019 User Guide

 Worksheet creation

Reserved attribute names

PI DataLink automatically generates some virtual attributes for events and uses reserved
names to identify these virtual attributes. To prevent conflicts with event-defined attributes, do
not define events that use the following reserved names as attribute names:
• Acknowledged by
• Acknowledged date
• Annotations
• Duration
• Element template
• End time
• Event categories
• Event name
• Event path
• Event template
• Is acknowledged
• Primary element
• Primary element path
• Severity
• Start time

PI DataLink 2019 User Guide 53

Worksheet creation

54 PI DataLink 2019 User Guide

PI DataLink functions
With PI DataLink functions, you can query any PI Data Archive 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 task panes
Function arrays
Function reference

Topics in this section

• Current Value function
• Archive Value function
• Compressed Data function
• Sampled Data function
• Timed Data function
• Calculated Data function
• Time Filtered function
• Explore Events function
• Compare Events function
• Asset Filter Search function
• Properties function

Current Value function

The Current Value function returns the most recent value of a historical PI point or PI AF
attribute. For a future PI point, the value returned depends on the time stamps of recorded
values relative to the current time:
• If all recorded values have time stamps before the current time, the function returns the last
recorded value.
• If recorded values have time stamps that straddle the current time, the function returns an
interpolated value.
• If all recorded values have time stamps after the current time, the function returns no data.
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.

PI DataLink 2019 User Guide 55

PI DataLink functions

This function supports bulk calls.

Input Description
Root path The common path to specified data items. Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns values for each.
Required.
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.

See also
PICurrVal()
Retrieval of large amounts of data
Interpolated values

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:

56 PI DataLink 2019 User Guide

 PI DataLink functions

Archive Value function

• If you select the Data item option, the Archive Value function returns the value of a PI point
or a PI AF attribute at a specified time stamp. This function supports bulk calls.
• If you select the Expression option, the Archive Value function returns the computed value
of a performance equation at a specified time stamp.
Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns 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.
To specify multiple expressions, enter a range of cells that contain complete
expressions. The function returns 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.
Required.

PI DataLink 2019 User Guide 57

PI DataLink functions

Input Description
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.
See Interpolated values.
• 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.
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 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.

See also

• PIArcVal()

58 PI DataLink 2019 User Guide

 PI DataLink functions

Specify data items.

• PIExpVal()
Specify an expression.
• Retrieval of large amounts of data

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
Data item(s) sinusoid
Time stamp 30-Sep-07 15:13
Retrieval mode previous
Time at left Selected

The function returns the following array:

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.
Note:
Values stored in the archive of PI Data Archive undergo a compression algorithm that
removes all values that represent the same slope. Values stored in the PI Data Archive
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:
• PI Data Archive 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 Data Archive server.
See Data items.

PI DataLink 2019 User Guide 59

PI DataLink functions

Input Description
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns values for each.
Required.
Start time The start of the time period for which the function returns values. See Time
inputs.
Required.
End time The end of the time period for which the function returns values. See Time
inputs.
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.
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.
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.
See Interpolated values.
• auto
Returns interpolated values, but uses the inside method for data items
with step attributes.

60 PI DataLink 2019 User Guide

 PI DataLink functions

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.
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 the value has a comment.
• S
Substituted. Indicates the value has changed from its originally recorded
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 the 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) or a range of expressions
in Expression(s), PI DataLink automatically selects Column or Row to
match the orientation of the specified range.

See also
• PICompDat()
Specify a time range without a filter expression.
• PICompFilDat()
Specify a time range with a filter expression.
• PINCompDat()
Specify a number of values without a filter expression.
• PINCompFilDat()

PI DataLink 2019 User Guide 61

PI DataLink functions

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
Data item(s) sinusoid
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

The function returns the following array:

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.
See Interpolated values.

62 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns 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.
To specify multiple expressions, enter a range of cells that contain complete
expressions. The function returns values for each.
Required if you select the Expression option.

Start time The start of the time period for which the function returns values. See Time
inputs.
Required.
End time The end of the time period for which the function returns values. See Time
inputs.
Required.
Time interval The frequency that the function returns calculated 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.
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.
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.
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.
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.

PI DataLink 2019 User Guide 63

PI DataLink functions

Input Description
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) or a range of expressions
in Expression(s), PI DataLink automatically selects Column or Row to
match the orientation of the specified range.

See also
• PISampDat()
Specify a data item with a filter expression.
• PISampFilDat()
Specify a data item without a filter expression.
• PIExpDat()
Specify an expression.

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
Data item(s) sinusoid
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 function returns the following array:

64 PI DataLink 2019 User Guide

 PI DataLink functions

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:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns 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.
To specify multiple expressions, enter a range of cells that contain complete
expressions. The function returns values for each.
Required if you select the Expression option.

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.
See Time inputs.
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.
See Interpolated values.
• exact time
Returns only values that exactly match specified time stamps; returns No
events found if no value exists.
Available if you select the Data item option.

PI DataLink 2019 User Guide 65

PI DataLink functions

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.

See also
• PITimeDat()
Specify a data item.
• PITimeExpDat()
Specify an expression.

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.

66 PI DataLink 2019 User Guide

 PI DataLink functions

Calculated Data function

• 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 specify no filter expression and no time interval, the function
supports bulk calls.
• 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 + next to Advanced to access all function inputs.

Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns values.
To specify multiple data items, enter a range of cells that contain PI point
names or PI AF attribute names. The function returns 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.
To specify multiple expressions, enter a range of cells that contain complete
expressions. The function returns values for each.
Required if you select the Expression option.

Start time The start of the time period for which the function returns values. See Time
inputs.
Required.
End time The end of the time period for which the function returns values. See Time
inputs.
Required.
Time interval The frequency that the function returns calculated 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.
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.

PI DataLink 2019 User Guide 67

PI DataLink functions

Input Description
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
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.
• count
Counts the number of seconds in the interval if the Calculation basis field
is set to time-weighted.
Counts the number of values stored during the interval if the Calculation
basis field is set to event-weighted.
• average (time-weighted)
Computes the time-weighted average of the recorded values during the
interval.
• average (event-weighted)
Computes the event-weighted average of the recorded values during the
interval.

68 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Calculation basis The calculation method:
• time-weighted
Default for all calculation modes except for event-weighted average. The
function weights each recorded value by the length of time that the value
applies. The function interpolates values at the interval boundaries.
• event-weighted
The function weights each recorded value equally. Select this option for
batch values. This method requires at least one recorded value in a time
period (two recorded values for standard deviation calculations).
If you enter an expression in the Expression(s) field and set the Expression
sampling field to interpolated, then the function interpolates values at the
time interval boundaries when there are no recorded values.
Expression sampling The method that the function uses to determine when to evaluate an
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
values.
If there are no stored values, the function returns either no value or an
interpolated value. For best results, select interpolated rather than
compressed during time periods with few stored values.
• interpolated
The function evaluates the expression at evenly spaced sampling
intervals, determined by Expression sampling frequency.
See Interpolated values.
Tip:
For most accurate results, select interpolated and set the Expression
sampling frequency field to a small frequency.

Available if you select Expression or if you specify a Filter expression.

Expression sampling The frequency that the function evaluates an expression. Required if you set
frequency Expression sampling to interpolated.
For example, set to 10m (10 minutes) to compute an interpolated value every
10 minutes.
Minimum percent good The minimum percentage of good data required in each time interval to
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.

PI DataLink 2019 User Guide 69

PI DataLink functions

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.
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 time Select this check box to show the time stamp that corresponds to the
minimum 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 recorded values that PI Data Archive 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.
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) or a range of expressions
in Expression(s), PI DataLink automatically selects Column or Row to
match the orientation of the specified range.

70 PI DataLink 2019 User Guide

 PI DataLink functions

See also
• PIAdvCalcVal()
Specify a data item to retrieve a single value
• PIAdvCalcFilVal()
Specify a data item and filter expression to retrieve a single value
• PIAdvCalcExpVal()
Specify an expression to retrieve a single value
• PIAdvCalcExpFilVal()
Specify an expression and a filter expression to retrieve a single value
• PIAdvCalcDat()
Specify a data item and time interval to retrieve multiple values
• PIAdvCalcFilDat()
Specify a data item, time interval, and filter expression to retrieve multiple values
• PIAdvCalcExpDat()
Specify an expression and time interval to retrieve multiple values
• PIAdvCalcExpFilDat()
Specify an expression, time interval, and filter expression to retrieve multiple values
• Retrieval of large amounts of data

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
Data item(s) sinusoid
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

The function returns the following array:

PI DataLink 2019 User Guide 71

PI DataLink functions

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 Data
Archive version.
• Results from corresponding performance-equation functions and asset-analytics
functions, such as TimeGE or TimeGT, are more accurate than those from the Time
Filtered function.
OSIsoft recommends that you compare the results of the Time Filtered function to the
output from performance-equation functions or asset-analytics functions before using
results of the Time Filtered function for decision making.

Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Expression(s) A Boolean performance equation that the function evaluates. See
Expressions.
To specify multiple expressions, enter a range of cells that contain complete
expressions. The function returns values for each.
Required.

72 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Start time The start of the time period for which the function returns values. See Time
inputs.
Required.
End time The end of the time period for which the function returns values. See Time
inputs.
Required.
Time interval The frequency that the function returns calculated 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.
Time units The units of time in which the function returns the result.
Required.
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.
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 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 recorded values that PI Data Archive 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.
Column Click this option to return values in a column.

PI DataLink 2019 User Guide 73

PI DataLink functions

Input Description
Row Click this option to return values in a row.
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.

See also
• PITimeFilterVal()
Return a single value.
• PITimeFilter()
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

The function returns the following array:

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.

Explore Events function

The Explore Events function returns events that meet specified criteria in a PI AF database. Use
the Explore Events function to view and explore events in a hierarchical format. The function
returns one event per row.
Use the fields at the top of the Explore Events task pane to specify which PI AF events you want
to retrieve. As you specify the criteria for events, the task pane's Preview list shows the
matching events. Modify the criteria to adjust the matching events before inserting the function

74 PI DataLink 2019 User Guide

 PI DataLink functions

array into the worksheet. Use the fields at the bottom of the task pane to specify the columns to
include and the position of the inserted function array.
For more details, see the following topics:
• Events in worksheets
PI DataLink can display data from PI AF events with either the Explore Events function or
the Compare Events function.
• Explore events related to an element
Follow this procedure to use the Explore Events function to analyze events related to a
particular PI AF element.
• Explore events with child events
Follow this procedure to use the Explore Events function to analyze events with child
events.
• Explore Events task-pane reference
The fields in the task pane let you specify the events to retrieve and the columns and data to
return to the worksheet.
• Reserved attribute names
To avoid conflicts with automatically generated attributes, do not define events that use
reserved attribute names.
• Explore Events example
Set the Explore Events function inputs to see the events that have been active during the
past month and that are based on a particular template.
• Manage PI DataLink settings from Excel
Use the Settings window to set the maximum number of events that the function returns.

Explore Events task-pane reference

The Explore Events function returns events in a hierarchical format. A preference setting limits
the number of events retrieved in the Preview list and returned to the worksheet.
Note:
Expand More search options to access all function inputs.

Input Description
Database The PI AF database from which the function returns events. Specify in the
format \\ServerName\DatabaseName. Click the field to see a list of
databases that contain event templates on connected PI AF servers. You must
specify the database before the function can find any matching events.
Tip:
To limit returned events to those under a specific parent event, you can
specify the event path of that parent event in the Database field. See
Search for events of a specific parent event.

PI DataLink 2019 User Guide 75

PI DataLink functions

Input Description
Search start A PI time expression that specifies the time that the function starts searching
the database for events. For example, specify *-12h to search for events from
database records starting 12 hours ago.
Search end A PI time expression that specifies the time that the function stops searching
the database for events. For example, specify * to search for events up to the
current time.
Limit to database level Select this check box to only search the database root level for matching
events. If you clear this check box, the function searches for matching events
at any level of the hierarchy.
Event name The name of matched events. You can specify partial names with wildcard
characters.
Event template An event template of matched events. Note that if you select a base event
template, the function includes events from derived templates.
When you select an event template, the Columns to display list updates to
reflect attributes of the selected template. The update removes any attributes
you previously inserted.
Element name A PI AF element referenced by the matched events. You can specify partial
names with wildcard characters. If using PI AF server version 2.8 or later, you
can specify the path to a specific element.
Element template An element template of an element referenced by matched events. Note that
if you select a base element template, the function includes events that
reference elements from derived templates.
PI AF server version 2.6 or later is required to filter on element templates.
Event category The category of matched events.
Minimum duration The minimum duration of matched events. Specify a value and time-unit
abbreviation.
Maximum duration The maximum duration of matched events. Specify a value and time-unit
abbreviation.
Search mode The method that the function uses to find matching events relative to the
time period specified by the search start and search end:
• active in range
Find events that are active any time during the specified time period.
• entirely in range
Find events that start and finish during the specified time period.
• starting in range
Find events that start during the specified time period and finish either
during or after the specified time period.
• ending in range
Find events that finish during the specified time period and start either
before or during the specified time period.
• in progress
Find events that start during the specified time period but have not yet
finished. Only available with PI AF server version 2.6 or later.

76 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Sort order The method that the function uses to sort matched events:
• name ascending
Order events by the event name, from A to Z.
• name descending
Order events by the event name, from Z to A.
• start time ascending
Order events by start time, from earliest to latest.
• start time descending
Order events by start time, from latest to earliest.
• end time ascending
Order events by end time, from earliest to latest.
• end time descending
Order events by end time, from latest to earliest.
Severity The severity of matched events. Specify an operator and severity type. The
function filters matched events based on the specified condition. Severity
types correspond to a value, listed from highest to lowest. For example, if you
enter < Warning, the function matches events less severe than Warning:
either Information or None.
Attribute value filters Up to four attribute conditions that the function uses to filter matched events.
Note:
You must specify an event template before you can specify an attribute-
value filter.
For each filter, specify:
• Attribute
An event attribute for which the function filters matched events. Available
attributes depend on the selected event template.
• Operator
The relational operator that the function applies to the specified attribute
value. Available operators depend on the attribute data type.
• Value
The value that the function uses to search for matching attributes. For
example, if you set the Operator field to =, then the function limits events
to those with the specified attribute equal to this value.
Acknowledgment filters Limit matched events to those that can be acknowledged:
• Select the Acknowledged check box to match events that have been
acknowledged.
• Select the Unacknowledged check box to match events that have not been
acknowledged.
• Select both check boxes to match any event that can be acknowledged,
regardless of its current acknowledgment state.
Limit to annotated Select this check box to match only annotated events. Clear this check box to
match all events, with or without annotations.

PI DataLink 2019 User Guide 77

PI DataLink functions

Input Description
Columns to display The columns in the returned function array. The list contains the names of
attributes. By default, the list includes the virtual attributes generated for all
events and the event attributes from the selected event template. You can:
• Select the Select all check box to include all the listed attributes as
columns in the returned function array.
• Select a check box to include the attribute, or clear a check box to exclude
an attribute as a column in the returned function array.
• Click to open the Add Attributes window where you can select

additional attributes to include as columns in the function array. See Add

attribute columns to the Explore Events task pane.
• Type the name of an event attribute next to the blank check box at the
bottom of the list.
• Right-click an attribute, click Insert attribute to insert a blank attribute
above the selected attribute, and then type the name of an event attribute.
• Select an attribute and click to move the attribute up in the list.

• Select an attribute and click to move the attribute down in the list.

• Select an attribute and click to remove the attribute from the list.

• Right-click an attribute and then click Delete attribute to remove the

attribute from the list.
If the length of the selected column names exceeds 759 characters, the
function cannot process columns individually. In this case, the task pane
prompts you to specify all columns as a group. With columns specified as a
group, the list says All event attributes and template attributes, and the
returned function array includes all the default attributes and their children
attributes, but no additional attributes that you specified.
Number of child event The number of levels of child events that the function includes in the function
levels array. Child events do not need to match the specified criteria. The function
returns each child event into a separate row, and adds an additional column
for each level returned. In rows containing child events, the added column
contains the child-event name.
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.

See also
Events in worksheets
Add attribute columns to the Explore Events task pane
Manage PI DataLink settings from Excel

78 PI DataLink 2019 User Guide

 PI DataLink functions

Explore Events example

To see events based on the event template PowerPlantShutDown in the database Production
on PI AF server AFSRV1 and active during the past month, set the following inputs for the
Explore Events function:
Input Value
Database \\AFSRV1\Production
Search start *-1mo
Search end *
Event template PowerPlantDownTime

The function returns the following array:

Compare Events function

The Compare Events function returns events that meet specified criteria in a PI AF database.
Use the Compare Events function to view events in a flat format. The function returns one
event per row, but can return attributes from related events in that same row. Specifically, to
facilitate event comparison, the function can return attributes from child events or parent
events in the same row as the returned event.
Use the fields at the top of the Compare Events task pane to specify which PI AF events you
want to retrieve. As you specify the search criteria for events, the task pane Preview list shows
the matching events. Modify the criteria to adjust the matching events before inserting the
function array into the worksheet. Use the fields at the bottom of the task pane to specify the
columns to include and the position of the inserted function array.
For more details, see the following topics:
• Events in worksheets
PI DataLink can display data from PI AF events with either the Explore Events function or
the Compare Events function.
• Compare events by including child events
Follow this procedure to use the Compare Events function to compare events that have child
events with the same names.
• Compare events by including parent events
Follow this procedure to use the Compare Events function to compare events from matching
hierarchies when child events have different names.
• Compare Events task-pane reference
The fields in the task pane let you specify the events to retrieve and the columns and data to
return to the worksheet.

PI DataLink 2019 User Guide 79

PI DataLink functions

• Path notation for Compare Events function

Use specific path notation in attribute names to designate the location in the event
hierarchy.
• Reserved attribute names
To avoid conflicts with automatically generated attributes, do not define events that use
reserved attribute names.
• Compare Events example
Set the Compare Events function inputs to compare temperature-alert events.
• Manage PI DataLink settings from Excel
Use the Settings window to set the maximum number of events that the function returns.

Compare Events task-pane reference

The Compare Events function returns events in a flat format. A preference setting limits the
number of events retrieved in the Preview list and returned to the worksheet.
Note:
Click + next to More search options to access all function inputs.

Input Description
Database The PI AF database from which the function returns events. Specify in the
format \\ServerName\DatabaseName. Click the field to see a list of
databases that contain event templates on connected PI AF servers. You must
specify the database before the function can find any matching events.
Tip:
To limit returned events to those under a specific parent event, you can
specify the event path of that parent event in the Database field. See
Search for events of a specific parent event.

Search start A PI time expression that specifies the time that the function starts searching
the database for events. For example, specify *-12h to search for events from
database records starting 12 hours ago.
Search end A PI time expression that specifies the time that the function stops searching
the database for events. For example, specify * to search for events up to the
current time.
Limit to database level Select this check box to only search the database root level for matching
events. If you clear this check box, the function searches for matching events
at any level of the hierarchy.
Event name The name of matched events. You can specify partial names with wildcard
characters.
Event template An event template of the matched events. Note that if you select a base event
template, the function includes events from derived templates.
When you select an event template, the Columns to display list updates to
reflect attributes of the selected template. The update removes any attributes
you previously inserted.

80 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Element name A PI AF element referenced by the matched events. You can specify partial
names with wildcard characters. If using PI AF server version 2.8 or later, you
can specify the path to a specific element.
Element template An element template of an element referenced by matched events. Note that
if you select a base element template, the function includes events that
reference elements from derived templates.
PI AF server version 2.6 or later is required to filter on element templates.
Event category The category of matched events.
Minimum duration The minimum duration of matched events. Specify a value and time-unit
abbreviation.
Maximum duration The maximum duration of matched events. Specify a value and time-unit
abbreviation.
Search mode The method that the function uses to find matching events relative to the
time period specified by the search start and search end:
• active in range
Find events that are active any time during the specified time period.
• entirely in range
Find events that start and finish during the specified time period.
• starting in range
Find events that start during the specified time period and finish either
during or after the specified time period.
• ending in range
Find events that finish during the specified time period and start either
before or during the specified time period.
• in progress
Find events that start during the specified time period but have not yet
finished. Only available with PI AF server version 2.6 or later.
Sort order The method the function uses to sort returned events:
• name ascending
Order events by the event name, from A to Z.
• name descending
Order events by the event name, from Z to A.
• start time ascending
Order events by start time, from earliest to latest.
• start time descending
Order events by start time, from latest to earliest.
• end time ascending
Order events by end time, from earliest to latest.
• end time descending
Order events by end time, from latest to earliest.

PI DataLink 2019 User Guide 81

PI DataLink functions

Input Description
Severity The severity of matched events. Specify an operator and severity type. The
function filters matched events based on the specified condition. Severity
types correspond to a value, listed from highest to lowest. For example, if you
enter < Warning, the function matches events less severe than Warning:
either Information or None.
Attribute value filters Up to four attribute conditions that the function uses to filter matched events.
Note:
You must specify an event template before you can specify an attribute-
value filter.
For each filter, specify:
• Attribute
An event attribute for which the function filters matched events. Available
attributes depend on the selected event template.
• Operator
The relational operator that the function applies to the specified attribute
value. Available operators depend on the attribute data type.
• Value
The value that the function uses to search for matching attributes. For
example, if you set the Operator field to =, then the function limits events
to those with the specified attribute equal to this value.
Acknowledgment filters Limit matched events to those that can be acknowledged:
• Select the Acknowledged check box to match events that have been
acknowledged.
• Select the Unacknowledged check box to match events that have not been
acknowledged.
• Select both check boxes to match any event that can be acknowledged,
regardless of its current acknowledgment state.
Limit to annotated Select this check box to match only annotated events. Clear this check box to
match all events, with or without annotations.

82 PI DataLink 2019 User Guide

 PI DataLink functions

Input Description
Columns to display The columns in the returned function array. The list contains the names of
attributes. By default, the list includes the virtual attributes generated for all
events and the event attributes from the selected event template. The
function includes the path of attributes; the function identifies unique
attributes by name and position in the hierarchy. You can:
• Select the Select all check box to include all the listed attributes as
columns in the returned function array.
• Select a check box to include the attribute, or clear a check box to exclude
an attribute as a column in the returned function array.
• Click to open the Add Attributes window where you can select

additional attributes to include as columns in the function array. See Add

child-event attributes as columns in the Compare Events task pane.
• Right-click an attribute and then click Clone for parent event to insert the
attribute for the parent event as a column in the function array. See Add
parent-event attributes as columns in the Compare Events task pane.
• Type the name of an event attribute next to the blank check box at the
bottom of the list.
• Right-click an attribute, click Insert attribute to insert a blank attribute
above the selected attribute, and then type the name of an event attribute.
• Select an attribute and click to move the attribute up in the list.

• Select an attribute and click to move the attribute down in the list.

• Select an attribute and click to remove the attribute from the list.

• Right-click an attribute and then click Delete attribute to remove the

attribute from the list.
If the length of the selected column names exceeds 759 characters, the
function cannot process columns individually. In this case, the task pane
prompts you to specify all columns as a group. With columns specified as a
group, the list says All event attributes and template attributes, and the
returned function array includes all the default attributes and their children
attributes, but no additional attributes that you specified.
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.

See also
Events in worksheets
Add child-event attributes as columns in the Compare Events task pane
Manage PI DataLink settings from Excel

PI DataLink 2019 User Guide 83

PI DataLink functions

Path notation for Compare Events function

The Compare Events function identifies attributes by path; therefore, attribute names must
always include path information, specified relative to the matched event shown in each row.
When specifying attributes, use the notation that designates the proper location in the event
hierarchy.
Supported path notation
Notation Description
.|A1 The A1 attribute of the matched event.
..|A1 The A1 attribute of the matched event's parent event.
..\..|A1 The A1 attribute of the matched event's grandparent event.
.\E1|A1 The A1 attribute of the matched event's E1 child event.

You can combine the notation to designate attributes further up the hierarchy. For example,
you can specify the Duration attribute for different events in the hierarchy:
• Great-grandparent event: ..\..\..|Duration
• Matched event: .|Duration
• Child event named Phase1: .\Phase1|Duration

Compare Events example

To see attributes from child events in a format that lets you easily compare the parent events,
use the Compare Events function. Suppose you have temperature-alert events and each has a
single child event that indicates a temperature threat when the pump temperature reaches a
certain level. You can retrieve a function array that shows the start time, duration, and
temperature recorded for the temperature-threat event stored for each temperature-alert
event. The parent events have names that start with TempAlert and the child events are
named TempThreat. To retrieve the function array for events stored during the past week in
the Production database on the PI AF server AFSRV1, enter the following inputs:
Input Value
Database \\AFSRV1\Production
Search start *-1w
Search end *
Event name TempAlert*

84 PI DataLink 2019 User Guide

 PI DataLink functions

Input Value
Column headers Select the following:
• Event name
• .|Start time
• .|End time
• .|Duration
• .|Primary element
• .\TempThreat|Start time*
• .\TempThreat|Duration*
• .\TempThreat|Temperature*
*Added to list from the Add Attributes window.

The function returns the following array:

Asset Filter Search function

The Asset Filter Search function returns assets (that is, PI AF elements or attributes) that meet
specified criteria. The criteria can include element name, element template, element category,
and element description, as well as the value of attributes. You can insert the returned assets
into the worksheet as static values or as a function array.
Use the fields at the top of the Asset Filter Search task pane to specify which PI AF element you
want to retrieve. Use the fields at the bottom of the task pane to specify the attributes to
retrieve, the output format, and the position.
For more details, see the following topics:
• Searches
You can search for data items with either the Search tool or the Asset Filter Search function.
• Search for assets by filtering
Follow this procedure to use the Asset Filter Search function to specify the elements to
retrieve and the output for the worksheet.
• Manage PI DataLink settings from Excel
Use the Settings window to set the maximum number of elements and attributes that the
function returns.

Properties function
The Properties function returns the property value of a specified data item.

PI DataLink 2019 User Guide 85

PI DataLink functions

Input Description
Root path The common path to specified data items. Valid entries include:
• PI Data Archive 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 Data Archive server.
See Data items.
Data item(s) One or more PI point names or PI AF attribute names, for which the function
returns property values.
Reference a range of cells that contain PI point names or PI AF attribute
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 four PI AF attribute properties:
categories, description, uom, and pipoint.
• 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 PointClass of
that point.
◦ PI AF attribute. The list contains four PI AF attribute properties:
categories, description, uom, and pipoint.
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.
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.

See also
PITagAtt()

86 PI DataLink 2019 User Guide

 PI DataLink functions

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

The function returns the following array:

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.

PI DataLink 2019 User Guide 87

PI DataLink functions

88 PI DataLink 2019 User Guide

Worksheet usage and maintenance
This section discusses how PI DataLink functions work within a worksheet and how to manage
and maintain your worksheet over time.

Topics in this section

• Function arrays
• Calculation frequency
• Worksheet sharing

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 the PI Data Archive 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

Topics in this section

• Common function array tasks
• Update inputs to a function array
• Array size
• Resize arrays

PI DataLink 2019 User Guide 89

Worksheet usage and maintenance

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.
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 + Shift + Enter 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, otherwise 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.
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.

90 PI DataLink 2019 User Guide

 Worksheet usage and maintenance

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.
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
Resize arrays
Manage PI DataLink settings from Excel

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

PI DataLink 2019 User Guide 91

Worksheet usage and maintenance

function array: PI DataLink retrieves new values from PI Data Archive or PI AF and
automatically resizes the array to fit the returned data.

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.

Topics in this section

• Automatic Update feature
• Triggered recalculation
• Recalculate manually

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.

92 PI DataLink 2019 User Guide

 Worksheet usage and maintenance

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.

See also
Manage PI DataLink settings from Excel
Activate Automatic Update
Cancel Automatic Update

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
Manage PI DataLink settings from Excel

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.
• Press 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 or chart 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.

PI DataLink 2019 User Guide 93

Worksheet usage and maintenance

Base PI DataLink functions on volatile Excel functions

You can maximize the refresh frequency and keep function arrays and charts current by basing
your PI DataLink functions on a volatile Excel 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 might impact
performance and make large worksheets difficult to use.

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.

Recalculate manually
At any time, you can manually recalculate PI DataLink functions.

Procedure
• 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 Data Archive 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.
• You can also save a worksheet as a web page or PDF file to share a static version of the
worksheet.

94 PI DataLink 2019 User Guide

 Worksheet usage and maintenance

• You can 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. See Common function array tasks.
• 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 (DLS)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.
2. In the Excel Options window, click Formulas.
3. Under Calculation options, set Workbook Calculation to Manual, and then click OK.

PI DataLink 2019 User Guide 95

Worksheet usage and maintenance

96 PI DataLink 2019 User Guide

Advanced topics
Topics in this discussion provide more in-depth information useful for work with PI DataLink
functions.

Topics in this section

• PI time
• Expressions
• Manual function entry
• Functions to write data

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.

Topics in this section

• PI time abbreviations
• PI time expressions
• Time-stamp specification
• Time-interval specification

PI time abbreviations
When specifying PI time, you can use specific abbreviations that represent time units and
reference times.
Time-unit abbreviations
Abbreviation Full version Plural version Corresponding time unit
s second seconds Second
m minute minutes Minute
h hour hours Hour
d day days Day
mo month months Month
y year years Year
w week weeks Week

To specify time units, you can specify the abbreviation, the full version, or the plural version of
the time unit, such as s, second, or seconds. You must include a valid value with any time unit.

PI DataLink 2019 User Guide 97

Advanced topics

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 Corresponding reference time
* Current time
t today 00:00:00 (midnight) of the current day
y yesterday 00:00:00 (midnight) of the previous day
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.
2: Use the first three letters as an abbreviation for any month of the year: jan, feb, mar, apr, may, jun,

jul, aug, sep, oct, nov, or dec.

PI time expressions
PI time expressions can include fixed times, reference-time abbreviations, and time offsets. A
time offset indicates the offset direction (either + or -) and the offset amount (a time-unit
abbreviation with a value).
For example, PI time expressions can have the following structure:
Structure Example
Fixed time only 24-aug-2012 09:50:00
Reference-time abbreviation only t
Time offset only +3h
Reference-time abbreviation with a time offset t+3h

Include at most one time offset in an expression; including multiple time offsets can lead to
unpredictable results.

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 current time.

98 PI DataLink 2019 User Guide

 Advanced topics

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

• 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 with a time offset

When included with 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

• Time offsets
Entered alone, time offsets specify a time relative to an implied reference time. The implied
reference time might be the current clock time or another time, depending on where you
enter the expression.
Input Meaning
-1d One day before the current time
+6h Six hours after the current time

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.
Start time 2:00:00
End time 3:15:00

PI DataLink 2019 User Guide 99

Advanced topics

Time interval 30m

Returned intervals 2:00:00 to 2:30:00
2:30:00 to 3:00: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.
Start time 2:00:00
End time 3:15:00
Time interval -30m
Returned intervals 2:15:00 to 2:45:00
2:45:00 to 3:15: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 Data Archive.
Note:
PI DataLink restricts data items that you can include in expressions. See Restrictions on
data items in expressions.
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 function
• Compressed Data function
• Sampled Data function
• Timed Data function
• Calculated Data function
• Time Filtered function
Subsequent sections describe basic information about expressions. PI DataLink supports all
the syntax, operators, and functions that PI Data Archive supports.
For a full description of performance equations and examples, see the PI Server topic
"Performance Equations syntax and functions reference" in Live Library (https://
livelibrary.osisoft.com).

Topics in this section

• Use expressions in PI DataLink functions
• Expression syntax

100 PI DataLink 2019 User Guide

 Advanced topics

• Expressions in Excel cells

• Cell references in expressions
• Restrictions on data items in expressions
• Expression examples
• Filter expressions

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 start

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 a complete expression.
You must use a cell reference in the following cases:
◦ To enter multiple expressions for a function
In the Expression(s) field, enter a range of cells that contain complete expressions.
◦ To enter an expression that includes an Excel function or Excel calculation operator, such
as the ampersand used to reference another cell
Enter these expressions in a cell as an Excel formula.
Tip:
Expressions entered with cell references are easier to view and edit. Make future
worksheet maintenance easier by using cell references to enter expressions.

Expression syntax
Follow these guidelines when writing expressions:
• Enclose any PI point or PI AF attribute names in single quotes.
'sinusoid'>1
• Enclose any time expression in single quotes.
't'
'11-Apr-17'
• Enclose any string values or digital states in double quotes.
'stringtag'="ACME"

PI DataLink 2019 User Guide 101

Advanced topics

Expressions in Excel cells

When entering an expression in an Excel cell, use the appropriate method:

• Excel string
Enter a single quote followed by the expression. This results in two single quotes in
succession for expressions that begin with a PI point or PI AF attribute name.
'abs('sinusoid')>1
''sinusoid'>1
The single quote forces Excel to interpret the expression as a string.
Use this method only if the expression contains no Excel functions or calculation operators
(including those used for cell references in expressions).

• Excel formula
Enter an equal sign followed by the expression within double quotes.
=" abs('sinusoid') > 1"
=" 'sinusoid' > 1"
Use this method if the expression contains an Excel function or calculation operator, such as
the ampersand used for cell references in expressions.
This method can be used for any expression.

Cell references in expressions

To include a cell reference within an expression, you must specify the expression in an Excel
cell. (In task-pane fields, you can only use a cell reference to specify the entry for the entire
field.)
In the Excel cell, enter the expression as an Excel formula following this approach:
• Split the expression into the strings before and after the cell references.
• Concatenate all the strings with the ampersand (&) calculation operator. At calculation,
Excel combines the strings before and after the ampersand to create a single string.

Examples
• Cell reference for single value
Suppose you want an expression that returns true when the PI point specified in cell B6 is
greater than 0:
'Point in B6' > 0
In the cell where you want to store the expression, enter:
="'" & B6 & "' > 0"
Excel resolves the formula based on the value of the cell B6, such as the point sinusoid. In
a PI DataLink function, you can reference this cell in any expression field that requires a
Boolean expression.

102 PI DataLink 2019 User Guide

 Advanced topics

• Cell references for multiple inputs to performance-equation function

Suppose you want an expression that uses the TimeGT performance-equation function with
inputs from an Excel worksheet.

This function finds the total time that a PI point is above a particular value. In the
worksheet, cell B6 contains the point, B7 the start time, B8 the end time, and B9 the value.
The start and end times are entered as PI time expressions. The equivalent expression is:
TimeGT('Point in B6','Time in B7','Time in B8',Value in B9)
In the cell where you want to store the expression, enter:
= "TimeGT('" & B6 & "','" & B7 & "','" & B8 & "'," & B9 & ")"
Excel resolves the formula based on the value of the cells.

• Excel-function and cell-reference inputs to performance equation function

Suppose you want to use the same performance-equation function but the time inputs use a
non-PI time format.

In this case, the time is entered as a string in a specific format. You can use the Excel TEXT
function to convert the time strings into a date. The equivalent expression is:
TimeGT('Point in B14','TEXT(B15,"DD-MMM-YYYY HH:MM:SS")','TEXT(B16,"DD-
MMM-YYYY HH:MM:SS")',Value in B17)
In the cell where you want to store the expression, enter:
="TimeGT('" & B14 & "','" & TEXT(B15,"DD-MMM-YYYY HH:MM:SS") & "','" &
TEXT(B16,"DD-MMM-YYYY HH:MM:SS") & "'," & B17 & ")"
Excel resolves the formula based on the value of the cells.

PI DataLink 2019 User Guide 103

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 Data Archive server.
Therefore, any PI points in an expression, including those referred to by PI AF attributes, must
be stored on the same PI Data Archive server. Similarly, PI points in a filter expression must be
stored on the same PI Data Archive server as any PI points specified by the Data item or
Expression fields.

Expression examples
The following examples show expressions that evaluate data items and manipulate or do
calculations on the values of data items:

• Arithmetic operation on PI points

('sinusoid')^3 + 'cdf144'/10
Returns the sum of the value of the PI point sinusoid cubed and the value of the PI point
cdf144 divided by 10.

• Boolean evaluation of PI point

abs('mytag') >= 14.65
Returns true (non-zero) if the absolute value of the PI point mytag is at least 14.65.

• Boolean evaluation of PI AF attribute

'\\Server\Database\Element|Manufacturer' = "ACME"
Returns true if the value of the PI AF attribute Manufacturer is ACME.

• Complex Boolean evaluation of simultaneous condition of two PI points

'sinusoid' < 45 and sqr('vdf1002') > 2
Returns 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.

• Evaluation of digital-state point

StateNo('BA:Phase.1')
Returns the digital state number (also known as the digital state code) of the digital point
BA.Phase.1 rather than returning the digital state value of the point.

104 PI DataLink 2019 User Guide

 Advanced topics

Filter expressions
Use a filter expression in a PI DataLink function to filter recorded 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 equal to or greater than 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 recorded 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.

Manual function entry

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 into the formula bar.

Topics in this section

• Define functions manually
• Guidelines for entering arguments manually
• Output codes

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 Microsoft Excel online help 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:

PI DataLink 2019 User Guide 105

Advanced topics

Data entered as argument Guideline

Standard functions You can include various functions in arguments that accept
expressions. For a list of functions, see the PI Server topic "Built-in
performance equation functions" in Live Library (https://
livelibrary.osisoft.com).
Strings Surround string arguments with double quotes. For example, to
retrieve the snapshot time and value for the PI point sinusoid from
the PI Data Archive server named casaba, select a 1 x 2 output array
and enter:
=PICurrVal("sinusoid", 1, "casaba")

Expressions Surround expression arguments with double quotes. Within the

expression, surround PI point or PI AF attribute names with single
quotes and surround string values or digital states with two double
quotes.
For example, to enter an expression that returns a value of true
when the PI point cdm158 equals Manual, type:
"'cdm158'=""Manual"""

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")
To specify no root path, such as if the data item is a PI point on the
default PI Data Archive server, enter two double quotes:
""
See Data items for information about valid entries.

Output codes Determines what appended data the function returns and how the
function orients output. See Output codes.

Output codes
PI DataLink function syntax contains an integer OutCode argument. This argument takes an
output code that determines which appended data the function returns and the orientation of
output cells.

106 PI DataLink 2019 User Guide

 Advanced topics

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
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 the OutCode argument set to 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 values.)
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 for
the bits that each function supports in its OutCode specification.

PI DataLink 2019 User Guide 107

Advanced topics

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:

In the Excel formula bar, enter:

=PIAdvCalcDat("sinusoid","y","t","1h","minimum","time-weighted", 50, 1,
325,"MyDataServer")
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 PI Data Archive or PI AF, the
PIPutVal() and PIPutValX() functions write values from a worksheet to PI Data Archive or
PI AF. The PIPutVal() and PIPutValX() functions can replace existing values at particular
time stamps with new user-supplied values. You must run the PIPutVal() or PIPutValX()
function from a macro-enabled workbook.
You can use the example workbooks distributed with PI DataLink to write data to PI Data
Archive or PI AF. See Write data to PI Data Archive or PI AF.

See also
PIPutVal() and PIPutValX()

Write data to PI Data Archive or PI AF

Use the example workbooks distributed with PI DataLink to write data to PI Data Archive or PI
AF with the PIPutVal() and PIPutValX() functions.

108 PI DataLink 2019 User Guide

 Advanced topics

Tip:
For an example of how you can write Visual Basic for Applications (VBA) code to use
these functions, open the Visual Basic editor for the example workbook and examine the
PutVal_code module.

Procedure
1. Open the example workbook from the ../PIPC/Excel directory:
◦ piexam32.xls, distributed with PI DataLink for 32-bit Excel
◦ piexam64.xls, distributed with PI DataLink for 64-bit Excel
The sample workbooks contain one worksheet, PutVal. This worksheet has two sections.
The first section uses the PIPutVal function to enter values for multiple data items, each
with a different time stamp.The second section uses the PIPutValX function to enter values
for multiple data items with the same time stamp.
2. In the appropriate cells of the PutVal worksheet, enter the time stamp, data item, and value
that you want to write, as well as the root path that specifies the server for the entered data
items.

1. Time stamp
2. Data item
3. Value to write
4. Root path
Worksheet with values entered to write to server

3. Click the Send above values button to start the macro.

The macro uses either the PIPutVal() or PIPutValX() function to write the specified
values and record the responses, and then uses the PIArcVal function to return the values
stored on the server.

PI DataLink 2019 User Guide 109

Advanced topics

1. Response from PIPutVal function

2. Value retrieved with PIArcVal function
Worksheet after macro runs

110 PI DataLink 2019 User Guide

Tag functions
A PI point is a stream of real-time data from a defined source. Point attributes, including Tag
(that is, the PI point name) and point source, describe a PI point.
Use PI DataLink tag functions to find points 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).

See also
Overview of PI DataLink functions
Properties function
Trends

Topics in this section

• Point ID to Tag function
• Attribute Mask to Tag function
• Search for PI points

Point ID to Tag function

The Point ID to Tag function returns the name of the PI point that corresponds to a specific
point ID.
Input Description
PI Data Archive The PI Data Archive 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
Data Archive server.
Point ID(s) One or more point IDs for which you want the function to return point names.
Required.
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.

See also
PIPointIDToTag()

PI DataLink 2019 User Guide 111

Tag functions

Point ID to Tag example

To see the name of the PI point that corresponds to a 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)

The function returns the following array:

In this case, 1 is the point ID and SINUSOID is the returned point name.

Attribute Mask to Tag function

The Attribute Mask to Tag function returns the names of PI points that match one or more
specified point attribute values.
Input Description
PI Data Archive The PI Data Archive 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
Data Archive server.
Tagname(s) PI point attribute value for which the function finds the corresponding point
Descriptor name. You must enter a value in at least one input. Use the wildcard character
(*) to find all matches or matches limited to specified characters. For
Point source example, enter S* in Point source to find any point with a point source of S or
Point type a point source that begins with S.
Point class
Engineering units
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.
Column Click this option to return values in a column.
Row Click this option to return values in a row.

See also
PIAttributeMaskToTag ()

112 PI DataLink 2019 User Guide

 Tag functions

Attribute Mask to Tag example

To see the PI points of type Float32 and that have a name that starts with BA, set the following
inputs for the Attribute Mask to Tag function:
Input Value
Tagname BA*
Point type Float32

The function returns the following array:

Note that you can use wildcards. The entered strings must match attribute values in PI Data
Archive.

Search for PI points

For tag-information functions, use the Tag Search window to query PI Data Archive for the IDs
or names of PI points 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 points 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 points by their descriptive aliases in the PI Module Database.
3. Enter the search criteria.
Use * or ? as wildcard characters, as appropriate. For example, set the Tag Mask field to
Tem* to return all point names that start with Tem, but set the field to Tem? to return 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.

PI DataLink 2019 User Guide 113

Tag functions

5. Click Search to find points that match the specified criteria.

6. Select the desired point in the results pane, and click OK to insert the value in the task pane.

114 PI DataLink 2019 User Guide

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 recorded 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 Microsoft
Excel add-in configuration).

Topics in this section

• Create a trend
• Trend right-click menu

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.
3. Define one or more traces to include in the trend. You can:
◦ Create a trace of values in the worksheet.
◦ Create a trace of PI point values retrieved from PI Data Archive.

PI DataLink 2019 User Guide 115

Trends

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 Data Archive
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 worksheet cell
that contains a time string or type the address of that worksheet cell
See PI time for a discussion of valid time strings.
b. Select the Enable Updates check box to refresh the trend with new PI Data Archive 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 recorded values 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.

116 PI DataLink 2019 User Guide

 Trends

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 PI Data Archive

When creating a trend with the Trend Add-in Wizard, you can define a trace for the trend from
values retrieved from PI Data Archive.

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 points (see
Search for PI points).
3. In the Server name field, specify the PI Data Archive 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.

PI DataLink 2019 User Guide 117

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.

118 PI DataLink 2019 User Guide

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 Data Archive documentation for more information about module databases
and configuration.
Note:
You must activate the PI DataLink (Legacy) add-in to use these tools (see Microsoft Excel
add-in configuration).

Topics in this section

• PI Module Database and worksheets
• Insert PI Module Database objects into your worksheet
• Module database functions

PI Module Database and worksheets

The PI Module Database is a hierarchical tree structure based on the contents of PI Data
Archive. The PI Module Database provides an entirely different way to build the infrastructure
of a worksheet. If the module database on your PI Data Archive is configured and includes
objects that represent the PI points 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 name (Tag attribute) 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 point names and other 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.

PI DataLink 2019 User Guide 119

PI Module Database objects

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 Data Archive list, select the connected PI Data Archive 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 Data Archive name setting (see Manage PI DataLink settings from Excel)
is enabled, PI DataLink also copies the corresponding PI Data Archive server name.
8. Click OK to copy the selected items to the worksheet and close the window.

Module database functions

Use PI DataLink module database functions to find the PI points 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 PI point without a module
path. The path provides a context that maps the alias to a specific PI point.

See also
Overview of PI DataLink functions

Topics in this section

• Alias to Tag function

120 PI DataLink 2019 User Guide

 PI Module Database objects

• Property to Value function

Alias to Tag function

The Alias to Tag function returns the name of the PI point that corresponds to a specified PI
alias.
Input Description
PI Data Archive The PI Data Archive 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
Data Archive server.
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 point that corresponds
to the specified alias on this date.
Required.
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.
The PI Data Archive 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
Data Archive server.
No server Choose to return only the PI point name.
Server at right Choose to display the PI Data Archive server that stores the point in the cell
to the right of the point name.
Server at bottom Choose to display the PI Data Archive server that stores the point in the cell
below the point name.

See also
PIAliasToTag()

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.

PI DataLink 2019 User Guide 121

PI Module Database objects

Input Description
PI Data Archive The PI Data Archive 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
Data Archive server.
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 value of the
specified property on this date.
Required.
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.
Column Click this option to return values in a column.
Row Click this option to return values in a row.

See also
PIPropertyToValue()

122 PI DataLink 2019 User Guide

Function reference
You can generate PI DataLink functions from PI DataLink task panes (see Overview of PI
DataLink functions). The resulting function array depends on the inputs. You can also enter
these same functions directly in the Excel formula bar (see Manual function entry).
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.

Topics in this section

• Single-value functions
• Multiple-value functions
• Calculation functions
• Tag functions reference
• Module database functions reference
• Input functions
• Deprecated functions

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.

Topics in this section

• PICurrVal()
• PIArcVal()
• PIExpVal()
• PITagAtt()

PICurrVal()
Returns the most recent value of a historical PI point or PI AF attribute. For a future PI point,
the value returned depends on the time stamps of recorded values relative to the current time:
• If all recorded values have time stamps before the current time, the function returns the last
recorded value.
• If recorded values have time stamps that straddle the current time, the function returns an
interpolated value.
• If all recorded values have time stamps after the current time, the function returns no data.
This function supports bulk calls.

PI DataLink 2019 User Guide 123

Function reference

Syntax
PICurrVal(DataItem, OutCode, RootPath)

Arguments
Argument Type Description
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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes for information
on how to compute the code. This function
supports bits 1 and 2.
RootPath String The path to the data item referenced by the
expression. See Data items.

Examples
=PICurrVal("let439",1,"holden")

Returns the current value and corresponding time stamp for the PI point let439 from the PI
Data Archive server named holden and places the time stamp in the column to the left of the
value.

See also
Current Value function
Define functions manually
Guidelines for entering arguments manually
Retrieval of large amounts of data
Interpolated values

PIArcVal()
Returns the value of a PI point or PI AF attribute at a specified time stamp. This function
supports bulk calls.

Syntax
PIArcVal(DataItem, TimeStamp, OutCode, RootPath, Mode)

Arguments
Argument Type Description
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.

124 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes 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.
Mode String The method the function uses to retrieve values:
• previous
• previous only
• interpolated
• auto
• next
• next only
• exact time

Examples
=PIArcVal("cdep158","11-dec-92 19:20",0, "casaba","interpolated")

Returns the interpolated value of the PI point cdep158 at 7:20 p.m. on December 11, 1992
from the PI Data Archive server named casaba.

See also
Archive Value function
Define functions manually
Guidelines for entering arguments manually
Interpolated values
Retrieval of large amounts of data

PIExpVal()
Returns the computed value of a performance equation at a specified time stamp.

Syntax
PIExpVal(Expression, TimeStamp, OutCode, RootPath)

Arguments
Argument Type Description
Expression String One or more performance equations that the function
computes a value for. See Expressions.
To specify multiple expressions, enter a range of cells that
contain complete expressions. The function returns values for
each.

TimeStamp String The time stamp for which the function returns values. See
Time inputs.

PI DataLink 2019 User Guide 125

Function reference

Argument Type Description

OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 1 and 2.
RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PIExpVal("sqr('sinusoid')","y",0,"thevax")

Calculates the square root of the value of the PI point sinusoid from the PI Data Archive
server named thevax at midnight yesterday.

See also
Archive Value function
Define functions manually
Guidelines for entering arguments manually

PITagAtt()
Returns a property value associated with a specified data item.

Syntax
PITagAtt(DataItem, Property, RootPath)

Arguments
Argument Type Description
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.
Property String The PI point attribute or PI AF attribute property
for which the function returns the value.
RootPath String The path to the data item. See Data items.

Examples
=PITagAtt(d1,"uom","")

Returns the engineering units for the PI point specified in cell D1 from the default PI Data
Archive server.

See also
Properties function

126 PI DataLink 2019 User Guide

 Function reference

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.

Topics in this section

• PINCompDat()
• PINCompFilDat()
• PICompDat()
• PICompFilDat()
• PISampDat()
• PISampFilDat()
• PIExpDat()
• PITimeDat()
• PITimeExpDat()

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
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
NumVals Integer The number of values that the function returns,
beginning at STime (specify a negative number to
retrieve values backward in time).
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes for information
on how to compute the code. This function
supports bits 1, 2, 5, and 6.
RootPath String The path to the data item. See Data items.

PI DataLink 2019 User Guide 127

Function reference

Argument Type Description

Mode String The method that the function uses to determine
which values to retrieve near the start time
(boundary type):
• inside
• outside
• interpolated
• auto

Examples
=PINCompDat("sinusoid","1:00:00",10,1,"","inside")

Returns ten values and the corresponding time stamps from the default PI Data Archive server
for the PI point sinusoid starting from 1:00 a.m. this morning, using boundary type inside.

See also
Compressed Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
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 values. When the expression
evaluates to false, the function excludes
corresponding values. See Filter expressions.

128 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes for information
on how to compute the code. This function
supports bits 1, 2, 5, and 6.
RootPath String The path to the data item. See Data items.
Mode String The method that the function uses to determine
which values to retrieve near the start time
(boundary type):
• inside
• outside
• interpolated
• auto

Examples
=PINCompFilDat("sinusoid","2:00:00",10,"'cdep158'>38",1,1,"","inside")

Returns ten values and the corresponding time stamps from the default PI Data Archive server
for the PI point sinusoid starting from 2:00 a.m. this morning, when the point cdep158 is
greater than 38, using boundary type inside.
The output contains the label Filtered between any values where the filter condition was
false.

See also
Compressed Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

PICompDat()
Returns PI point values or PI AF attribute values stored during a specified time period.

Syntax
PICompDat(DataItem, STime, ETime, OutCode, RootPath, Mode)

PI DataLink 2019 User Guide 129

Function reference

Arguments
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
ETime String The end of the time period for which the function
returns values. See Time inputs.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes for information
on how to compute the code. This function
supports bits 1, 2, 4, 5, and 6.
RootPath String The path to the data item. See Data items.
Mode String The method that the function uses to determine
which values to retrieve near the start time
(boundary type):
• inside
• outside
• interpolated
• auto

Examples
=PICompDat("sinusoid","1:00:00","3:00:00",1,"","inside")

Returns values and corresponding time stamps from the default PI Data Archive server for the
PI point sinusoid from 1:00a.m. to 3:00 a.m. this morning using boundary type inside.

See also
Compressed Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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)

130 PI DataLink 2019 User Guide

 Function reference

Arguments
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
ETime String The end of the time period for which the function
returns values. See Time inputs.
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.
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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes for information
on how to compute the code. This function
supports bits 1, 2, 4, 5, and 6.
RootPath String The path to the data item. See Data items.
Mode String The method that the function uses to determine
which values to retrieve near STime or ETime
(boundary type):
• inside
• outside
• interpolated
• auto

Examples
=PICompFilDat("sinusoid","2:00:00","10:00:00","'cdep158'>38",1,1,"","inside")

Returns values and the corresponding time stamps for the PI point sinusoid from the default
PI Data Archive server, starting at 2:00 a.m. and ending at 10:00a.m., when the PI point
cdep158 is greater than 38, using boundary type inside.
The output contains the label Filtered between any values where the filter condition was
false.

See also
Compressed Data function

PI DataLink 2019 User Guide 131

Function reference

Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
ETime String The end of the time period for which the function
returns values. See Time inputs.
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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes 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.

Examples
=PISampDat("sinusoid","y","t","3h",1,"")

Returns sampled data and the corresponding time stamps for the PI point sinusoid from the
default PI Data Archive server, beginning at midnight yesterday and ending at midnight today,
reporting values in 3-hour intervals.

See also
Sampled Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

132 PI DataLink 2019 User Guide

 Function reference

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)

Arguments
Argument Type Description
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.
STime String The start of the time period for which the function
returns values. See Time inputs.
ETime String The end of the time period for which the function
returns values. See Time inputs.
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.
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.
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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes 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.

Examples
=PISampFilDat("sinusoid","11-Jan-1997","+3h","1h",A1,1,1,"")

Returns sampled data for the PI point sinusoid from the default PI Data Archive 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

PI DataLink 2019 User Guide 133

Function reference

function returns the label Filtered at that time. The function shows time stamps in the first
column and values in the second column.

See also
Sampled Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

PIExpDat()
Returns evenly-spaced, computed values of a performance equation over a specified time
period.

Syntax
PIExpDat(Expression, STime, ETime, Interval, OutCode, RootPath)

Arguments
Argument Type Description
Expression String One or more performance equations that the
function computes a value for. See Expressions.
To specify multiple expressions, enter a range of
cells that contain complete expressions. The
function returns values for each.

STime String The start of the time period for which the function
calculates a value. See Time inputs.
ETime String The end of the time period for which the function
calculates a value. See Time inputs.
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.
OutCode Integer An output code that determines what appended
data the function returns and how the function
orients output. See Output codes 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.

Examples
=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax")

Calculates the square root of the value of the PI point sinusoid retrieved from the PI Data
Archive server named thevax at one-hour intervals, starting from midnight yesterday to
midnight today.

134 PI DataLink 2019 User Guide

 Function reference

The function displays the time stamp for each value in the column to the left of the calculated
value.

See also
Sampled Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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
Argument Type Description
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.
RootPath String The path to the data item. See Data items.
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.

Examples
=PITimeDat("sinusoid",b1:b12,"","interpolated")

Retrieves interpolated values at the time stamps located in cells B1 through B12 for the PI
point sinusoid on the default PI Data Archive server.
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.

See also
Timed Data function

PI DataLink 2019 User Guide 135

Function reference

Define functions manually

Guidelines for entering arguments manually
Interpolated values

PITimeExpDat()
Returns values of a performance equation calculated at specified time stamps.

Syntax
PITimeExpDat(Expression, TimeStamps, RootPath)

Arguments
Argument Type Description
Expression String One or more performance equations that the
function computes a value for. See Expressions.
To specify multiple expressions, enter a range of
cells that contain complete expressions. The
function returns 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.
RootPath String The path to the data item. See Data items.

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.

Examples
=PITimeExpDat("sqr('sinusoid')",b1:b12,"")

Calculates the square root of the value of the PI point sinusoid retrieved from the default PI
Data Archive server at the times specified in cells B1 through B12.
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.

See also
Timed Data function
Define functions manually
Guidelines for entering arguments manually

Calculation functions
Calculation functions compute values from PI point values, PI AF attributes, or performance
equation evaluations during a specific time period.

136 PI DataLink 2019 User Guide

 Function reference

Topics in this section

• PIAdvCalcVal()
• PIAdvCalcFilVal()
• PIAdvCalcExpVal()
• PIAdvCalcExpFilVal()
• PIAdvCalcDat()
• PIAdvCalcFilDat()
• PIAdvCalcExpDat()
• PIAdvCalcExpFilDat()
• PITimeFilter()
• PITimeFilterVal()

PIAdvCalcVal()
Returns a value calculated from PI point or PI AF attribute values during a specified time
period. This function supports bulk calls.

Syntax
PIAdvCalcVal(DataItem, STime, ETime, Mode, CalcBasis, MinPctGood, CFactor,
OutCode, RootPath)

Arguments
Argument Type Description
DataItem String The PI point name or PI AF attribute name for which the
function 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.
ETime String The end of the time period for which the function calculates a
value. See Time inputs.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted

PI DataLink 2019 User Guide 137

Function reference

Argument Type Description

MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, and 9 (if Mode is set to
minimum, maximum, or range).
RootPath String The path to the data item. See Data items.

Examples
=PIAdvCalcVal("sinusoid","y","t","total","time-weighted",50,1,4,"")

Returns a time-weighted total of the PI point sinusoid calculated from the values on the
default PI Data Archive server from yesterday to today.
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.

See also
Calculated Data function
Define functions manually
Guidelines for entering arguments manually
Retrieval of large amounts of data

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
Argument Type Description
DataItem String The PI point name or PI AF attribute name for which the
function 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.
ETime String The end of the time period for which the function calculates a
value. See Time inputs.

138 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• 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 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
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, and 9 (if Mode is set to
minimum, maximum, or range).
RootPath String The path to the data item. See Data items.

Examples
=PIAdvCalcFilVal("sinusoid","y","t","'cdm158'=""Manual""","total","time-
weighted","compressed","10m",50,1,4,"")

Returns the time-weighted total for the PI point sinusoid calculated from the values on the
default PI Data Archive server, summing values from yesterday to today during the time
periods when the PI point cdm158 is set to Manual.
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

PI DataLink 2019 User Guide 139

Function reference

events of the point sinusoid. 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.

See also
Calculated Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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
Argument Type Description
Expression String One or more performance equations that the function
computes a value for. See Expressions.
To specify multiple expressions, enter a range of cells that
contain complete expressions. The function returns values for
each.

STime String The start of the time period for which the function calculates
a value. See Time inputs.
ETime String The end of the time period for which the function calculates a
value. See Time inputs.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
SampMode String The sampling method the function uses to determine when to
evaluate Expression:
• compressed
• interpolated

140 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

SampFreq String The frequency that the function evaluates Expression 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
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, and 9 (if Mode is set to
minimum, maximum, or range).

RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PIAdvCalcExpVal("'sinusoid'+'cdt158'","y","t","total","time-
weighted","compressed","10m",50,1,4,"")

Returns the time-weighted total for the expression 'sinusoid'+'cdt158' calculated from
the values on the default PI Data Archive server, using values from yesterday to today.
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 combined
compressed events of sinusoid 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.

See also
Calculated Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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)

PI DataLink 2019 User Guide 141

Function reference

Arguments
Argument Type Description
Expression String One or more performance equations that the function
computes a value for. See Expressions.
To specify multiple expressions, enter a range of cells that
contain complete expressions. The function returns values for
each.

STime String The start of the time period for which the function calculates
a value. See Time inputs.
ETime String The end of the time period for which the function calculates a
value. See Time inputs.
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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
SampMode String The sampling method the function uses to determine when to
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.
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, and 9 (if Mode is set to
minimum, maximum, or range).

142 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PIAdvCalcExpFilVal("'sinusoid'+'sinusoidu'","y","t","'cdm158'=""Manual""","total
","time-weighted","compressed","10m",50,1,4,"")

Returns the time-weighted total for the expression 'sinusoid'+'sinusoidu' calculated

from the values on the default PI Data Archive server when the PI point cdm158 is set to
Manual using values from yesterday to today.
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 combined
compressed events of sinusoid and sinusoidu. 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.

See also
Calculated Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

PIAdvCalcDat()
Returns evenly spaced values calculated from PI point or PI AF attribute values during a
specified time period.

Syntax
PIAdvCalcDat(DataItem, STime, ETime, Interval, Mode, CalcBasis, MinPctGood,
CFactor, OutCode, RootPath)

Arguments
Argument Type Description
DataItem String The PI point name or PI AF attribute name for which the
function 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.
ETime String The end of the time period for which the function calculates
values. See Time inputs.

PI DataLink 2019 User Guide 143

Function reference

Argument Type Description

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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, 7, 8, and 9 (if Mode is set to
minimum, maximum, or range).

RootPath String The path to the data item. See Data items.

Examples
=PIAdvCalcDat("sinusoid","y","t","3h","total","time-weighted",50, 1,4,"")

Returns the time-weighted total for the PI point sinusoid calculated from the values on the
default PI Data Archive server for three-hour intervals from midnight yesterday to midnight
today.
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.

See also
Calculated Data function
Define functions manually
Guidelines for entering arguments manually

144 PI DataLink 2019 User Guide

 Function reference

PIAdvCalcFilDat()
Returns evenly spaced values calculated from filtered PI point or PI AF attribute values during
a specified time period.

Syntax
PIAdvCalcFilDat(DataItem, STime, ETime, Interval, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)

Arguments
Argument Type Description
DataItem String The PI point name or PI AF attribute name for which the
function 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.
ETime String The end of the time period for which the function calculates
values. See Time inputs.
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.
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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
SampMode String The sampling method the function uses to determine when to
evaluate FiltExp:
• compressed
• interpolated

PI DataLink 2019 User Guide 145

Function reference

Argument Type Description

SampFreq String The frequency that the function evaluates 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
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, 7, 8, and 9 (if Mode is set to
minimum, maximum, or range).

RootPath String The path to the data item. See Data items.

Examples
=PIAdvCalcFilDat("sinusoid","y","t","3h","'cdm158'=""Manual""","total","time-
weighted","compressed","10m",50,1,4,"")

Returns the time-weighted total for the PI point sinusoid, calculated from the values on the
default PI Data Archive server for three-hour intervals from midnight yesterday to midnight
today when PI point cdm158 is set to Manual.
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 sinusoid. 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.

See also
Calculated Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

PIAdvCalcExpDat()
Returns evenly spaced values calculated from a performance equation during a specified time
period.

Syntax
PIAdvCalcExpDat(Expression, STime, ETime, Interval, Mode, CalcBasis,SampMode,
SampFreq, MinPctGood, CFactor, OutCode, RootPath)

146 PI DataLink 2019 User Guide

 Function reference

Arguments
Argument Type Description
Expression String One or more performance equations that the function
computes a value for. See Expressions.
To specify multiple expressions, enter a range of cells that
contain complete expressions. The function returns values for
each.

STime String The start of the time period for which the function calculates
values. See Time inputs.
ETime String The end of the time period for which the function calculates
values. See Time inputs.
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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
SampMode String The sampling method the function uses to determine when to
evaluate Expression:
• compressed
• interpolated
SampFreq String The frequency that the function evaluates Expression 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
MinPctGood Number The minimum percentage of good data required during the
time 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).

PI DataLink 2019 User Guide 147

Function reference

Argument Type Description

OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, 7, 8, and 9 (if Mode is set to
minimum, maximum, or range).

RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PIAdvCalcExpDat("'sinusoid'+'cdt158'","y","t","3h","total","time-
weighted","compressed","10m",50,1,4,"")

Computes the expression 'sinusoid'+'cdt158' at any time stamp between midnight

yesterday and midnight today with a recorded value stored on the default PI Data Archive
server, and then calculates the time-weighted total of the computed values in three-hour
intervals.
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 sinusoid or
cdt158 has a recorded value stored.

See also
Calculated Data function
Define functions manually
Guidelines for entering arguments manually
Interpolated values

PIAdvCalcExpFilDat()
Returns evenly spaced values calculated from a filtered performance equation during a
specified time period.

Syntax
PIAdvCalcExpFilDat(Expression, STime, ETime, Interval, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)

Arguments
Argument Type Description
Expression String One or more performance equations that the function
computes a value for. See Expressions.
To specify multiple expressions, enter a range of cells that
contain complete expressions. The function returns values for
each.

STime String The start of the time period for which the function calculates
values. See Time inputs.

148 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

ETime String The end of the time period for which the function calculates
values. See Time inputs.
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.
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.
Mode String The type of calculation that the function performs:
• total
• minimum
• maximum
• stdev
• range
• count
• average (time-weighted)
• average (event-weighted)
CalcBasis String The calculation method:
• time-weighted
• event-weighted
SampMode String The sampling method the function uses to determine when to
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.
MinPctGood Number The minimum percentage of good data required during the
time 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).
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, 7, 8, and 9 (if Mode is set to
minimum, maximum, or range).

RootPath String The path to the data item referenced by the expression. See
Data items.

PI DataLink 2019 User Guide 149

Function reference

Examples

=PIAdvCalcExpFilDat("'sinusoid'+'cdt158'","y","t","3h","'cdm158'=""Manual""","tot
al","time-weighted","compressed","10m",50,1,4,"")

Calculates a time-weighted total for the expression 'sinusoid'+'cdt158' when 'cdm158'

= "Manual" at three-hour intervals from yesterday to today from the default PI Data Archive
server.
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 sinusoid or
cdt158 has a recorded value or the value of cdm158 changes to or from Manual.

See also
Calculated Data function
Filter expressions
Define functions manually
Guidelines for entering arguments manually
Interpolated values

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
Argument Type Description
Expression String A Boolean performance equation that the function evaluates.
See Expressions.
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
values. See Time inputs.
ETime String The end of the time period for which the function calculates
values. See Time inputs.
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.

150 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

TimeUnit String Time unit of the calculated result:
• seconds
• minutes
• hours
• days
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2, 3, 7, and 8.

RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PITimeFilter($A$1,"y","t","1h","seconds",65,"thevax")

Returns the number of seconds that the expression in cell A1 is true on the PI Data Archive
server named thevax during one-hour intervals, starting from midnight yesterday to midnight
today.
The function shows the time stamp of the start of each calculation interval to the left of the
value.

See also
Time Filtered function
Define functions manually
Guidelines for entering arguments manually

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
Argument Type Description
Expression String A Boolean performance equation that the function evaluates.
See Expressions.
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. See Time inputs.
ETime String The end of the time period for which the function calculates a
value. See Time inputs.

PI DataLink 2019 User Guide 151

Function reference

Argument Type Description

TimeUnit String Time unit of the calculated result:
• seconds
• minutes
• hours
• days
OutCode Integer An output code that determines what appended data the
function returns and how the function orients output. See
Output codes for information on how to compute the code.
This function supports bits 2 and 3.

RootPath String The path to the data item referenced by the expression. See
Data items.

Examples
=PITimeFilterVal($A$1,"y","t","seconds",0,"thevax")

Returns the number of seconds that the expression in cell A1 is true on the PI Data Archive
server named thevax from midnight yesterday to midnight today.

See also
Time Filtered function
Define functions manually
Guidelines for entering arguments manually

Tag functions reference

Tag functions help you work with PI points.

Topics in this section

• PIPointIDToTag()
• PIAttributeMaskToTag ()

PIPointIDToTag()
Returns the name of the PI point that corresponds to a specific PI point ID.

Syntax
PIPointIDToTag(PointID, Server)

Arguments
Argument Type Description
PointID String A PI point ID, which is a unique internal ID that is not reused
when a point is deleted.

152 PI DataLink 2019 User Guide

 Function reference

Argument Type Description

Server String The PI Data Archive 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 Data Archive server.

Examples
=PIPointIDToTag("123","thevax")

Searches the PI Data Archive server named thevax for point ID 123, and returns that point's
name (the Tag attribute).

See also
Point ID to Tag function

PIAttributeMaskToTag ()
Returns the names of PI points that match one or more specified PI point attribute values.

Syntax
PIAttributeMaskToTag(TagName, Descriptor, PointSource, PointType, PointClass,
EngUnits, OutCode, Server)

Arguments
Argument Type Description
TagName String Name of returned points.1
Descriptor String Descriptor of returned points.1
PointSource String Point source of returned points.1
PointType String Point type of returned points.1
PointClass String Point class of returned points.1
EngUnits String Engineering units of returned points.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.
Server String The PI Data Archive 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 Data Archive server.
1 Use wildcard character (*) to find all matches or matches limited to specified characters.

Examples
=PIAttributeMaskToTag("sin*","*","*","*","*","*",0,"thevax")

PI DataLink 2019 User Guide 153

Function reference

Returns the names of points that start with sin from the PI Data Archive server named
thevax.

See also
Attribute Mask to Tag function

Module database functions reference

Module database functions find the PI points that correspond to aliases and properties in a
module database tree.

Topics in this section

• PIAliasToTag()
• PIPropertyToValue()

PIAliasToTag()
Returns the name of the PI point that corresponds to a specified PI alias.

Syntax
PIAliasToTag(Alias, ModulePath, QueryDate, OutCode, Server)

Arguments
Argument Type Description
Alias String The module database alias that corresponds to the PI point to
return.
ModulePath String The full module path to the alias
QueryDate Integer An effective date of the alias. The function returns the name
of the point that 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 point name.
• 1
Returns the PI Data Archive server that stores the point in
the cell to the right of the point name.
• 2
Returns the PI Data Archive server that stores the point in
the cell below the point name.
Server String The PI Data Archive 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 Data Archive server.

Examples
=PIAliasToTag("Temperature","\Unit1\Reactor1","*",0,"thevax")

154 PI DataLink 2019 User Guide

 Function reference

Returns the name of the PI point 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
Data Archive server named thevax. The module database is queried at the current time.

See also
Alias to Tag function

PIPropertyToValue()
Returns the value or values corresponding to a specified PI property.

Syntax
PIPropertyToValue(Property, ModulePath, QueryDate, Server, OutCode)

Arguments
Argument Type Description
Property String The module database property that corresponds to the PI
point for which the function retrieves values.
ModulePath String The full module path to the property.
QueryDate Integer An effective date of the PI property value. The function
returns the values that correspond to the specified property
on this date.
Server String The PI Data Archive 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 Data Archive 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.

Examples
=PIPropertyToValue("Implementer","\Unit1\Reactor1","*","thevax")

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 Data Archive server
named thevax. The module database is queried at the current time.

See also
Property to Value function

Input functions
Input functions write values to PI Data Archive or PI AF.

PI DataLink 2019 User Guide 155

Function reference

PIPutVal() and PIPutValX()

Writes a value to the PI Data Archive server or PI AF server and returns a string that indicates
the status.
Note:
• Only use the PIPutVal and PIPutValX functions within Visual Basic for Applications
(VBA). Do not enter these functions in the Excel formula bar. See Functions to write
data.
• In the current version of PI DataLink, there is no difference between the PIPutVal
function and the PIPutValX function. In PI DataLink versions earlier than PI DataLink
2013, the PIPutVal function only supported three traditional PI point types: real,
integer, and digital. In those versions of PI DataLink, the PIPutValX function added
support for string points and subsecond time stamps.

Syntax
PIPutVal(DataItem, Value, TimeStamp, RootPath, OutCell)
PIPutValX(DataItem, Value, TimeStamp, RootPath, OutCell)

Arguments
Argument Type Description
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.
RootPath String The path to the data item. See Data items.
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 Data Archive data types. The functions
interpret time stamps using client-machine time-zone information for PI Data Archive unless
the PI Data Archive time zone setting is enabled.

156 PI DataLink 2019 User Guide

 Function reference

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 Data Archive.

Deprecated functions
Several functions have been replaced by more powerful functions. To support older worksheets
that use these replaced functions, PI DataLink supports the old, deprecated functions, but
OSIsoft recommends that you use the corresponding new functions.
Old function New function
PICalcVal PIAdvCalcVal
PICalcDat PIAdvCalcDat
PIExTimeVal PIArcVal (with Mode set to exact time)

PI DataLink 2019 User Guide 157

Function reference

158 PI DataLink 2019 User Guide

Troubleshooting
Consult the topics in this section if you experience difficulty using PI DataLink. If these topics
do not address or solve the problem, contact Technical Support (see the OSIsoft Tech Support
Contact Us page (https://techsupport.osisoft.com/Contact-Us/)).

Topics in this section

• Log files
• PI DataLink tab not available
• Array and cell limits
• Data retrieval limits
• Data item not supported by function
• Duplicate event exists
• Security
• PI Data Archive connection issues
• Eliminate timeout exception error
• Data does not update

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 Data Archive server connectivity
Examine the PI Data Archive log file in PI SMT for PI Data Archive server connectivity issues.

PI DataLink tab not available

If the PI DataLink tab does not appear after you install PI DataLink, you might need to
manually configure the add-in for Excel (see Microsoft Excel add-in configuration), or reduce
security settings for add-ins (see Security).
Some user-written VBA scripts in Excel worksheets (or add-ins) reset the main Excel ribbon. In
such cases, the PI DataLink tab might 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.

PI DataLink 2019 User Guide 159

Troubleshooting

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 point names, to 255 characters.

Data retrieval limits

Error code -11091 indicates that a single query initiated by a PI DataLink function attempted
to retrieve more recorded values from PI Data Archive than allowed by the ArcMaxCollect
tuning parameter.
Because this limit applies to recorded values retrieved from PI Data 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 recorded values 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.

Duplicate event exists

The returned message Duplicate event exists: specify index for EventName
indicates that the parent event in this worksheet row contains more than one child event
named EventName. To resolve, change the specification of the Compare Events function to use
an indexed version of the event for the attribute displayed in this column.
When a parent event has child events with duplicate names, PI DataLink automatically adds an
index to the child event name in the Add Attributes window. If other events at the same level do
not have duplicate names, they will not have the index. For more details, see Add child-event
attributes as columns in the Compare Events task pane.

160 PI DataLink 2019 User Guide

 Troubleshooting

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 a PIPutVal() or PIPutValX () function use macros and require
that macros be enabled (see PIPutVal() and PIPutValX()).
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.

PI Data Archive connection issues

This version of PI DataLink uses tighter security settings for connecting to PI Data Archive. The
new settings reduce exposure to security weaknesses associated with PI password
authentication. For more information, see the OSIsoft Tech Support alert, AL00206 - Security
Alert: PI Authentication Weakness (https://techsupport.osisoft.com/Troubleshooting/Alerts/
AL00206).
The new security settings can result in errors if PI DataLink uses:
• PI user names and passwords to connect to PI Data Archive
• Default user to connect to PI Data Archive
Specifically, these settings might generate the following error:
Cannot connect to the PI Data Archive. Windows authentication trial
failed because insufficient privilege to access the PI Data Archive.
Trust authentication trial failed because insufficient privilege to
access the PI Data Archive.
To resolve these errors, you can:
• Configure PI mappings for users who connect to PI Data Archive.
OSIsoft recommends this approach (available in PI Data Archive version 3.4.380 and later).
This is the most secure connection method. For information on creating PI mappings, see
the PI Server topic "Mapping management" in Live Library (https://livelibrary.osisoft.com).
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 Data Archive.

PI DataLink 2019 User Guide 161

Troubleshooting

This is the next-best approach. 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. With this
approach, you must enter your user name and password the first time you connect to each
PI Data Archive during a particular Microsoft Excel session.
For more information, see the PI Server topic "Manage authentication" in Live Library (https://
livelibrary.osisoft.com).
Note:
Entering an incorrect password at a login prompt can result in the same error message.

Topics in this section

• Enable an authentication protocol
• Configure a computer to allow explicit login prompts
• Enter login credentials from Connection Manager

Enable an authentication protocol

To connect to PI Data Archive 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 Data Archive 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 Data Archive 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.

Configure a computer to allow explicit login prompts

To connect to PI Data Archive by logging in as a PI user, use PI SDK Utility to configure your
computer to allow explicit login prompts. You must configure each computer where you want
to connect to PI Data Archive by logging in as a PI user.
Caution:
OSIsoft recommends that you select an alternative, more secure method to connect to PI
Data Archive.

162 PI DataLink 2019 User Guide

 Troubleshooting

Procedure
1. Click Start > All Programs > PI System > PISDKUtility to open PI SDK Utility.
2. Click Connections > Options to open the Connection Options window.
3. Select the Allow login prompt (if all configured protocols fail) check box.
4. Click OK.

After you finish

Enter your user name and password to access PI Data Archive each new Excel session. You can
access the connection prompt by searching PI Data Archive with the Search tool or by
connecting manually from Connection Manager. See Enter login credentials from Connection
Manager.

Enter login credentials from Connection Manager

If you connect to PI Data Archive by logging in as a PI user, then you must enter your user name
and password for each PI Data Archive you connect to during each Excel session.

Before you start

Configure a computer to allow explicit login prompts.

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.
3. In the list of servers, right-click the PI Data Archive server that you want to connect to, and
then click Connect As to open the Connect to PI Data Archive window.
4. From the Authentication list, select PI User Authentication.
If the window does not show the Authentication list, then you must configure the computer
to allow explicit login prompts.
5. Enter you user name and password, and then click OK.

Eliminate timeout exception error

Searches of PI Data Archive servers with large point databases might reach the data timeout
before PI Data Archive 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.

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.

PI DataLink 2019 User Guide 163

Troubleshooting

3. Right-click the PI Data Archive server that returned the error, and then click Properties to
open the PI Data Archive Properties window.
4. Increase the value of the Data Timeout field, and then click OK.

Data does not update

PI DataLink caches configuration data for PI points and non-time-based data from PI AF (that
is, data other than PI point data references and events). As a result, data inserted into
worksheets may not update to show values based on changed configuration or non-time-based
data, even when you recalculate the function. Before calculating a function, PI DataLink checks
when the cache was last cleared; if the cache has not been cleared within the last six hours, PI
DataLink automatically clears the cache. To clear the cache and obtain updated data sooner, do
one of the following:
• Click Clear Cache on the Settings window. See Manage PI DataLink settings from Excel.
• Close and reopen Microsoft Excel.

164 PI DataLink 2019 User Guide

Technical support and other resources
For technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through the
OSIsoft Tech Support Contact Us page (https://techsupport.osisoft.com/Contact-Us/). The
website offers additional contact options 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
• Details about your 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
To ask questions of others who use OSIsoft software, join the OSIsoft user community,
PI Square (https://pisquare.osisoft.com). Members of the community can request advice and
share ideas about the PI System. The PI Developers Club space within PI Square offers
resources to help you with the programming and integration of OSIsoft products.

PI DataLink 2019 User Guide 165

Technical support and other resources

166 PI DataLink 2019 User Guide