DATALINK USER GUIDE

Rockwell Automation Publication HSEDL-UM025A-EN-E–September 2013

Supersedes Publication HSEDL-UM024A-EN-E
Contacting Rockwell Customer Support Telephone — 1.440.646.3434
Online Support — http://www.rockwellautomation.com/support/overview.page
Copyright Notice © 2013 Rockwell Automation, Inc. All rights reserved. Printed in the USA.
This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation,
Inc. Any reproduction and/or distribution without prior written consent from Rockwell Automation, Inc. is
strictly prohibited. Please refer to the license agreement for details.
Trademark Notices FactoryTalk, FactoryTalk Historian Machine Edition (ME), FactoryTalk Historian Site Edition (SE), FactoryTalk
Live Data, FactoryTalk Services Platform, FactoryTalk VantagePoint, FactoryTalk View, FactoryTalk ViewStudio,
Rockwell, Rockwell Automation, Rockwell Software, RSView, RSView Machine Edition, RSView ME Station,
RSView Studio, and RSLinx Enterprise are trademarks of Rockwell Automation, Inc.
Any Rockwell Automation logo, software or hardware not mentioned herein is also a trademark, registered or
otherwise, of Rockwell Automation, Inc.
For a complete list of products and their respective trademarks, go to
http://www.rockwellautomation.com/rockwellautomation/legal-notices/overview.page?%23tab4#/tab4.
Other Trademarks ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows,
Windows ME, Windows NT, Windows 2000, Windows Server-, Windows XP, Windows 7, and Vista are either
registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Adobe, Acrobat, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in
the United States and/or other countries.
ControlNet is a registered trademark of ControlNet International.
DeviceNet is a trademark of the Open DeviceNet Vendor Association, Inc. (ODVA)
OLE for Process Control (OPC) is a registered trademark of the OPC Foundation.
Oracle, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation.
All other trademarks are the property of their respective holders and are hereby acknowledged.
Warranty This product is warranted in accordance with the product license. The product’s performance may be affected
by system configuration, the application being performed, operator control, maintenance, and other related
factors. Rockwell Automation is not responsible for these intervening factors. The instructions in this
document do not cover all the details or variations in the equipment, procedure, or process described, nor do
they provide directions for meeting every possible contingency during installation, operation, or
maintenance. This product’s implementation may vary among users.
This document is current as of the time of release of the product; however, the accompanying software may
have changed since the release. Rockwell Automation, Inc. reserves the right to change any information
contained in this document or the software at any time without prior notice. It is your responsibility to obtain
the most current information available from Rockwell when installing or using this product.
Table of Contents

Introduction ..................................................................................................................................... 1
FactoryTalk Historian DataLink overview ..................................................................................... 1
About this release ......................................................................................................................... 2
Upgrade compatibility ......................................................................................................... 2
Supported data types ......................................................................................................... 2
Historian Server configuration ............................................................................................ 3
Microsoft Excel add-in configuration ............................................................................................ 3
View add-in status .............................................................................................................. 4
Enable a disabled add-in .................................................................................................... 4
Activate an inactive add-in ................................................................................................. 5
About this document ..................................................................................................................... 5

Basics .............................................................................................................................................. 7
User interface ............................................................................................................................... 7
PI DataLink tab ................................................................................................................... 7
Function task panes ........................................................................................................... 8
Right-click menu ................................................................................................................. 9
Overview of FactoryTalk Historian DataLink functions ................................................................. 9
Data items ........................................................................................................................ 10
Input entry ........................................................................................................................ 11
Time inputs ....................................................................................................................... 11
Appended data ................................................................................................................. 12
Display formats................................................................................................................. 13
Search for data items ................................................................................................................. 13
Use the browse pane to limit the search .......................................................................... 16
Use the scope path to limit the search ............................................................................. 16
Manage preference settings ....................................................................................................... 17
Manage connections to servers.................................................................................................. 19
Worksheet construction .............................................................................................................. 20
Asset-relative displays...................................................................................................... 21
Create an asset-relative display ....................................................................................... 21

FactoryTalk Historian DataLink functions ................................................................................. 25

Current Value function ................................................................................................................ 25
Current Value example..................................................................................................... 26
Archive Value function ................................................................................................................ 26
Archive Value example..................................................................................................... 28
Compressed Data function ......................................................................................................... 29
Compressed Data example .............................................................................................. 31

FactoryTalk Historian DataLink User Guide iii

Table of Contents

Sampled Data function ............................................................................................................... 32

Sampled Data example .................................................................................................... 33
Timed Data function ................................................................................................................... 34
Timed Data example ........................................................................................................ 35
Calculated Data function ............................................................................................................ 36
Calculated Data example ................................................................................................. 39
Time Filtered function ................................................................................................................. 40
Time Filtered example ...................................................................................................... 41
Properties function ...................................................................................................................... 42
Properties example .......................................................................................................... 43

Worksheets ................................................................................................................................... 45
Function arrays ........................................................................................................................... 45
Common function array tasks .......................................................................................... 45
Update inputs to a function array ..................................................................................... 46
Array size ......................................................................................................................... 47
Resize arrays ................................................................................................................... 47
Calculation frequency ................................................................................................................. 48
Automatic Update feature ................................................................................................ 48
Triggered recalculation ..................................................................................................... 49
Manual recalculation ........................................................................................................ 50
Worksheet sharing ...................................................................................................................... 50
Set Workbook Calculation option to manual .................................................................... 51

Advanced topics ........................................................................................................................... 53

Historian time .............................................................................................................................. 53
Historian time abbreviations ............................................................................................. 53
Historian Time expressions .............................................................................................. 54
Time-stamp specification ................................................................................................. 54
Time-interval specification ................................................................................................ 56
Expressions ................................................................................................................................ 56
Use expressions in FactoryTalk Historian DataLink functions .........................................57
Expression syntax ............................................................................................................ 57
Restrictions on data items in expressions ........................................................................ 58
Expression examples ....................................................................................................... 58
Filter expressions ............................................................................................................. 58
Manual function entry ................................................................................................................. 59
Define functions manually ................................................................................................ 59
Guidelines for entering arguments manually ................................................................... 59
Output codes .................................................................................................................... 60
Functions to write data ............................................................................................................... 62

Tag functions ................................................................................................................................ 63

Point ID to Tag function .............................................................................................................. 63
Point ID to Tag example ................................................................................................... 64
Attribute Mask to Tag function .................................................................................................... 64
Attribute Mask to Tag example ........................................................................................ 65
Search for tags ........................................................................................................................... 65

iv
 Trends ............................................................................................................................................ 67
Create a trend ............................................................................................................................. 67
Create a trace of values in the worksheet ........................................................................ 69
Create a trace of Historian point values retrieved from a Historian Server ......................69
Trend right-click menu ................................................................................................................ 70

Historian Module Database objects ............................................................................................ 71

Historian Module Database and worksheets .............................................................................. 71
Insert Historian Module Database objects into your worksheet .................................................72
Module database functions ......................................................................................................... 72
Alias to Tag function ......................................................................................................... 73
Property to Value function ................................................................................................ 73

Notifications .................................................................................................................................. 75
Search and insert notifications ................................................................................................... 75
Add a AF server to the Notification Search function ........................................................76
Adjust display of retrieved notifications ............................................................................ 77
Manage retrieved notifications ......................................................................................... 78
Inserted notifications ................................................................................................................... 78
Notification display settings ........................................................................................................ 79

Function reference ....................................................................................................................... 81

Single-value functions ................................................................................................................ 81
PICurrVal() ....................................................................................................................... 81
PIArcVal() ......................................................................................................................... 82
PIExpVal() ........................................................................................................................ 83
PITagAtt() ......................................................................................................................... 83
Multiple-value functions .............................................................................................................. 84
PINCompDat() .................................................................................................................. 84
PINCompFilDat() .............................................................................................................. 85
PICompDat() .................................................................................................................... 86
PICompFilDat()................................................................................................................. 87
PISampDat()..................................................................................................................... 88
PISampFilDat() ................................................................................................................. 89
PIExpDat() ........................................................................................................................ 90
PITimeDat() ...................................................................................................................... 91
PITimeExpDat() ................................................................................................................ 92
Calculation functions .................................................................................................................. 94
PIAdvCalcVal() ................................................................................................................. 94
PIAdvCalcFilVal() ............................................................................................................. 95
PIAdvCalcExpVal() ........................................................................................................... 97
PIAdvCalcExpFilVal() ....................................................................................................... 98
PIAdvCalcDat()............................................................................................................... 100
PIAdvCalcFilDat() ........................................................................................................... 101
PIAdvCalcExpDat() ........................................................................................................ 103
PIAdvCalcExpFilDat()..................................................................................................... 105
PITimeFilter() .................................................................................................................. 107
PITimeFilterVal() ............................................................................................................ 108
Tag functions ............................................................................................................................ 109
PIPointIDToTag() ........................................................................................................... 109
PIAttributeMaskToTag () ................................................................................................ 109

FactoryTalk Historian DataLink User Guide v

Table of Contents

Module Database functions ...................................................................................................... 110

PIAliasToTag() ............................................................................................................... 110
PIPropertyToValue()....................................................................................................... 111
Input functions .......................................................................................................................... 112
PIPutVal() and PIPutValX() ............................................................................................ 112

Troubleshooting ......................................................................................................................... 115

Log files .................................................................................................................................... 115
PI DataLink tab not available .................................................................................................... 115
Array and cell limits .................................................................................................................. 115
Data retrieval limits ................................................................................................................... 116
Data item not supported by function ......................................................................................... 116
Security ..................................................................................................................................... 116
Historian Server connection issues .......................................................................................... 117
Configure a computer to allow explicit login prompts.....................................................117
Enable an authentication protocol .................................................................................. 118
Cannot connect to PI OLEDB Enterprise Agent ....................................................................... 118
Timeout exception .................................................................................................................... 119

Index ............................................................................................................................................ 121

vi
Chapter 1

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

FactoryTalk Historian DataLink overview

FactoryTalk Historian DataLink is a Microsoft Excel add-in that enables you to retrieve
information from your FactoryTalk Historian System directly into a worksheet. Combined
with the computational, graphic, and formatting capabilities of Microsoft Excel, FactoryTalk
Historian DataLink offers powerful tools for gathering, monitoring, analyzing, and reporting
FactoryTalk Historian System data.
With FactoryTalk Historian DataLink, you can:
• Retrieve Historian point values from a Historian Server
• Retrieve attribute values from a Historian Asset Framework (AF) server
• Retrieve system metadata to create a structured view of FactoryTalk Historian System
data:
ο Historian point names and attributes
ο Historian Module Database paths, aliases, and properties
ο AF attributes and elements
• Reference these items using FactoryTalk Historian DataLink functions to calculate and
filter data
• Update retrieved values when the worksheet recalculates
FactoryTalk Historian DataLink includes a user interface to help you build functions and
retrieve data. FactoryTalk Historian DataLink embeds functions in worksheet cells and can
provide active updates of real-time data from your FactoryTalk Historian System.
You can also use the rich calculation and formatting capabilities of Excel to organize and
present FactoryTalk Historian System data to fit your purpose or audience.
There are two ways to work with FactoryTalk Historian DataLink functions in Excel
worksheets:
• Install a stand-alone version of FactoryTalk Historian DataLink on a local PC.
•
Contact your Rockwell Automation sales representative for more information.

FactoryTalk Historian DataLink User Guide 1

Introduction

About this release

This release of FactoryTalk Historian DataLink installs an add-in for Microsoft Excel 2007
SP3 or later. This add-in cannot run in earlier versions of Excel. Topics in this section
describe system requirements, upgrade compatibility with previous releases, and supported
data types.
For up-to-date system requirements, and installation instructions, refer to FactoryTalk
Historian DataLink Release Notes.

Upgrade compatibility

FactoryTalk Historian DataLink is backwards compatible. This version of FactoryTalk

Historian 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 FactoryTalk Historian DataLink.
FactoryTalk Historian DataLink 5.0 uses AF SDK whereas previous releases used either PI
SDK or PI API. Different behaviors might require you to change existing worksheets:
• Returned error messages might differ. You might need to change worksheets that look for
certain strings (for example, in Excel VBA code or macros).
• FactoryTalk Historian 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 Historian Server are no longer supported. If prompted, you
can enter a user name and password. However, Rockwell Automation recommends that
you configure mappings to connect to Historian Server.
The 64-bit version of FactoryTalk Historian DataLink 5.0 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

FactoryTalk Historian DataLink supports the following Historian point data types:
• Digital (defined states)
• Int (16 and 32)
• Float (16, 32 and 64)
• String (text)

2
 Microsoft Excel add-in configuration

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

Historian Server configuration

FactoryTalk Historian DataLink can retrieve data from Historian Server 2x and later.
However, FactoryTalk Historian DataLink must connect to Historian Server and have proper
access to points. This might require configuration changes for:
• Firewall database. The firewall database on each Historian Server computer must be
configured to allow access from client computers that run FactoryTalk Historian
DataLink.
• Authentication and authorization. Those using FactoryTalk Historian DataLink must be
able to authenticate their identity with Historian Server and have access to Historian
Server. Rockwell Automation recommends that you use PI mappings (available in
Historian Server version 3.0 and later). You can also use Trusts or Historian password
authentication. Rockwell Automation does not recommend Historian 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 Historian Server documentation.

Microsoft Excel add-in configuration

FactoryTalk Historian DataLink has three application add-ins to Microsoft Excel.
Name Location Type

FactoryTalk Historian ..\PIPC\Excel\OSIsoft.PIDataLink.UI.vsto COM Add-in

DataLink

FactoryTalk Historian DataLink User Guide 3

Introduction

Name Location Type

FactoryTalk Historian ..\PIPC\Excel\OSIsoft.PIDataLink.UI(Legacy).vsto COM Add-in

DataLink (Legacy)

To use all FactoryTalk Historian DataLink features, these application add-ins must be active.
The setup program installs all the add-ins, and activates the DataLink add-in. The setup
program does not activate the FactoryTalk Historian DataLink (Legacy) add-in. You must
activate the add-in if you want to use tag functions, Module Database objects, or trends.
In rare cases, Microsoft Excel might disable an add-in. You must enable an add-in before you
can activate it.

Note: To activate an application add-in, you must have administrator privileges on the
computer. If you are not an administrator, right-click Excel.exe in Windows
Explorer, and then click Run as administrator to run Microsoft Excel as an
administrator.

See also
• Tag functions (page 63)
• Module Database objects (page 71)
• Trends (page 67)
• Notifications (page 75)

View add-in status

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

Procedure
1. Click the File tab and then click Options. (In Microsoft Excel 2007, click the Microsoft
Office Button, and then click Excel Options.)
2. On the Excel Options window, click Add-Ins.
3. Search the list of add-ins to find the current status of an add-in.
Each add-in will be listed under either:
ο Active Application Add-ins
ο Inactive Application Add-ins
ο Disabled Application Add-ins.

Enable a disabled add-in

If an add-in is disabled, you must enable the add-in before you can make it active.
Procedure
1. Click the File tab and then click Options. (In Microsoft Excel 2007, click the Microsoft
Office Button, and then click Excel Options.)

