DATALINK USER GUIDE
PUBLICATION HSEDL-UM024A-EN-E–June 2012
Supersedes Publication HSEDL-UM023A-EN-E
●
●
●
●
●
Copyright
Contact Rockwell Automation
Customer Support Telephone — 1.440.646.3434
Online Support — http://www.rockwellautomation.com/support
Copyright Notice
© 2012 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA.
© 2010 OSIsoft, Inc. All rights reserved.
This document and any accompanying Rockwell Software products are copyrighted by Rockwell Automation Technologies, Inc. Any reproduction and/or distribution
without prior written consent from Rockwell Automation Technologies, Inc. is strictly prohibited. Please refer to the license agreement for details.
Trademark Notices
FactoryTalk, Rockwell Automation, Rockwell Software, the Rockwell Software logo are registered trademarks of Rockwell Automation, Inc.
The following logos and products are trademarks of Rockwell Automation, Inc.:
FactoryTalk Historian Site Edition (SE), FactoryTalk Historian Machine Edition (ME), RSView, FactoryTalk View, RSView Studio, FactoryTalk ViewStudio, RSView
Machine Edition, RSView ME Station, RSLinx Enterprise, FactoryTalk Services Platform, FactoryTalk Live Data, and FactoryTalk VantagePoint.
The following logos and products are trademarks of OSIsoft, Inc.:
PI System, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK.
Other Trademarks
ActiveX, Microsoft, Microsoft Access, SQL Server, Visual Basic, Visual C++, Visual SourceSafe, Windows, Windows ME, Windows NT, Windows 2000, Windows Server
2003, and Windows XP 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).
Ethernet is a registered trademark of Digital Equipment Corporation, Intel, and Xerox Corporation.
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.
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013.
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 anytime without prior notice. It is your responsibility to obtain the most current
information available from Rockwell when installing or using this product.
ii
Contents
Introduction ............................................................ 1
About this Document ............................................................ 2
FactoryTalk Historian DataLink Editions ..................................... 2
PI SDK........................................................................... 3
FactoryTalk Historian DataLink Language Support ..................... 3
System Requirements............................................................ 4
Installation and Upgrade ........................................................ 4
Installation to a Local PC ................................................... 4
Upgrade ........................................................................ 5
Configuration ................................................................. 5
Microsoft Excel 2007 ..................................................... 5
Microsoft Excel 2010 ..................................................... 6
Basics .................................................................... 7
User Interface..................................................................... 7
FactoryTalk Historian DataLink for Excel 2007 ......................... 8
PI Ribbon ................................................................... 8
Function Task Panes ..................................................... 9
FactoryTalk Historian DataLink for Excel XP-2003 .................... 10
PI Menu .................................................................... 11
Function Dialog Boxes .................................................. 13
Context Menu ................................................................ 14
FactoryTalk Historian Server Connections .................................. 15
Graphic Function Components ................................................ 17
iii
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Entry Fields ................................................................... 17
Standard Arguments ........................................................ 18
Tagname(s) or Expression .............................................. 19
Start Time ................................................................ 19
End Time .................................................................. 20
PI Server .................................................................. 20
Output Cell ............................................................... 20
Time Arguments ............................................................. 21
Appended Data .............................................................. 22
Appended Data Array ................................................... 23
Show Timestamps ....................................................... 24
Interval Timestamps .................................................... 24
Show Percent Good ..................................................... 25
Show Value Attributes .................................................. 25
Show Annotations ....................................................... 26
Orientation Controls ........................................................ 26
Display Formats .............................................................. 27
Preference Settings ............................................................. 29
Spreadsheet Construction ..................................................... 31
FactoryTalk Historian DataLink Functions ....................... 33
Current Value .................................................................... 33
Archive Value .................................................................... 34
Compressed Data ................................................................ 36
Sampled Data .................................................................... 39
Timed Data ....................................................................... 41
Calculated Data ................................................................. 43
Time Filtered .................................................................... 48
iv
FactoryTalk Historian Tags and Attributes ...................... 51
Tag Search ........................................................................ 51
Tag Functions .................................................................... 54
● Contents
●
●
●
●
●
Point ID to Tag ............................................................... 54
Attribute Mask to Tag ...................................................... 55
Tag Attributes ............................................................... 56
Module Database Objects ........................................... 57
Module Database Browse ...................................................... 58
Module Database Functions ................................................... 60
Alias to Tag ................................................................... 61
Property to Value ........................................................... 61
Spreadsheets .......................................................... 63
Calculation Frequency.......................................................... 63
Automatic Update ........................................................... 63
Triggered Recalculation .................................................... 64
Manual Recalculation ....................................................... 65
Functions and Array Values .................................................... 66
Array Management .............................................................. 67
Update Arguments .......................................................... 68
Resize Arrays ................................................................. 69
Share Spreadsheets ............................................................. 70
Trend Displays ........................................................ 73
Create a Trend................................................................... 74
Worksheet Data .............................................................. 75
FactoryTalk Historian Data ................................................ 76
Manage Traces ............................................................... 77
Specify the Time Range ........................................................ 78
Title and Placement ............................................................ 79
Context Menu .................................................................... 80
Supplementary Information ........................................ 83
Setup .............................................................................. 83
v
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
High Availability Connection Preferences ............................... 84
FactoryTalk Historian Server Connectivity.............................. 84
Firewall Database ....................................................... 84
FactoryTalk Historian Trusts .......................................... 85
Point Access Permissions ............................................... 85
FactoryTalk Historian Time .................................................... 86
FactoryTalk Historian Time Abbreviations .......................... 86
FactoryTalk Historian Time Expressions ............................. 87
FactoryTalk Historian Time String Examples ....................... 88
FactoryTalk Historian Data Type Support ................................... 89
FactoryTalk Historian Expressions ............................................ 90
Syntax ......................................................................... 91
Operators ..................................................................... 91
Performance Equation Functions ......................................... 93
Math Functions ........................................................... 94
Aggregate Functions .................................................... 95
Miscellaneous Functions ................................................ 95
FactoryTalk Historian Archive Retrieval ............................. 96
FactoryTalk Historian Archive Search................................ 96
FactoryTalk Historian Archive Statistics ............................ 97
Point Attributes .......................................................... 97
Time Functions .......................................................... 98
Dynamic Response ....................................................... 99
Alarm Status Functions ................................................. 99
String Functions ......................................................... 99
String Conversion ...................................................... 100
FactoryTalk Historian Expression Examples .......................... 101
Manual Function Entry........................................................ 101
Use Array Functions ....................................................... 102
Mathematical Functions .................................................. 102
String Arguments .......................................................... 103
Cell References ............................................................ 103
PIServer Argument ........................................................ 103
Outcodes .................................................................... 104
Write Data to FactoryTalk Historian ....................................... 105
vi
● Contents
●
●
●
●
●
Troubleshooting ............................................................... 106
FactoryTalk Historian Menu Not Available ............................ 106
Array and Cell Limits ..................................................... 107
Row Limitations ........................................................... 107
Security ..................................................................... 108
FactoryTalk Historian Security .......................................... 108
FactoryTalk Historian DataLink Function Reference ........ 111
Single Value Functions ....................................................... 111
PICurrVal() .................................................................. 111
PIArcVal() ................................................................... 112
PIExpVal() ................................................................... 113
Multiple Value Functions ..................................................... 114
PINCompDat() .............................................................. 114
PINCompFilDat() ........................................................... 115
PICompDat() ................................................................ 116
PICompFilDat() ............................................................. 117
PISampDat() ................................................................ 118
PISampFilDat() ............................................................. 119
PIExpDat() .................................................................. 121
PITimeDat() ................................................................ 122
PITimeExpDat() ............................................................ 123
Calculation Functions......................................................... 124
vii
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
PICalcVal() .................................................................. 124
PIAdvCalcVal() ............................................................. 126
PIAdvCalcFilVal() .......................................................... 127
PIAdvCalcExpVal() ......................................................... 129
PIAdvCalcExpFilVal() ...................................................... 130
PICalcDat() ................................................................. 132
PIAdvCalcDat() ............................................................. 133
PIAdvCalcFilDat() .......................................................... 134
PIAdvCalcExpDat() ........................................................ 136
PIAdvCalcExpFilDat() ..................................................... 137
PITimeFilter() .............................................................. 139
PITimeFilterVal() .......................................................... 140
Tag Functions .................................................................. 141
PIPointIDToTag() .......................................................... 141
PIAttributeMaskToTag () ................................................. 142
PITagAtt() ................................................................... 143
Module Database Functions ................................................. 144
PIAliasToTag() .............................................................. 144
PIPropertyToValue() ...................................................... 145
Input Functions ................................................................ 146
PIPutVal() ................................................................... 146
viii
Technical Support and Resources ............................... 149
Technical Support ............................................................. 149
Knowledgebase ............................................................ 149
Worldwide Support ........................................................ 150
Training Programs ......................................................... 150
Consulting Services ....................................................... 150
TechConnect Support ..................................................... 150
Find the Version and Build Numbers ................................... 151
View Computer Platform Information ................................. 152
Index .................................................................. 153
Chapter 1
Introduction
FactoryTalk Historian DataLink is a Microsoft Excel add-in that enables
you to retrieve information from your FactoryTalk Historian server directly
into a spreadsheet. With FactoryTalk Historian DataLink, you can:
Retrieve point values from a FactoryTalk Historian server.
Retrieve system metadata to create a structured view of FactoryTalk
Reference these items using FactoryTalk Historian DataLink functions
Keep values updated when the spreadsheet recalculates.
Build a trend from the spreadsheet data or selected FactoryTalk
Historian data:
FactoryTalk Historian tag names and attributes.
FactoryTalk Historian Module Database (MDB) paths, aliases and
properties.
to calculate and filter data.
Historian points.
FactoryTalk Historian DataLink provides a graphical interface to retrieve
data and build functions and calculations. DataLink functions are
embedded in spreadsheet cells and can provide active updates of real-time
data from the FactoryTalk Historian server.
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.
1
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
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 data.
About this Document
The FactoryTalk Historian DataLink Online Help provides a detailed
description of product features and a complete reference to FactoryTalk
Historian DataLink functions. The content of the print guide and the online
help is identical. Trend control objects also launch a separate help file
which includes information on programmatic controls for trends.
Specific references to FactoryTalk Historian DataLink for Excel XP-2003
are labeled (2003), and those specific to FactoryTalk Historian DataLink
for Excel 2007 are labeled (2007), when necessary.
FactoryTalk Historian DataLink Editions
Throughout this book, references to Microsoft Excel 2007 apply to Microsoft
Excel 2007 and later. References to Microsoft Office 2007 apply to Microsoft Office
2007 and later.
Two editions of FactoryTalk Historian DataLink are installed on your
system:
An add-in is installed for Microsoft Excel 2007. This add-in cannot
An add-in is installed for Microsoft Excel XP or 2003. This add-in
The differences between the add-ins reside primarily in design and user
interface (page 7) changes for Office 2007 and later.
2
run in earlier versions of Excel. This edition is configured
automatically if you have Excel 2007 on your system.
resembles earlier versions of FactoryTalk Historian DataLink and
must be configured manually.
1 ● Introduction
●
●
●
●
●
PI SDK
PI SDK is installed with FactoryTalk Historian DataLink, and connects
FactoryTalk Historian DataLink to your FactoryTalk Historian server to
retrieve FactoryTalk Historian point data. FactoryTalk Historian is based
on OSIsoft PI and uses PI SDK. FactoryTalk Historian DataLink uses both
PI SDK and the Microsoft Excel SDK. When an error occurs at the PI SDK
level, FactoryTalk Historian DataLink displays the error in the cell. For
example, if a function attempts to retrieve the current value of a tag that
does not exist, the output cell displays a "Tag not found" message.
PI SDK also allows users with Microsoft Visual Basic for Applications
(VBA) experience to develop Excel routines that call PI SDK functions.
Users who plan to develop programs outside of Excel must purchase a
separate PI SDK or PI API license. Contact your Rockwell Automation
sales representative for more information.
FactoryTalk Historian DataLink Language Support
This release of FactoryTalk Historian DataLink provides multi-language
support. The user interface of the add-in appears in the same language as
the Microsoft Excel that it runs in, if the language is supported by
FactoryTalk Historian DataLink. Otherwise the add-in appears in English.
To view the add-in in a different language, use the Microsoft Office
language setting tool to change the language of Microsoft Excel.
To get the multi-language support, you must install the separate language
pack.
3
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
System Requirements
For up to date system requirements, see the KB article 42682
(https://rockwellautomation.custhelp.com/app/answers/detail/a_id/42682)
at the Rockwell Automation Support Center.
Installation and Upgrade
Before installation, each user of FactoryTalk Historian DataLink must be
licensed to use this product. Contact Rockwell Automation for more information.
The user may install FactoryTalk Historian DataLink from the distribution
CD.
After a successful installation of FactoryTalk Historian DataLink to a
network file server, other users will be able to install from the network
drive to a local PC a complete standalone version of FactoryTalk Historian
DataLink.
Installation of a standalone version places a copy of all the FactoryTalk
Historian DataLink files onto the user's local PC.
Installation to a Local PC
In order to use FactoryTalk Historian DataLink, every user must install a
complete standalone version. Installation may be performed either from the
distribution CD or from the network drive.
A self-extracting zip file is supplied as the distribution kit for FactoryTalk
Historian DataLink.
To install FactoryTalk Historian DataLink:
1. Log on to a user's PC with an account that has administrative
2. Unzip the file into a temporary directory.
4
privileges.
1 ● Introduction
●
●
●
●
●
3. Run Setup.exe from the temp directory and follow the directions
displayed in the installation wizard.
After the installation, you will be prompted to restart your computer.
You can view the results of the installation process by examining the setup
log, fth_installer.log, saved under the following location:
C:\Program Files\Rockwell Software\FactoryTalk
Historian\Installation Manager\<Name of the Historian
suite>\FTHInstallerLogs\<Date and Time of the Installation>.
Upgrade
To upgrade FactoryTalk Historian DataLink to a newer version, remove
the current version of the product from the computer and install the new
one.
Configuration
After installation, you may need to configure the FactoryTalk Historian
DataLink add-in in Microsoft Excel.
Microsoft Excel 2007
The FactoryTalk Historian DataLink setup program automatically installs
the DataLink add-in for Microsoft Excel 2007 if this version is found on
your system. No configuration is necessary.
Installation makes FactoryTalk Historian DataLink available to all users of
the client machine. If an individual user deactivates FactoryTalk Historian
DataLink or a related add-in, updates do not reactivate the add-in; it must
be restored manually. To restore add-ins:
1. Click the Microsoft Office Button and select Excel Options.
5
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
2. Click Add-ins > Manage Disabled Items > Go and enable
PIDatalink.UI.dll.manifest.
3. Go to Add-ins > Manage Com Add-Ins > Go and enable PI DataLink.
4. Click OK.
Microsoft Excel 2010
The FactoryTalk Historian DataLink setup program automatically installs
the DataLink add-in for Microsoft Excel 2010 if this version is found on
your system. No configuration is necessary.
Installation makes FactoryTalk Historian DataLink available to all users of
the client machine. If an individual user deactivates FactoryTalk Historian
DataLink or a related add-in, updates do not reactivate the add-in; it must
be restored manually. To restore add-ins:
1. Click the File tab and select Excel Options.
2. Click Add-ins > Manage Disabled Items > Go and enable
PIDatalink.UI.dll.manifest.
3. Go to Add-ins > Manage Com Add-Ins > Go and enable PI DataLink.
4. Click OK.
6
Chapter 2
Basics
The following sections introduce basic FactoryTalk Historian DataLink
concepts and features. You should familiarize yourself with these sections
before using FactoryTalk Historian DataLink to build a spreadsheet and
retrieve FactoryTalk Historian data, particularly if you are new to
FactoryTalk Historian DataLink or Office 2007.
These sections describe:
Common interface components, and how they differ between
DataLink add-ins for Excel XP-2003 and Excel 2007.
Core features required to begin working with FactoryTalk Historian
DataLink.
Different approaches to building a FactoryTalk Historian DataLink
spreadsheet, depending on your goals, needs, and resources.
User Interface
FactoryTalk Historian DataLink is an add-in application to Microsoft
Excel, and appears within the Microsoft Excel user interface in the form of
menus, dialog boxes and task panes specific to FactoryTalk Historian
DataLink.
While the underlying functionality of FactoryTalk Historian DataLink is
the same for Excel XP-2003, and 2007, the user interface and tools used to
build and manage FactoryTalk Historian DataLink spreadsheets differ
slightly to reflect the design and objects available from the corresponding
version of Microsoft Excel.
7
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
FactoryTalk Historian
DataLink for Excel XP-2003
FactoryTalk Historian DataLink for Excel 2007
PI menu.
PI ribbon.
Function dialog boxes.
Function task panes.
Right-click context menu.
Right-click context menu.
Trend Control Wizard.
Trend Control Wizard.
Depending on your version of Excel, you may work with either of the
following groups of FactoryTalk Historian DataLink components:
The following sections describes the visual and operational differences
between DataLink add-ins.
FactoryTalk Historian DataLink for Excel 2007
FactoryTalk Historian DataLink for Excel 2007 includes design elements
introduced in Microsoft Office 2007.
If you are upgrading from a previous version of FactoryTalk Historian
DataLink, familiarize yourself with the new design elements before you
begin working with FactoryTalk Historian DataLink.
PI Ribbon
The DataLink add-in for Microsoft Excel 2007 uses a ribbon menu.
The ribbon menu is a graphical menu that combines features of both a
standard menu and a toolbar.
Click PI in the Excel menu bar to select the tab for the PI DataLink
8
ribbon menu.
2 ● Basics
●
●
●
●
●
Click an item in the PI ribbon to open a corresponding task pane or
dialog box.
Place the cursor over an item to display a descriptive tooltip.
Function Task Panes
FactoryTalk Historian DataLink for Microsoft Excel 2007 provides custom
task panes to define FactoryTalk Historian DataLink functions.
A task pane is a moveable and dockable panel of controls that functions
much like a dialog box, except that you can continue to work on a
spreadsheet while a task pane is open.
FactoryTalk Historian DataLink opens a task pane when you add a
function or select a cell in a function array for editing. To open a function
task pane:
9
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Click in the desired output cell, and then click a function on the PI
ribbon to add a function.
Click a cell in an existing function array to display a corresponding
task pane and edit function arguments.
Right-click a function array cell and choose the function name to
manually display the task pane.
You can
turn off automatic display
(page 29) of task panes if you prefer.
Once a function task pane is open:
Type or change values, and then click OK to save your changes and
close the task pane. Click Apply to save changes 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 in the task pane title bar to detach and Move, or
Resize the task pane.
You can also click the title bar to drag and dock a task pane, or place your
cursor over the edge and drag to resize the pane.
Dialog boxes are used for other tasks including Tag Search, Preferences
and Connections in the add-in for Excel 2007.
FactoryTalk Historian DataLink for Excel XP-2003
FactoryTalk Historian DataLink for Excel XP-2003 appears in Microsoft
Excel as a standard menu and related dialog box controls.
If you have used previous releases of FactoryTalk Historian DataLink, the
add-in for Excel XP-2003 maintains the same look and feel.
10
2 ● Basics
●
●
●
●
●
PI Menu
FactoryTalk Historian DataLink for Excel XP-2003 adds a PI menu to the
Excel menu bar once the DataLink add-in is loaded. If you do not see the
PI menu, you may need to configure the DataLink add-in for Excel.
11
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
FactoryTalk Historian DataLink for Excel XP-2003 uses a standard menu
configuration:
12
2 ● Basics
●
●
●
●
●
Choose an item from the PI menu to open a corresponding dialog box.
Function Dialog Boxes
FactoryTalk Historian DataLink for Microsoft Excel XP-2003 provides
dialog boxes to define FactoryTalk Historian DataLink functions.
FactoryTalk Historian DataLink opens a corresponding function dialog box
when you add or edit a function. To open a function dialog box:
Click in a cell and then choose a function from the PI menu to add a
function.
Right-click a cell in an existing function array to display the context
menu, and then choose the function name from the menu to edit
function arguments.
Once a function dialog box is open:
Type or change values, and then click OK to save your changes and
close the dialog box.
13
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
FactoryTalk Historian DataLink automatically retrieves values from
FactoryTalk Historian and populates the function array in your
spreadsheet when you click OK.
Click Cancel or X to close the dialog box without saving changes.
Context Menu
FactoryTalk Historian DataLink adds several commands to the standard
Microsoft Excel context menu. You can use these commands to manage
function arrays that are already inserted into a spreadsheet.
Context menus are the same for both add-in versions of FactoryTalk Historian
DataLink.
To display the context menu:
Right-click anywhere in a cell or group of cells that contains a
FactoryTalk Historian DataLink function array.
A function array is the cluster of cells that contain the output from a
single FactoryTalk Historian DataLink function. You can also rightclick an embedded trend control to see a related context menu (page
80).
The following items appear in the context menu:
Choose Select DataLink Function to select the entire function array.
Choose Recalculate (Resize) Function to recalculate (page 64) the
Choose <function name> to open a corresponding function dialog box
14
You should select an array before attempting to copy, cut or drag it to
a new spreadsheet location.
array, retrieving new values from FactoryTalk Historian.
For some functions, a different number of values may be available
with each recalculation, causing the array to resize.
(page 13) and update arguments to collect different data.
2 ● Basics
●
●
●
●
●
FactoryTalk Historian Server Connections
Use the Connections dialog box to manage connections to FactoryTalk
Historian servers in your computing environment.
To connect to a FactoryTalk Historian server:
Click the Connections icon on the ribbon bar (2007), or choose PI >
Connections (2003) to display the Connections dialog box.
Each configured FactoryTalk Historian server available to FactoryTalk
Historian DataLink appears in the Server pane to the left.
If you do not see the desired server, you can add a connection.
To add additional FactoryTalk Historian server connections:
15
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Choose Server > Add Server or right-click in the server pane and
choose Add Server to display the Add Server dialog box and
configure a new FactoryTalk Historian server connection. A selected
check box next to a server name in the Connections dialog box
indicates an open connection to the FactoryTalk Historian server.
To manage connection settings:
Click to select a check box and open a connection to a FactoryTalk
Select a FactoryTalk Historian server in the server pane to access
DataLink functions to a spreadsheet and retrieve values from FactoryTalk Historian.
The name of the default FactoryTalk Historian server appears at the bottom right
of the dialog box. You can maintain connections to more than one FactoryTalk
16
Historian server in the list. Clear a check box to close a connection.
connection settings.
An open connection to a FactoryTalk Historian server is required to add
2 ● Basics
●
●
●
●
●
Historian server at a time, although you may need to specify the target server
when you define a FactoryTalk Historian DataLink function.
Graphic Function Components
FactoryTalk Historian DataLink provides a graphical user interface to build
functions in Excel. Common dialog box features make it easy to supply
arguments to define the function.
The tool used to build a function depends on the version of FactoryTalk
Historian DataLink installed:
The add-in for Excel XP-2003 provides dialog boxes (page 13) to
define functions.
The add-in for Excel 2007 provides task panes (page 9) to define
functions.
Advanced users familiar with FactoryTalk Historian DataLink and the
FactoryTalk Historian server can type function syntax (page 101)
directly into the Excel formula bar.
The following sections describe common features in FactoryTalk Historian
DataLink function dialog boxes and task panes, how real-time data is
acquired and presented, and how FactoryTalk Historian DataLink functions
can be used within a spreadsheet.
Entry Fields
Labeled entry fields accept specific arguments used to define a function.
Most arguments may be entered directly, or referenced in spreadsheet cells.
While the options differ by argument, all entry fields allow one or more of
the following choices:
Type text directly in an edit field , such as a tag
name or the address of an output cell.
17
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Select an item from choices in a list , such as a calculation or a
sampling method.
Reference spreadsheet cells that contain arguments, such as a
tag name, output cell location, or time stamp.
Be sure to type strings in cells that you may reference with a leading
apostrophe ('). This forces Excel to interpret the contents as a string.
Select values from a FactoryTalk Historian server or other sources
through a tag or module database search.
For example, you can type a tag name string into the Tagname field, or
click the button next to the field to display the Tag Search dialog box, and
search the FactoryTalk Historian server for tags.
You can also manually supply a reference to a spreadsheet cell that
contains a tag name:
Click first in the edit field, and then click the cell (or click the cell and
drag to an adjacent cell to select a range) on the spreadsheet.
DataLink automatically enters the cell reference into the edit field.
Fields marked Optional are optional, and a value is not required.
Standard Arguments
Some arguments are common to most FactoryTalk Historian DataLink
functions in dialog boxes or task panes, and are usually required to define
the function:
Tagname(s) or Expression (page 19)
Start Time (page 19)
End Time (page 20)
18
Some entry fields display a default entry when the dialog box or pane opens.
2 ● Basics
●
●
●
●
●
PI Server (page 20)
Output Cell (page 20)
Tagname(s) or Expression
The Tagname(s) or Expression field is required by most functions to
evaluate FactoryTalk Historian point (tag) data or the results of a
FactoryTalk Historian expression (page 91). One or more tag names, or the
syntax of a FactoryTalk Historian expression may be:
Typed directly in a field.
For example, sinusoid.
Typed in one or more spreadsheet cells, which are then referenced in
the field.
For example, a reference to the array
Sheet1!$B$3:Sheet1!$B$4, which in turn contains the tag
name strings 'sinusoid and 'cdt158.
Note that cell references allow multiple tag names to be specified for a
function, whereas you cannot specify multiple tag names directly
unless the field is labeled Tagname(s).
Note that single quotes are added to each tag name to denote string
values in Excel. Both strings and time expressions referenced in cells should
be enclosed in single quotes. For example:
TimeEq('CD:M158','y' ,'t', "Manual")
Selected in the Tag Search dialog box (page 51), based on a search for
.
tags by name, alias or attribute.
Start Time
The beginning of a time range (page 21) over which the function is
evaluated, from Start Time to End Time. All event values corresponding to
19
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
the time range are retrieved from the FactoryTalk Historian archive or
calculated to create the resulting function array.
End Time
The end of the time range, frequently expressed as the current time, where
the Start Time is the current time minus a specified time interval.
Start and end times may be expressed in absolute or relative terms to
establish a time range in the past, or up to and including the current time.
PI Server
An instance of a FactoryTalk Historian DataLink function runs against
only one FactoryTalk Historian/PI server. The PI Server specifies a target
FactoryTalk Historian server from a known servers list. If you do not select
a server or leave the field blank, the default FactoryTalk Historian server
(page 15) is used.
Servers that appear above the dotted line in the servers list are currently
connected; those below are disconnected.
Output Cell
Specify where you want to place the resulting function array using the
Output Cell field. If you select a cell before the function dialog or task
pane is displayed, the currently-selected cell is used as the default Output
Cell value.
The output cell value always specifies the top left corner of the function
array. If you append (page 22) time stamps and other data, keep in mind
that the data column may be shifted downward or to the right of the output
cell location, overwriting data in those adjacent cells.
If you click in the Output Cell field and then select a multi-cell array in
the spreadsheet, you can override the default display of all function results.
20
2 ● Basics
●
●
●
●
●
Instead, only the results that fit within the specified array dimensions are
displayed.
Time Arguments
Many FactoryTalk Historian DataLink functions require Start Time and
End Time arguments to retrieve an array of event values over a specific
time range. Follow these guidelines when specifying time arguments:
Time strings may be entered directly in edit fields in either absolute or
relative FactoryTalk Historian time (page 86) formats (for example,
10-Dec-99 19:12 or -3h).
If the start time is more recent than the end time, results are displayed
in reverse chronological order.
Time stamps referenced in spreadsheet cells may also use fixed or
relative FactoryTalk Historian time formats, and should be preceded
by an apostrophe 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 arguments call for an interval or duration of time, represented by
a single value rather than start and end times. Whether referenced or
entered directly, interval values should use relative FactoryTalk
Historian time strings such as a number followed by a time variable
(for example, 1d or 30m), and may not specify or refer to a fixed
FactoryTalk Historian or Excel time stamp. For example, to specify an
interval of 32 minutes, enter or reference a cell containing the string
32m.
21
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
To enter intervals in terms of frequency, convert the frequency to
equivalent seconds. For example, a frequency of 25 Hz should be
entered as a 0.04s interval (=1/25 of a second).
When using relative formats (for example, -2h), the reference time
used to translate the time format is different for function start and end
times. The current wall clock time is the reference for a relative start
time, but the start time is then used as the reference for a relative end
time.
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.
Appended Data
Time stamps are particularly relevant to FactoryTalk Historian point
events. Each event value is accompanied by a time stamp that gives it
context.
Most FactoryTalk Historian DataLink functions can return corresponding
time stamp values and other point data with FactoryTalk Historian event or
calculated expression values. These data can be appended to values
returned in a FactoryTalk Historian function array, and include:
Event time stamps.
Time stamps indicating start and end times of an interval.
Time stamps indicating the occurrence of minimum and maximum
The percentage of good values over a sampling interval.
Value attributes.
Manually entered event annotations.
Source FactoryTalk Historian server names.
22
values.
2 ● Basics
●
●
●
●
●
Function Array Columns
Function/Mode
Output Cell
Column 2
Column 3
Column 4
Column 5
Any function without
appended data
value
Current and Archive Value,
Sampled Data
time stamp
value
Compressed Data
time stamp
value
annotations
Time Filtered
start time
end time
value
pct good
Calculated (minimum)
start time
end time
min time
min value
Calculated (maximum)
start time
end time
max time
max value
Calculated (range)
start time
end time
min time
max time
value
Calculated (other)
start time
end time
value
pct good
Alias
server
value
When specified, appended data appear in columns (or rows) adjacent to the
primary values returned by a function according to the following rules:
Time data are added in columns to the left (or rows above) primary
values.
Other related data are added in columns to the right (or rows below)
primary values.
Appended Data Array
The following table illustrates how data are appended per function. For
functions that can display output in rows or columns (page 26), substitute
Columns 1-5 with Rows 1-5.
The table assumes all appended data are specified for display, and that some
function arrays can expand to five columns if all related data are appended.
23
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Show Timestamps
A show timestamps check box appears when a function returns an array of
FactoryTalk Historian values over time. If selected, this option returns a
corresponding time stamp with each FactoryTalk Historian event value.
For functions that return multiple event values (for example, Sampled
Data), the orientation controls (page 26) determine how time stamps are
displayed in relation to each value.
For some functions that return a single value (for example, Current Value),
options are provided to provide equivalent options:
Select no timestamp to suppress the time stamp display.
Select time at left to return a time stamp into a cell to the left of the
event value.
Select time on top to display the time stamp in a cell above the
retrieved event value.
When a reference to an array of tag names in cells is specified in the
Tagname field, these preferences are ignored. Time stamp and event
values are instead positioned to match the orientation of the input tag array.
For tag names in a single column, time stamps appear to the left of values.
For tag names in a single row, time stamps appear on top of values.
Interval Timestamps
Functions that return values at specific time intervals (for example,
Calculated Data) provide options to display different time stamps:
Choose show start time to display the start time of each interval.
Choose show end time to display the end time of each interval.
For calculated minimum, maximum, and range values:
Choose show min/max time to display time stamps for minimum and
24
maximum values over each interval.
2 ● Basics
●
●
●
●
●
Time stamps are displayed to match the specified row or column
orientation. If all time stamps are shown, the order from left column to
right or top row to bottom is start time, end time, minimum value time,
maximum value time, event value.
Show Percent Good
Select show percent good to display the percentage of time for which
good values are returned over the total time range of the array. Percent
good values are typically added in a column to the right or a row below
retrieved values.
Good values are event values determined to be valid by the FactoryTalk
Historian server, and not in an error state. The percentage of good values
helps in assessing the reliability of calculations built on FactoryTalk
Historian point values, particularly if calculated values are to be used in
further calculations.
For example, totals may still be calculated over a time range even if some
of the data are bad. The resulting time-weighted total value equals the total
divided by the fraction of the interval where good data is available.
However, this normalization assumes that the average over the time range
with bad data is equivalent to the average value over the entire time range,
which becomes less reliable if a large fraction of the time range contains
bad data.
Show Value Attributes
Select show value attributes to display extended status bits associated
with returned event values. The returned bits correspond to value attributes
stored in FactoryTalk Historian, and may be one of the following:
A = annotated, indicating a comment has been added to the event.
S = substituted, indicating the event value has been changed from its
original value.
25
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Q = questionable, indicating that there is some reason to doubt the
accuracy of the value.
Value attributes are displayed in a column to the right of event values.
Show Annotations
Select show annotations to display any annotations associated with
returned event values in a column to the right.
Annotations are notes or comments appended to a data value in
FactoryTalk Historian for descriptive purposes.
Orientation Controls
For functions that return an array of FactoryTalk Historian values, use the
column and row buttons to determine the orientation of returned data.
Choose column to display data in columns.
Choose row to display the data in rows.
Additional columns (page 22) or rows are added for time stamps and
related data if they are selected for display. The function's Output field
always indicates the upper left-hand corner of the entire range used for the
array.
array overrides row and column selection to determine the orientation of output
data.
26
For functions that return a range of values, the orientation of the input tag
2 ● Basics
●
●
●
●
●
Display Formats
You can change the default time and number formats used by FactoryTalk
Historian DataLink to format data in function arrays. Default formats are
specified in the Settings (page 29) dialog box, where two settings are
available for formats:
The default number format General formats numbers (and all non-
time stamp data) to match the formatting Category General in the
Excel Format Cells dialog box.
The default time format dd-mmm-yy hh:mm:ss.000 matches the
standard FactoryTalk Historian time stamp format. You can add .000
to the end of the string (dd-mmm-yy hh:mm:000) to display sub-second
time stamps. Note that Excel does not support microsecond precision
formats.
27
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
You can customize default format strings using any valid Excel format
codes from the Format Cells dialog box in Excel. For example, German
equivalents of General and dd-mmm-yyyy hh:mm:ss are Standard and TT-
MM-JJJJ hh:mm:ss, respectively.
You can also apply individual time and date formatting to any spreadsheet
cell, including those containing FactoryTalk Historian DataLink functions,
by choosing Format > Cells > Number. See your Excel documentation
for more information on formatting dates and times.
28
2 ● Basics
●
●
●
●
●
Preference Settings
Use the Settings dialog box to specify global preferences and default
formatting for the output of PI DataLink functions.
To access the settings:
1. Click Settings on the PI ribbon (2007), or choose PI > Settings
(2003).
2. Set the desired preferences and click OK.
29
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Copy items to
sheet
Choose In a row or In a column to copy the names of multiple tags
selected in a Tag Search (or items in a Module Browse search) to
the spreadsheet in a row or column of values, respectively. The
default setting is In a column.
This command is also available as a shortcut to the Tag Search
ribbon item (2007).
Copy PI Server
Name
Select the check box to copy the name of the FactoryTalk Historian
server data source into an adjacent spreadsheet cell when tag names
are copied to a spreadsheet.
Use PI Server Time
Zone
Select the check box to force FactoryTalk Historian DataLink to use
the FactoryTalk Historian server time zone as a reference value to
interpret functions. If cleared, FactoryTalk Historian DataLink uses the
time zone setting of the client machine.
This option is relevant only if a PI server has a time zone setting
different from the client machine.
Display #N/A
instead of Blanks
Select the check box to substitute #N/A (Not Applicable) for blank
cells when there are fewer data points than cells in a function array.
Functions added to a spreadsheet maintain their original array size,
even if variance over a particular time period produces fewer data
values, resulting in one or more empty cells.
This feature is particularly useful when function results are plotted
through the Excel charting package.
Locale
Independent
Select the check box to force FactoryTalk Historian DataLink to
interpret input time strings according to PI time format rules,
regardless of the locale settings of the client machine. PI time
assumes all strings are English and use the date-time order
dd-MMM-
yyyy hh:mm:ss
.
Clear the check box to parse date-time formats according to regional
settings on the client machine, falling back to PI time format rules
only if necessary.
Disable automatic
task pane display
on click
For Excel 2007 only, select this check box to prevent the automatic
display of the function task pane when clicking in a function cell.
Right-click to choose the function name and display the pane
manually.
Disable "Resize to
show all values"
message
Select this check box to display no warning message when the
number of values retrieved by a recalculated array exceed the number
that can be displayed.
Review the following for additional information:
30
2 ● Basics
●
●
●
●
●
Number Format
Type a number format to indicate how numeric function output should
be displayed by default. The format string may be any valid number
format code from the
Excel Format dialog box
(page 26).
On install, FactoryTalk Historian DataLink assigns the default number
format from Excel to this field, unless you have set your own format
preference previously in DataLink. If your version of Excel runs a
different locale, this format includes correct syntax to reflect the
locale.
For example: 35.03 would appear as 35,03 in French Excel.
Time Format
Enter a time stamp format for function output. The time format string
may be any valid
date-time format
(page 21) code from the Excel
Format dialog box.
On install, DataLink assigns the default FactoryTalk Historian time
stamp format to this field, unless you have set your own format
preference previously in DataLink. If your version of Excel runs a
different locale, this format includes correct syntax to reflect the
locale.
For example: dd-mm-yy (03-07-09) would appear as jj-mm-aa
(03-07-09) in French Excel.
Automatic Update
Use this section to set preferences for
Automatic Update
(page 63)
when this feature is enabled:
Choose a calculation method:
Calculate (F9) forces all volatile functions (and any functions that
reference them) to recalculate.
Full Calculate (Ctrl+Alt+Shift+F9) forces all embedded
functions, regardless of volatility, to recalculate.
Then type a calculation interval in seconds. The minimum value is 5
seconds. Type 0 to accept the automatic interval selected by
FactoryTalk Historian DataLink based on duration of previous
calculation times.
Spreadsheet Construction
Once you are familiar with the basic tools and concepts of FactoryTalk
Historian DataLink, and are ready to build a spreadsheet and use
FactoryTalk Historian DataLink functions, where do you begin?
31
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Your goals
First consider your goals.
What data do you want to display in a spreadsheet in order to
monitor performance or answer a business question?
In which FactoryTalk Historian server 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.
Functional
One way to build a spreadsheet is simply to add
functions
(page 33),
building the display around them as needed. Later on you can add tag
information to help clarify what the data represents. This may be the
best approach if you are still exploring your requirements or learning
how FactoryTalk Historian DataLink works.
Structured
Another way to build a spreadsheet is to add structure from the
beginning. Use
tag search and tag functions
(page 51) to add tags
and other attributes as metadata to frame your subject, then add
functions to retrieve the corresponding FactoryTalk Historian point
data. This requires a bit more planning and familiarity with
FactoryTalk Historian DataLink , but once tag information is present in
the spreadsheet, you can use it to build functions more easily through
cell references. Spreadsheets built in this manner are also more
flexible for re-use.
Module-Driven
If you have a configured FactoryTalk Historian Module Database for
your FactoryTalk Historian server, you can build maximum flexibility
into your spreadsheet by incorporating objects from your
module
database
(page 57). Like tag data, module database objects can be
referenced in functions. You can also add module context features to
maximize the potential re-use of the spreadsheet across parallel or
redundant subjects.
Targeted Reports
If you are a system administrator, or a builder of spreadsheets for
other users, you may want to place FactoryTalk Historian DataLink
functions on a second spreadsheet in a workbook, and copy/paste the
results to the first spreadsheet for display. Function syntax and
business logic can be hidden and protected by using Excel to secure
the second sheet. This strategy also works well for documents
distributed through FactoryTalk Historian DataLink Server.
32
Chapter 3
Required
Arguments
Tagname.
Special Notes
Reference a range of cells containing tag names to display current
snapshot values for each.
Updates whenever Excel calculates or recalculates any cell in the
spreadsheet. To force an immediate recalculation, press F9.
FactoryTalk Historian DataLink Functions
FactoryTalk Historian DataLink functions enable you to query, calculate
and return FactoryTalk Historian point values and attributes to spreadsheet
cells. Like other Excel functions, FactoryTalk Historian DataLink function
results are displayed in arrays which can be recalculated to display updated
event values as needed.
To access FactoryTalk Historian functions:
Click in the desired output cell, and then choose PI > <function
name> to open a function dialog box (XP-2003), or click a function on
the FactoryTalk Historian ribbon to open a new function task pane
(2007).
The function descriptions in this section describe arguments specific to
each function in terms of these common features.
Current Value
Retrieves the current or most recent (snapshot) value of a FactoryTalk
Historian point, based on tag name.
33
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required
Arguments
Tagname or Expression
Timestamp
Timestamp
The time reference used to retrieve the archive value from
FactoryTalk Historian, which can be a fixed
time value
(page 21) or
expressed relative to the current time.
Example:
To see the current value of the sinusoid tag, the following arguments are
set for the Current Value function:
Tagname = sinusoid
time at left
The resulting function array appears as:
Archive Value
Retrieves a FactoryTalk Historian point value, or evaluates an expression
corresponding to a specified time stamp.
34
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Retrieval Mode
One of five modes can be selected to produce an archive value:
Previous
Retrieves the value exactly matching or preceding the specified
time stamp.
Previous only
Retrieves the value preceding the specified time stamp.
Interpolated
Interpolates the value at the specified time, or follows Previous
only behavior.
Auto
Interpolates the value at the specified time, or follows Previous
behavior.
Next
Retrieves the value exactly matching or following the specified
time stamp.
Next Only
Retrieves the value following the specified time stamp.
Exact Time
Retrieves only a value exactly matching the time stamp, or returns
No events found if no value exists.
Special Notes
Reference a range of cells containing tag names to display archived
values for each.
For tags with step attributes, Previous and Previous only modes are
substituted for Auto and Interpolated calculation modes, respectively.
PIExpVal() is used if an expression is substituted for a tag; otherwise
PIArcVal() is used.
Example:
To see the value of the sinusoid tag corresponding to a specific time, the
following arguments are set for the Archive Value function:
Tagname = sinusoid
Timestamp = 30-Sep-07 15:13
Retrieval Mode = previous
time at left
35
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required
Arguments
Tagname
Start Time
End Time or Number of Values, depending on the function type
The resulting function array appears as:
Compressed Data
Returns either all values of a FactoryTalk Historian point occurring within
a specified time range, or a number of point values beginning at a certain
time.
Compressed values are data recorded by the FactoryTalk Historian server
after a compression algorithm has removed all values that represent the
same slope.
Separate dialog boxes are provided for Compressed Data (Start Time/End
Time) and Compressed Data (Start Time/Number) in FactoryTalk Historian
DataLink for Excel XP-2003. For 2007, you can select a Time Range or Number of
Values calculation in the task pane.
36
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Filter Expression
Add a filter expression to filter event values using a mathematical
expression, eliminating data for which the expression evaluates as
false. The filter expression is applied to the raw data from FactoryTalk
Historian (and not values that result from the calculation itself).
For example, the simple filter expression:
sinusoid < 70
would remove all values over 70 from the calculation. You can also
use any valid FactoryTalk Historian performance equation in the filter
expression to build more complex expressions to remove atypical
peaks in data values, for example.
Select mark as filtered to substitute
Filtered
as a placeholder for
each value or block of values filtered from the array based on the
filter
expression
(page 91).
Boundary Type
Specify a boundary type to determine how to handle data values near
the start and end times of the value range:
Inside (default)
Returns values at start and end times, if they exist, or the nearest
values occurring within the range.
Outside
Returns the closest values occurring immediately outside the
range.
Interpolated
Returns interpolated values at start and end times.
Auto
Interpolated, but using Inside behavior for tags with step
attributes set on Windows-based FactoryTalk Historian servers.
Count of Values
Normally the first row or column of the array includes the count of
values retrieved for the time range. Select hide count to hide the
count of values and show only retrieved values in the array.
37
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Show Value
Attributes
Select show value attributes to display extended status bits associated
with returned event values. The returned bits correspond to value
attributes stored in FactoryTalk Historian, and may be one of the
following:
A = annotated, indicating a comment has been added to the
event.
S = substituted, indicating the event value has been changed from
its original value.
Q = questionable, indicating that there is some reason to doubt
the accuracy of the value.
Value attributes are displayed in a column to the right of event
values.
Show Annotations
Select show annotations to display any annotations associated with
returned event values in a column to the right.
Annotations are notes or comments appended to a data value in
FactoryTalk Historian for descriptive purposes.
Special Notes
Reference a range of tag names to display compressed values for
each. Note that by default, values are displayed in rows for a column
of referenced tags, and in columns for a row of referenced tags.
If the Start or End Time is the current time (*), then the first (or last)
value is actually the current snapshot value, and not an archive value.
Once the snapshot value passes through the FactoryTalk Historian
Server's compression algorithm, it may not actually be recorded in PI.
The PICompFilDat() function is used for End Time functions if a filter
expression are specified; otherwise, the PICompDat() function is
used.
The PINCompFilDat() function is used for Number of Values functions
if a filter expression is specified; otherwise, the PINCompDat()
function is used.
Example:
To see the most recent 10 values of the sinusoid tag, the following
arguments are set for the Compressed Data function:
Number of Values
Tagname = sinusoid
38
Start Time = <cell reference to current time>
Number of Values = 10
backwards in time
Boundary Type = inside
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Required
Arguments
Tagname or Expression
Start Time
End Time
Time Interval
show timestamps
column
The resulting function array appears as:
Note that all events between two specified times could also be retrieved by
the same function using the Time Range argument.
Sampled Data
Returns evenly-spaced, interpolated sample values for a FactoryTalk
Historian point or expression over a regular interval.
39
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Time Interval
Type a time interval as a
FactoryTalk Historian time
(page 86)
expression. The interval is the sampling frequency used to collect or
calculate values over the course of the time range.
For example, an interval of 15m (15 minutes) returns a value for
every 15 minute interval.
Filter Expression
Add a filter expression to filter event values using a mathematical
expression, eliminating data for which the expression evaluates as
false. The filter expression is applied to the raw data from FactoryTalk
Historian (and not values that result from the calculation itself).
For example, the simple filter expression:
sinusoid < 70
would remove all values over 70 from the calculation. You can also
use any valid PI performance equation in the filter expression to build
more complex expressions to remove atypical peaks in data values,
for example.
Select mark as filtered to substitute
Filtered
as a placeholder for
each value or block of values filtered from the array based on the
filter
expression
(page 91).
Special Notes
You can use a
FactoryTalk Historian Expression
(page 91) instead of a
tag name for this function.
Reference a range of tag names to display sampled values for each.
Note that by default, values are displayed in rows for a column of
referenced tags, and in columns for a row of referenced tags.
The PISampFilDat() function is used if a filter expression is specified;
otherwise, the PISampDat() function is used.
PIExpDat() is used if a PI Expression is substituted for a tag.
Example:
To see periodic, interpolated values over the previous 24 hours for the
sinusoid tag, the following arguments are set for the Sampled Data
function:
Tagname = sinusoid
Start Time = -1d
End Time = <cell reference to current time>
40
Time Interval = 3h
show timestamps
column
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Required
Arguments
Tagname
Timestamp
Timestamp
A reference to one or more spreadsheet cells containing time stamp
values.
Retrieval Mode
There are two modes to select from:
Interpolated
Interpolates values corresponding to specified time stamps.
Exact Time
Retrieves only values exactly matching specified time stamps, or
returns
No events found
if no value exists.
The resulting function array appears as:
where a value is displayed for each 3-hour interval.
Timed Data
Returns actual or interpolated sample values for a FactoryTalk Historian
point to match an array of specified time stamps.
41
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Special Notes
You can use a
PI Expression
(page 91) instead of a tag name for this
function.
Reference a range of tag names to display sampled values for each.
Note that by default, values are displayed in rows for a column of
referenced tags, and in columns for a row of referenced tags.
For tags with step attributes, the value preceding a specified time
stamp is substituted for an interpolated value when the calculation
mode is
Interpolated
.
Example:
To see values corresponding to an array of time stamps for the
sinusoidu tag, the following arguments are set for the Timed Data
function:
Tagname = sinusoidu
Timestamps = <cell reference to existing array of compressed
data for sinusoid tag>
Retrieval Mode = interpolated
The resulting function array appears as:
42
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Required
Arguments
Tagname or Expression
Start Time
End Time
Conversion Factor
Filter Expression
Add a filter expression to filter event values using a mathematical
expression, eliminating data for which the expression evaluates as
false. The filter expression is applied to the raw data from FactoryTalk
Historian (and not values that result from the calculation itself).
For example, the simple filter expression:
sinusoid < 70
would remove all values over 70 from the calculation. You can also
use any valid PI performance equation in the filter expression to build
more complex expressions to remove atypical peaks in data values,
for example.
Select mark as filtered to substitute
Filtered
as a placeholder for
each value or block of values filtered from the array based on the
filter
expression
(page 91).
Time Interval
Type a time interval as a
FactoryTalk Historian time
(page 86)
expression. The interval is the sampling frequency used to collect or
calculate values over the course of the time range.
For example, an interval of 15m (15 minutes) returns a value for
every 15 minute interval.
where the column of timed data appears in the column to the right, based
on time stamps retrieved for a different tag in the first two columns at left.
Calculated Data
Returns one or more evenly-spaced, calculated values based on
FactoryTalk Historian point values or evaluated expressions. A range of
different calculation and sampling preferences are provided.
Separate dialog boxes are provided for Calculated Data and Advanced
Calculated Data in FactoryTalk Historian DataLink for Excel XP-2003. For the Excel
2007 version, click the + sign next to Advanced to access all function options in a
single Calculated Data task pane.
43
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Calculation Mode
The following calculations are provided:
Total
Minimum
Maximum
Standard deviation
Range
Average
Count
Mean
All calculation modes are time-weighted except for the
Mean
function,
which is an event-weighted version of the
Average
function.
Calculation Basis
Select either a time- or event-weighted basis for the calculation:
Calculations are time-weighted by default. Each event value is
weighted for purposes of the calculation by the duration of time
over which the event applies.
Event-weighted calculations weigh each event value equally. At
least one event (two for standard deviation calculations) must
exist within a time range for a successful calculation.
Conversion Factor
The conversion factor is used for Total calculations where the time
unit of the point calculated is not the same as the server default time
unit. A conversion factor may be necessary to convert to the units
desired for the calculation from the server default of units per day.
The following table illustrates the use of conversion factors for points
using different units of flow. Note that a conversion factor of one
means that the conversion factor is not needed, and that units cannot
be specified.
Flow unit
Conversion Factor needed to match server default
(units/day)
Units/day
1.0
Units/hour
24
Units/minute
1440
Units/second
86400
44
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Expression
Sampling Mode
Different sampling modes are available for functions that include
expressions:
For FactoryTalk Historian tag calculations, select one of three
sampling modes.
Point Compressed mode is the default used for FactoryTalk
Historian tag calculations. This mode considers the time stamps for
the FactoryTalk Historian tag for which the calculation is being
performed. It does not consider time stamps for other FactoryTalk
Historian tags used in the filter expression. This mode performs
the calculation using the time intervals between time stamps that
the filter expression evaluates to true. The Point Compressed
mode is not as accurate as the Expression Compressed mode, but
it remains the default to ensure compatibility with earlier versions
of the FactoryTalk Historian Server.
Expression Compressed mode considers the time stamps for
FactoryTalk Historian tags used in the filter expression. It does not
consider the time stamps for the FactoryTalk Historian tag for
which the calculation is being performed unless that FactoryTalk
Historian Tag happens to be used in the filter expression. This
mode determines the intervals for which the filter expression is
true and then performs the calculation using the interpolated value
of interval endpoints. The Expression Compressed mode produces
more accurate results than the Point Compressed mode.
Interpolated mode evaluates the expression at evenly-spaced
sampling intervals determined by the Expression Sampling
Frequency.
For FactoryTalk Historian expression calculations, select one of two
sampling modes:
Compressed mode evaluates the expression for each event value
at corresponding time stamps.
Interpolated mode evaluates the expression at evenly-spaced
sampling intervals determined by the Expression Sampling
Frequency.
Expression
Sampling
Frequency
Specify the frequency at which a calculation or filter expression is
evaluated when the Expression Sampling Mode is set to
Interpolated
.
For example, a frequency of
10m
(10 minutes) returns an interpolated
value for every 10 minute interval while the filter expression evaluates
as
true
.
45
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Minimum Percent
Good
Specify the minimum
percentage of good data
(page 25) required in
each time range to calculate and return a value. Insufficient good
data is substituted as a placeholder when a value is not returned.
Timestamps
Select show start time to display the Start time of each interval
used to calculate a value. Start times are added in a column to the
left or a row above calculated values.
Select show end time to display the End time of each interval used
to calculate a value. End times are added in a column to the left or a
row above calculated values.
For Maximum, Minimum and Range calculations, select show
min/max time to display time stamps corresponding to minima
and/or maxima over each interval used to calculate a value:
For Minimum and Maximum calculations, the time stamp of the
corresponding value is displayed.
For Range functions, both time stamps are displayed.
Percent Good
Select show percent good to display the percentage of time for
which good values are returned over the total time range of the array.
Percent good values are typically added in a column to the right or a
row below retrieved values.
Good values are event values determined to be valid by the
FactoryTalk Historian server, and not in an error state. The
percentage of good values helps in assessing the reliability of
calculations built on FactoryTalk Historian point values, particularly if
calculated values are to be used in further calculations.
Special Notes
You can use a
FactoryTalk Historian Expression
(page 91) instead of a
tag name for this function.
Reference a range of tag names to display sampled values for each.
Note that by default, values are displayed in rows for a column of
referenced tags, and in columns for a row of referenced tags.
For Maximum or Minimum calculations with specified intervals, time
stamps indicate the start time of each calculation interval.
Time stamps cannot be displayed for Total, Standard Deviation,
Average, Count or Mean calculations when the interval is unspecified.
The PIAdvCalcVal() function is used to retrieve a single value if you
do not specify an interval; otherwise the PIAdvCalcDat() function is
used to retrieve multiple interval values. Function names including
'Exp' and 'Fil' are used for calculations that include PI Expressions and
Filter Expressions, respectively.
46
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
Example:
To see the hourly range of values beginning the same day at midnight until
the present time for the sinusoid tag, the following arguments are set for
the Calculated Data function:
PI Tag
Tagname = sinusoid
Start Time = t
End Time = *
Time Interval = 1h
Calculation Mode = range
Calculation Basis = time-weighted
show start time
show end time
column
The resulting function array appears as:
47
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required
Arguments
Expression
Start Time
End Time
Time Units
Time Interval
Type a time interval as a
FactoryTalk Historian time
(page 86)
expression. The interval is the sampling frequency used to collect or
calculate values over the course of the time range.
For example, an interval of 15m (15 minutes) returns a value for
every 15 minute interval.
Time Units
Specify the units of time used to display the result of the calculated
expression.
Special Notes
You can type the expression in a spreadsheet cell and reference the
cell name in the function. Begin expressions with a single quote if you
want Excel to interpret the expression as a string.
where the range is calculated for each one hour interval. Note that any
available calculation could be specified over any interval.
Time Filtered
Returns the amount of time over which a FactoryTalk Historian expression
evaluates as true for a specified time range.
Time Filtered results vary slightly depending on your FactoryTalk Historian
server version.
Example:
To see the amount of time for which the value of the sinusoid tag was over
75 over a 7-day period, the following arguments are set for the Time
Filtered function:
Expression = sgn('sinusoid'-75)=1
Start Time = -7d
End Time = *
Time Units = h
48
3 ● FactoryTalk Historian DataLink Functions
●
●
●
●
●
show percent good
column
The resulting function array appears as:
where the results show the tag value was over 75 for 7.85 hours over the
previous 7 days.
49
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
50
Chapter 4
FactoryTalk Historian Tags and Attributes
A FactoryTalk Historian point is a stream of real-time data from a defined
source, and is described by a corresponding tag name and other attributes.
In FactoryTalk Historian DataLink and this online help, FactoryTalk
Historian points are frequently referred to as FactoryTalk Historian tags,
and the terms are used somewhat interchangeably. However, a tag is
simply a name for a FactoryTalk Historian point. When you retrieve
FactoryTalk Historian data into an Excel spreadsheet, the tag name is the
most commonly-used FactoryTalk Historian attribute to refer to data from
a FactoryTalk Historian point.
FactoryTalk Historian tag names can help identify point data, describe the
source of function data values and arrays, and be referenced as attributes to
retrieve data. This section describes the use of tags and other point
attributes in building a FactoryTalk Historian DataLink spreadsheet,
including both:
Direct retrieval of tags into spreadsheet cells.
Functions used to resolve tag names from other point attributes, or
retrieve attributes based on a tag name.
Tag Search
Use the Tag Search dialog box to query the FactoryTalk Historian server
directly for FactoryTalk Historian tag names to copy into functions and
51
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Basic Search
Allows you to create a tag mask by specifying FactoryTalk Historian
point attributes. The mask is used to find a list of tags on the server
with matching attributes.
Advanced Search
Provides a query-building interface with access to more point
attributes for complex searches.
spreadsheets. Selected tags are copied to the spreadsheet, or added to a
Tagname edit field as a function argument.
To access tag search:
Click Tag Search on the PI ribbon (2007), or choose PI > Tag
Search (2003), or click Tag Search next to a Tagname field.
The Tag Search dialog box provides three types of searches:
52
4 ● FactoryTalk Historian Tags and Attributes
●
●
●
●
●
Alias Search
Provides a logical tree view of a FactoryTalk Historian server through
the FactoryTalk Historian Module Database, which you can use to
select tags by their descriptive aliases.
To search for tags:
1. Click a tab to choose a Basic, Advanced or Alias search.
2. Type the required search criteria and click Search.
Use '*' or '?' as wildcard characters to search for tag names and
attributes. For example, the tag mask Tem* returns all point names that
start with Tem while Tem? returns only points that start with Tem and
end with another single character. All point mask fields are case
insensitive.
You can also click Favorites to access previous searches.
3. Tags returned from a search appear listed in a search results panel.
Select the desired tags in the results panel, and click OK.
Click column headers in the search results panel to sort the results.
Ctrl-click or Shift-click to select multiple tags.
Tag Search Tips
If multiple tags are selected, the first selected tag name in the list is
copied to the Tag name field for a function reference.
The current cell is taken as the starting point for a list of tags copied
into a spreadsheet along a single column or row, depending on the
Copy items to sheet setting.
Choose In a row or In a column from the Tag Search shortcuts on
the PI ribbon menu (2007) to copy the names of multiple tags to the
spreadsheet in a row or column of values, respectively.
The FactoryTalk Historian server name corresponding to a tag is
appended to the tag name if the Copy PIServer Name setting is
enabled.
53
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required Fields
Point ID
Tag Functions
The following section describes FactoryTalk Historian DataLink tag
functions. These functions can be used to resolve FactoryTalk Historian
point IDs or other point attributes into a matching tag name. You can also
retrieve other point attribute values based on a tag name.
To access tag functions:
Click in the desired output cell, and then choose PI > <function
name> to open a function dialog box (XP-2003), or click a function on
the FactoryTalk Historian ribbon to open a new function task pane
(2007).
Tag functions use common function components (page 17).
Point ID to Tag
Returns the tag name that corresponds to a specific FactoryTalk Historian
point ID.
Example:
To retrieve the name of a tag corresponding to a PI point ID, the following
arguments are set for the Point ID to Tag function:
Point ID = (reference to a cell containing a point
ID value)
The resulting function array appears as:
54
4 ● FactoryTalk Historian Tags and Attributes
●
●
●
●
●
Required Fields
One or more of the following fields is required to retrieve matching
values:
Tagname
Descriptor
Point Source
Point Type
Point Class
Engineering Units
where the tag name is displayed in the column to the right, based on a
reference to the cell containing the point ID on the left.
Attribute Mask to Tag
Returns a list of tag names in FactoryTalk Historian that match one or
more specified tag attribute values.
Example:
To retrieve the names of tags matching one or more specified point
attributes, the following arguments are set for the Attribute Mask to Tag
function:
Tagname = BA*
Point Type = Float32
The resulting function array appears as:
55
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required Fields
Tagname
Attribute
Attribute
Specify the tag attribute to be retrieved from FactoryTalk Historian.
Special Notes
Reference a range of tag names to display attributes for each.
The list of tag attributes available depends on the point class
associated with the tag.
Note that attribute strings must match attribute values in FactoryTalk
Historian, and wildcards can be used. The function operates the same as a
tag search (page 51).
Tag Attributes
Retrieves an attribute associated with a specified FactoryTalk Historian tag
name.
Example:
To retrieve attributes of a FactoryTalk Historian point based on the tag
name, the following arguments are set for the Tag Attributes function:
Tagname = (reference to a cell array containing tag names)
Attributes = pointid (column 2), pointsource (column 3),
pointtype (column 4), descriptor (column 5)
The resulting function arrays appear as:
where the tag names are referenced in the column to the left, and a separate
Tag Attributes function is used for each attribute column.
56
Chapter 5
Module Database Objects
The FactoryTalk Historian Module Database provides an entirely different
way to build the infrastructure of a spreadsheet. If your FactoryTalk
Historian server's module database is configured and includes objects that
represent the tags you want to use, your spreadsheets can be easier to build
and provide more flexibility and potential for re-use.
The FactoryTalk Historian Module Database is typically configured by
your system or FactoryTalk Historian administrator, and stores aliases and
properties that refer to FactoryTalk Historian points and their attributes,
respectively. The hierarchical structure of these objects provides a
relational context between points.
For example, you may have five FactoryTalk 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
spreadsheet 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 spreadsheet to alternate
between views of multiple assets. For instance, when you select the name
of any of the five tanks in a spreadsheet cell, the alias mapping to the
matching FactoryTalk Historian point allows DataLink functions to
retrieve values for the appropriate tank.
57
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
The following topics describe the tools provided by FactoryTalk Historian
DataLink to access FactoryTalk Historian Module Database objects. See
your FactoryTalk Historian server documentation for more information
about module databases and configuration.
Module Database Browse
The Module Database dialog box allows you to browse for FactoryTalk
Historian aliases, properties and module paths in the FactoryTalk Historian
Module Database, a hierarchical tree structure based on the contents of a
FactoryTalk Historian server. You can select these items and copy them
directly into a spreadsheet.
58
5 ● Module Database Objects
●
●
●
●
●
Aliases and properties corresponding to FactoryTalk Historian points must be
configured in your FactoryTalk Historian server Module Database to use the browse
and Module Database functions.
To browse and select from the FactoryTalk Historian Module Database:
1. Select a cell and click Module Browse on the PI ribbon, or choose PI
> Module Browse. The Module Database dialog box appears.
2. Under Types, select the type of object you are looking for:
59
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Alias
Property
Module
Use the PI Server drop-down list to display module databases for
different connected FactoryTalk Historian servers.
3. Specify a Query Date and time to supply a temporal context for
objects displayed in the module database, if necessary, to select the
correct object version.
4. Browse the tree control to find the desired item, and add it or a parent
collection object to the spreadsheet:
Select an item to copy it to the spreadsheet.
Select a module's Aliases or Properties parent to copy all
associated aliases or properties to the spreadsheet.
5. Select Copy module path to copy the full module path of the alias or
property to an adjacent spreadsheet cell, along with the selected object.
The module path provides the context for the selected object.
If the Copy PIServer Name setting is activated, the corresponding
FactoryTalk Historian server name is also copied.
6. Click OK to close the dialog box and copy the selected items.
Module Database Functions
The following section describes FactoryTalk Historian DataLink module
database functions. Module Database functions resolve aliases and
properties from a module database tree into tag names through a module
path. You can enter a module path as a function argument or reference it
from a spreadsheet cell.
To access module database functions:
60
5 ● Module Database Objects
●
●
●
●
●
Required
Arguments
Alias
Module Path
Query Date
Alias
Specify a FactoryTalk Historian alias name. An alias can be entered
directly or referenced in a cell. You can also browse to an alias in the
FactoryTalk Historian Module Database.
Module Path
Type the module path from the FactoryTalk Historian Module
Database where the specified alias can be found. The module path is
entered automatically if the alias argument is selected by browsing
the Module Database.
Query Date
Specify a date to retrieve a specific version of the alias.
Click in the desired output cell, and then choose PI > <function
name> to open a function dialog box (XP-2003), or click a function on
the FactoryTalk Historian ribbon to open a new function task pane
(2007).
You cannot resolve an alias or property object into a tag name without a
module path. The path provides a context for the alias that maps it to a specific
FactoryTalk Historian point.
Module Database functions use common function components (page 17).
Alias to Tag
Returns a FactoryTalk Historian tag name corresponding to a specified
FactoryTalk Historian alias.
Property to Value
Returns the value or values corresponding to a specified FactoryTalk
Historian property.
61
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Required
Arguments
Property
Module Path
Query Date
Property
Specify a FactoryTalk Historian property name. A property can be
entered directly or referenced in a cell. You can also browse to a
property in the FactoryTalk Historian Module Database.
Module Path
Type the module path from the FactoryTalk Historian Module
Database where the specified property can be found. The module
path is entered automatically if the property argument is selected by
browsing the Module Database.
Query Date
Specify a date to retrieve a specific version of the property.
DataLink can return values for Boolean, Date, Double, Integer, Long, Null,
Single and String property types, or Double, Integer, Long and Single array
property types.
62
Chapter 6
Spreadsheets
When you add a function to a spreadsheet, FactoryTalk Historian DataLink
retrieves the requested data from the FactoryTalk Historian server into an
array. The size of the array can vary depending on the function, how many
matching archive values are available in FactoryTalk Historian, the number
of values requested, or the number of input references.
The following topics provide an overview of how FactoryTalk Historian
DataLink functions work within a spreadsheet, and how to manage and
maintain your spreadsheet over time.
Calculation Frequency
You can choose an automatic update interval to keep function data current
in your spreadsheets, or use function-triggered and manual recalculation
methods used in previous versions of FactoryTalk Historian DataLink.
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
Automatic Update forces Excel to recalculate functions and trends on open
worksheets at a specified interval. To activate Automatic Update:
Click the Update toggle button on the PI ribbon (2007), or choose
Update from the FactoryTalk Historian menu (2003).
63
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Calculation
Interval
Calculation interval is a
preference setting
(page 29) that is measured
in seconds, and must be greater than 5 seconds.
A value of 0 represents an automatic interval in which DataLink
adjusts the time between calculation cycles to twice the calculation
duration time, with a minimum interval of 5 seconds. The automatic
interval is recommended to insure that Excel remains responsive 50%
of the time.
You can adjust the Automatic Update interval manually to allow more
time between updates. If recalculation takes longer than your
specified interval, a message prompts to switch to the automatic
interval setting, or to turn off Automatic Update entirely.
Note that updates are paused when a menu, task pane or dialog box
is open or the current spreadsheet is in edit mode.
Cancellation
Press Esc to cancel a recalculation in process. DataLink finishes
calculation for the currently-processing function, and Calculation
aborted appears in unprocessed function array cells. If you cancel
during an update while Automatic Update is on, DataLink turns
Automatic Update off.
All workbooks open in the current Excel session are calculated
immediately, and then at specified intervals based on your Automatic
Update preference settings.
Automatic Update remains activated (with an indicator message in the
Excel status bar) until it is toggled off. During a recalculation event the
status bar also displays the calculation interval.
Automatic Update cannot update protected workbooks, which are read-only.
Review the following for additional information:
Triggered Recalculation
In Excel, functions recalculate based on a triggering event. If you do not
64
use the Automatic Update functionality, you can maximize the refresh
frequency and keep function arrays current by referencing volatile time
functions within non-volatile FactoryTalk Historian DataLink functions.
6 ● Spreadsheets
●
●
●
●
●
Volatile Excel time functions such as now() and today() recalculate with
the most frequency. Whenever a user edits a spreadsheet cell, or presses
F9, Excel updates all volatile time functions in the spreadsheet. The update
in turn triggers any functions that reference a time stamp based on a
volatile time function.
To base a FactoryTalk Historian DataLink function on a volatile Excel
function:
1. Use the Excel function bar to enter a volatile function in a spreadsheet
cell.
2. For example, you can use (today()+1/3) to represent 8 am the
same day, or now() as a cell reference to replace the current
FactoryTalk Historian time *.
3. To create an absolute time stamp that updates at the same time, use 2-
feb-97 00:30:30 + now() - now().
4. Reference the cell when defining the Start Time or End Time
arguments of a DataLink function.
To maximize the frequency of updates when Automatic Update is not in use,
check your Excel calculation preferences to ensure that both the spreadsheet and
application are set to
this may impact performance and make large spreadsheets difficult to use.
Automatic
rather than
Manual
calculation. Keep in mind that
Manual Recalculation
Most FactoryTalk Historian DataLink functions are non-volatile, but the
Current Value (page 33) function is an exception. Current Value is a
volatile function, and updates whenever a spreadsheet recalculates. The
values of non-volatile functions do not change unless an argument changes,
and must be updated manually, through automatic update using Full
Calculate mode, or through a reference to a volatile function value.
65
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Manual recalculation is the best method for variable-size arrays (page 69)
where the number of values returned may differ. If more values are
available than the current size of the array, an array does not expand to
display the additional values on recalculation unless it is manually
recalculated.
To manually recalculate a single function:
Right-click in any part of an array and choose Recalculate (Resize)
Function from the context menu.
Update function arguments in either version of FactoryTalk Historian
DataLink. The array values refresh when you click OK or Apply to
close the dialog box or task pane, even if no changes are made to
function arguments.
Excel key combinations can also be used to recalculate all spreadsheets in
a workbook, essentially a manual, on-demand version of Automatic
Update. To recalculate all spreadsheet 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.
Functions and Array Values
When you add a function to a spreadsheet, FactoryTalk Historian DataLink
enters the active function syntax into the target cell. Once defined, a
function queries the FactoryTalk Historian server and returns values, which
appear in the same cell used to enter the function.
The difference between the actual content of cells and the surface display
of data values retrieved by a function should be familiar to users of
Microsoft Excel. For new users of Excel, it helps to keep this distinction in
mind, and remember that the actual content of a spreadsheet cell always
appears in the Excel formula bar, and not necessarily in individual
spreadsheet cells.
66
6 ● Spreadsheets
●
●
●
●
●
For example, when you select a cell and add a Current Value function,
you specify the name of the FactoryTalk Historian tag whose current value
you want to see in the Tagname field. If you type the sinusoid tag,
FactoryTalk Historian DataLink pastes the following function into the
target cell:
=PICurrVal("sinusoid",0,)
Excel evaluates this function, retrieves the latest value of sinusoid from
FactoryTalk Historian, and displays it in the cell. If you select the cell, the
function syntax above appears in the Excel formula bar.
Array Management
Function arrays can be moved within, copied, or removed from a
spreadsheet. To select an array, do one of the following:
Click and drag to select every cell in the array. Keep in mind that the
array may have empty values, which must also be selected.
Right-click any part of the array and choose Select DataLink
Function from the context menu to select all cells in the array.
Once selected, you can easily manage the array:
Right-click any cell in the array and choose the desired Cut, Copy,
Delete, Clear or Format operation from the context menu. Manually
remove initial $ characters in the formula bar to make cell references
relative.
Right-click in a new cell and choose Paste to reinsert a cut or copied
array.
Place the cursor over the edge of the selected array until a crosshair
cursor appears, then click and drag the array to a new cell to move it.
Open the function dialog box or task pane and update the Output cell
(page 68) to place the array in a new location.
67
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
You must move or clear an entire Excel array including all cells, or DataLink
displays an error message: You cannot change part of an array.
You can also copy the values from a function array if you want to use them
elsewhere in a spreadsheet. Once 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 Paste Special
to paste them in the desired location.
You do not need to select the entire array column or row to copy
values.
Update Arguments
You can update a function array with new argument values:
1. Right-click and select the function name from the context menu (2003
or 2007), or display the function dialog box or task pane.
The corresponding function dialog box appears and displays the
current arguments in the appropriate edit fields.
2. Change any parameters as desired to update the array with new
arguments, and click OK or Apply.
68
If the Output Cell argument is changed, the results depend on the
location of the new cell reference:
If the new cell reference is part of the original array, then the
entire array is moved such that the upper-leftmost cell of the array
is placed in the newly-referenced cell.
If the new cell reference is not part of the original array, then the
array is copied and pasted with the upper-leftmost cell located in
the newly-referenced cell. The original array remains in its
original location.
6 ● Spreadsheets
●
●
●
●
●
Note that you can also edit function syntax directly by pressing F2 to edit
in the Excel formula bar. Press Ctrl+Shift+Enter to save the edits when
complete.
Resize Arrays
When a spreadsheet is called up at different times, a different number of
values may be available for a defined function. If the number of values
exceeds the current size of the array, the array does not expand to display
the additional values unless you manually recalculate (page 65) the
function.
If fewer than the original number of retrieved values exist, empty values
are returned to fill the recalculated array, and are marked #N/A if specified,
or left blank. If additional values exist that cannot be displayed, the text
Resize to show all values appears at the bottom of the function array,
unless you set a preference to disable (page 29) this message.
To resize the array to fit available data:
Right-click in any part of an array and choose Recalculate (Resize)
Function from the context menu.
Empty values are typically added when a function references a time range
that extends to the current time, using relative start and end times. When
the function is recalculated, the time range covers a new interval which
may include more data variance, and thereby a different number of
recorded events in the archive.
For example, consider a compressed data function created to request 40
values beginning at midnight the previous day. When the function is
recalculated a week later, and only 35 event values (including filtered
events) are recorded, the final five cells of the original array are filled with
blank strings to preserve the array size.
Empty values may change the appearance of a spreadsheet, but help to
ensure that variances in recorded data are incorporated without updating
69
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
the function. To maintain a constant size for Compressed Data (page 36)
functions, specify the number of values to retrieve rather than a time range.
Or to display only a predetermined portion of results, specify a limited
output cell range (page 18).
Share Spreadsheets
If you want to share FactoryTalk Historian data and make spreadsheets
accessible to other users, keep the following considerations in mind:
You can send a FactoryTalk Historian DataLink spreadsheet to
another Microsoft Excel user. The user must have FactoryTalk
Historian DataLink installed and an active connection to the same
FactoryTalk Historian server in order to recalculate functions and see
dynamically updated FactoryTalk Historian point values.
If users do not have FactoryTalk Historian DataLink installed, they
can still see the last data saved in the spreadsheet provided the Excel
Calculation options are set to Manual prior to the spreadsheet being
opened in Excel.
In Excel 2007, click the Office 2007 button, then click Excel
Options > Formulas to access these options.
You can also save in HTML or PDF format in Excel 2007 to share a
You can copy and paste (page 67) values from function arrays to new
If you have Microsoft SharePoint Server in your computing
70
In Excel XP-2003, the manual setting is available under Tools >
Options on the Calculation tab.
static spreadsheet.
locations on a spreadsheet using Paste Special. Although the
spreadsheet 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.
environment, you can publish a DataLink spreadsheet to a SharePoint
6 ● Spreadsheets
●
●
●
●
●
site and use FactoryTalk Historian DataLink Server to display and
recalculate FactoryTalk Historian function data.
71
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
72
Chapter 7
Trend Displays
FactoryTalk Historian DataLink includes an ActiveX trend control object
that can be inserted into any Excel spreadsheet to display the trend of event
values over time. Embedded trend objects can display data from both the
spreadsheet and selected FactoryTalk Historian points.
73
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Create a Trend
A wizard makes it easy to insert and configure trends. To insert a trend:
1. Click in the cell where you want to place the top left corner of the
trend object, click PI > Insert Trend (XP-2003), or click Insert
Trend on the PI ribbon (2007) to display the Trend Add-in Wizard.
When selecting the input cell, consider that the default size of the
trend object requires approximately 14 x 8 standard cells.
2. Choose the source of tag names:
Select Data on worksheet to base the trend on array values (page
75) that already appear in spreadsheet cells.
Select Data from PI to base the trend on specific point data
retrieved directly from FactoryTalk Historian (page 76).
3. Complete the remaining steps of the trend wizard.
74
7 ● Trend Displays
●
●
●
●
●
Worksheet Data
If you choose Data on worksheet, the trend wizard prompts you to select
the cell range containing the data you want to trend.
To specify worksheet data for the trend:
1. Click in the Cell Range containing data field, then click and drag to
select a cell range in the spreadsheet.
Unless you clear Include all cells in array, you only need to select
one cell of a function array. The rest of the array is added
automatically to the cell range reference when you click Add.
For discrete data points that are not part of an array you still need to
select every desired cell.
2. Select First element is trace name to use the value of an adjacent cell
to name the trace on the trend.
75
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
The first element is the cell above the first value of the selected range
if the data is arranged in column format, and the first cell to the left of
the first value of the range for data in row format.
3. Select Stepped to plot a stepped trend instead of a continuous trace.
This option is usually specified for discrete tags.
4. Click Add to add the selected cell range to the trend.
5. Add cell references as necessary, or click Next or Finish to continue.
FactoryTalk Historian Data
If you choose Data from PI, the trend wizard prompts you to reference or
search for FactoryTalk Historian tag names.
To specify FactoryTalk Historian data for the trend:
76
7 ● Trend Displays
●
●
●
●
●
1. Click in the Tag name field, then click and drag to select a cell range
in the spreadsheet.
You can also enter a cell reference directly, or use the reference button
to display a reference dialog used to browse and add cell
references.
You can also click the selection button to search for tags (page 51)
in FactoryTalk Historian. Tags selected through a tag search are added
automatically added to the list of traces.
2. Change the default server name (if necessary) in the Server name
field, and click Add to add the selected tag name references to the
trend.
You can use the reference button to display a reference dialog
used to browse and add cell references.
3. Add tag names as necessary, or click Next or Finish to continue.
Manage Traces
When building a trend from worksheet or FactoryTalk Historian data, you
accumulate traces in the trace panel to the right of the wizard screen.
Several controls are provided to manage the traces that appear in the trend:
Select the Markers check box next to a trace name to display markers
on the trace to indicate the location of archived data points.
Traces are drawn in different colors. By default a trend also includes
color-blind markers to differentiate traces on monochrome screens. Colorblind markers are evenly spaced along a trace and do not indicate archived
data points.
Click the arrow buttons above the trace panel to move traces up and
down in the trace legend display.
77
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Click the X and X All buttons to remove selected and all traces,
respectively.
Click the Rename button to rename a selected trace in the trace
legend.
Specify the Time Range
When the trend traces are determined, the wizard prompts you to specify a
time range for the trend if any of the traces are drawn directly from
FactoryTalk Historian.
To specify a time range:
1. Click in the Start Time and End Time fields, then click to select a
time stamp cell in the spreadsheet.
You can also type a time string directly or use the reference button
to display a reference dialog used to browse and add cell
references.
2. Select Enable Updates to refresh the trend with new FactoryTalk
3. Choose Next or Finish to continue.
78
If you type a
the correct time stamp format.
combined or absolute time string
(page 86), be sure to use
Historian data if the time range changes or extends to the present.
7 ● Trend Displays
●
●
●
●
●
Title and Placement
Complete the trend and determine its location in the final screen.
To complete the trend:
1. Type a Trend title.
2. Clear Show Value Attributes if you do not want value attributes to
appear along trend traces.
The icons appear when the range of data contains events that have the
Questionable, Substituted, or Annotated bits set.
3. Select a different location for the trend, if desired, by placing it on a
separate worksheet or changing the default placement cell.
If New worksheet is selected, the trend is placed on a blank worksheet
at the top left corner.
79
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
If Existing worksheet is selected, then the cell (or range used to size
the trend) where the trend is to be placed must be specified or
referenced in the accompanying field. If you change your default
placement cell, make sure the new cell does not contain data (which
will be covered by the trend display).
Context Menu
Once a trend is inserted into a spreadsheet, you can update, edit or manage
it using the context menu. To access context menu options:
Right-click the trend display and choose an option from the menu:
Choose Change Scale to change the y-axis scaling and time
range.
Choose Revert to undo any changes and revert to the original
trend settings defined in the Trend Add-in Wizard.
Chose Scroll Bar to enable a scroll bar at the bottom of the trend
to scroll the display through adjacent time ranges.
80
7 ● Trend Displays
●
●
●
●
●
Choose Format to edit the display of individual traces or the
trend as a whole using the Trend Control Properties dialog box.
You can change the color or line thickness of a trace, or add
legend items to the trend.
Choose Define Trend to display the trace definition screen of the
trend wizard to update or change the trace sources.
Choose Define Trend Time Range to display the time range
definition screen of the trend wizard to update the time range.
Choose Delete Trend to remove the trend from the spreadsheet.
A deleted trend cannot be restored and must be recreated.
81
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Choose Export Data to paste the values used to plot the trend
into spreadsheet cells. You can specify row or columnar format,
and also export trace names as headings.
Choose Move/Resize and enter a cell location to move the upper
left hand corner of the trend to the specified cell. Enter a cell
range to resize the trend.
Choose Copy/Paste to copy the entire trend display to the
clipboard and prompts for a destination cell to paste the control.
82
Chapter 8
Supplementary Information
Setup
There are two ways for users to work with FactoryTalk Historian DataLink
functions in Excel spreadsheets:
Users can install a stand-alone version of FactoryTalk Historian
DataLink on their local PC.
Web users may view spreadsheets with FactoryTalk Historian
DataLink functions using FactoryTalk Historian DataLink Server.
Contact your Rockwell Automation sales representative for more
information.
Previous versions of FactoryTalk Historian DataLink allowed a shared version
to be installed and run from a central file server. This feature is no longer
supported.
You can install FactoryTalk Historian DataLink from a distribution CD or
an installation kit downloaded from Rockwell Automation. The installation
program automatically installs both Excel XP-2003 and 2007 versions of
the DataLink add-in to your system, regardless of which version of Excel
you have installed.
If you have Excel XP-2003 on your PC, you must configure the add-in
manually after installation by adding it to Excel.
If you have Excel 2007 on your PC, the install program automatically
configures the add-in for Excel 2007.
83
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
High Availability Connection Preferences
The connection preference is set at the time of the first connection.
For FactoryTalk Historian DataLink 3.1.6 and above, the connection
preference for DataLink functions is set to Any. However, since the
connection preference is set at the time of the connection, the order in
which the connection is made matters. If the first connection is made with
DataLink functions, then it makes a connection with connection preference
of Any. If the first connection is made with the trend control, tag search, or
the connection manager, then the connection preference is set to Prefer
Primary.
See "Default Connection Preferences" in the FT Historian SE High
Availability Administrator Guide for an explanation of connectivity
preferences.
FactoryTalk Historian Server Connectivity
Client computers running Microsoft Excel and FactoryTalk Historian
DataLink can retrieve data from FactoryTalk Historian 3 servers.
For more information on FactoryTalk Historian server connectivity and
security, consult your FactoryTalk Historian server documentation, or
download documentation from the Rockwell Automation technical support
site (http://techsupport.osisoft.com/downloadcenter.aspx).
Firewall Database
The firewall database on a FactoryTalk Historian server machine must be
configured to allow access from client computers running FactoryTalk
Historian DataLink. For example,
PIConfig> @table pi_gen,pifirewall PIConfig> @ostr
hostmask,value PIConfig> @select hostmask=* PIconfig> @ends
*.*.*.*, ALLOW
blocks no IP ranges, indicating that all client machines may connect to
FactoryTalk Historian 3 server. In contrast,
84
8 ● Supplementary Information
●
●
●
●
●
*.*.*.*, DISALLOW 192.168.100.*, ALLOW
allows connections only from TCP/IP addresses starting with 192.168.100.
FactoryTalk Historian Trusts
A FactoryTalk Historian trust allows clients to connect to a FactoryTalk
Historian server machine and retrieve data without explicit user login. A
trust may instead allow a user to log in based on an IP address, Windows
domain, user name, application or other criteria.
FactoryTalk Historian trusts are established on the FactoryTalk Historian
server and stored in a trust database.
Point Access Permissions
FactoryTalk Historian DataLink prompts the user for a user name and
password upon connection to a FactoryTalk Historian server. The user
name is used in conjunction with the PtOwner, PtAccess, DataOwner, and
DataAccess fields.
For example, if the sinusoid tag is configured with PtAccess
O:RW, G:NONE, W:NONE, and PtOwner is user1, a user must log
in as user1 in order to access the tag. Otherwise, the tag cannot be
found.
If sinusoid DataAccess is O:R, G:NONE, W:NONE, and
DataOwner is user1, a user must log in as user1 in order to see
sinusoid tag data. Otherwise, a read access error message is returned.
However, the same user may not write data to sinusoid because the
DataAccess attribute is O:R (read only). The FactoryTalk Historian
System Manager would need to change DataAccess to O:RW (read and
write) to enable a user logging in as user1 to read and write data to
sinusoid.
85
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Name
Short name
Plural name
Member names
Fractions
second
s
seconds
no
yes
minute
m
minutes
no
yes
hour h hours
no
yes
day d days
no
no
month
mo
months
yes (for example, December)
no
year y years
no
no
week
w
weeks
no
no
weekday
wd
weekdays
yes (for example, Tuesday)
no
yearday
yd
yeardays
no
no
The PIAdmin account is a super-privileged user and has read and write access
to all tags. For this reason, System Administrators should not normally allow
FactoryTalk Historian DataLink users to log in as PIAdmin.
FactoryTalk Historian Time
FactoryTalk Historian Time abbreviations and FactoryTalk Historian Time
expressions allow you to specify times and time ranges for data using
constants, variables, and short expressions.
FactoryTalk Historian Time Abbreviations
An interval is a unit of time that can be used in time entries. Intervals that
support fractional values are listed below. For intervals where the Fractions
column indicates No, fractional amounts cannot be used in time strings.
You can spell out month and weekday names, or type the first three letters
(for example, Dec, Tue).
86
8 ● Supplementary Information
●
●
●
●
●
Constant
Result
*
The current time.
Today or t
12:00 am of the current day.
Yesterday or y
12:00 am of the previous day.
Sunday or sun
00:00:00 (midnight) on the most recent past Sunday (in reference to the
Historian Server).
Expression
Description
Examples
Relative Time
Relative time expressions specify a number of days, hours,
minutes, or seconds with either a leading plus sign or a
leading minus sign.
The reference time, or starting time, for the relative time
expression is the current time if both start and end times are
relative.
+1d
-24h
-3m
+24s
Combined
Time
A combined time expression is a specific reference time
followed by a relative time expression.
*+8h
18-dec-02 -
3m
t+32s
Absolute Time
An absolute time expression is any time expression that is
neither a relative nor a combined time expression.
*
14-Dec-97
11-Nov-96
2:00:00.0001
t
y
PI Times can also be expressed using certain constants:
FactoryTalk Historian Time Expressions
FactoryTalk Historian allows three types of time expressions: relative time,
combined time, and absolute time. These time expression types are defined
in the following table.
87
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
PI Time String
Meaning
06-dec-91 15:00:00
3:00:00 pm on December 6, 1991
*
Current time (now)
25
00:00:00 (midnight) on the 25th of the
current month
25-aug-92
00:00:00 (midnight) on August 25th, 1992
8:
08:00:00 on the current date
25 8:
08:00:00 on the 25th of the current month
t
00:00:00 on the current date (today)
y
00:00:00 on the previous date (yesterday)
sun, mon, tue, wed, thu, fri, sat
00:00:00 on the most recent Sunday,
Monday, ... Saturday
When using FactoryTalk Historian times, follow these guidelines:
Use absolute or combined time expressions. Avoid using relative time
expressions. Multiple relative time expressions in a time range may
cause an incorrect start time or an error message, depending on the
context of the expression.
Relative and combined time expressions contain only a single
operator: either a single plus sign (+) or a single minus sign (-).
Additional operators can lead to unpredictable results. For example,
the following are not valid time expressions:
*+1d+4h
T-1d+12h
The name or short name for an interval used to denote FactoryTalk
Historian time is not case-sensitive.
FactoryTalk Historian Time String Examples
Time Syntax Examples
88
8 ● Supplementary Information
●
●
●
●
●
PI Time String
Meaning
*-1h
One hour ago
t+8h
8:00:00 am today
y-8h
4:00:00 pm on the day before yesterday
mon+14.5h
2:30:00 pm last Monday
sat-1m
11:59:00 pm last Friday
PI Time String
Meaning
1.5h
One and one-half hours
32m
Thirty-two minutes
49s
Forty-nine seconds
+5h
Five hours added to the time beginning with
the start time.
-5h
Five hours subtracted from the time
beginning with the end time.
Time Interval Examples
In interval expressions, a positive or unmarked interval is based on the start
time, and a negative interval is based on the end time of a time expression.
For example, if the start time is y, the end time is t, and the interval is +5h
for a Sampled Data function, then interpolated values are generated at y,
y+5h, y+10h, y+15h, and y+20h. If the interval is -5h, the interpolated
values are generated at y+4h, y+9h, y+14h, y+19h and t.
FactoryTalk Historian Data Type Support
FactoryTalk Historian DataLink supports the following FactoryTalk
Historian point data types:
89
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Data Type
Support
Digital (defined states)
supported
Int (16 and 32)
supported
Float (16, 32 and 64)
supported
String (text)
supported
Timestamp
supported
Blob
not supported
FactoryTalk Historian Expressions
FactoryTalk Historian expressions (also known as FactoryTalk Historian
Performance Equations) are used for functions that incorporate
mathematical operations and calculations based on FactoryTalk Historian
points.
For some functions you can substitute a PI Expression for a tag name to
calculate values as they are retrieved from the FactoryTalk Historian
server. Functions that allow an expression argument include both PI Tag
and PI Expression buttons in the function dialog box or task pane.
To base a function on a FactoryTalk Historian calculation expression:
1. Click the PI Expression button at the top of the function dialog box or
2. Type the expression directly in the Expression(s) field, or use the field
90
task pane.
The Tagname(s) field becomes an Expression(s) field. Other fields
may activate, or become inactive.
to reference a cell containing an expression.
Using field references allow you to specify multiple expressions for a
function. Remember that an expression in a referenced cell is a string,
and should be preceded by an apostrophe.
8 ● Supplementary Information
●
●
●
●
●
Some functions also provide a field for a Filter Expression argument. You
can supply a filter expression to limit the values returned by a function, and
reference a filter expression in a worksheet cell.
Functions that may use these expressions include:
Archive Value (page 34)
Compressed Data (page 36)
Sampled Data (page 39)
Timed Data (page 41)
Calculated Data (page 43)
Time Filtered (page 48)
The following sections briefly outline FactoryTalk Historian expression
basics. FactoryTalk Historian DataLink supports all functional syntax,
operators and functions supported by the FactoryTalk Historian server.
For a full description of FactoryTalk Historian Performance Equations and
examples, see the FT Historian SE Applications User Guide.
Syntax
Follow these guidelines when writing FactoryTalk Historian expressions:
Begin the expression with a single quote to force Excel to interpret the
expression as a string.
Enclose tag names in the expression in single quotes.
Type two single quotes for an expression that begins with a tag name.
Operators
The following operators are supported in FactoryTalk Historian
Expressions:
91
●
●
●
●
●
FactoryTalk Historian DataLink User Guide
Type
Operator
Syntax Example
Meaning
Arithmetic
+
A + B
Addition: A + B
-
A - B
Subtraction: A minus B
*
A * B
Multiplication: A times B
/
A / B
Division: A divided by B
^
A ^ B
Raising to a power: A to the power of B (AB)
Mod
A mod B
Modulus: the remainder of A divided by B
Relational
<
A < B
Less than: returns true if A is less than B
=
A = B
Equal to: returns true if A equal to B
>
A > B
Greater than: returns true if A is greater than
B
<=
A <= B
Less than or equal to: returns true if A is less
than or equal to B
<>
A <> B
Not equal to: returns true if A is not equal to
B
>=
A >= B
Greater than or equal to: returns true if A is
greater than or equal to B
Prefix
Not
NOT A
Complementation: returns true if A is 0 and
False otherwise
-
- A
Negation (as prefix operator): returns the
negative of A
Conjunction,
Disjunction
and Inclusion
And
A and B
Conjunction: returns true if operands A & B
both evaluate to true. If both A and B are
integers, returns the result of a bitwise AND
operation.
Or
A or B
Inclusive disjunction: returns true if either
operand A or operand B evaluates to true. If
both A and B are integers, returns the result
of a bitwise OR operation.
in ..
A in B..D
Membership in a range: returns true if the
value of A is between B and D
in ( )
A in (B1, B2,
Membership in a discrete set: returns true if
the value of A matches any of the values
92
Loading...