4
 About this document

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. (In Microsoft Excel 2007, click the Microsoft
Office Button, and then click Excel 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.

About this document

The FactoryTalk Historian DataLink User Guide provides a detailed description of product
features and a complete reference to FactoryTalk Historian DataLink functions. The content
of the PDF and Help versions of the guide is identical.
This document assumes that you have knowledge about FactoryTalk Historian System
concepts. Consult the Historian Server and AF documentation for more information about
those products. Knowledge of Historian Server and AF will help you understand terms used
in FactoryTalk Historian DataLink.

FactoryTalk Historian DataLink User Guide 5

Chapter 2

Basics
When you use FactoryTalk Historian DataLink, you define FactoryTalk Historian DataLink
functions that extract FactoryTalk Historian System data into function arrays in an Excel
worksheet. A function array is a cluster of cells that contain the output from a single
FactoryTalk Historian DataLink function. The following sections introduce basic FactoryTalk
Historian DataLink concepts and features. Familiarize yourself with these sections before
using FactoryTalk Historian DataLink to build a worksheet and retrieve FactoryTalk
Historian System data.
These sections describe:
• User interface features
• Core features for working with FactoryTalk Historian DataLink
• Different approaches to build a FactoryTalk Historian DataLink worksheet, depending on
your goals, needs, and resources

User interface
FactoryTalk Historian DataLink adds specific menu commands, windows, and task panes to
Microsoft Excel.
The following sections describe core elements of the FactoryTalk Historian DataLink
interface.

PI DataLink tab

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

• Click the PI DataLink tab to access the FactoryTalk Historian DataLink commands.
• Click a command to open the corresponding task pane or window.
• Place the cursor over a command to display a descriptive tooltip.

FactoryTalk Historian DataLink User Guide 7

Basics

Function task panes

Use function task panes to define FactoryTalk Historian 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 (page 17) of task panes if you prefer.

• Right-click a function-array cell, and then click the function name to manually open the
task pane.
In an open function task pane:
• Enter or change input values, and then:
ο Click OK to save the input values, write the resulting function array, and close the
task pane.
ο Click Apply to save the input values and write the resulting function array without
closing the task pane.
• Click the X button in the task pane title bar to close the task pane without saving changes.
• Click the arrow button to select the Move, Size, or Close commands.
• Drag the title bar to undock the task pane.
• Double-click the title bar to dock the task pane.

8
 Overview of FactoryTalk Historian DataLink functions

• Place your cursor at the edge and drag to resize the pane.

Right-click menu

FactoryTalk Historian 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 FactoryTalk Historian DataLink commands, right-click
anywhere in a FactoryTalk Historian DataLink function array.
FactoryTalk Historian 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: FactoryTalk Historian DataLink retrieves new values
from Historian Server or AF and automatically resizes the array to fit the returned data.
• Function Name
Opens the corresponding function task pane and shows inputs for the function array.
Trends offer an alternative right-click menu.
See also
• Trend right-click menu (page 70)
• Function task panes (page 8)

Overview of FactoryTalk Historian DataLink functions

FactoryTalk Historian DataLink functions extract FactoryTalk Historian 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 FactoryTalk Historian DataLink function task panes
• How real-time data is acquired and presented
• How FactoryTalk Historian DataLink functions can be used within a worksheet
See also
• Function task panes (page 8)
• Manual function entry (page 59)

FactoryTalk Historian DataLink User Guide 9

Basics

Data items

FactoryTalk Historian DataLink functions return data about specified FactoryTalk Historian
System data items, either Historian Points or 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 Historian point or
a AF attribute.
• Partial paths in the Data item, Expression, or Filter expression fields and the common
base path in the Root path field. Historian point names or AF attribute names are
examples of partial paths. FactoryTalk Historian DataLink combines the common base
path with the partial path to set the full path that evalues to either a Historian point or AF
attribute.
FactoryTalk Historian DataLink requires a full path to find the data item. To find a Historian
point, FactoryTalk Historian DataLink must know the Historian Server to search and the
point name. To find a AF attribute, FactoryTalk Historian DataLink must know the 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 Historian point on the default Historian 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
Historian point Historian Server that stores the point or a blank to indicate the default
Historian Server. Valid entries include:
 PIServer
 \\PIServer
AF attribute AF server and database along with any elements, subelements, and
parent attributes not specified in Data item. Valid entries include:
 \\PIAFserver\database
 \\PIAFserver\database\element
 \\PIAFserver\database\element\subelement
 \\PIAFserver\database\element|ParentAttribute
 \\PIAFserver\database\element|ParentAttribute1|ParentAttribute2
Note: The AF server and database must be in the same field. You
cannot specify the AF server in the Root path field and the database in
the Data item field.

See also
Expressions (page 56)

10
 Overview of FactoryTalk Historian DataLink functions

Input entry

Labeled inputs on function task panes accept appropriate values for the function. For many
inputs, you can enter either a value or a reference to a worksheet cell that contains the value.
Some inputs have a default value shown when the task pane opens. Inputs marked (optional)
are optional, and do not require a value.

For inputs with edit fields , you can:

• Enter text directly in the edit field, such as a 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 AF attribute names, time stamps, or output cell locations.

• Click to open the Search tool, and then select data items found in a search of a
connected Historian Server or 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 Historian point in the Data item(s) field, you can:
• Enter the string for the point name.

• Click to open the Search tool, and search Historian 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.
FactoryTalk Historian DataLink automatically enters the cell reference into the edit
field.

Time inputs

Many FactoryTalk Historian DataLink functions require Start time and End time inputs to
retrieve an array of event values over a specific time period. Other FactoryTalk Historian
DataLink functions require a Time stamp input to retrieve values at a specific time. Follow
these guidelines when specifying time inputs:
• Enter either a fixed time, such as 10-Dec-99 19:12, or a Historian Time expression
that specifies a relative time, such as -3h. For example, you might enter a fixed time to

FactoryTalk Historian DataLink User Guide 11

Basics

define a time period in the past, or you might enter a relative time expression to define a
time period that includes the current time.
• If the start time is more recent than the end time, FactoryTalk Historian 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 FactoryTalk Historian DataLink to interpret as a time.
Some FactoryTalk Historian 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: FactoryTalk Historian DataLink supports only the default 1900 date system
supported by Excel. FactoryTalk Historian DataLink does not support Excel's 1904
date system, and returns incorrect time stamps if this system is used.

See also
• Time-stamp specification (page 54)
• Time-interval specification (page 56)

Appended data

FactoryTalk Historian DataLink can append information about the values retrieved. This
appended data can provide context to retrieved values. Appended data can include:
• Event time stamps
• Time stamps that show the start and end times of an interval
• Time stamps that show when the minimum and maximum values occurred
• The percentage of good values over a sampling interval
• Value attributes
• Manually entered event annotations
• Source server names

12
 Search for data items

FactoryTalk Historian DataLink displays the specified appended data in the columns (or
rows) adjacent to the primary values that the function returns:
• Time data are displayed in columns to the left of (or rows above) primary values.
• Other related data are displayed in columns to the right of (or rows below) primary
values.

Display formats

Use the Settings window (page 17) to specify the time and number formats that FactoryTalk
Historian 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 Historian Time stamp format. You can add :000 to
the end of the string (dd-mmm-yy hh:mm:ss:000) to display subsecond time stamps.
Note that Excel does not support microsecond precision formats.
You can customize these format strings using any valid Excel format codes from the Format
Cells window in Excel.
You can also apply individual time and date formatting to any worksheet cell, including those
containing FactoryTalk Historian DataLink functions, with the Format Cells window. See
your Excel documentation for more information on formatting dates and times.

Search for data items

Use the Search tool to search any specified Historian Server or AF server for data items. You
can insert data items into your worksheet and later reference these data items in FactoryTalk
Historian DataLink functions. You can also insert a data item directly into a function task
pane.
Before you begin
Connect to any Historian Server or AF server that you want to search. See Manage
connections to servers (page 19).
Procedure

FactoryTalk Historian DataLink User Guide 13

Basics

1. Open the Search tool:

ο To insert one or more items into a worksheet, select the upper leftmost cell of the
range in the worksheet where you want to insert the data items, and then on the PI
DataLink tab, in the Search group, click Search.

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

c. Click Search to initiate the search.

14
 Search for data items

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:
− Historian Points with names or descriptors that match.
− AF attributes with names or descriptions that match.
− AF attributes that have parent elements with names or descriptions that match.

Note: Searches of Historian Server return no more than 100,000 Historian Points. To
be certain that you see all results, constrain your search to return fewer
Historian Points.

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

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

FactoryTalk Historian DataLink User Guide 15

Basics

Create an asset-relative display (page 21)

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 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 AF server or a particular database on that
server, or a particular element within that database. As you navigate a 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 AF server (indicated by ), the browse pane
shows all the databases on that server. If you clicked a Historian Server (indicated by ),
the browse pane shows a list of filter fields that you can use to limit retrieved Historian
Points.
• Click a database (indicated by ) to limit the search to that database.
The tool updates the browse pane to show all the top-level elements in the selected
database, and updates the scope path at the top of the window to list the selected
database.
• Click an element (indicated by ) to limit the search to that element.
The tool updates the browse pane to show all the parent elements and parent attributes
under the selected element, updates the scope path at the top of the window to list the
selected element, and lists any attributes under the selected element in the results pane.
Note that the browse pane only shows attributes that are parent attributes, whereas the
results pane shows both parent and non-parent attributes under the selected element.
• Click an attribute (indicated by ) to limit the search to that attribute.
The tool updates the browse pane to show any parent attributes under the selected
attribute, updates the scope path at the top of the window to list the selected attribute, and
lists any attributes under the selected attribute in the results pane.

Use the scope path to limit the search

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

16
 Manage preference settings

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 AF server or
a particular database on that server, or a particular element within that database. As you
navigate a AF server hierarchy in the scope path, the results pane updates to show any
attributes directly under the currently selected scope path.
Procedure
In the scope path:
• Click Home to reset the scope to all the Historian Servers and AF servers listed in
Connection Manager.
• Click the arrow next to Home, and then click a particular server to reset the scope to that
server.
• Click the server to reset the scope to that entire server.
• Click the arrow next to a AF server, and then click a particular database to reset the scope
to that database.
• Click the database to reset the scope to the entire database.
• Click the arrow next to the database, and then click a particular element to reset the scope
to that element.
• Click an element to reset the scope to the entire element.
• Click the arrow next to an element, and then click a subelement or attribute to reset the
scope to that subelement or attribute.
• Click a parent attribute to reset the scope to all its subattributes.
• Click the arrow next to a parent attribute and select a particular subattribute to reset the
scope to that subattribute.

Manage preference settings

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

FactoryTalk Historian DataLink User Guide 17

Basics

Setting Description
Copy Historian Server name (Legacy Select to paste the name of the Historian Server data
add-in only) source into an adjacent worksheet cell when you insert
Historian point names from tag functions into a
worksheet.
Use Historian Server time zone Select to have FactoryTalk Historian DataLink interpret
the input and output time stamps as being in the
Historian Server time zone for data items or expressions
that contain either a Historian point or a AF attribute that
is a Historian point data reference.
If not selected, or the data item or expression contains a
AF attribute that is not a Historian point data reference,
FactoryTalk Historian DataLink interprets the input and
output time stamps as being in the client-workstation time
zone.
This option is relevant only if a Historian Server has a
time zone setting different from the client workstation.
Display #N/A instead of blanks Select to show #N/A (not applicable) rather than blanks
in cells without values when a recalculation returns fewer
values than a function array can show.
This feature is particularly useful if you use the Excel
charting package to plot function results.
Locale independent Select to have FactoryTalk Historian DataLink interpret
input time strings according to Historian Time format
rules, regardless of the locale settings of the client
workstation. Historian 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 Historian Time format rules only if necessary.
Disable automatic task pane display Select to turn off the automatic opening of the function
on click task pane upon a click of a function cell.
Disable "Resize to show all values" Select to display no warning message when a
message recalculation returns more values than a function array
can show.
Number format Enter the format for numbers in function output. The
format string may be any valid number format code from
the Excel Format window (see "Display formats" on
page 13).
During installation, FactoryTalk Historian DataLink enters
the default number format from Excel in this field, unless
you have set a different format preference previously in
FactoryTalk Historian 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.

18
 Manage connections to servers

Setting Description
Time format Enter the format for time stamps in function output. The
time format string may be any valid date-time format
code from the Excel Format window.
During installation, FactoryTalk Historian DataLink enters
the standard Historian Time stamp format in this field,
unless you have set a different format preference
previously in FactoryTalk Historian DataLink on this
computer. If your version of Excel runs a different locale,
this format includes correct syntax to reflect the locale.
For example:
dd-mmm-yy hh:mm:ss
would appear as
jj-mmm-aa hh:mm:ss
in French Excel.
Calculate (F9) Select to recalculate all volatile functions (and any
functions that reference them) during each recalculation
that the Automatic Update feature initiates. The Current
Value function is the only volatile FactoryTalk Historian
DataLink function.
Full calculate (Ctrl+Alt+Shift+F9) Select to recalculate all functions, regardless of volatility,
during each recalculation that the Automatic Update
feature initiates.
Interval (seconds) Enter the number of seconds between each recalculation
that the Automatic Update feature initiates. The minimum
value is five seconds. Enter 0 to have FactoryTalk
Historian DataLink compute an automatic interval based
on the duration of previous calculation times.

Manage connections to servers

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

FactoryTalk Historian DataLink User Guide 19

Basics

To connect with AF servers, FactoryTalk Historian DataLink uses the Windows

credentials of the logged-in user. To connect with Historian Servers, FactoryTalk
Historian DataLink can use a 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 Historian Server or AF server).
ο Select a server and click Properties to view the connection properties for that server.
ο Right-click a server and choose Remove to remove the connection definition to that
server.

Worksheet construction
Once you are familiar with the basic tools and concepts of FactoryTalk Historian DataLink,
you are ready to build a worksheet that uses FactoryTalk Historian 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 FactoryTalk Historian DataLink functions can
return the data most relevant to your task.
Select an approach
Techniques you might use to build your worksheet include:
• Function-based
Add functions (page 25) 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 FactoryTalk Historian DataLink works.
• Structure-based
Add structure as you build a worksheet. Use the Search tool (see "Search for data items"
on page 13) 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 FactoryTalk Historian DataLink, but once you add data items to the
worksheet, you can use them to build functions more easily through cell references. You
can easily reuse worksheets built this way.
• Report-based
Place FactoryTalk Historian 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

20
 Worksheet construction

second worksheet from most users. This approach is useful if you are a system
administrator or build worksheets for other users.

Asset-relative displays

An asset-relative display shows the values for a set of AF attributes along with the
corresponding asset (a AF element). You can select a different asset to show the values for
that asset.

Asset-relative display for React1 element

Asset-relative display for React2 element

Asset-relative displays require a common set of attribute names for assets. For example, to
create an asset-relative display you can use 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 FactoryTalk Historian
DataLink function that references these cells. After you create the asset-relative display, you
can select a different asset from the list to see the attribute values for that asset.
Procedure
1. Insert a set of data items with a common structure into your worksheet (page 22).
2. Configure a FactoryTalk Historian DataLink function to retrieve data about the inserted
data items (page 23)
See also
• Asset-relative displays (page 21)
• Search for data items (page 13)

FactoryTalk Historian DataLink User Guide 21

Basics

Insert a set of data items with a common structure into your worksheet
Asset-relative displays require the worksheet to contain set of data items (AF attributes) that
have a common structure along with a root-path drop-down list for those data items.
Procedure
1. Select a cell in the worksheet where you will insert the data items.
2. On the PI DataLink tab, click Search to open the Search tool.

3. Set the search scope, specify the data items you want to find, and click Search .
For asset-relative displays, you want to find AF attributes that have a common parent
element and the same attribute structure. These attributes might have the same attribute
template. For example, you might find all the reactors at your facility.
4. Split the data-item path such that the assets for the display appear in the Root path
column.
Move the Root path length slider until the Root path column shows the unique elements
for the listed attributes. Typically this will be at or near the Maximum setting.

5. Select the data items that you want to insert into the worksheet.
6. Under Insert root paths in, select Drop-down list.
7. Click OK.
FactoryTalk Historian DataLink inserts the unique data items into the worksheet below a
drop-down list that contains the unique assets (from the root-path column).

22
 Worksheet construction

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

Configure a FactoryTalk Historian DataLink function to retrieve data about the

inserted data items
Asset-relative displays require you to configure a FactoryTalk Historian 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.
FactoryTalk Historian 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.
FactoryTalk Historian 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.

FactoryTalk Historian DataLink User Guide 23

Chapter 3

FactoryTalk Historian DataLink functions

With FactoryTalk Historian DataLink functions, you can query any Historian Server or AF
server, apply calculations to retrieved results, and return values to worksheet cells. Like other
Excel functions, FactoryTalk Historian DataLink functions return results in function arrays,
which you can recalculate to update values as needed. Use function task panes to define
inputs for FactoryTalk Historian 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 (page 8)
• Function arrays (page 45)
• Function reference (page 75)

Current Value function

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

FactoryTalk Historian DataLink User Guide 25

FactoryTalk Historian 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,
FactoryTalk Historian DataLink inserts the selected cell into the Output
cell field.
Specify the top-left corner of the function array. FactoryTalk Historian
DataLink expands the range downward and to the right of the output
cell, as necessary to return specified data. FactoryTalk Historian
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, FactoryTalk Historian
DataLink pastes the function formula in the unneeded cells of the
specified array.
No time stamp Click this option to return only values. The function returns values in a
column for a column of referenced data items, or returns values in a
row for a row of referenced data items.
Time at left Click this option to return two columns: the time stamp in the left
column and the value in the right column.
Time on top Click this option to return two rows: the time stamp in the top row and
the value in the bottom row.

RELATED TOPICS
• PICurrVal() (page 81)

Current Value example

To see the current value of the Historian point sinusoid, set the following inputs for the
Current Value function:
Input Value
Data item(s) sinusoid
Time at left Selected

The function returns the following array:

Archive Value function

• If you select the Data item option, the Archive Value function returns the value of a
Historian point or AF attribute at a specified time stamp.
• If you select the Expression option, the Archive Value function returns the computed
value of a performance equation at a specified time stamp.

26
 Archive Value function

Input Description
Root path The common path to specified data items, including those in
expressions. Valid entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian
Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which the
function returns values.
Reference a range of cells that contain Historian point names or AF
attribute names to return values for each.
Required if you select the Data item option.
Expression(s) One or more performance equations that the function computes a value
for. See Expressions (page 56).
Reference a range of cells that contain expressions to return values for
each.
Required if you select the Expression option.
Time stamp The time stamp for which the function returns values. Specify either a
fixed time or a time expression relative to the current time. See Time
inputs (page 11). Required.
Retrieval mode The method the function uses to determine returned values. Choices
include:
 previous
Returns the value that exactly matches or precedes the specified time
stamp.
 previous only
Returns the value that precedes the specified time stamp.
 interpolated
Returns the interpolated value at the specified time.
 auto
Returns the interpolated value at the specified time, or follows the
previous method. (Uses the previous method for data items with step
attributes.)
 next
Returns the value that exactly matches or follows the specified time
stamp.
 next only
Returns the value that follows the specified time stamp.
 exact time
Returns only a value that exactly matches the time stamp, or returns
No events found if no value exists at that time stamp.
Available if you select the Data item option.

FactoryTalk Historian DataLink User Guide 27

FactoryTalk Historian 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, FactoryTalk
Historian DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian
DataLink expands the range downward and to the right of the output cell,
as necessary to return specified data. FactoryTalk Historian 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, FactoryTalk Historian
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.

RELATED TOPICS
• PIArcVal() (page 82)
Specify data items.
• PIExpVal() (page 83)
Specify an expression.

Archive Value example

To see the value of the Historian 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:

28
 Compressed Data function

Compressed Data function

• If you select the Time range option, the Compressed Data function returns all the values
of a Historian point or 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 Historian Server archive undergo a compression algorithm
that removes all values that represent the same slope. Values stored in the
Historian Server snapshot have not undergone this compression algorithm. If you
specify the current time in the time period of the Compressed Data function, the
function retrieves a snapshot value for that time. That snapshot value might not be
subsequently stored in the archive due to compression.

Input Description

Root path The common path to specified data items, including those in
expressions. Valid entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian
Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which
the function returns values.
Reference a range of cells that contain Historian point names or AF
attribute names to return values for each.
Required.
Start time The start of the time period for which the function returns values.
See Time inputs (page 11). Required.
End time The end of the time period for which the function returns values.
Required if you select the Time range option.
Number of values The number of values that the function returns, beginning at Start
time. Required if you select the Number of values option.
Backwards in time Select this check box to return values recorded at Start time and
earlier. Available if you select the Number of values option and
enter a value in the Number of values field.
If you enter a cell reference in the Number of values field, this
check box is disabled. Instead, enter a negative number in the
referenced cell to have the same effect.
Filter expression A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).
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.

FactoryTalk Historian DataLink User Guide 29

FactoryTalk Historian DataLink functions

Input Description

Boundary type The method that the function uses to determine which values to
return near the start time or end time:
 inside (default)
Returns values at start and end times, if they exist, or the nearest
values that occur within the range.
 outside
Returns the nearest values that occur immediately outside the
range.
 interpolated
Returns interpolated values at the start and end times.
 auto
Returns interpolated values, but uses the inside method for data
items with step attributes.
Output cell The worksheet cell where the function writes the resulting function
array. If you select a cell before you open the function task pane,
FactoryTalk Historian DataLink inserts the selected cell into the
Output cell field.
Specify the top-left corner of the function array. FactoryTalk
Historian DataLink expands the range downward and to the right of
the output cell, as necessary to return specified data. FactoryTalk
Historian 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,
FactoryTalk Historian 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. FactoryTalk Historian DataLink shows time
stamps to the left of values displayed in a column or above values
displayed in a row.
Show value attributes Select this check box to show the extended status bits associated
with returned values. Possible status bits include:
 A
Annotated, indicates a comment has been added to the event
 S
Substituted, indicates the event value has been changed from its
original value
 Q
Questionable, indicates that there is some reason to doubt the
accuracy of the value
FactoryTalk Historian DataLink shows value attributes in a column
to the right of event values.
Show annotations Select this check box to show annotations associated with returned
values. Annotations contain notes or comments that describe a data
value. FactoryTalk Historian DataLink shows annotations in a
column to the right of the value.
Column Click this option to return values in a column.

30
 Compressed Data function

Input Description

Row Click this option to return values in a row.

Note: If you specify a range of items in Data item(s), FactoryTalk
Historian DataLink automatically selects Column or Row to match
the orientation of the items.

RELATED TOPICS
• PICompDat() (page 86)
Specify a time range without a filter expression.
• PICompFilDat() (page 87)
Specify a time range with a filter expression.
• PINCompDat() (page 84)
Specify a number of values without a filter expression.
• PINCompFilDat() (page 85)
Specify a number of values with a filter expression.

Compressed Data example

To see the most recent 10 values of the Historian 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:

FactoryTalk Historian DataLink User Guide 31

FactoryTalk Historian DataLink functions

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 Historian point or AF attribute over a regular interval.
• If you select the Expression option, the Sampled Data function returns evenly-spaced,
interpolated values of a performance equation over a regular interval.
Input Description
Root path The common path to specified data items, including those in expressions.
Valid entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which the
function returns values.
Reference a range of cells that contain Historian point names or AF
attribute names to return values for each.
Required if you select the Data item option.
Expression(s) One or more performance equations that the function computes a value for.
See Expressions (page 56).
Reference a range of cells that contain expressions to return 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 (page 11). Required.
End time The end of the time period for which the function returns values. Required.
Time interval The sampling frequency used to calculate values during the time period.
Enter a value and time unit. For example, enter 15m (15 minutes) to return
a value for every 15-minute interval in the time period. See Time-interval
specification (page 56). Required.

32
 Sampled Data function

Input Description
Filter expression A Boolean performance equation that the function uses to filter values.
When the expression evaluates to false, the function excludes
corresponding values. See Filter expressions (page 58).

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, FactoryTalk
Historian DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian
DataLink expands the range downward and to the right of the output cell,
as necessary to return specified data. FactoryTalk Historian 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, FactoryTalk Historian
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. FactoryTalk Historian DataLink shows time stamps to the
left of values displayed in a column or above values displayed in a row.
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), FactoryTalk Historian DataLink
automatically selects Column or Row to match the orientation of the
specified range.

RELATED TOPICS
• PISampDat() (page 88)
Specify a data item with a filter expression.
• PISampFilDat() (page 89)
Specify a data item without a filter expression.
• PIExpDat() (page 90)
Specify an expression.

Sampled Data example

To see periodic, interpolated values over the previous 24 hours for the Historian 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)

FactoryTalk Historian DataLink User Guide 33

FactoryTalk Historian DataLink functions

Input Value

Time interval 3h
Show time stamps Selected
Column Selected

The function returns the following array:

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 Historian point or 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:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which the
function returns values.
Reference a range of cells that contain Historian point names or AF attribute
names to return values for each.
Required if you select the Data item option.
Expression(s) One or more performance equations that the function computes a value for.
See Expressions (page 56).
Reference a range of cells that contain expressions to return 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.
Required.

34
 Timed Data function

Input Description
Retrieval mode The method the function uses to retrieve data:
 interpolated
Returns interpolated values that correspond to specified time stamps. For
data items with the step attributes, retrieves the value preceding the specified
time stamp.
 exact time
Returns only values that exactly match specified time stamps; returns No
events found if no value exists.
Output cell The worksheet cell where the function writes the resulting function array. If you
select a cell before you open the function task pane, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary to
return specified data. FactoryTalk Historian 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, FactoryTalk Historian DataLink pastes
the function formula in the unneeded cells of the specified array.

RELATED TOPICS
• PITimeDat() (page 91)
Specify a data item.
• PITimeExpDat() (page 92)
Specify an expression.

Timed Data example

To see values that correspond to an array of time stamps for the Historian 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:

FactoryTalk Historian DataLink User Guide 35

FactoryTalk Historian DataLink functions

The time-data array is based on time stamps in the first column.

Calculated Data function

• If you select the Data item option, the Calculated Data function returns one or more
evenly-spaced, calculated values based on Historian point or AF attribute values and
specified calculation preferences.
• If you select the Expression option, the Calculated Data function returns one or more
evenly-spaced, calculated values based on an evaluated performance equation and
specified calculation preferences.

Note: Click the + sign next to Advanced to access all function inputs.

Input Description
Root path The common path to specified data items, including those in expressions. Valid
entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which the
function returns values.
Reference a range of cells that contain Historian point names or AF attribute
names to return values for each.
Required if you select the Data item option.
Expression(s) One or more performance equations that the function computes a value for.
See Expressions (page 56).
Reference a range of cells that contain expressions to return 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 (page 11). Required.
End time The end of the time period for which the function returns values. Required.

36
 Calculated Data function

Input Description
Time interval The sampling frequency used to calculate values during the time period. Enter
a value and time unit. For example, enter 15m (15 minutes) to return a value for
every 15-minute interval in the time period. See Time-interval specification
(page 56).
Filter expression A Boolean performance equation that the function uses to filter values. When
the expression evaluates to false, the function excludes corresponding values.
See Filter expressions (page 58).
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.
 average
Computes the average of values during the interval.
 count
Counts the number of values stored during the interval.
 mean
Computes the event-weighted version of the average calculation.
Calculation basis The calculation method:
 time-weighted
Default. The function weights each event value by the length of time that the
event applies.
 event-weighted
The function weights each event equally. Select this option for batch values.
This method requires at least one event in a time period (two events for
standard deviation calculations).
Expression The method that the function uses to determine when to evaluate an
sampling expression:
 compressed
The function evaluates the expression during the time period at time stamps
where Historian Points or AF attributes in the expression have stored events.
 interpolated
The function evaluates the expression at evenly spaced sampling intervals,
determined by Expression sampling frequency.
Available if you select Expression or if you specify a Filter expression.

FactoryTalk Historian DataLink User Guide 37

FactoryTalk Historian DataLink functions

Input Description
Expression The frequency that the function evaluates an expression. Required if you set
sampling Expression sampling to interpolated.
frequency For example, set to 10m (10 minutes) to return an interpolated value for every
10-minute interval.
Minimum percent The minimum percentage of good data required in each time interval to
good calculate and return a value for that interval. The function returns the label
Insufficient good data for an interval that does not meet this
percentage.
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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian 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. FactoryTalk Historian 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. FactoryTalk Historian DataLink shows the end
time in a column to the left or in a row above returned values. Only available if
you specify Time interval.
Show min/max Select this check box to show the time stamp that corresponds to the minimum
time or maximum value during the interval used to calculate the value. Only
available for three values of Calculation mode:
 maximum
Shows the time stamp of the maximum value.
 minimum
Shows the time stamp of the minimum value.
 range
Shows the time stamps of the minimum value and the maximum value.
Show percent good Select this check box to show the percentage of time that good values were
returned during the array time period. FactoryTalk Historian DataLink shows
the percent-good values in a column to the right or in a row below returned
values.
Good values are event values that Historian Server determined were valid, and
not in an error state. You might use the percentage of good values to assess
the reliability of calculations built on Historian 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.

38
 Calculated Data function

Input Description
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), FactoryTalk Historian DataLink automatically selects
Column or Row to match the orientation of the specified range.

RELATED TOPICS
• PIAdvCalcVal() (page 94)
Specify a data item to retrieve a single value
• PIAdvCalcFilVal() (page 95)
Specify a data item and filter expression to retrieve a single value
• PIAdvCalcExpVal() (page 97)
Specify an expression to retrieve a single value
• PIAdvCalcExpFilVal() (page 98)
Specify an expression and a filter expression to retrieve a single value
• PIAdvCalcDat() (page 100)
Specify a data item and time interval to retrieve multiple values
• PIAdvCalcFilDat() (page 101)
Specify a data item, time interval, and filter expression to retrieve multiple values
• PIAdvCalcExpDat() (page 103)
Specify an expression and time interval to retrieve multiple values
• PIAdvCalcExpFilDat() (page 105)
Specify an expression, time interval, and filter expression to retrieve multiple values

Calculated Data example

To see the hourly range of values from midnight today until the present time for the Historian
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

FactoryTalk Historian DataLink User Guide 39

FactoryTalk Historian DataLink functions

The function returns the following array:

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 Historian
Server version.

Input Description
Root path The common path to specified data items, including those in expressions. Valid
entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian Server.
See Data items (page 10).
Expression(s) A Boolean performance equation that the function evaluates. See Expressions
(page 56).
Reference a range of cells that contain expressions to return values for each.
Required.
Start time The start of the time period for which the function returns values. See Time
inputs (page 11). Required.
End time The end of the time period for which the function returns values. Required.
Time interval The sampling frequency used to calculate values during the time period. Enter
a value and time unit. For example, enter 15m (15 minutes) to return a value for
every 15-minute interval in the time period. See Time-interval specification
(page 56).
Time units The units of time in which the function returns the result. Required.

40
 Time Filtered function

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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian 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. FactoryTalk Historian 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. FactoryTalk Historian 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. FactoryTalk Historian DataLink shows
the percent-good values in a column to the right or in a row below returned
values.
Good values are event values that Historian Server determined were valid, and
not in an error state. You might use the percentage of good values to assess
the reliability of calculations built on Historian 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 Expression(s), FactoryTalk Historian
DataLink automatically selects Column or Row to match the orientation of the
items.

RELATED TOPICS
• PITimeFilterVal() (page 108)
Return a single value
• PITimeFilter() (page 107)
Specify a time interval and return multiple values

Time Filtered example

To see the number of hours that the value of the Historian point sinusoid exceeded 75
during the previous seven days, set the following inputs for the Time Filtered function:

FactoryTalk Historian DataLink User Guide 41

FactoryTalk Historian DataLink functions

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.

Properties function
The Properties function returns the property value of a specified data item.
Input Description
Root path The common path to specified data items. Valid entries include:
 Historian Server name if the data item is a Historian point.
 AF server and database if the data item is a AF attribute.
 Blank if the data item is a Historian point on the default Historian Server.
See Data items (page 10).
Data item(s) One or more Historian point names or AF attribute names, for which the
function returns property values.
Reference a range of cells that contain Historian point names or AF attribute
names to display values for each. By default, FactoryTalk Historian DataLink
writes values in rows for a column of referenced data items, and in columns for
a row of referenced data items.

42
 Properties function

Input Description
Property The property for which the function returns values. The listed properties
depend on the entered data item:
 Single Historian 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 AF attribute. The list contains three AF attribute properties:
categories, description, and uom.
 Reference to multiple cells. The list depends on the type of data item in the
first referenced cell:
 Historian point. The list contains the point attributes from the point class of
that point.
 AF attribute. The list contains three AF attribute properties: categories,
description, and uom.
If the list is blank, FactoryTalk Historian 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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian DataLink
pastes the function formula in the unneeded cells of the specified array.

RELATED TOPICS
• PITagAtt() (page 83)

Properties example

To see attribute values of some Historian 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:

FactoryTalk Historian DataLink User Guide 43

FactoryTalk Historian DataLink functions

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.

44
Chapter 4

Worksheets
This section discusses how FactoryTalk Historian DataLink functions work within a
worksheet and how to manage and maintain your worksheet over time.

Function arrays
A function array is the cluster of cells that contains the output from a single FactoryTalk
Historian DataLink function. When you add a function to a worksheet, FactoryTalk Historian
DataLink enters the function formula into the specified output cells. The function queries
Historian Server or AF server and returns values in a function array. The size of the array
depends on the function, the number of matching values available, the number of values
requested, and the output requested.
The worksheet shows the returned values in the cells of a function array. However, these cells
actually contain the function formula. You can view the function formula in the Excel
formula bar when you click a cell.

1 — Function formula in formula bar

2 — Returned values in function array

Common function array tasks

Function arrays can be moved within, copied, or removed from a worksheet.

To select an array, do one of the following:
• Click and drag to select every cell in the array. Keep in mind that the array may have
empty values, which must also be selected.

FactoryTalk Historian DataLink User Guide 45

Worksheets

• 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 + Alt + Shift to apply
that change.

• Right-click any cell in the array and then click the desired Cut, Copy, Delete, Clear, or
Format command.
• Right-click a new cell and then click Paste to reinsert a cut or copied array.
• Place the pointer at the edge of the selected array, and when the pointer becomes a
movement pointer, drag the array to a new cell to move it.

Note: You must move or clear an entire function array, including all cells, or
FactoryTalk Historian DataLink returns an error message: You cannot
change part of an array.

• Open the function task pane and update the Output cell field to place the array in a new
location. See Update inputs to a function array (page 46).
You can also copy the values from a function array if you want to use them elsewhere in a
worksheet. After you copy and paste the values, they are no longer part of a function array;
they are simply cell values and are not updated. To copy array values:
• Select the function values you want, copy them, and use the Paste Special command to
paste values in the desired location.
You do not need to select the entire array column or row to copy values.

Update inputs to a function array

Use the function task pane to update a function array with new input values.
Procedure
1. Open the function task pane for an array:
ο With the automatic-task-pane display enabled, click a cell or multiple cells.
ο With the automatic-task-pane display disabled, select a cell or multiple cells, right-
click, and choose the function name.
The function task pane shows the current inputs for the selected function array.
If you selected a single cell, FactoryTalk Historian DataLink automatically detects
adjacent function arrays that differ only by source (that is, by data item or expression)
and selects those arrays for editing.

46
 Function arrays

If you selected multiple cells, FactoryTalk Historian 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 FactoryTalk Historian
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 FactoryTalk Historian
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 FactoryTalk Historian 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 FactoryTalk Historian DataLink returns:
• If the update returns fewer values, FactoryTalk Historian DataLink either returns blanks
or #N/A in the cells without values.
• If the update returns more values than the function array can show, FactoryTalk Historian
DataLink returns the text Resize to show all values at the bottom of the array
unless the preference settings disable the message.
Empty values can change the appearance of a worksheet. To maintain a constant size,
consider setting function inputs to limit returned data. For example, in the Compressed Data
function, you can specify the number of values to retrieve rather than a time period during
which you retrieve all values.
See also
• Calculation frequency (page 48)
• Resize arrays (page 47)
• Manage preference settings (page 17)

Resize arrays

An update or recalculation of a FactoryTalk Historian DataLink function might return more

or fewer values than a function array can show. Use the Recalculate (Resize) Function

FactoryTalk Historian DataLink User Guide 47

Worksheets

command to rewrite the entire function array: FactoryTalk Historian DataLink retrieves new
values from Historian Server or 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
FactoryTalk Historian DataLink writes a function array and calculates the current values for
the function whenever you click OK or Apply on the function task pane. To keep the data
current, you must recalculate the function array. Subsequent sections discuss approaches to
recalculate a function array.
For detailed information on how Excel manages calculation, see the Excel Recalculation
(http://msdn.microsoft.com/en-us/library/bb687891.aspx) topic in the MSDN library.

Automatic Update feature

The Automatic Update feature automatically initiates a recalculation of functions and trends
at a specified interval. Automatic Update applies to any workbook opened by the same Excel
session. Automatic Update pauses when you open a menu, task pane, or window, or you have
the current worksheet in edit mode. Automatic Update cannot update protected workbooks,
which are read-only.
Your preference settings affect Automatic Update:
• Type of update
A preference setting determines which functions update during Automatic Update. There
are two choices:
ο Calculate (F9)
Select this option to recalculate all volatile functions and any functions that reference
them during each recalculation.
ο Full Calculate (Ctrl+Alt+Shift+F9)
Select this option to recalculate all functions, regardless of volatility, during each
recalculation.
• Frequency of update
In the Interval field, enter the number of seconds between automatic recalculation. The
minimum value is five seconds. Enter 0 to have FactoryTalk Historian DataLink
automatically set the interval to twice the calculation duration, with a minimum interval
of five seconds. Rockwell Automation recommends you use the automatic interval to
ensure that Excel remains responsive 50% of the time.

48
 Calculation frequency

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 preference settings (page 17)
• Activate Automatic Update (page 49)
• Cancel Automatic Update (page 49)

Activate Automatic Update

Activate the Automatic Update feature to recalculate FactoryTalk Historian DataLink
functions automatically at a specified interval.
Procedure
• On the PI DataLink tab, click the Update button.
Excel immediately recalculates all FactoryTalk Historian 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 preference settings (page 17)

Cancel Automatic Update

Cancel the Automatic Update feature to stop automatic recalculation of FactoryTalk Historian
DataLink functions.
Procedure
• On the PI DataLink tab, click the highlighted Update button to clear the selection.
• Click ESC to cancel a recalculation in progress. FactoryTalk Historian DataLink finishes
the calculation for the currently-processing function, writes Calculation aborted
in unprocessed function array cells, and turns off Automatic Update.

Triggered recalculation

Excel recalculates volatile functions and any function that references a volatile function
whenever you edit any worksheet cell or press F9. Volatile functions include the Excel time
functions, now() and today(). The Current Value function is a volatile function; other
FactoryTalk Historian DataLink functions are not. You can trigger recalculation of non-
volatile FactoryTalk Historian DataLink functions by referencing a volatile function within
the non-volatile FactoryTalk Historian DataLink functions.

FactoryTalk Historian DataLink User Guide 49

Worksheets

Base FactoryTalk Historian DataLink functions on volatile Excel functions

If you do not use the Automatic Update feature, you can maximize the refresh frequency and
keep function arrays current by basing your FactoryTalk Historian DataLink functions on a
volatile Excel function.
Procedure
1. Use the Excel formula bar to enter a volatile function in a worksheet cell.
For example, you can use (today()+1/3) to represent 8 a.m. the same day, or
now()as a cell reference to replace the current Historian 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 FactoryTalk
Historian DataLink function.

Note: To maximize the frequency of updates when Automatic Update is not in use,
check your Excel calculation preferences to ensure that both the worksheet and
application are set to Automatic rather than Manual calculation. Keep in mind that
this may impact performance and make large worksheets difficult to use.

Manual recalculation

You can also manually recalculate FactoryTalk Historian DataLink functions:

• Press F9 to force all volatile functions (and any functions that reference them) to
recalculate.
• Press Ctrl+Alt+Shift+F9 to force all functions to recalculate.
• Right-click any part of a function array and then click Recalculate (Resize) Function.
This command will write the entire array and automatically size the array to fit the
returned data.

Worksheet sharing
To share FactoryTalk Historian System data with others, you can share worksheets created
with FactoryTalk Historian DataLink. To determine the best way to share your worksheets,
consider the following:
• You can send a FactoryTalk Historian DataLink workbook to another Microsoft Excel
user. The user must have FactoryTalk Historian DataLink installed and an active
connection to the same Historian Server and AF server in order to recalculate functions
and see dynamically updated Historian point and AF attribute values.
• Those who do not have FactoryTalk Historian DataLink installed can still see the last
data saved in the worksheet provided the Excel Workbook Calculation option is set to
Manual before they open the worksheet in Excel. See Set Workbook Calculation option
to manual (page 51).

50
 Worksheet sharing

• You can also save a worksheet as a web page or PDF file to share a static version of the
worksheet.
• You can copy and paste (page 45) 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.

Set Workbook Calculation option to manual

To let those without FactoryTalk Historian DataLink view the last data saved in the
workbook, set the Excel Workbook Calculation option to Manual before you save a
workbook.
Procedure
1. Click the File tab and select Options. (In Excel 2007, click the Microsoft Office Button,
and then click Excel Options.)
2. In the Excel Options window, click Formulas.
3. Under Calculation options, set Workbook Calculation to Manual, and then click OK.

FactoryTalk Historian DataLink User Guide 51

Chapter 5

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

Historian time
You can use a special syntax, called Historian Time, to specify inputs for time stamps and
time intervals. Historian Time uses specific abbreviations, which you combine to create time
expressions.

Historian time abbreviations

When specifying Historian Time, you can use specific abbreviations that represent time units
and reference times.

Time-unit abbreviations

Abbreviation Time unit

s second
m minute
h hour
d day
mo month
y year
w week

To specify time units, you can specify the abbreviation, the full time unit, or the plural
version of the time unit, such as s, second, or seconds. You must include a valid value
with any time unit. If specifying seconds, minutes, or hours, you can specify a fractional
value, such as 1.25h. You cannot specify fractional values for other time units.

Reference-time abbreviations

Abbreviation Full version Reference time

* Current time
t today 00:00:00 (midnight) of the current day

FactoryTalk Historian DataLink User Guide 53

Advanced topics

Abbreviation Full version Reference time

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.

Historian Time expressions

Historian Time expressions can include a reference time and a time offset, indicated by a
direction (either + or -) and a time unit with a value. Historian Time expressions might
include:
• Only a reference time, such as t
• Only a time offset, such as +3h
• A reference time with a time offset, such as t+3h
A reference time can be a fixed time, such as 24-aug-2012 09:50:00, or a valid
reference-time abbreviation, such as t.
You can only include one time offset in an expression. Including multiple offsets can lead to
unpredictable results. For example, the following time expressions are not valid:
*+1d+4h
t-1d+12h

Time-stamp specification

To specify inputs for time stamps, you can enter time expressions that contain:
• Fixed times
A fixed time always represents the same time, regardless of the field or the current time.
Input Meaning
23-aug-12 15:00:00 3:00 p.m. on August 23, 2012

54
 Historian time

Input Meaning
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 or fixed times with a time offset

When included with a fixed time or a reference-time abbreviation, a time offset adds or
subtracts from the specified time.
Input Meaning
*-1h One hour ago
t+8h 08:00:00 (8:00 a.m.) today
y-8h 16:00:00 (4:00 p.m.) the day before yesterday
mon+14.5h 14:30:00 (2:30 p.m.) last Monday
sat-1m 23:59:00 (11:59 p.m.) last Friday
1-jan-11-1d 00:00:00 (12:00 a.m.) 31 December 2010

• Time offsets
Entered alone in a time field, time offsets specify a time relative to an implied reference
time. The implied reference time depends on the field where you enter the expression:
ο For a start time, the reference time is the current clock time.
ο For an end time, the reference time is the start time.
ο For a single time stamp, the reference time is the current clock time.
Time field Input Meaning
Start time -1d One day before the current clock time (24
hours before the current clock time)
End time +6h Six hours after the start time
End time -30m 30 minutes before the start time
Time stamp -15s 15 seconds before the current clock time

FactoryTalk Historian DataLink User Guide 55

Advanced topics

Time-interval specification

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

Examples with positive time-interval value

Start time 2:00:00 3:15:00

End time 3:15:00 2:00:00

Time interval 30m 30m

Returned intervals 2:00:00 to 2:30:00 2:30:00 to 3:00:00
2:30:00 to 3:00:00 2:00:00 to 2:30:00

• Negative values define intervals that finish at the later time in the period and that begin at
or after the earlier time in the period.

Examples with negative time-interval value

Start time 2:00:00 3:15:00

End time 3:15:00 2:00:00
Time interval -30m -30m
Returned intervals 2:15:00 to 2:45:00 2:45:00 to 3:15:00
2:45:00 to 3:15:00 2:15:00 to 2:45:00

Expressions
In FactoryTalk Historian DataLink, expressions are performance equations that you can use
in functions to incorporate mathematical operations and calculations based on FactoryTalk
Historian System data items. For example, you might use an expression in a FactoryTalk
Historian DataLink function to calculate values as they are retrieved from Historian Server.

Note: FactoryTalk Historian DataLink restricts data items that you can include in
expressions. See Restrictions on data items in expressions (page 58).

Some FactoryTalk Historian 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 FactoryTalk Historian DataLink functions also have a Filter Expression field. Specify
a filter expression to limit the values that a function returns.
FactoryTalk Historian DataLink functions that can use expressions include:

56
 Expressions

• Archive Value (page 26)

• Compressed Data (page 29)
• Sampled Data (page 32)
• Timed Data (page 34)
• Calculated Data (page 36)
• Time Filtered (page 40)
Subsequent sections describe basic information about expressions. FactoryTalk Historian
DataLink supports all the syntax, operators, and functions that Historian Server supports.
For a full description of performance equations and examples, see the FactoryTalk Historian
SE Server Applications User Guide, available on your FactoryTalk Historian SE installation
DVD.

Use expressions in FactoryTalk Historian DataLink functions

Use expressions in FactoryTalk Historian DataLink functions to incorporate mathematical

operations and calculations based on FactoryTalk Historian System data items. Functions that
accept either a data item or an expression have Data item and Expression options at the top
of the task pane.
Before you begin
Open the function task pane.
Procedure
1. Click the Expression option at the top of the function task pane.
The Data item(s) field becomes an Expression(s) field. The availability of other fields
might change.
2. Enter the expression directly in the Expression(s) field, or enter a reference to a cell that
contains an expression.
Use cell references to specify multiple expressions for a function. Remember that an
expression in a referenced cell is a string, and should be preceded by a single quote.

Expression syntax

Follow these guidelines when writing expressions:

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

FactoryTalk Historian DataLink User Guide 57

Advanced topics

Restrictions on data items in expressions

FactoryTalk Historian DataLink permits the following data items in expressions:

• Historian Points
• AF attributes that store data references to Historian Points
• AF attributes that store constant values
Furthermore, a FactoryTalk Historian DataLink function can only return data from a single
Historian Server. Therefore, any Historian Points in an expression, including those referred to
by AF attributes, must be stored on the same Historian Server. Similarly, Historian Points in a
filter expression must be stored on the same Historian Server as any Historian Points
specified by the Data item or Expression fields.

Expression examples

The following expression computes the sum of the value of the Historian point sinusoid
cubed and the value of the Historian point cdf144 divided by 10:
(('sinusoid')^3 + 'cdf144'/10)
The following expression evaluates to true (non-zero) if the absolute value of the Historian
point mytag is at least 14.65:
(abs('mytag') >= 14.65)
The following expression evaluates to true if the value of the AF attribute Manufacturer is
ACME:
('\\Server\Database\Element|Manufacturer' = "Manual")
The following expression evaluates to true if the value of the Historian point sinusoid
is less than 45 and the square root of the value of the Historian point vdf1002 is greater
than 2:
('sinusoid' < 45 and sqr('vdf1002') > 2)

Filter expressions

Use a filter expression in a FactoryTalk Historian DataLink function to filter returned event
values with a Boolean performance equation. FactoryTalk Historian DataLink removes data
for which the expression evaluates as false.
FactoryTalk Historian DataLink applies the filter expression to the raw data retrieved (and
not values that result from the calculation itself). For example, adding the simple filter
expression 'sinusoid' < 70 to the Calculated Data function would remove all values
over 70 from the calculation.
Filter expressions can contain any valid Boolean performance equation; however, data items
in filter expressions must reference a Historian point. You can build complex expressions.
For example, you might use filter expressions to remove atypical peaks in data values.

58
 Manual function entry

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.
See also
• Expression syntax (page 57)
• Restrictions on data items in expressions (page 58)

Manual function entry

Though you can use the FactoryTalk Historian DataLink interface to build any FactoryTalk
Historian DataLink function, experienced users might prefer to enter functions directly in the
Excel formula bar.
The following topics apply to FactoryTalk Historian DataLink functions entered directly in
the formula bar.

Define functions manually

If you do not want to use the function task pane, you can define FactoryTalk Historian
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 FactoryTalk Historian DataLink function and its arguments into the Excel
formula bar.
3. Press Ctrl+Shift+Enter to place the FactoryTalk Historian DataLink function into the
selected output cells.
Refer to the online Help for Microsoft Excel for more information on array formulas.

Guidelines for entering arguments manually

The following table lists types of data you might enter as arguments to FactoryTalk Historian
DataLink functions, and provides guidelines for entering them.
Data entered as argument Guideline
Standard functions You can include various functions in arguments that accept
expressions. See the FactoryTalk Historian SE Server
Applications User Guide for a list of functions.
Strings Surround string arguments with double quotes.
For example, to retrieve the snapshot time and value for the
Historian point sinusoid from the Historian Server named
casaba, select a 1 x 2 output array and enter:
=PICurrVal("sinusoid", 1, "casaba")

FactoryTalk Historian DataLink User Guide 59

Advanced topics

Data entered as argument Guideline

Cell references You can use cell references for any FactoryTalk Historian
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 AF attributes specified in cells B3
through B5 and stored in the AF server DLAFPI, database
MyTest, and element Reactor, enter:
=PICurrVal(B3:B5,0,"\\DLAFPI\MyTest\Reactor")
See Data items (page 10) for information about valid entries.
Output codes Determines what appended data the function returns and how
the function orients output. See Output codes (page 60).

Output codes

FactoryTalk Historian DataLink function syntax contains an integer OutCode argument.

This argument takes an output code that determines which appended data (page 12) the
function returns and the orientation of output cells.
FactoryTalk Historian 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 FactoryTalk Historian 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 FactoryTalk Historian DataLink functions

Bit Purpose

1st Show time stamps

2nd Orient data in rows rather than columns

60
 Manual function entry

Bit Purpose

3rd Show percent good

4th Hide count
5th Show extended status
6th Show annotations

7th1 Show start time

8th1 Show end time

9th1 Show min/max time

1
Requires that the 1st bit be enabled also

With an OutCode argument of 0, a function returns the value in a column orientation with
no appended data. To compute the OutCode argument, use the following formula:

For example, with an OutCode argument of 0, the PISampDat() function returns the
sampled values in the designated output cell. With an OutCode argument of 1, the function
returns time stamps in column one and sampled values in column two of an n x 2 array. With
an OutCode argument of 3, the function returns time stamps in row one and the sampled
values in row two of a 2 x n array. (In these results, n is the number of sampled events.)

Note: Functions support different bits and therefore OutCode argument values. Those
valid for one function are not necessarily valid for another function. See the
function reference (page 75) for the bits that each function supports in its
OutCode specification.

EXAMPLE
Suppose you want the Calculated Data function to display percent good, start time, and
min/max time. To display the start time and min/max time, you must enable the show-time-
stamps bit. To calculate the OutCode argument:

FactoryTalk Historian DataLink User Guide 61

Advanced topics

In the Excel formula bar, enter:

=PICalcDat("sinusoid","y","t","1h","minimum", 1, 325,"piserver")

Note: If an OutCode argument specifies the display of multiple columns or rows but the
worksheet does not show them, right-click the function array and choose
Recalculate/Resize to rewrite the function array.

Functions to write data

Unlike standard FactoryTalk Historian DataLink functions, which retrieve data from a
Historian Server or AF server, the PIPutVal() and PIPutValX() (page 112) functions
write a value from a worksheet to a Historian Server or AF server. These functions can
replace existing values with new user-supplied values that have matching time stamps.
The PIPutVal() and PIPutValX() functions are Excel macro functions. You can run
the PIPutVal() or PIPutValX() function from an Excel 4.0 macro sheet, or in VBA
using the application.run method. See the putval_code module in the
piexam32.xls file distributed with FactoryTalk Historian DataLink for 32-bit Excel and
in the piexam64.xls file distributed with FactoryTalk Historian DataLink for 64-bit
Excel. In particular, see the tags marked PutVal and the VBA module PutVal_code for
an example of a VBA module used to enter FactoryTalk Historian DataLink functions in a
worksheet.
Note that VBA does not recognize FactoryTalk Historian DataLink functions, but you can
formulate a function as a text string, and then set the formula array property of a range of
cells to the text string value. The VBA code can then check the cell values for the
FactoryTalk Historian DataLink function results. This yields the same results as manual entry
of FactoryTalk Historian DataLink functions in the same range of cells.

62
Chapter 6

Tag functions
A Historian point is a stream of real-time data from a defined source. Point attributes,
including the tag (that is, the Historian point name) and point source, describe a Historian
point.
Use FactoryTalk Historian DataLink tag functions to find tags that correspond to Historian
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 FactoryTalk Historian DataLink (Legacy) add-in to use these
functions (see Microsoft Excel add-in configuration (page 3)).

See also
• Overview of FactoryTalk Historian DataLink functions (page 9)
• Properties function (page 42)
• Trends (page 67)

Point ID to Tag function

The Point ID to Tag function returns the tag that corresponds to a specific Historian point ID.
Input Description
Historian Server The Historian Server that the function returns data from. If you do not select a
server or leave the field blank, the function searches the default Historian
Server.
Point ID(s) One or more point IDs for which you want the function to return tags. 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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian DataLink
pastes the function formula in the unneeded cells of the specified array.

RELATED TOPICS

FactoryTalk Historian DataLink User Guide 63

Tag functions

• PIPointIDToTag() (page 109)

Point ID to Tag example

To see the tag that corresponds to a Historian 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 tag.

Attribute Mask to Tag function

The Attribute Mask to Tag function returns tags that match one or more specified Historian
point attribute values.
Input Description
Historian Server The Historian Server that the function returns data from. If you do not select a
server or leave the field blank, the function searches the default Historian
Server.
Tagname(s) Historian point attribute value for which the function finds the corresponding
tag. You must enter a value in at least one input. Use the wildcard character (*)
Descriptor to find all matches or matches limited to specified characters. For example,
Point source enter S* in Point source to find any tag with a point source of "S" or a point
source that begins with "S."
Point type
Point class
Engineering units
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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian DataLink
pastes the function formula in the unneeded cells of the specified array.
Column Click this option to return values in a column.

64
 Search for tags

Row Click this option to return values in a row.

RELATED TOPICS
• PIAttributeMaskToTag () (page 109)

Attribute Mask to Tag example

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

The function returns the following array:

Note that attribute strings must match attribute values in Historian Server, and wildcards can
be used.

Search for tags

For tag-information functions, use the Tag Search window to query Historian Server for
point IDs or tags to insert in the task pane.
Procedure

1. On the task pane, click next to the Point ID(s) or Tagname(s) field.
2. In the Tag Search window, click the appropriate tab for your search:
ο Basic Search
Use to create a mask from specified Historian Point Attributes and search for tags
that have matching attribute values.
ο Advanced Search
Use to build a query for a complex search that involves more point attributes than the
basic search.
ο Alias Search

FactoryTalk Historian DataLink User Guide 65

Tag functions

Use to select tags by their descriptive aliases in the Historian Module Database.
3. Enter the search criteria.
Use '*' or '?' as wildcard characters, as appropriate. For example, the Tag Mask Tem*
returns all point names that start with Tem, but Tem? returns only points that start with
Tem and end with another single character. All search fields are case insensitive.
4. If desired, click Favorites to access previous searches.
5. Click Search to find tags that match the specified criteria.
6. Select the desired tag in the Results panel, and click OK to insert the value in the task
pane.
If you select multiple tags, FactoryTalk Historian DataLink only pastes the first tag in the
task pane.

66
Chapter 7

Trends
The FactoryTalk Historian DataLink version for 32-bit Microsoft Office includes an ActiveX
trend object. You can insert a trend into a worksheet to visually depict changes in event
values over time. Trends can depict data in the worksheet or from selected Historian Points.

Note: You must activate the FactoryTalk Historian DataLink (Legacy) add-in to insert or
edit trends (see Microsoft Excel add-in configuration (page 3)).

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.

FactoryTalk Historian DataLink User Guide 67

Trends

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

ο Create a trace of values in the worksheet (page 69).
ο Create a trace of Historian point values retrieved from a Historian Server (page 69).
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 Historian point values retrieved from a Historian
Server, specify the time period to retrieve values:
a. Specify the start of the period in the Start Time field and the end of the period in the
End Time field. You can:
− Select a time string from the list.
− Type a time value in the field.
− Click to change the field to a data-reference field, and then click the work-
sheet cell that contains a time string or type the address of that worksheet cell.
See Historian Time (page 53) for a discussion of valid time strings.
b. Select the Enable Updates check box to refresh the trend with new Historian Server
data if the time range changes or extends to the present.
7. Click Next.
8. Specify the title and placement of the trend:
a. In the Trend title field, type a title for the trend.
b. Clear the Show Value Attributes check box if you do not want value attributes to
appear on trend traces.
The icons appear when the data contains events that have the Questionable,
Substituted, or Annotated bits set.
c. If desired, specify a different location for the trend. You can select:
− New worksheet to place the trend at the top left corner of a blank worksheet.
− Existing worksheet to place the trend in the current worksheet beginning in the
specified cell.
If you change the cell, make sure the new cell does not contain data.
9. Click Finish.

68
 Create a trend

Create a trace of values in the worksheet

When creating a trend with the Trend Add-in Wizard, you can define a trace for the trend
from values in a worksheet.
Procedure
1. In the Trend Add-in Wizard, click Data on worksheet.
2. Click the Cell Range containing data field, and then select the worksheet cells that
contain the values.
3. Specify options appropriate to the specified cell range:
ο Select the First element is trace name check box to use the value of an adjacent cell
as the name of the trace. (If the cell range is a column, then the name of the trace is in
the cell above the first value; if the cell range is a row, then the name of the trace is in
the cell to the left of the first value.)
ο Select the Include all cells in array check box to include all the cells in a function
array in the cell range. If you select this check box, the Cell Range containing data
field only needs to specify one cell in a function array.
ο Select the Stepped check box to plot a stepped trend instead of a continuous trace.
You might select this check box for Historian Points that store discrete values.
4. Click Add to insert the trace in the trend.

Create a trace of Historian point values retrieved from a Historian Server

When creating a trend with the Trend Add-in Wizard, you can define a trace for the trend
from values retrieved from a Historian Server.
Procedure
1. In the Trend Add-in Wizard, click Data from PI.
2. In the Tag name field, specify the Historian point name you want to retrieve values for.
You can:
ο Type the name of the point.
ο Click the field and then select the worksheet cells that contain names of points.
ο Click to open the Tag Search window, which you can use to search for tags
(page 65).
3. In the Server name field, specify the Historian 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.

FactoryTalk Historian DataLink User Guide 69

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

70
Chapter 8

Historian Module Database objects

The topics in this section describe the tools that FactoryTalk Historian DataLink provides to
access Historian Module Database objects. You can find these tools on the PI DataLink tab
in the Module Database group. See the Historian Server documentation for more
information about module databases and configuration.

Note: You must activate the FactoryTalk Historian DataLink (Legacy) add-in to use these
tools (see Microsoft Excel add-in configuration (page 3)).

Historian Module Database and worksheets

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

FactoryTalk Historian DataLink User Guide 71

Historian Module Database objects

Insert Historian Module Database objects into your worksheet

Use the Module Browse window to browse Historian aliases, properties, and module paths in
the Historian Module Database. You can select these items and copy them directly into a
worksheet.

Note: Aliases and properties corresponding to Historian Points must be configured in

your Historian Module Database to use the Module Database functions in
FactoryTalk Historian DataLink.

Procedure
1. Select a cell, and then on the PI DataLink tab click Module Browse to open the Module
Browse window.
2. Select the type of object you are looking for:
ο Alias
ο Property
ο Module
3. From the PI Server list, select the connected Historian Server that contains the module
database you want to browse.
4. From the Query date list, specify the effective date and time of the module database
hierarchy that you want to see.
5. Browse the tree hierarchy to find the desired item.
6. Select an item or a parent collection object that you want to copy to the worksheet:
ο Select an item to copy it to the worksheet.
ο Select a parent object (either Aliases or Properties) in a module to copy all the
aliases or properties of that module to the worksheet.
7. Select the Copy module path check box to copy the full module path of the alias or
property to the adjacent worksheet cell.
The module path provides the context for the selected object

Note: If the Copy PI Server name setting (see "Manage preference settings" on
page 17) is enabled, FactoryTalk Historian DataLink also copies the
corresponding Historian Server name.

8. Click OK to copy the selected items to the worksheet and close the window.

Module database functions

Use FactoryTalk Historian DataLink module database functions to find the tags that
correspond to aliases and properties in a module database tree. These functions use the
module path. You can enter a module path as a function argument or reference it from a

72
 Module database functions

worksheet cell. You can find module database functions on the PI DataLink tab in the
Module Database group.

Note: The function cannot resolve an alias or property object into a tag without a module
path. The path provides a context that maps the alias to a specific Historian point.

Also see Overview of FactoryTalk Historian DataLink functions (page 9).

Alias to Tag function

The Alias to Tag function returns the Historian tag that corresponds to a specified Historian
alias.
Option Description
Historian Server The Historian Server that the function returns data from. If you do not select a
server or leave the field blank, the function searches the default Historian
Server.
Alias(s) An alias in Historian Module Database. Required.
Module path The module path from the Historian Module Database where the specified alias
can be found. If you specify Alias by browsing the Module Database, then
FactoryTalk Historian DataLink enters Module path automatically. Required.
Query date An effective date of the alias. FactoryTalk Historian DataLink returns the tag
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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian DataLink
pastes the function formula in the unneeded cells of the specified array.
No server Choose to return only the Historian tag.
Server at right Choose to display the Historian Server that stores the tag in the cell to the right
of the tag.
Server at bottom Choose to display the Historian Server that stores the tag in the cell below the
tag.

RELATED TOPICS
• PIAliasToTag() (page 110)

Property to Value function

The Property To Value function returns the value or values corresponding to a specified
Historian property.

FactoryTalk Historian DataLink User Guide 73

Historian Module Database objects

FactoryTalk Historian DataLink can return values for Boolean, Date, Double, Integer, Long,
Null, Single, and String property types, or for Double, Integer, Long, and Single array
property types.
Option Description
Historian Server The Historian Server that the function returns data from. If you do not select a
server or leave the field blank, the function searches the default Historian
Server.
Property(s) A Historian property in Historian Module Database. Required.
Module path The module path from the Historian Module Database where the specified
property can be found. If you specify Property by browsing the Module
Database, then FactoryTalk Historian DataLink enters Module Path
automatically. Required.
Query date An effective date of the Historian property. FactoryTalk Historian DataLink
returns the tag that corresponds to 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, FactoryTalk Historian
DataLink inserts the selected cell into the Output cell field.
Specify the top-left corner of the function array. FactoryTalk Historian DataLink
expands the range downward and to the right of the output cell, as necessary
to return specified data. FactoryTalk Historian 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, FactoryTalk Historian 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.

RELATED TOPICS
• PIPropertyToValue() (page 111)

74
Chapter 9

Notifications
FactoryTalk Historian DataLink includes the Notifications add-in. When activated, this add-
in adds the Notification Search function to the PI DataLink tab. Use the Notification Search
function to retrieve FactoryTalk Historian System notifications that you subscribe to and to
insert those notifications into worksheets.
The Notifications add-in runs on Windows XP and later operating systems, and requires
Excel 2007 SP3 or later versions. PI Notifications must be installed on the computer to
activate the add-in (see Microsoft Excel add-in configuration (page )).

Note: You must have an account on at least one AF 2.0 server with Notifications 1.0,
and be subscribed to at least one notification rule to receive notifications.

To access the Notification Search function, click the desired output cell in the worksheet, and
then on the PI DataLink tab (in the Notifications group), click Notification Search to open
the Notification Search window.

Search and insert notifications

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

FactoryTalk Historian DataLink User Guide 75

Notifications

Procedure
1. On the PI DataLink tab, in the Notifications group, click Notification Search to open
the Notification Search window.
2. On the Search tab, select the AF server you will search for notifications:
ο From the PI Systems list, select a AF server and click Connect to connect to that
server.

If necessary, click Show List to open the AF Servers window, where you can
add a AF server (see "" on page ) to the list.

ο Click and then click a worksheet cell that contains the name of a AF server.
Click the button again to show the PI Systems list.
3. From the View Notifications list, select the option to filter returned notifications:
ο Select Active to return all currently-active notifications.
ο Select Timerange and enter Start Time and End Time values to return notifications
that occurred over a specific time range.
ο Select Recent and enter a value and a time interval to return the most recent
notifications over a specific time period.
4. In the Output Cell field, specify the worksheet cell where you want to insert the
notifications.
5. Click Search to retrieve the notifications that match the specified criteria into the results
area at the bottom of the tab.
6. Examine the retrieved notifications. You can:
ο Adjust display of retrieved notifications (page )
ο Manage retrieved notifications (page )
7. Click OK to insert the displayed notifications into the worksheet and close the window.
FactoryTalk Historian DataLink inserts the notification query into the worksheet as a
function array at the designated location. Like other FactoryTalk Historian DataLink
functions, the Notification Search function updates data when the worksheet recalculates
(see "" on page ).

Add a AF server to the Notification Search function

Your FactoryTalk Historian System might have multiple AF servers, each of which might
have PI Notifications installed and be a source of relevant notifications. For example, you
might subscribe to notifications from AF servers that run in different facilities or that
represent different business units.
Before you can view the notifications from a particular AF server in Excel, you must add that
AF server to the PI Systems list that the Notification Search function maintains.
Before you begin

76
 Search and insert notifications

Subscribe to the notifications in FactoryTalk Historian System Explorer.

Procedure

8. On the Search tab of the Notification Search window, click Show List next to the
PI Systems list to open the AF Servers window.

9. Click Add AF Server to open the AF Server Properties window.

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

Adjust display of retrieved notifications

On the Notification Search window, the results area at the bottom of the Search tab shows
the notifications that match the specified search criteria. You can adjust the display of these
notifications.
Procedure
• Click column headings to sort notifications by a particular attribute.
• Right-click the results to show and hide columns:

FactoryTalk Historian DataLink User Guide 77

Notifications

ο Click Expand All or Collapse All to expand or collapse a notification grouping.

ο Click Show Contact Events to toggle the display of contact events for each
notification.

Manage retrieved notifications

On the Notification Search window, the results area at the bottom of the Search tab shows
the notifications that match the specified search criteria. Before you insert retrieved
notifications into your worksheet, you can assess, manage, and respond to these notifications.
Procedure
Right-click a notification and choose a command:
• Acknowledge Instance
Acknowledge that action has been taken regarding the notification, and that no further
escalation is needed. If desired, enter a comment, and click OK.
• Acknowledge Subscription
Acknowledge receipt of a notification you are subscribed to. If desired, enter a comment
and click OK.
• Add Comment
Comment on a notification.
• View Notification Rule Summary
Display the properties of the notification rule that triggered a selected notification.

Inserted notifications
FactoryTalk Historian DataLink functions can reference notifications data in worksheet cells.
For example, you might use the Start Time value from a retrieved notification to retrieve
sampled data that indicates the progress of a batch process.

If your notifications are set to display acknowledgments, these columns include links to PI
Notifications web pages where you can acknowledge or comment on a notification.

78
 Notification display settings

Notification display settings

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

Columns
• Select columns from the Available columns list and click Add to move them to the
Column order list, which specifies the data inserted into the worksheet.

Note: Include the Acknowledge column to add a link in the worksheet to

acknowledge receipt of a notification, and include the Acknowledge With
Comment column to add a link in the worksheet to make a comment on a
notification.

• Click Add All to move all columns to the Column order list.
• Select columns from the Column order list and click the arrow buttons above the list to
change column order.
• Select columns from the Column order list and click Remove to remove the selected
columns from the list.
• Click Clear to remove all columns from the Column order list.
Contact events
• Select the Display contact events check box to include contact events related to each
notification, such as sending to each recipient, comments and acknowledgments.

FactoryTalk Historian DataLink User Guide 79

Notifications

• Select the Indent contacts check box to indent contact events in the worksheet. This can
help you identify them.
ο Select Using separate columns to add a second column for contact events.
ο Select Formatting cells to indent contact events in the same column as notification
events.
• Select the Group notifications with Excel grouping check box to use Excel's grouping
functionality to nest contact events beneath individual parent notifications that spawned
them.
Display and orientation
• Select the Display column headers check box to add headers to the notifications data.
• Select the Display count check box to add a row or column that contains the count of
notifications before the notifications data.
• Under Orient results in, select Columns to display notifications data in columns or
select Rows to display notifications data in rows.

80
Appendix A

Function reference
You can generate FactoryTalk Historian DataLink functions from FactoryTalk Historian
DataLink task panes (page 9). The resulting function array depends on the inputs. You can
also enter these same functions directly (page 59) in the Excel formula bar.
This section contains a reference to supported FactoryTalk Historian DataLink functions.
Each topic describes the function syntax and arguments; most topics also include an example.
Subsequent sections group functions by type.

Single-value functions
Single-value functions retrieve the value of a data item at a specific time. They return exactly
one value per data item.

PICurrVal()

Returns the current value of a Historian point from the snapshot or a AF attribute from the
database.
SYNTAX
PICurrVal(DataItem, OutCode, RootPath)
ARGUMENTS
Argument Description

DataItem The Historian point name or AF attribute name for which the function
(string) returns a value. Specify a range of cells that contain Historian point
names or AF attribute names to return a value for each.
OutCode An output code that determines what appended data the function
(integer) returns and how the function orients output. See Output Codes (page
60) for information on how to compute the code. This function supports
bits 1 and 2.
RootPath The path to the data item. See Data items (page 10).
(string)

EXAMPLE
The following function returns the current value and corresponding time stamp for the
Historian point let439 from the Historian Server named holden and places the time
stamp in the column to the left of the value:
=PICurrVal("let439",1,"holden")
RELATED TOPICS

FactoryTalk Historian DataLink User Guide 81

Function reference

• Current Value function (page 25)

• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIArcVal()

Returns the value of a Historian point or AF attribute at a specified time stamp.

SYNTAX
PIArcVal(DataItem, TimeStamp, OutCode, RootPath, Mode)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the
function returns a value. Specify a range of cells that contain
Historian point names or AF attribute names to return a value for
each.
TimeStamp (string) The time stamp for which the function returns values. See Time
inputs (page 11).
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes
(page 60) for information on how to compute the code. This
function supports bits 1 and 2.
RootPath (string) The path to the data item. See Data items (page 10).
Mode (string) The method the function uses to retrieve values:
 previous
 previous only
 interpolated
 auto
 next
 next only
 exact time

EXAMPLE
The following function returns the interpolated value of the Historian point cdep158 at 7:20
p.m. on December 11, 1992 from the Historian Server named casaba:
=PIArcVal("cdep158","11-dec-92 19:20",0, "casaba","interpolated")
RELATED TOPICS
• Archive Value function (page 26)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

82
 Single-value functions

PIExpVal()

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

SYNTAX
PIExpVal(Expression, TimeStamp, OutCode, RootPath)
ARGUMENTS
Argument Description
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
Reference a range of cells that contain expressions to return
values for each.
TimeStamp (string) The time stamp for which the function returns values. See Time
inputs (page 11).
OutCode (string) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes
(page 60) 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 (page 10).

EXAMPLE
The following function calculates the square root of the value of the Historian point
sinusoid from the Historian Server named thevax at midnight yesterday:
=PIExpVal("sqr('sinusoid')","y",0,"thevax")
RELATED TOPICS
• Archive Value function (page 26)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PITagAtt()

Returns a property value associated with a specified data item.

SYNTAX
PITagAtt(DataItem, Property, RootPath)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the
function returns a value. Specify a range of cells that contain
Historian point names or AF attribute names to return a value for
each.
Property (string) The Historian point attribute or AF attribute property for which the
function returns the value.

FactoryTalk Historian DataLink User Guide 83

Function reference

Argument Description
RootPath (string) The path to the data item. See Data items (page 10).

EXAMPLE
The following function returns the engineering units for the Historian point specified in cell
D1 from the default Historian Server:
=PITagAtt(d1,"uom",)
RELATED TOPICS
• Properties function (page 42)

Multiple-value functions
Multiple-value functions associate a Historian point or AF attribute with a time period over
which there can be one or many corresponding values.

PINCompDat()

Returns a specific number of Historian point values or AF attribute values beginning at a

certain time.
SYNTAX
PINCompDat(DataItem, STime, NumVals, OutCode, RootPath, Mode)
ARGUMENTS
Argument Description

DataItem (string) The Historian point name or AF attribute name for which the
function returns values. Specify a range of cells that contain
Historian point names or AF attribute names to return values for
each.
STime (string) The start of the time period for which the function returns values.
See Time inputs (page 11).
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
(page 60) 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 (page 10).

84
 Multiple-value functions

Argument 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

EXAMPLE
The following function returns ten values and the corresponding time stamps from the default
Historian Server for the Historian point cdf144 starting from 1:00 a.m. this morning, using
boundary type "inside":
=PINCompDat("cdf144","1:00:00",10,1,,"inside")
RELATED TOPICS
• Compressed Data function (page 29)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PINCompFilDat()

Returns a specific number of filtered Historian point values or filtered AF attribute values
beginning at a certain time.
SYNTAX
PINCompFilDat(DataItem, STime, NumVals, FiltExp, FiltCode,
OutCode, RootPath, Mode)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the function
returns values. Specify a range of cells that contain Historian point
names or AF attribute names to return values for each.
STime (string) The start of the time period for which the function returns values. See
Time inputs (page 11).
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 (page 58).
FiltCode (integer) A code that indicates whether to label filtered values:
 1
Insert the label Filtered in place of a value or block of values
that the function filtered from the output based on FiltExp.
 0
Do not label filtered values.

FactoryTalk Historian DataLink User Guide 85

Function reference

Argument Description
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes (page
60) 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 (page 10).
Mode (string) The method that the function uses to determine which values to
retrieve near the start time (boundary type):
 inside
 outside
 interpolated
 auto

EXAMPLE
The following function returns ten values and the corresponding time stamps from the default
Historian Server for the Historian point cdf144 starting from 2:00 a.m. this morning, when
the tag cdep158 is greater than 38, using boundary type "inside":
=PINCompFilDat("cdf144","2:00:00",10,"'cdep158'>38",1,1,,)
The output contains the label Filtered between any values where the filter condition was
false.
RELATED TOPICS
• Compressed Data function (page 29)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PICompDat()

Returns Historian point values or AF attribute values stored during a specified time period.
SYNTAX
PICompDat(DataItem, STime, ETime, OutCode, RootPath, Mode)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the
function returns values. Specify a range of cells that contain
Historian point names or AF attribute names to return values for
each.
STime (string) The start of the time period for which the function returns values.
See Time inputs (page 11).
ETime (string) The end of the time period for which the function returns values.

86
 Multiple-value functions

Argument Description
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes
(page 60) 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 (page 10).
Mode (string) The method that the function uses to determine which values to
retrieve near STime or ETime (boundary type):
 inside
 outside
 interpolated
 auto

EXAMPLE
The following function returns values and corresponding time stamps from the default
Historian Server for the Historian point cdf144 from 1:00 a.m. to 3:00 a.m. this morning
using boundary type "inside":
=PICompDat("cdf144","1:00:00","3:00:00",1,,"inside")
RELATED TOPICS
• Compressed Data function (page 29)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PICompFilDat()

Returns filtered Historian point values or filtered AF attribute values stored during a specified
time period.
SYNTAX
PICompFilDat(DataItem, STime, ETime, FiltExp, FiltCode, OutCode,
RootPath, Mode)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the function
returns values. Specify a range of cells that contain Historian point
names or AF attribute names to return values for each.
STime (string) The start of the time period for which the function returns values. See
Time inputs (page 11).
ETime (string) The end of the time period for which the function returns values.
FiltExp (string) A Boolean performance equation that the function uses to filter values.
When the expression evaluates to false, the function excludes
corresponding values. See Filter expressions (page 58).

FactoryTalk Historian DataLink User Guide 87

Function reference

Argument Description
FiltCode A code that indicates whether to label filtered values:
(integer)  1
Insert the label Filtered in place of a value or block of values that
the function filtered from the output based on FiltExp.
 0
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 (page
60) 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 (page 10).
Mode (string) The method that the function uses to determine which values to
retrieve near STime or ETime (boundary type):
 inside
 outside
 interpolated
 auto

EXAMPLE
The following function returns values and the corresponding time stamps for the Historian
point cdf144 from the default Historian Server, starting at 2:00 a.m. and ending at
10:00 a.m., when the Historian point cdep158 is greater than 38, using boundary type
"inside":
=PICompFilDat("cdf144","2:00:00","10:00:00","'cdep158'>38",1,1,,)
The output contains the label Filtered between any values where the filter condition was
false.
RELATED TOPICS
• Compressed Data function (page 29)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PISampDat()

Returns evenly-spaced, interpolated values for a Historian point or AF attribute stored over a
specified time period.
SYNTAX
PISampDat(DataItem, STime, ETime, Interval, OutCode, RootPath)
ARGUMENTS

88
 Multiple-value functions

Argument Description
DataItem(string) The Historian point name or AF attribute name for which the function
returns values. Specify a range of cells that contain Historian point
names or AF attribute names to return values for each.
STime (string) The start of the time period for which the function returns values. See
Time inputs (page 11).
ETime (string) The end of the time period for which the function returns values.
Interval The interval between returned values. Enter a value and time unit that
(string) specifies the length of the interval. For example, enter 15m (15 minutes)
to return a value for every 15-minute interval during the time period.
See Time-interval specification (page 56).
OutCode An output code that determines what appended data the function
(integer) returns and how the function orients output. See Output Codes (page
60) for information on how to compute the code. This function supports
bits 1 and 2.
RootPath The path to the data item. See Data items (page 10).
(string)

EXAMPLE
The following function returns sampled data and the corresponding time stamps for the
Historian point sinusoid from the default Historian Server, beginning at midnight
yesterday and ending at midnight today, reporting values in 3-hour intervals:
=PISampDat("sinusoid","y","t","3h",1,)
RELATED TOPICS
• Sampled Data function (page 32)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PISampFilDat()

Returns evenly-spaced, interpolated and filtered values for a Historian point or AF attribute
stored over a specified time period.
SYNTAX
PISampFilDat(DataItem, STime, ETime, Interval, FiltExp, FiltCode,
OutCode, RootPath)
ARGUMENTS
Argument Description

DataItem(string) The Historian point name or AF attribute name for which the
function returns values. Specify a range of cells that contain
Historian point names or AF attribute names to return values for
each.
STime (string) The start of the time period for which the function returns values.
See Time inputs (page 11).

FactoryTalk Historian DataLink User Guide 89

Function reference

Argument Description

ETime (string) The end of the time period for which the function returns values.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m (15
minutes) to return a value for every 15-minute interval during the
time period. See Time-interval specification (page 56).
FiltExp (string) A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).
FiltCode (integer) A code that indicates whether to label filtered values:
 1
Insert the label Filtered in place of a value or block of values
that the function filtered from the output based on FiltExp.
 0
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
(page 60) for information on how to compute the code. This function
supports bits 1 and 2.
RootPath (string) The path to the data item. See Data items (page 10).

EXAMPLE
The following function returns sampled data for the Historian point sinusoid from the
default Historian Server. The function retrieves values at midnight 11-Jan-97, 1:00 a.m. on
11-Jan-97, 2:00 a.m. on 11-Jan-97, and 3:00 a.m. on 11-Jan-97. If the condition in cell A1 is
not satisfied at any of those times, the function returns the label Filtered at that time. The
function shows time stamps in the first column and values in the second column.
=PISampFilDat("sinusoid","11-Jan-97","+3h","1h",A1,1,1,)
RELATED TOPICS
• Sampled Data function (page 32)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIExpDat()

Returns evenly-spaced, computed values of a performance equation over a specified time

period.
SYNTAX
PIExpDat(Expression, STime, ETime, Interval, OutCode, RootPath)
ARGUMENTS

90
 Multiple-value functions

Argument Description
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates a value.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m (15
minutes) to return a value for every 15-minute interval during the
time period. See Time-interval specification (page 56).
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes
(page 60) for information on how to compute the code. This function
supports bits 1 and 2.
RootPath (string) The path to the data item. See Data items (page 10).

EXAMPLE
The following function calculates the square root of the value of the Historian point
sinusoid retrieved from the Historian Server named thevax at one-hour intervals,
starting from midnight yesterday to midnight today:
=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax")
The function displays the time stamp for each value in the column to the left of the calculated
value.
RELATED TOPICS
• Sampled Data function (page 32)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PITimeDat()

Returns actual or interpolated sample values of a Historian point or AF attribute at specified

time stamps.
SYNTAX
PITimeDat(DataItem, TimeStamps, RootPath, Mode)
ARGUMENTS
Argument Description
DataItem(string) The Historian point name or AF attribute name for which the
function returns values. Specify a range of cells that contain
Historian point names or AF attribute names to return values for
each.

FactoryTalk Historian DataLink User Guide 91

Function reference

Argument Description
TimeStamps (reference) A reference to one or more worksheet cells that contain time
stamps for which the function returns values. See Time inputs
(page 11).
RootPath (string) The path to the data item. See Data items (page 10).
Mode (string) The method the function uses to retrieve data:
 interpolated
 exact time

RETURNS
Values at the specified time stamps, presented in the same orientation as the time stamp
reference. If the time stamp reference is a row, the function presents values in a row. If the
time stamp reference is a column, the function presents values in a column. The orientation of
the output array must match the orientation of the time stamp reference.
EXAMPLE
The following function retrieves interpolated values at the time stamps located in cells B1
through B12 for the Historian point mytag on the default Historian Server:
=PITimeDat("mytag",b1:b12,,"interpolated")
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
RELATED TOPICS
• Timed Data function (page 34)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PITimeExpDat()

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

SYNTAX
PITimeExpDat(Expression, TimeStamps, RootPath)
ARGUMENTS
Argument Description
Expression (string) One or more performance equations that the function computes
a value for. See Expressions (page 56).
Reference a range of cells that contain expressions to return
values for each.
TimeStamps (reference) A reference to one or more worksheet cells that contain time
stamps for which the function returns values. See Time inputs
(page 11).
RootPath (string) The path to the data item. See Data items (page 10).

RETURNS

92
 Multiple-value functions

Values at the specified time stamps, presented in the same orientation as the time stamp
reference. If the time stamp reference is a row, the function presents values in a row. If the
time stamp reference is a column, the function presents values in a column. The orientation of
the output array must match the orientation of the time stamp reference.
EXAMPLE
The following function calculates the square root of the value of the Historian tag
sinusoid retrieved from the default Historian Server at the times specified in cells B1
through B12:
=PITimeExpDat("sqr('sinusoid')",b1:b12,)
This function requires a twelve-cell horizontal output array, such as C1:C12 or B14:B25.
RELATED TOPICS
• Timed Data function (page 34)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

FactoryTalk Historian DataLink User Guide 93

Function reference

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

PIAdvCalcVal()

Returns a value calculated from Historian point or AF attribute values during a specified time
period.
SYNTAX
PIAdvCalcVal(DataItem, STime, ETime, Mode, CalcBasis, MinPctGood,
CFactor, OutCode, RootPath)
ARGUMENTS
Argument Description

DataItem(string) The Historian point name or AF attribute name for which the function
calculates a value. Specify a range of cells that contain Historian
point names or AF attribute names to calculate a value for each.
STime (string) The start of the time period for which the function calculates a value.
See Time inputs (page 11).
ETime (string) The end of the time period for which the function calculates a value.
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
MinPctGood The minimum percentage of good data required during the time
(number) period to calculate and return a value.
CFactor (number) A factor that the function applies to the returned value. Enter 1 if a
conversion factor is not needed. For time-weighted total calculations,
specify a factor that converts recorded rate values to the server
default time unit (units per day).

94
 Calculation functions

Argument Description

OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes (page
60) 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 (page 10).

EXAMPLE
The following function returns a time-weighted total of the Historian point cdf144
calculated from the values on the default Historian Server from yesterday to today:
=PIAdvCalcVal("cdf144","y","t","total","time-weighted",50,1,4,)
The function multiplies the result by 1, and only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of the calculated total.
RELATED TOPICS
• Calculated Data function (page 36)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIAdvCalcFilVal()

Returns a value calculated from filtered Historian point or AF attribute values during a
specified time period.
SYNTAX
PIAdvCalcFilVal(DataItem, STime, ETime, FiltExp, Mode, CalcBasis,
SampMode, SampFreq, MinPctGood, CFactor, OutCode, RootPath)
ARGUMENTS
Argument Description
DataItem (string) The Historian point name or AF attribute name for which the
function calculates a value. Specify a range of cells that contain
Historian point names or AF attribute names to calculate a value
for each.
STime (string) The start of the time period for which the function calculates a
value. See Time inputs (page 11).
ETime (string) The end of the time period for which the function calculates a
value.
FiltExp (string) A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).

FactoryTalk Historian DataLink User Guide 95

Function reference

Argument Description
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
SampMode (string) The sampling method the function uses to determine when to
evaluate FiltExp:
 compressed
 interpolated
SampFreq (string) The frequency that the function evaluates FiltExp if SampMode
is set to interpolated. Enter a relative Historian Time
expression (page 54). For example, set to 10m (10 minutes) to
return an interpolated value for every 10-minute interval.
MinPctGood (number) The minimum percentage of good data required during the time
period to calculate and return a value.
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
(page 60) 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 (page 10).

EXAMPLE
The following function returns the time-weighted total for the Historian point cdf144
calculated from the values on the default Historian Server, summing values from yesterday to
today during the time periods when the Historian point cdm158 is set to Manual:
=PIAdvCalcFilVal("cdf144","y","t","'cdm158'=""Manual""","total","t
ime-weighted","compressed","10m",50,1,4,)
The function multiplies the result by 1. Because the sampling mode is compressed, the
function ignores the sampling frequency and samples the filter expression at the compressed
events of the point cdf144. The function only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of the calculated total.
RELATED TOPICS

96
 Calculation functions

• Calculated Data function (page 36)

• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

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 Description

Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates a
value.
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
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 relative Historian
Time expression (page 54). For example, set to 10m (10 minutes)
to return an interpolated value for every 10-minute interval.

FactoryTalk Historian DataLink User Guide 97

Function reference

Argument 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
(page 60) 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 (page 10).

EXAMPLE
The following function returns the time-weighted total for the expression
'cdf144'+'cdt158' calculated from the values on the default Historian Server, using values
from yesterday to today:
=PIAdvCalcExpVal("'cdf144'+'cdt158'","y","t","total","time-
weighted","compressed","10m",50,1,4,)
The function multiplies the result by 1. Because the sampling mode is compressed, the
function ignores the sampling frequency and samples the filter expression at the combined
compressed events of cdf144 and cdt158. The function only returns a result if at least 50
percent of the data is good. The function returns the percent good to the right of the
calculated total.
RELATED TOPICS
• Calculated Data function (page 36)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIAdvCalcExpFilVal()

Returns a filtered, calculated Historian point value based on a performance equation.

SYNTAX
PIAdvCalcExpFilVal(Expression, STime, ETime, FiltExp, Mode,
CalcBasis, SampMode, SampFreq, MinPctGood, CFactor, OutCode,
RootPath)
ARGUMENTS

98
 Calculation functions

Argument Description
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates a
value.
FiltExp (string) A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
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 (page 56).
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
(page 60) 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 (page 10).

FactoryTalk Historian DataLink User Guide 99

Function reference

EXAMPLE
The following function returns the time-weighted total for the expression
'cdf144'+'cdt158' calculated from the values on the default Historian Server when
'productid' = "Product2" using values from yesterday to today:
=PIAdvCalcExpFilVal("'cdf144'+'cdt158'","y","t","'productid'=
"Product2"","total","time-weighted","compressed","10m",50,1,4,)
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 cdf144 and cdt158. The function only returns a result if at least 50
percent of the data is good. The function returns the percent good to the right of the
calculated total.
RELATED TOPICS
• Calculated Data function (page 36)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIAdvCalcDat()

Returns evenly spaced values calculated from Historian point or AF attribute values during a
specified time period.
SYNTAX
PIAdvCalcDat(DataItem, STime, ETime, Interval, Mode, CalcBasis,
MinPctGood, CFactor, OutCode, RootPath)
ARGUMENTS
Argument Description
DataItem(string) The Historian point name or AF attribute name for which the function
calculates values. Specify a range of cells that contain Historian point
names or AF attribute names to calculate values for each.
STime (string) The start of the time period for which the function calculates values.
See Time inputs (page 11).
ETime (string) The end of the time period for which the function calculates values.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m (15
minutes) to return a value for every 15-minute interval during the time
period. See Time-interval specification (page 56).

100
 Calculation functions

Argument Description
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
MinPctGood The minimum percentage of good data required during the time
(number) period to calculate and return a value.
CFactor (number) A factor that the function applies to the returned value. Enter 1 if a
conversion factor is not needed. For time-weighted total calculations,
specify a factor that converts recorded rate values to the server
default time unit (units per day).
OutCode (integer) An output code that determines what appended data the function
returns and how the function orients output. See Output Codes (page
60) 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 (page 10).

EXAMPLE
The following function returns the time-weighted total for the Historian point cdf144
calculated from the values on the default Historian Server for three-hour intervals from
midnight yesterday to midnight today:
=PIAdvCalcDat("cdf144","y","t","3h","total","time-weighted",50,
1,4,)
The function multiplies the result by 1, and only returns a result if at least 50 percent of the
data is good. The function returns the percent good to the right of each calculated total.
RELATED TOPICS
• Calculated Data function (page 36)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

PIAdvCalcFilDat()

Returns evenly spaced values calculated from filtered Historian point or AF attribute values
during a specified time period.

FactoryTalk Historian DataLink User Guide 101

Function reference

SYNTAX
PIAdvCalcFilDat(DataItem, STime, ETime, Interval, FiltExp, Mode,
CalcBasis, SampMode, SampFreq, MinPctGood, CFactor, OutCode,
RootPath)
ARGUMENTS
Argument Description
DataItem(string) The Historian point name or AF attribute name for which the
function calculates values. Specify a range of cells that contain
Historian point names or AF attribute names to calculate values
for each.
STime (string) The start of the time period for which the function calculates
values. See Time inputs (page 11).
ETime (string) The end of the time period for which the function calculates
values.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m
(15 minutes) to return a value for every 15-minute interval during
the time period. See Time-interval specification (page 56).
FiltExp (string) A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
SampMode (string) The sampling method the function uses to determine when to
evaluate FiltExp:
 compressed
 interpolated
SampFreq (string) The frequency that the function evaluates FiltExp if SampMode
is set to interpolated. Enter a relative Historian Time
expression (page 54). For example, set to 10m (10 minutes) to
return an interpolated value for every 10-minute interval.
MinPctGood (number) The minimum percentage of good data required during the time
period to calculate and return a value.

102
 Calculation functions

Argument Description
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
(page 60) 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 (page 10).

EXAMPLE
The following function returns the time-weighted total for the Historian point cdf144,
calculated from the values on the default Historian Server for three-hour intervals from
midnight yesterday to midnight today when Historian point cdf144 is set to Manual:
=PIAdvCalcFilDat("cdf144","y","t","3h","'cdm158'=""Manual""",
"total","time-weighted","compressed","10m",50,1,4,)
The function multiplies the result by 1. Because the sampling mode is compressed, the
function ignores the sampling frequency and samples the filter expression at the compressed
events of cdf144. The function only returns a result if at least 50 percent of the data is good.
The function returns the percent good to the right of the calculated total.
RELATED TOPICS
• Calculated Data function (page 36)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

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)
ARGUMENTS
Argument Description
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
Reference a range of cells that contain expressions to return
values for each.

FactoryTalk Historian DataLink User Guide 103

Function reference

Argument Description
STime (string) The start of the time period for which the function calculates
values. See Time inputs (page 11).
ETime (string) The end of the time period for which the function calculates
values.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m
(15 minutes) to return a value for every 15-minute interval during
the time period. See Time-interval specification (page 56).
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
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 relative Historian
Time expression (page 54). For example, set to 10m (10 minutes)
to return an interpolated value for every 10-minute interval.
MinPctGood (number) The minimum percentage of good data required during the time
period to calculate and return a value.
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
(page 60) 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 (page 10).

EXAMPLE
The following function computes the expression 'cdf144'+'cdt158' at any time stamp
between midnight yesterday and midnight today with an event stored at the default Historian

104
 Calculation functions

Server, and then calculates the time-weighted total of the computed values in three-hour
intervals:
=PIAdvCalcExpDat("'cdf144'+'cdt158'","y","t","3h","total", "time-
weighted","compressed", "10m",50,1,4,)
The function multiplies each calculated total by 1 and returns a value when the percent of
good values is at least 50 percent during the three-hour interval. The function returns the
percent good to the right of the calculated total. Note that because the sampling mode is
compressed, the function ignores the sampling frequency, and samples values whenever a
cdf144 or cdt158 event is stored.
RELATED TOPICS
• Calculated Data function (page 36)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

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 Description
Expression (string) One or more performance equations that the function computes a
value for. See Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates
values.
Interval (string) The interval between returned values. Enter a value and time unit
that specifies the length of the interval. For example, enter 15m
(15 minutes) to return a value for every 15-minute interval during
the time period. See Time-interval specification (page 56).
FiltExp (string) A Boolean performance equation that the function uses to filter
values. When the expression evaluates to false, the function
excludes corresponding values. See Filter expressions (page 58).

FactoryTalk Historian DataLink User Guide 105

Function reference

Argument Description
Mode (string) The type of calculation that the function performs:
 total
 minimum
 maximum
 stdev
 range
 average
 count
 mean
CalcBasis (string) The calculation method:
 time-weighted
 event-weighted
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 (page 56).
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
(page 60) 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 (page 10).

EXAMPLE
The following function calculates a time-weighted total for the expression 'cdf144'+'
cdt158' when 'productid' = "Product2" at three-hour intervals from yesterday to
today from the default Historian Server:
=PIAdvCalcExpFilDat("'cdf144'+'cdt158'","y","t","3h","'productid'=
"Product2"","total","time-weighted","compressed","10m",50,1,4,)
The function multiplies each calculated total by 1 and returns a value when the percent of
good values is at least 50 percent during the three-hour interval. The function returns the
percent good to the right of the calculated total. Note that because the sampling mode is
compressed, the function ignores the sampling frequency, and samples values whenever a

106
 Calculation functions

cdf144 or cdt158 event is stored or the value of productid changes to or from

Product2.
RELATED TOPICS
• Calculated Data function (page 36)
• Filter expressions (page 58)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

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 Description
Expression (string) A Boolean performance equation that the function evaluates.
See Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates
values.
Interval (string) The interval between returned values. Enter a value and time
unit that specifies the length of the interval. For example, enter
15m (15 minutes) to return a value for every 15-minute interval
during the time period. See Time-interval specification (page 56).
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
(page 60) 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 (page 10).

EXAMPLE

FactoryTalk Historian DataLink User Guide 107

Function reference

The following function returns the number of seconds that the expression in cell A1 is true on
the Historian Server named thevax during one-hour intervals, starting from midnight
yesterday to midnight today:
=PITimeFilter($A$1,"y","t","1h","seconds",65,"thevax")
The function shows the time stamp of the start of each calculation interval to the left of the
value.
RELATED TOPICS
• Time Filtered function (page 40)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

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 Description

Expression (string) A Boolean performance equation that the function evaluates. See
Expressions (page 56).
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 (page 11).
ETime (string) The end of the time period for which the function calculates a value.
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
(page 60) 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 (page 10).

EXAMPLE
The following function returns the number of seconds that the expression in cell A1 is true on
the Historian Server named thevax from midnight yesterday to midnight today:

108
 Tag functions

=PITimeFilterVal($A$1,"y","t","seconds",0,"thevax")
RELATED TOPICS
• Time Filtered function (page 40)
• Define functions manually (page 59)
• Guidelines for entering arguments manually (page 59)

Tag functions
Tag functions help you work with Historian tags.

PIPointIDToTag()

Returns the tag that corresponds to a specific Historian point ID.

SYNTAX
PIPointIDToTag(PointID, PIServer)
ARGUMENTS
Argument Description
PointID (string) A Historian point ID, which is a unique internal ID not reused upon
deletion of a point
PIServer (string) The Historian Server that the function returns data from. If you do not
select a server or leave the field blank, the function searches the
default Historian Server.

EXAMPLE
The following function searches the Historian Server named thevax for point ID 123, and
returns that point's tag:
=PIPointIDToTag("123","thevax")
RELATED TOPICS
• Point ID to Tag function (page 63)

PIAttributeMaskToTag ()

Returns tags that match one or more specified Historian point attribute values.
SYNTAX
PIAttributeMaskToTag(TagName, Descriptor, PointSource, PointType,
PointClass, EngUnits, OutCode, PIServer)
ARGUMENTS

FactoryTalk Historian DataLink User Guide 109

Function reference

Argument Description
TagName (string) Name of returned tags.1
Descriptor (string) Descriptor of returned tags.1
PointSource (string) Point source of returned tags.1
PointType (string) Point type of returned tags.1
PointClass (string) Point class of returned tags.1
EngUnits (string) Engineering units of returned tags.1
OutCode (integer) An output code that determines how the function orients output:
 0
Write values in a column.
 2
Write values in a row.
PIServer (string) The Historian Server that the function returns data from. If you
do not select a server or leave the field blank, the function
searches the default Historian Server.
1
Use wildcard character (*) to find all matches or matches limited to specified characters.

EXAMPLE
The following function returns the tags that start with "sin" from the Historian Server
named thevax:
=PIAttributeMaskToTag("sin*","*","*","*","*","*",0,"thevax")
RELATED TOPICS
• Attribute Mask to Tag function (page 64)

Module Database functions

PIAliasToTag()

Returns the PI tag that corresponds to a specified PI alias.

SYNTAX
PIAliasToTag(Alias, ModulePath, QueryDate, OutCode, PIServer)
ARGUMENTS
Argument Description
Alias (string) The module database alias that corresponds to the PI tag to return.
ModulePath The full module path to the alias
(string)
QueryDate An effective date of the alias. The function returns the tag that
(integer) corresponds to the specified alias on this date.

110
 Module Database functions

Argument Description
OutCode (integer) An output code that determines whether to append the server name
to the result:
 0
Returns only tag.
 1
Returns the Historian Server that stores the tag in the cell to the
right of the tag.
 2
Returns the Historian Server that stores the tag in the cell below
the tag.
PIServer (string) The Historian Server that the function returns data from. If you do
not select a server or leave the field blank, the function searches
the default Historian Server.

EXAMPLE
The following function returns the tag that corresponds to the Temperature alias of
module Reactor1, which is a submodule of Unit1. Unit1 is at the root of the module
database for a Historian Server named thevax. The module database is queried at the
current time.
=PIAliasToTag("Temperature","\Unit1\Reactor1","*",0,"thevax")
RELATED TOPICS
• Alias to Tag function (page 73)

PIPropertyToValue()

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

SYNTAX
PIPropertyToValue(Property, ModulePath, QueryDate, PIServer,
OutCode)
ARGUMENTS
Argument Description
Property (string) The module database property that corresponds to the PI point for
which the function retrieves values.
ModulePath The full module path to the property.
(string)
QueryDate An effective date of the PI property value. The function returns the
(integer) values that correspond to the specified property on this date.
PIServer (string) The Historian Server that the function returns data from. If you do not
select a server or leave the field blank, the function searches the
default Historian Server.

FactoryTalk Historian DataLink User Guide 111

Function reference

Argument Description
OutCode (integer) An output code that determines how to orient the result:
 0
Returns values in a column.
 2
Returns values in a row.

EXAMPLE
The following function returns the value corresponding to the Implementer property of
module Reactor1 which is a submodule of Unit1. Unit1 is at the root of the module
database for a Historian Server named thevax. The module database is queried at the
current time.
=PIPropertyToValue("Implementer","\Unit1\Reactor1","*","thevax")
RELATED TOPICS
• Property to Value function (page 73)

Input functions

PIPutVal() and PIPutValX()

Writes a value to Historian Server or PI AF server and returns a string that indicates the
status.
SYNTAX
PIPutVal(DataItem, Value, TimeStamp, RootPath, OutCell)
PIPutValX(DataItem, Value, TimeStamp, RootPath, OutCell)
ARGUMENTS
Argument 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 (page 11).

RootPath (string) The path to the data item. See Data items (page 10).

112
 Input functions

Argument Description

OutCell (reference) A reference to the cell where FactoryTalk Historian 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 FactoryTalk Historian System Explorer.
The PIPutVal and PIPutValX functions support all Historian Server data types,
including string input to string tags and subsecond data. The functions interpret time stamps
using client machine time zone information for Historian Server unless the Use Historian
Server Time Zone setting is enabled.
The functions do not verify the user-specified range for a point before writing the value. The
range is defined as zero to zero + span, where zero and span are point attributes
specified during point creation. The function returns a value written string even if Over
Range or Under Range is stored in Historian Server.
EXAMPLE
The following function writes the value located in the cell A5 in the Historian Server archive
on the default Historian Server for the PI point testtag with a time stamp of midnight
today:
=PIPutVal("testtag",a5,"t",,e5)
The function writes the result of the macro function in cell E5 on the worksheet.

FactoryTalk Historian DataLink User Guide 113

Appendix B

Troubleshooting
Consult the topics in this section if you experience difficulty using PI DataLink. If these
topics do not address or solve the problem, see Technical support and other resources (page
121) for details on contacting Technical Support.

Log files
PI DataLink does not generate a generic log file. You can use error messages in worksheets to
diagnose issues. However, some specific processes do generate log files:
• Installation
The ../pipc/dat directory contains the installation log files,
SetupPIDataLink_x64.log and SetupPIDataLink_x86.log.
• Historian Server connectivity
Examine the Historian Server log file in SMT for Historian Server connectivity issues.

PI DataLink tab not available

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

Array and cell limits

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

FactoryTalk Historian DataLink User Guide 115

Troubleshooting

Data retrieval limits

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

Data item not supported by function

The returned message "Data item not supported by function" can indicate:
• A AF attribute uses a custom data reference that does not allow calculations. To use in
FactoryTalk Historian 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 AF attribute of type
PI Point Array.

Security
Excel security features for add-ins, ActiveX controls, and macros control the types of
components that can run inside Excel. The security settings either disable, enable with
prompting, or completely enable these types of objects.
Excel security settings may conflict with certain FactoryTalk Historian DataLink features:
• FactoryTalk Historian DataLink is an Excel add-in. Security settings that disable add-ins
prevent FactoryTalk Historian DataLink from loading in Excel.
• Trends use a signed ActiveX control marked safe for initialization and require that
ActiveX controls be enabled.
• Worksheets that contain the PIPutVal or PIPutValX (page 112) function use macros and
require that macros be enabled.
If you regularly apply Excel security to worksheets, or encounter problems using these
FactoryTalk Historian DataLink features, you may need to reduce or eliminate Excel security
settings depending on how you plan to use FactoryTalk Historian DataLink.

116
 Historian Server connection issues

For further information on Excel security, consult Microsoft Excel online Help and online
resources.

Historian Server connection issues

This version of FactoryTalk Historian DataLink uses tighter security settings for connecting
to Historian Server. The new settings reduce exposure to security weaknesses associated with
PI password authentication.
The new security settings can result in errors if FactoryTalk Historian DataLink uses:
• PI user names and passwords to connect to Historian Server
• Default user to connect to Historian Server
Specifically, these settings might generate error -10407 "No Access - Secure Object" with
information about insufficient privilege to access Historian Server. The settings might also
generate a message about a disabled explicit login prompt.
To resolve these errors, you can:
• Configure mappings for users who connect to Historian Server. Rockwell Automation
recommends this approach (available in Historian Server version 3.0 and later). This is
the most secure connection method. See the Configuring Historian Server Security guide
for information on creating mappings. To use mappings, you must also enable the
Windows Security authentication protocol on each computer that runs FactoryTalk
Historian DataLink.
• Configure Trusts for users who connect to Historian Server. This is the next-best
approach. See the Configuring Historian Server Security guide for information on
creating Trusts. To use Trusts, you must also enable the Trust authentication protocol on
each computer that runs FactoryTalk Historian DataLink.
• Configure each computer to allow an explicit login prompt when a mapping or Trust is
not available. Rockwell Automation does not recommend this approach. Explicit logins
are not secure.

Note: Entering an incorrect password at a login prompt can result in the same error
message.

See also
• Configure a computer to allow explicit login prompts (page 117)
• Enable an authentication protocol (page 118)

Configure a computer to allow explicit login prompts

To connect to FactoryTalk Historian Server by logging in as a PI user, use PI SDK Utility to

allow explicit login prompts on your computer. You must configure each computer where
you connect to FactoryTalk Historian Server by logging in as a PI user.

FactoryTalk Historian DataLink User Guide 117

Troubleshooting

Caution: Rockwell Automation recommends that you select an alternative, more secure
method to connect to Historian Server.

Procedure
1. Click Start > All Programs > Rockwell Software > FactoryTalk Historian SE >
PISDKUtility to open PI SDK Utility.
2. Under PI-SDK, click Connections to show available PI Servers and update the utility
menus.
3. Click Connections > Options to open the Connection Options window.
4. Select the Allow login prompt (if all configured protocols fail) check box.
5. Click OK.
After you finish
A prompt will ask you for a user name and password each time you initiate a new connection
to Historian Server.

Enable an authentication protocol

To connect to Historian Server with a defined mapping or Trust, use PI SDK Utility to enable
the corresponding protocol on your computer. You must configure each computer where you
connect to Historian Server with a mapping or Trust.
Procedure
1. Click Start > All Programs > Rockwell Software > FactoryTalk Historian SE >
PISDKUtility to open PI SDK Utility.
2. Under PI-SDK, click Connections to show available PI Servers and update the utility
menus.
3. Click Connections > Options to open the Connection Options window.
4. Under Specify Authentication Procedure, use the arrow keys to move and sort the
enabled protocols listed under Protocol order. List the needed protocols:
ο To use PI mappings, Windows Security must be listed. This should be the first
protocol in the Protocol order list.
ο To use Trusts, PI Trust must be listed.
5. Click OK.

Cannot connect to PI OLEDB Enterprise Agent

The search error message, "Cannot connect to PI OLEDB Enterprise Agent," indicates that
the Windows service, PI OLEDB Enterprise Agent, is not running.
To clear the error, open the Services panel (such as through Administrative Tools from
Control Panel), and start the PI OLEDB Enterprise Agent service.

118
 Timeout exception

Timeout exception
Searches of PI Servers with large point databases might reach the data timeout before PI
Server returns all results. You will receive the following error:
OSIsoft.PI.Net.PITimeoutException: [-10722] PINET: Timeout on
PI RPC or System Call.
To eliminate the error, use Connection Manager to increase the data timeout value:
1. On the PI DataLink tab, in the Resources group, click Settings to open the Settings
window.
2. Click Connection Manager to open the Servers window.
3. Right-click the PI Server that returned the error, and then click Properties to open the PI
Server Properties window.
4. Increase the value of the Data Timeout field, and then click OK.

FactoryTalk Historian DataLink User Guide 119

Appendix C

Index
connections • 19
A conversion factor • 36
Current Value function • 25
add-ins, Excel
activating • 5
D
configuration • 3
enabling • 4 data items
viewing status • 4 description • 10
Advanced Calculated Data function • 36 restrictions in expressions • 58
Alias to Tag function • 73 searching for • 13
annotations • 29, 60 unsupported by function • 116
appended data • 12 data types • 2
Archive Value function • 26 display formats
arrays notifications • 79
common tasks • 45 number • 13
function • 45 time • 13
size • 47 trends • 70
updating inputs • 46
asset-relative displays E
creating • 22 errors • 115
description • 21 expression sampling frequency • 36
Attribute Mask to Tag function • 64 expression sampling mode • 36
automatic update expressions
activating • 49 calculation • 56
canceling • 49 data item restrictions • 58
description • 48 examples • 58
average • 36 filter • 58
syntax • 57
B
backwards in time • 29 F
boundary type • 29 filter expressions • 58
functions
C calculation frequency • 48
Calculated Data function • 36 defining • 8, 59
calculation basis • 36 manual entry • 59
calculation expressions • 56 modifying • 46
calculation mode • 36 module database • 72
cell references • 11 overview • 9
cells, worksheet reference • 81
function values • 45 tag • 63
references • 11 task panes • 8
Compressed Data function • 29

FactoryTalk Historian DataLink User Guide 121

Index

I PI DataLink tab
description • 7
inputs
not available • 115
task pane • 11
PI Module Database
time • 11
browsing • 72
time interval • 56
inserting objects in worksheet • 72
time stamp • 54
PI Notifications • 75
interface features • 7
PI point attributes
limiting searches with • 13
L
returning tags for • 64
legacy functions returning values of • 42
add-in for • 3 PI points
tag functions • 63 search limits • 13
trends • 67 specifying as data item • 10
supported data types • 2
M PI SDK • 2
Microsoft Excel PI Server
add-in configuration • 3 limiting search to • 13
security settings • 116 managing connections to • 19
minimum percent good • 36 PI time
Module Database, browse • 72 specifying time intervals • 56
move function arrays • 45 specifying time stamps • 54
PIAdvCalcDat • 100
N PIAdvCalcExpDat • 103
PIAdvCalcExpFilDat • 105
notifications PIAdvCalcExpFilVal • 98
add-in description • 75 PIAdvCalcExpVal • 97
display format • 79 PIAdvCalcFilDat • 101
inserting into worksheet • 75 PIAdvCalcFilVal • 95
searching for • 75 PIAdvCalcVal • 94
working with in worksheet • 79 PIAliasToTag • 111
number formats • 13 PIArcVal • 82
PICompDat • 86
O PICompFilDat • 87
outcode argument • 60 PICurrVal • 81
PIExpDat • 91
P PIExpVal • 83
percent good • 36, 40, 60 PINCompDat • 84
performance equations • 56 PINCompFilDat • 85
PI AF attributes PIPropertyValue • 112
showing values for elements • 21 PIPutVal • 112
specifying as data item • 10 PISampDat • 89
supported data types • 2 PISampFilDat • 89
PI AF SDK • 2 PITagAtt • 83
PI AF server PITimeDat • 92
adding to Notification Search function • 76 PITimeExpDat • 93
connections to • 19 PITimeFilter • 107
limiting search to • 13 PITimeFilterVal • 108
PI API • 2 Point ID to Tag function • 63
PI calculation expressions • 57 Property to Value function • 73

122
Q task panes • 8
time display formats • 13
quotes
Time Filtered function • 40
arguments in function formulas • 59
time inputs • 11
expressions • 57
time interval • 32, 36, 40, 56
time inputs • 11
time stamps • 11, 12, 54
worksheet cells • 11
Timed Data function • 34
totals • 36
R
trends
refresh data commands for • 70
automatic • 49 creating • 67
manual • 50 description • 67
retrieval mode • 26, 34 right-click menu • 70
right-click menu troubleshooting • 115
trend • 70
worksheet cell • 9 V
root paths
value attributes, show • 29
drop-down list • 22
volatile functions
root paths • 10
basing PI DataLink functions on • 50
specifying from search • 13
Current Value function • 25
triggered recalculation • 49
S
Sampled Data function • 32 W
search
worksheets
data items • 13
constructing for PI DataLink • 20
limiting by browsing server • 16
PI DataLink functions in • 45
limiting with path • 17
sharing with others • 50
tags in legacy functions • 65
security
Excel settings • 116
settings • 17
setup
Excel add-in configuration • 3
show annotations • 29, 60
show end time • 36, 40, 60
show min/max time • 36
show percent good • 36, 40, 60
show start time • 36, 40, 60
show time stamps • 25, 26, 29, 32, 60
show value attributes • 29
single quotes
expressions • 57
time inputs • 11
worksheet cells • 11
standard deviation • 36

T
tag functions • 63
Tag Search window • 65

FactoryTalk Historian DataLink User Guide 123

Rockwell Automation Support
Rockwell Automation provides technical information on the Web to assist you in using its products. At
http://www.rockwellautomation.com/support/, you can find technical manuals, a knowledge base of FAQs,
technical and application notes, sample code and links to software service packs, and a MySupport feature that
you can customize to make the best use of these tools.
For an additional level of technical phone support for installation, configuration, and troubleshooting, we offer
TechConnect support programs. For more information, contact your local distributor or Rockwell Automation
representative, or visit http://www.rockwellautomation.com/support/.

Installation Assistance
If you experience a problem within the first 24 hours of installation, review the information that is contained in
this manual. You can contact Customer Support for initial help in getting your product up and running.
United States or Canada 1.440.646.3434
Outside United States or Use the Worldwide Locator at http://www.rockwellautomation.com/support/americas/phone_en.html, or contact your
Canada local Rockwell Automation representative.

New Product Satisfaction Return

Rockwell Automation tests all of its products to ensure that they are fully operational when shipped from the
manufacturing facility. However, if your product is not functioning and needs to be returned, follow these
procedures.
United States Contact your distributor. You must provide a Customer Support case number (call the phone number above to obtain
one) to your distributor to complete the return process.
Outside United States Please contact your local Rockwell Automation representative for the return procedure.

Documentation Feedback
Your comments will help us serve your documentation needs better. If you have any suggestions on how to
improve this document, complete this form, publication RA-DU002, available at
http://www.rockwellautomation.com/literature/.

Rockwell Automation Publication HSEDL-UM025A-EN-E–September 2013

Supersedes Publication HSEDL-UM024A-EN-E Copyright © 2013 Rockwell Automation, Inc. All rights reserved. Printed in the U.S.A.