8520-rm091_-en-p.pdf - Literature Library | Rockwell Automation
Historian SE - Rockwell Automation
-
Upload
khangminh22 -
Category
Documents
-
view
10 -
download
0
Transcript of Historian SE - Rockwell Automation
DATALINK USER’S GUIDEPUBLICATION HSEDL-UM020A-EN-E–September 2007
Historian SE
HSEDL-UM020A-EN-E 8/8/07 1:29 PM Page 1
Contact Rockwell AutomationCustomer Support Telephone — 1.440.646.3434Online Support — http://support.rockwellautomation.com
Copyright Notice© 2007 Rockwell Automation Technologies, Inc. All rights reserved. Printed in USA.© 2007 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 NoticesFactoryTalk, 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), RSView, FactoryTalk View, RSView Studio, FactoryTalk View Studio, RSView Machine Edition, RSView ME Station, RSLinx Enterprise, FactoryTalk Services Platform, and FactoryTalk Live Data.
The following logos and products are trademarks of OSIsoft, Inc.:PI System, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK.
Other TrademarksActiveX, 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 LegendUse, 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
WarrantyThis 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.
Version: 9.00.05
FactoryTalk Historian Site Edition DataLink User Guide Page iii
Table of Contents
Chapter 1: Introduction..............................................................................................................1 Contents of FactoryTalk Historian DataLink ..............................................................1 System Requirements ...............................................................................................1 For the PI System Manager.......................................................................................3
Chapter 2: Add-in to Excel.........................................................................................................9 Overview....................................................................................................................9 Tutorial .....................................................................................................................10 PI Menu....................................................................................................................17 Dialog Boxes............................................................................................................18 Time in FactoryTalk Historian DataLink...................................................................22 FactoryTalk Historian DataLink Functions...............................................................27 Details for FactoryTalk Historian DataLink Functions and Dialog Boxes ................30 Writing Data from Excel to PI...................................................................................82 Limits from Excel for FactoryTalk Historian DataLink..............................................84
Appendix A: Troubleshooting ....................................................................................................85 DataLink Add-in Doesn't Load Properly...................................................................85 Connection Problems Reported in Log Files...........................................................86
Appendix B: Expression Syntax.................................................................................................87 Calculation Expressions ..........................................................................................87 Filter Expressions ....................................................................................................90
Appendix C: Examples of PI Time Strings ................................................................................93 Start and End Time..................................................................................................93 Time Interval ............................................................................................................94
Appendix D: Setup.ini Arguments..............................................................................................95 Silent Installs............................................................................................................95 PI SDK Installation...................................................................................................95 FactoryTalk Historian DataLink Installation .............................................................96
Contents
Page iv
Appendix E: Outcodes ................................................................................................................97 Example...................................................................................................................97
Appendix F: Technical Support and Resources ......................................................................99 Before You Call or Write for Help ............................................................................99
Index ............................................................................................................................................101
FactoryTalk Historian Site Edition DataLink User Guide Page 1
Chapter 1: Introduction
FactoryTalk Historian DataLink provides a link between the PI 3 or PI 2 Server, and spreadsheet programs running on Microsoft Windows platforms. With FactoryTalk Historian DataLink, a user running Microsoft Excel can exchange information directly with the FactoryTalk Historian System databases. Combined with the functionality of the spreadsheet programs, this feature makes FactoryTalk Historian DataLink a powerful, yet easy-to-use tool for gathering, analyzing, and reporting PI data.
Contents of FactoryTalk Historian DataLink
FactoryTalk Historian DataLink consists of an add-in for Microsoft Excel
FactoryTalk Historian DataLink for Excel is built with the PI SDK product. It allows users who have experience using Microsoft Visual Basic for Applications (VBA) to develop Excel routines that call PI SDK functions.
However, users who wish to develop programs outside of Excel must purchase a separate PI SDK or PI API license. Please contact an OSIsoft sales representative for more information.
System Requirements
FactoryTalk Historian DataLink runs within a suitable spreadsheet application on a Microsoft Windows PC client machine and retrieves information stored on a PI Server through standard network software.
Operating System and Network Software
The PI Server may run on OpenVMS, Windows, or UNIX. FactoryTalk Historian DataLink communicates with the PI Server via the TCP/IP protocol.
Introduction
Page 2
TCP/IP
To use TCP/IP, one of the following operating systems is necessary:
Microsoft Windows 2000, XP, or Vista
Microsoft Windows 2003 Server
Users of Microsoft Windows should use the TCP/IP layer built into the operating system.
TCP/IP on OpenVMS
If the PI Server runs on OpenVMS, one of the following TCP/IP software packages is necessary on the VMS machine:
DEC TCP/IP Services for OpenVMS, version 2.0+
Process Software TCPWare, version 3.1+
Cisco MultiNet, version 3.4+
Attachmate Pathway, runtime release 1.1+
Spreadsheet Programs Supported
FactoryTalk Historian DataLink supports the following spreadsheet program (32-bit versions only):
Microsoft Excel 2000, version 9.0 and later.
Configuration of Microsoft Excel
If FactoryTalk Historian DataLink will be used with Microsoft Excel, and this is a first time installation (not an upgrade) of FactoryTalk Historian DataLink, you will need to add FactoryTalk Historian DataLink.
1. Start Excel.
2. Bring up Excel's add-in manager via Tools > Add-ins.
3. Browse and select the file PIPC32.XLL. For a local installation, the file PIPC32.xll will be in the ...\PIPC\EXCEL directory. For a shared installation of FactoryTalk Historian DataLink, look in the ...\PIPC\EXCEL directory on the network drive.
For the PI System Manager
FactoryTalk Historian Site Edition DataLink User Guide Page 3
If FactoryTalk Historian DataLink is upgraded and placed in a directory different from the previous versions, then Excel's add-in manager should be used first to remove the old PIPC32.XLL. Then, the new PIPC32.XLL file in the new location should be selected.
New Features for Microsoft Excel Users
A list of new features in this version of FactoryTalk Historian DataLink is in the ...\PIPC\readme_datalink.txt file.
Bug Fixes
A list of known problems that are fixed in this version of FactoryTalk Historian DataLink is in the ...\PIPC\readme_datalink.txt file.
For the PI System Manager
PI 2 Server
PI Server Service
If FactoryTalk Historian DataLink communicates with the PI Server via TCP/IP, the PI System Manager must perform a one-time configuration of the PI Server service. This PI Server service is used by not only FactoryTalk Historian DataLink, but by all OSIsoft PC client applications. Please consult the PIBuild:PIServer.txt file on the VAX/Alpha machine.
Security File
The PI Server service supports a combination of node authentication and username/password security for PC client applications. The PI Server access file, PISysDat:PIServer.Dat, determines which machines have access to PI data. This file should be created if it does not currently exist.
For node authentication security, add entries for particular machines. For example: [USERDATABASE] DEFAULT=PI [CLIENTACCESS] DEFAULT=R PINET1=RW PINET2=RW PC1=RW PC2=NONE
The above entries in PISysDat:PIServer.Dat result in the following:
Introduction
Page 4
1. The machines named "PINET1" and "PINET2" have unconditional read and write access to PI data. This level of access must be provided to PINet nodes.
2. The machine named "PC1" also has unconditional read and write access to PI data. This level of security means that anyone with access to "PC1" itself will have unconditional read and write access to PI data via FactoryTalk Historian DataLink.
3. The machine named "PC2" has no access to PI data. This level of security means that no one can use FactoryTalk Historian DataLink on "PC2" to retrieve data into spreadsheets.
4. All other PCs have unconditional read access to PI data. This level of security means that all users on these machines will be able to get data from but not write data to PI with FactoryTalk Historian DataLink.
5. For username/password security, add the letter L after the access type as follows:
[USERDATABASE] DEFAULT=PI [CLIENTACCESS] DEFAULT=RL PINET1=RW PINET2=RW PC1=RLWL PC2=NONE
This PIServer.Dat is the same as the previous example except in two cases:
• The machine named "PC1" has conditional read and write access. This level of security means that only user with proper user name and password can read and write on "PC1" via FactoryTalk Historian DataLink.
• All other PCs have conditional access to PI data. This level of security means that users must provide a valid PI username and password to access PI data and no user can write data back into PI.
Be aware that TCP/IP node names are case-sensitive. In addition, the values for the entries in the CLIENTACCESS section (that is, R and W) are also case-sensitive.
For node or username/password security to function properly, it is essential that the PI Server be able to determine the name of the PC client running FactoryTalk Historian DataLink. The following sections provide specific information for DECNet and different vendor's TCP/IP.
Name Translation - UCX (or TCPIP for VMS 7.2+)
Under DEC TCP/IP Services for VMS, the PI 2 Server asks UCX to supply the hostname for a given FactoryTalk Historian DataLink connection. UCX in turn queries the UCX host database on the VAX/Alpha or the Domain Name Server (if configured).
To confirm that UCX is determining the PC name properly, type the following from DCL after FactoryTalk Historian DataLink has connected to the PI 2 Server:
$ ucx show device /port=545
You should see the remote hostname listed under Remote. It is this hostname whose access level to PI data is being controlled by PISysDat:PIServer.Dat.
For the PI System Manager
FactoryTalk Historian Site Edition DataLink User Guide Page 5
If instead, you see a number (for example, 192.168.100.77) for the remote host, this means that UCX (and hence the PI 2 Server) cannot determine the name of the PC client. Accordingly, the PI 2 Server uses the DEFAULT level access in PISysDat:PIServer.Dat.
To add an entry in the UCX host table for a PC: $ ucx set host "mypc" /addr=192.168.100.77
Consult your UCX documentation for more details.
Name Translation - MultiNet
Under MultiNet, the PI 2 Server asks MultiNet to supply the hostname for a given FactoryTalk Historian DataLink connection. MultiNet in turn queries the MultiNet host database on the VAX/Alpha or the Domain Name Server (if configured). To confirm that MultiNet is determining the PC name properly, type the following from DCL after FactoryTalk Historian DataLink has connected to the PI 2 Server:
$ multinet show
You should then see the name of the local host as well as the name of the foreign (PC) host. It is this latter hostname whose access level to PI data is being controlled by PISysDat:PIServer.Dat.
If instead, you see a number (for example, 192.168.100.77) for the foreign host, this means that MultiNet (and hence the PI 2 Server) cannot determine the name of the PC client. Accordingly, the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer.Dat.
To add an entry in the MultiNet host table on the VAX/Alpha for a PC, you need to edit the MultiNet:Hosts.Local file. After editing, you should run the following commands:
$ multinet host_table compile $ @multinet:install_databases
Consult your MultiNet documentation for more details.
Name Translation - PathWay
Under PathWay, the PI 2 Server asks PathWay to supply the hostname for a given FactoryTalk Historian DataLink connection. PathWay in turn queries the host database on the VAX/Alpha or the Domain Name Server (if configured). To confirm that PathWay is determining the PC name properly, type the following from DCL after FactoryTalk Historian DataLink has connected to the PI 2 Server:
$ netstat
Introduction
Page 6
You should then see the name of the local host as well as the name of the foreign (PC) host. It is this latter host name whose access level to PI data is being controlled by PISysDat:PIServer.Dat.
If instead, you see a number (for example, 192.168.100.77) for the foreign host, this means that PathWay (and hence the PI 2 Server) cannot determine the name of the PC client. Accordingly, the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer.Dat.
To add an entry in the PathWay host table on the VAX for a PC, you need to edit the twg$etc:Hosts.file. Consult your PathWay documentation for more details.
Name Translation - TCPWare
Under TCPWare, the PI 2 Server asks TCPWare to supply the hostname for a given FactoryTalk Historian DataLink connection. TCPWare in turn queries the host database on the VAX/AlphaAXP or the Domain Name Server (if configured). To confirm that TCPWare is determining the PC name properly, type the following from DCL after FactoryTalk Historian DataLink has connected to the PI 2 Server:
$ netcu show connections /host_names
You should then see the name of the local host as well as the name of the remote (PC) host. It is this latter host name whose access level to PI data is being controlled by PISysDat:PIServer.Dat.
If instead, you see a number (for example, 192.168.100.77) for the remote host, this means that TCPWare (and hence the PI 2 Server) cannot determine the name of the PC client. Accordingly, the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer.Dat.
To add an entry in the TCPWare host table on the VAX/Alpha for a PC, you need to edit the TCPWare:Hosts file. You may need to restart TCPWare in order for the change to take effect. Consult your TCPWare documentation for more details.
PI 3 Server
Firewall Database
The firewall database on the machine on which PI 3 Server is running must be configured to allow access by PCs on which FactoryTalk Historian DataLink is running. For example,
PIConfig> @table pi_gen,pifirewall PIConfig> @ostr hostmask,value PIConfig> @select hostmask=* PIconfig> @ends *.*.*.*, ALLOW
The above indicates that all PCs may connect to PI 3 Server. *.*.*.*, DISALLOW 192.168.100.*, ALLOW
For the PI System Manager
FactoryTalk Historian Site Edition DataLink User Guide Page 7
The above indicates that only PCs whose TCP/IP address start with 192.168.100 are allowed to connect.
For more information, consult the PI Server User Manuals included on the FactoryTalk Historian SE installation CD under Redist > Docs.
Trust Database
The trust database on the machine on which PI 3 Server is running may be configured to allow access without explicit login by PCs on which FactoryTalk Historian DataLink is running. For example,
PIconfig> @table pitrust PIconfig> @ostr trust,ipaddr,iphost,piuser PIconfig> @select trust=* PIconfig> @ends MyPCTrust,0.0.0.0,mypc,piadmin
The above indicates that any app connecting to PI 3 Server from "mypc" gets piadmin privileges by default.
For more information, consult the PI Server User Manuals that are included on the FactoryTalk Historian SE installation CD under Redist > Docs.
Point Access/Data Access Attributes
When FactoryTalk Historian DataLink connects to PI 3 Server, it asks the user for a username and password. This username is used in conjunction with the PtOwner, PtAccess, DataOwner, and DataAccess fields.
For example, if the tag SINUSOID is configured such that PtAccess is O:RW, G:NONE, W:NONE, and PtOwner is USER1, FactoryTalk Historian DataLink users must log in as USER1 in order to see this tag. Otherwise, the tag will not be found.
Also, if SINUSOID DataAccess is O:R, G:NONE, W:NONE, and DataOwner is USER1, FactoryTalk Historian DataLink users must log in as USER1 in order to see data for this tag. Otherwise, a read access error message is returned.
However, even logging on as USER1 in this case will not allow FactoryTalk Historian DataLink to write data to SINUSOID because the DataAccess attribute is O:R (read only). The PI System Manager would need to change DataAccess to O:RW (read and write). Only after this change is made can FactoryTalk Historian DataLink users who log in as USER1 be able to read and write data for SINUSOID.
For more information, consult the PI Server User Manuals that are included on the FactoryTalk Historian SE installation CD under Redist > Docs.
Introduction
Page 8
Note: The user PIAdmin is a "super"-privileged user. A user of FactoryTalk Historian DataLink who logs in as PIAdmin has read and write access to all tags. For this reason, FactoryTalk Historian DataLink users normally should NOT log in as PIAdmin.
FactoryTalk Historian Site Edition DataLink User Guide Page 9
Chapter 2: Add-in to Excel
Overview
The FactoryTalk Historian DataLink add-in for Excel provides users of Microsoft Excel with the ability to retrieve data associated with tags on a PI Server, directly into a spreadsheet. Moreover, users have the ability to write spreadsheet values back into PI.
FactoryTalk Historian DataLink provides the following functions to retrieve data from PI:
Current value
Value at a specific time
Tag attributes
Evenly spaced (sampled) data
Sampled data while a given expression is true
Compressed (archived) data
Compressed data while a given expression is true
Sampled data for a user specified array of timestamps
Data from calculations on PI tag expressions
Amount of time while a PI tag expression was true
Totals, minima, maxima, standard deviations, ranges, averages, counts and means for PI tags and PI expressions
Tagname from a specified Point ID
Tagnames from specified attribute masks
Alias value from module database
Property value from module database
Add-in to Excel
Page 10
Tutorial
The goal of this tutorial is to get you started with using FactoryTalk Historian DataLink in Excel as quickly as possible. FactoryTalk Historian DataLink's features are not discussed in detail in this tutorial. Rather, it will serve to familiarize the user with the overall operation of this add-in.
Verify Communications with PI Server
In this first example, we will confirm that FactoryTalk Historian DataLink has been installed properly and that it can connect to the PI Server.
Start Excel and make sure that the PI menu choice is in Excel's menu bar. If PI does not appear, you need to use Excel's add-in manager. See Configuration of Microsoft Excel.
From the PI Connection Manager dialog box, check the checkboxes in the left-hand panel.
If the Status indicates that the PI Server is not connected, click the checkbox to connect.
Tutorial
FactoryTalk Historian Site Edition DataLink User Guide Page 11
Tag Attributes and Current Value
In this next example, we obtain the tag descriptor, current value, and engineering units for some tags.
1. Open Excel.
2. From the PI menu, select Settings... and make sure that the In a column radio button in the "Copy items to sheet" section is chosen.
3. Next, dismiss the dialog box and move the cursor to cell A2 in the spreadsheet.
4. Select Tag Search... from the PI menu and enter "BA*" into the Tag Mask field.
5. Click Search to find tags that being with "BA". The Search Results list should contain at least five tags: BA:ACTIVE.1, BA:CONC.1, BA:LEVEL.1, BA:PHASE.1, and BA:TEMP.1.
6. Select these five tags from the Search Results list by clicking on the first tag (BA:ACTIVE.1) and then simultaneously holding the CTRL key and clicking on each of
Add-in to Excel
Page 12
the four other tags. Then, click OK to copy the five tags along a single column, from A2 to A6.
7. Move the cursor to cell B2. From the PI menu, select Tag Attributes.... Click the edit box under Tagname(s).
8. Position the mouse over cell A2 in the spreadsheet. Click and drag to select the reference A2:A6.
9. Type or select "descriptor" from drop-down box below Attribute.
10. Click OK in the dialog box. FactoryTalk Historian DataLink then retrieves Tag descriptors into cells B2 to B6.
11. Move the cursor to cell C2. From the PI menu, select Current Value.... Click the edit box under Tagname. Position the mouse over cell A2 in the spreadsheet. Click and drag to select the reference A2:A6. In the dialog box, click the time at left radio button.
Tutorial
FactoryTalk Historian Site Edition DataLink User Guide Page 13
12. Click OK in the dialog box. FactoryTalk Historian DataLink then retrieves current values and the timestamps of these current values into columns D and C, respectively.
13. Move the cursor to cell E2 in the spreadsheet. From the PI menu, select Tag Attributes... again. Click the edit box under Tagname(s).
14. Position the mouse over cell A2 in the spreadsheet. Click and drag to select the reference A2:A6. Select engunits from the Attribute list box.
15. Click OK in the dialog box. FactoryTalk Historian DataLink then retrieves engineering units into cells E2 to E6.
Add-in to Excel
Page 14
Actual Values from the PI Server
In this example, we gather sampled data for a single tag.
1. Move the cursor to cell C10. From the PI menu, select Sampled Data.... Click the Tag Search button. The Tag Search dialog box then appears.
2. Enter "CD*" into the Tag Mask field. Click Search to search for tags that begin with CD. The tag "cdt158" should be returned. Select this tag and click OK.
3. The tag cdt158 then appears in the Tagname field in the Sampled Data dialog box. Enter t (for midnight today) in the Start Time field, +8h (eight hour offset from start time) in the End Time field, and 1h (one hour interval) in the Time Interval field. Click the show timestamps check box.
4. Click OK. FactoryTalk Historian DataLink then retrieves interpolated data from midnight to 8:00am at 1-hour intervals.
Tutorial
FactoryTalk Historian Site Edition DataLink User Guide Page 15
Changing Arguments from the Dialog Box
In this example, we make a change to the end time used in the previous example.
1. Right click on any part of the array created in the previous example
2. Select Sampled Data...
3. Change the end time from "+8h" to "+9h" and click OK. FactoryTalk Historian DataLink then retrieves interpolated data from midnight to 9:00am at 1-hour intervals. Note that the array size has increased by one row.
Add-in to Excel
Page 16
Using Old Arrays as Templates
In this example, we show how to use an old array as a template for a different tag.
1. Right click on any part of the array created in the previous example
2. Select Sampled Data...
3. Change the tag edit field from "CDT158" to "SINUSOID"
4. Change the Output Cell from $C$10 to $A$10 and click OK. Notice that the sampled data for tag "SINUSOID" is in A10.
FactoryTalk Historian DataLink Summary
As the above examples indicate, the fastest way to use FactoryTalk Historian DataLink to transfer data between PI and Excel is to select an option from the PI menu item. A dialog box then appears. Enter the appropriate parameters and FactoryTalk Historian DataLink retrieves the requested PI values. The next sections describe the features of FactoryTalk Historian DataLink in greater detail.
PI Menu
FactoryTalk Historian Site Edition DataLink User Guide Page 17
PI Menu
When FactoryTalk Historian DataLink is added to Excel, it adds the PI menu item to Excel's menu bar.
Pop-up menu selections are available from this menu item. These are:
Current Value retrieves the current value for a tag
Archive Value retrieves a single value from the archive (may be interpolated)
Tag Attributes retrieves a tag attribute
Add-in to Excel
Page 18
Compressed Data (Start Time/Number) retrieves compressed data based on a start time and a specified number of values with an optional filter condition
Compressed data (Start Time/End Time) retrieves compressed data based on a start time and an end time with an optional filter condition
Sampled Data retrieves evenly spaced (sampled) data from the archive with an optional filter condition
Timed Data retrieves sampled data synchronized with an array of timestamps
Calculated Data retrieves totals, minima, maxima, ranges, standard deviations, averages and means for multiple time periods
Advanced Calculated Data is similar to calculated data but with more advanced options (i.e. event weighted)
Time Filtered retrieves the amount of time over which a tag expression is true
Point ID to Tag retrieves a tagname from specified point ID
Attribute Mask to Tag retrieves tagnames from specified attribute masks
Alias retrieves an alias tagname from the module database
Property retrieves a property value from the module database
Insert Trend creates a trend that can directly get data from PI or off the worksheet
Tag Search searches for PI tags
Module Database displays module database contents such as aliases and properties
Connections manages PI Server connections
Settings displays FactoryTalk Historian DataLink settings and preferences
About displays version information on FactoryTalk Historian DataLink
Help displays help on FactoryTalk Historian DataLink
Dialog Boxes
Edit Fields
The edit fields can contain either the necessary text information or references to cells, which contain the necessary text information. FactoryTalk Historian DataLink determines the type of information entered in the edit field by context.
Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 19
As opposed to typing in the cell reference, you may also use the mouse to click the edit field, and then click the cell (or click the cell and drag to adjacent cells) on the spreadsheet. In this procedure, Excel automatically enters the cell reference(s) into the edit field for you.
For example, in the dialog box below, the edit fields for Tagname and Output ask for a cell on the spreadsheet that contains the tagname and a cell on the spreadsheet where you wish to place the output of the current value, respectively.
PI Server and Output Fields
The PI Server field allows the selection of a PI server from the known servers list. In the drop-down list, the servers above the dotted line are the servers currently connected and the ones below are currently disconnected. The PI Server field in all of the dialog boxes is labeled as opt. or optional. If the PI Server field is blank, FactoryTalk Historian DataLink will use the default PI Server. You can change the default PI Server in the Connections... dialog box available from the PI menu.
The Output field allows you to specify the upper left-hand corner of the range where FactoryTalk Historian DataLink will place the resulting data.
Data Displayed as Columns or Rows
For dialog boxes that expect to return an array of PI values (for example, Sampled data), there is a set of radio buttons with options column(s) or row(s). Choose column(s) to display the data in either one column, two columns if timestamps OR percent good are to be
Add-in to Excel
Page 20
displayed, or three columns if timestamps AND percent good are to be displayed. Choose row(s) to display the data in either one, two, or three rows.
Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 21
For dialog boxes that expect to return a single PI value (e.g., Current value), there is a set of radio buttons with options no timestamp, time at left or time on top. Choose time at left to display data in two columns. Choose time on top to display data in two rows.
For dialog boxes that support an array of tags, the orientation of the tag array will override your row/column option selection in determining the orientation of the output data.
List Boxes
List boxes appear for the Mode field in Archive Value..., for the Type fields in Compressed Data (Number) and (Times)..., for the Mode fields in Calculated and Advanced Calculated data..., and for the Time Unit fields in Time Filtered... dialog boxes. The default retrieval mode from Archive Value... is interpolated, the default boundary type from both Compressed Data (Number) and (Times)... is inside, the default calculation mode from both Calculated and Advanced Calculated Data... is total, the default expression sampling mode from Advanced Calculated Data... is pt. compressed, and the default time unit for Time Filtered... is seconds.
Combo Boxes
Combo boxes appear for the Attribute field in Tag Attributes.... The Point Class field is automatically populated with all the available point classes for the listed PI server. Whenever a new PI server is selected in the PI Server field, the Point Class field is repopulated. Whenever a point class is selected in the Point Class field, the Attribute field is repopulated. When a valid tag is entered, its point class will be retrieved and entered into the Point Class field automatically.
Tag Search in Dialog Boxes
The <...> button next to the tagname field in the dialog boxes allows you to search the PI database for tags. Clicking the button will bring up the Tag Search dialog box. If you press OK in the Tag Search dialog box, the first tagname selected will be copied to the tagname edit field. The PI Server name is also copied to the PI Server edit field if you checked the "Copy PI Server name" box in the FactoryTalk Historian DataLink settings.
Add-in to Excel
Page 22
Time in FactoryTalk Historian DataLink
Returned Values
The timestamps returned by the FactoryTalk Historian DataLink dialog boxes are in Excel format; i.e., the number represents the number of days since 1900. For example, 10-Dec-99 7:12pm is entered into a cell as the number 36504.8.
However FactoryTalk Historian DataLink formats these timestamps into a PI time string; specifically, dd-mmm-yy hh:mm:ss. For example, 7:12 PM on December 10th, 1999 is displayed as 10-Dec-99 19:12:00.
You can change this format to another by selecting the cells and choosing Format, Cells, Number. See your Excel documentation for more information on formatting numbers as time.
User-Specified Time and Number Formatting
If you do not like the general and dd-mmm-yy hh:mm:ss formatting codes for number and time, respectively, you can specify another default number and time formatting code in FactoryTalk Historian DataLink. This is done via the PI > Settings... dialog box.
Time in FactoryTalk Historian DataLink
FactoryTalk Historian Site Edition DataLink User Guide Page 23
The number format "0.0" formats numbers to one decimal place and the time format "hh:mm:ss" timestamps to be hour:minute:seconds.
The entries for the number format and time format fields may be any valid Excel format code from Format, Cells, Number, Custom.
For example in German, the equivalent of "General" and "dd-mmm-yyyy hh:mm" are "Standard" and "TT-MM-JJJJ hh:mm" respectively.
Add-in to Excel
Page 24
Entering Timestamps into FactoryTalk Historian DataLink
Many of the dialog boxes ask for a start time and an end time. In the edit fields, type the desired PI time string, for example, 10-Dec-99 19:12. Note that for PI time in relative time format (for example, '-1d'), the reference time is different for the start time and the end time. The current wall clock is the reference time for the translation of the relative time in the start time field. However, the start time is used as the reference time for the translation of the relative time in the end time field.
If you want to use cell references, you may refer either to cells that contain a PI time in string format (e.g., '10-Dec-99 19:12) or to cells that contain an Excel time (for example, 36504.8, formatted in whatever style you wish). Remember that Excel stores time as the number of days since 1900, but displays it according to Format, Cells, Number.
For the time interval edit field, you may specify a number followed by an h or an m or an s (for hours, minutes, or seconds, respectively). For example, to indicate a time interval of thirty two minutes, type 32m into the edit field.
If you want to use cell references, you may refer only to cells that contain a valid PI time interval string. That is, you cannot refer to a cell containing an Excel time (i.e., a number). For example, to specify an interval of 32 minutes, the time interval edit field of a dialog box must refer to a cell that contains the string 32m.
Time in FactoryTalk Historian DataLink
FactoryTalk Historian Site Edition DataLink User Guide Page 25
See Start and End Time (page 93) and Time Interval (page 94) for examples of valid PI time strings.
Show Time Check Box
A show time check box appears in some of the dialog boxes, whose PI function normally returns an array of PI values. Selecting this check box returns the timestamps as well as the values. These timestamps appear at the leftmost column if the column(s) radio button is selected; and along the topmost row if the row(s) is selected. If this box is unchecked, FactoryTalk Historian DataLink does not display the timestamps.
If you reference an array of tags in either the Sampled Data or Calculated Data dialog box, FactoryTalk Historian DataLink returns one common set of timestamps for the entire group of tags.
Add-in to Excel
Page 26
Positioning Timestamp Data Returned by FactoryTalk Historian DataLink
Some dialog boxes that return a single value (for example, Current Value) provide radio buttons that control where timestamps are displayed.
Select no timestamp to suppress the timestamp.
Select time at left to return a timestamp into a cell to the left of the retrieved values.
Select time on top to display the timestamp in a cell above the retrieved values.
Note: When an array reference is specified in the Tagname field, the time at left and time on top radio buttons produce the same result. In this case, FactoryTalk Historian DataLink returns the timestamp and value depending on whether the reference of tag names is horizontal or vertical. For tag names in a single column, timestamps will appear to the left of the values. For tag names in a single row, timestamps will appear on top of the values.
Timestamp Data for a Time Interval or Range
Some dialog boxes that return a single value for each interval of time (for example, Calculated Data) provide check boxes that control which timestamps are displayed.
When a time interval is specified:
Select Start Time to display the start time of the interval.
Select End Time to display the end time of the interval.
For minimum, maximum, and range functions:
Select Min/Max Time to display timestamps for the interval's minimum and maximum values.
The timestamps are displayed according to the orientation (rowwise or columnwise) specified. For instance, if the orientation is columnwise and if all check boxes are selected, the order of the columns from left to right would be: start time, end time, the timestamp of the minimum value, the timestamp of the maximum value. If the check box for End Time is cleared, for the same example the order from left to right would be: start time, the timestamp of the minimum value, the timestamp of the maximum value.
FactoryTalk Historian DataLink Functions
FactoryTalk Historian Site Edition DataLink User Guide Page 27
FactoryTalk Historian DataLink Functions
Functions vs. Values
When a FactoryTalk Historian DataLink dialog box brings data from the PI Server to Excel, it does not put the actual value into a cell. Rather, FactoryTalk Historian DataLink pastes a custom PI function into the cell.
For example, when you call up the Current Value dialog box and enter SINUSOID into the Tagname field, FactoryTalk Historian DataLink pastes the following function into the cell:
=PICurrVal("sinusoid",0,)
Excel then evaluates this function, and displays the resulting number. Thus, the FactoryTalk Historian DataLink dialog boxes are a front end to construct the corresponding FactoryTalk Historian DataLink functions, and to format the output.
These FactoryTalk Historian DataLink functions can also be entered manually into the cells in a worksheet. The arguments to the function are described further in Details for FactoryTalk Historian DataLink Functions and Dialog Boxes (page 30). Since most of the FactoryTalk Historian DataLink functions return more than one data element, the functions should be entered into Excel as array functions. Please see the Entering PI Functions Directly into Excel section below for a more detailed explanation of how array functions are used.
These FactoryTalk Historian DataLink functions can only be used in cells of a worksheet. They cannot be called within a procedure in Excel Visual Basic. Visual Basic does not recognize FactoryTalk Historian DataLink functions. The only way to invoke the FactoryTalk Historian DataLink functions in VBA is to formulate the function as a text string and then set the formula Array property of a range of cells to this text string. This is the same as manually entering the PI functions into that range of cells. The VBA code can then check the cell values for the PI function results. For an example of entering PI functions into the spreadsheet using VBA, see the putval_code module in the piexam32.xls distributed with FactoryTalk Historian DataLink.
The FactoryTalk Historian DataLink output function PIPutVal() is an Excel Macro function and cannot be used directly in the cells of a worksheet. PIPutVal() can only be used in an Excel 4.0 macro sheet or run as a macro in VBA. In VBA, use the application.run method to invoke macro functions. Please refer to the putval_code module in the piexam32.xls for an example of invoking the macro function in VBA.
Error Reporting
FactoryTalk Historian DataLink is written in C++ and Visual Basic and utilizes both the FactoryTalk Historian System's SDK and Microsoft Excel's API. When an error occurs at the
Add-in to Excel
Page 28
PI SDK level, FactoryTalk Historian DataLink displays the PI SDK error in the cell. For example, if you try to find the current value for a tag which does not exist, the message "PIPoint not found" appears in the output cell.
Refreshing PI Data in a Spreadsheet
There are two ways to refresh the data on a spreadsheet. One way is to right click on any part of the array and select the Recalculate (Resize) function. This method works best if you have a variable size array where the number of values returned could be different depending on what range of values retrieved. If there are fewer values, there is no problem. However, if more values are retrieved, those values will not show unless the Recalculate function is selected.
The second way is to make a change to the arguments passed to the FactoryTalk Historian DataLink functions. Because FactoryTalk Historian DataLink retrieves data from the PI Server via functions, values on the spreadsheet update only when a function argument changes. Pressing F9 in Excel does not force FactoryTalk Historian DataLink functions to get new data from the PI server. The only exception is the Current value function, which updates whenever Excel recalculates. This was intentionally done because most of the other DataLink functions do not represent chronically changing data. However, to bypass this, Ctrl+Alt+Shift+F9 forces all DataLink functions to recalculate.
The best way to create a spreadsheet that updates with minimal user interaction is to use some Excel dynamic time functions like now() or today() to build a time stamp, e.g. use (today()+1/3) for 8am today. Then refer to this cell in the start time or end time argument of the DataLink query. Whenever Excel recalculates (due to the user pressing F9 or changing any cells in the spreadsheet), the dynamic time functions will be updated by Excel, causing the FactoryTalk Historian DataLink function to run. Note that the value of the time stamp does not have to change in order for Excel to trigger the FactoryTalk Historian DataLink function. As long as an Excel dynamic time function is used to construct the time stamp and this time stamp is used in the DataLink argument, Excel will trigger the DataLink function when the spreadsheet recalculates.
Changing Arguments using Dialog Boxes
If an argument needs to be changed, right click on any part of the array and select the FactoryTalk Historian DataLink function. A dialog box will appear with all the edit fields filled in with the arguments that were previously specified for that array. Any of the edit fields can be changed and the new array will reflect those changes.
If the output edit field is changed, there are two different behaviors depending on what new cell is referenced. If the newly referenced cell is part of the original array, then the entire array gets moved with the upper-leftmost cell of the array at the newly referenced cell. If the newly referenced cell is not part of the original array, then the array is pasted with the upper-leftmost cell of the array at the newly referenced cell.
FactoryTalk Historian DataLink Functions
FactoryTalk Historian Site Edition DataLink User Guide Page 29
Selecting an Entire DataLink Function
If a large FactoryTalk Historian DataLink function array needs to be copied, moved or deleted, the easiest way is to right click on any part of the array and select Select DataLink Formula. Then perform the desired operation. The entire Excel function array must be moved or deleted, or an error "You cannot change part of an array" appears.
Entering PI Functions Directly into Excel
Array Values
All of FactoryTalk Historian DataLink functions except PIPutVal() return array values. This being the case, you must first select the appropriate array output range. Next, enter the PI function and its arguments into Excel's formula bar. Finally, place the PI function into the cells with the CTRL+SHIFT+ENTER combination of keystrokes. Refer to the online help for Microsoft Excel for more information on array functions. Also, note that Excel function wizard will only insert function into one cell on the spreadsheet. Therefore, it may not be appropriate to use the function wizard to enter PI functions into Excel.
Outcode
The outcode argument is an integer that controls whether or not the timestamps are returned and whether the output cells are row or column oriented.
For example, an outcode of 0 in PICurrVal() results in the snapshot value in the single cell. An outcode of 1 places the snapshot time in column one and the snapshot value in column two of a 1 x 2 array. An outcode of 2 places the snapshot time in row one and the snapshot value in row two of a 2 x 1 array. Refer to the detail description for each individual PI function for the meaning of its outcode. In general, if you specify an array output range that is greater than the number of values returned from the function, the extra cells are displayed as empty cells even though they have an embedded formula.
String Arguments
For string arguments to functions, you need to surround the arguments with double quotes. For example, select a 1 x 2 output array and enter:
=PICurrVal("sinusoid", 1, "casaba")
to retrieve the snapshot time and value for the tag sinusoid from the PI Server "casaba."
Add-in to Excel
Page 30
Using Cell Reference in Arguments
You can use cell references for all the arguments in all of FactoryTalk Historian DataLink functions. For example, the following function:
=PICurrVal(A1, A2, A3)
gives the same result as the example above if the three arguments are stored in cell A1, A2, and A3 respectively.
PIServer Argument
The PIServer argument is optional. The default PIServer can be changed in the Connections dialog box. If you want to use the default server, you can omit the PIServer argument. For example, to retrieve the current value for the tag sinusoid from the default PI Server, enter:
=PICurrVal("sinusoid",0,)
into a 1x1 output range .
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
The following sections describe each of the FactoryTalk Historian DataLink functions in detail. Each section describes the dialog box first and then discusses each of the arguments for the corresponding custom PI function or functions.
Current Value Dialog Box
This dialog box gets the current Snapshot value of a PI tag.
Required Field
Tagname. The reference to Tagname may be an array.
Special Notes
This function updates whenever Excel calculates or recalculates any cell in the spreadsheet. To force an immediate recalculation, press the F9 key.
PICurrVal()
PICurrVal(tagname, outcode, PIServer)
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 31
Arguments
Argument Explanation
Tagname (string) The tag for which you want the snapshot (current) value.
outcode (integer) An output code; either 0, 1, or 2.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Current value
1 Timestamps Current value
An output code of 2 transposes the output array that results from an output code of 1.
Example
The following retrieves the current value and the corresponding timestamp for the tag let439 from the PI Server "holden:"
=PICurrVal("let439",1,"holden")
Archive Value Dialog Box
This dialog box gets a value at a specified time. There are five modes to select from:
Previous - Retrieves the value in the archive at or before the specified timestamp
Previous only - Retrieves the value in the archive only before the specified timestamp
Interpolated - Interpolates the value at the specified timestamp except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the previous value is simply carried forward.
Auto - Same as interpolated except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the value at or before the specified timestamp is returned
Next - Retrieves the value in the archive at or after the specified timestamp
Next Only - Retrieves the value in the archive only after the specified timestamp
Exact Time - Retrieves the value in the archive for a specified time if an entry exists at that time. If no value exists, the message "No events found" is returned
Add-in to Excel
Page 32
Required Fields
Tagname or Expression
Timestamp
Related Topics
PIArcVal() (page 32)
PIExpVal() (page 33)
PIArcVal()
PIArcVal(tagname, timestamp, outcode, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you want the archive value.
time stamp (string) The PI timestamp.
outcode (integer) An output code; either 0, 1, or 2.
PIServer (string) The PI Server.
mode (string) The retrieval mode.
Returns
Outcode Column 1 Column 2
0 Archive value
1 Timestamp Archive value
An output code of 2 transposes the output array that results from an output code of 1.
Example
The following retrieves the interpolated value for the tag cdep158 at 7:20pm on December 11, 1992 from the PI Server "casaba:"
=PIArcVal("cdep158","11-dec-92 19:20",0, "casaba","interpolated")
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 33
PIExpVal()
PIExpVal(expression, timestamp, PIServer)
Arguments
Argument Explanation
expression (string) The expression for which you want the archive value.
time stamp (string) The PI timestamp.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Archive value
1 Timestamp Archive value
An output code of 2 transposes the output array that results from an output code of 1.
Example
The following calculates the square root of the value of the tag sinusoid from the PI Server named THEVAX at midnight yesterday:
=PIExpVal("sqr('sinusoid')","y",0,"thevax")
Tag Attributes Dialog Box
This dialog box retrieves a point attribute for a given tag.
Required Fields
Tagname
Tag attribute
For PI3, the list of tag attributes depends on the point class selected. For a complete list of tag attributes, refer to the attributes listed in the combo box or to the description of attributes for each point class in the PI Server User Manuals, available from the FactoryTalk Historian SE installation CD under Redist > Docs.
Add-in to Excel
Page 34
For PI 2, choose a tag attribute from the combo box. The default attribute is descriptor. Tag attributes are:
Attribute Explanation
Descriptor 26-character tag descriptor
Exdesc 80-character extended tag descriptor
typicalvalue Typical value
Units Engineering unit string
Zero Zero
Span Span
digstartcode Code for the first digital state string for the tag
dignumber Number of digital states minus 1
pointtype Point type character
pointsource Point source character
location1 Location parameter 1
location2 Location parameter 2
location3 Location parameter 3
location4 Location parameter 4
location5 Location parameter 5
filtercode Filter code
squareroot Square root flag
scan Scan flag
excdev Exception deviation in percent of span
excmin Exception minimum time in seconds
excmax Exception maximum time in seconds
archiving Archiving flag
compressing Compression flag
Res Resolution code
compdev Compression deviation in percent of span
compmin Compression minimum time in seconds
compmax Compression maximum time in seconds
totalcode Totalization code
convers Conversion factor for postprocessed points
displaydigits Controls the format of numeric values on terminal-based PI screens
instrumenttag Tagname for value in another system; used by some interfaces
sourcept Tagname for output to other systems; used by some interfaces
taglong Long tagname (up to 80 characters)
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 35
Attribute Explanation
tagshort 12 character tagname
creator Creator of the tag
createdate Creation date of the tag
changer User who modified the tag's attributes
changedate Change date of the tag
pointnumber ID number reused upon deletion of a point
pointid Unique internal ID number not reused upon deletion of a point
PITagAtt() PITagAtt(tagname, attribute, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want an attribute.
attribute (string) The tag attribute, see the list under Tag Attributes Dialog Box (page 33).
PIServer (string) The PI Server.
Returns
Tag attribute
Example
The following retrieves from the default PI Server the engineering units for the tag located in cell D1:
=PITagAtt(d1,"units",)
Compressed Data (Start Time/Number) Dialog Box
This dialog box returns compressed values from the PI Server based on a start time and a specified number of data points. If a filter expression is not specified, the PINCompDat() function is called. Otherwise, the PINCompFilDat() function is called.
Required Fields
Tagname
Start Time
Add-in to Excel
Page 36
Number of data points
Filter Expression
If a filter expression is specified, the specified number of compressed values are retrieved from the PI Server while a given filter expression is true. If the mark as filtered option is selected, a "Filtered" status is returned for each group of values that does not satisfy the filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
Boundary Type
There are 4 boundary types:
Inside (default) - Returns specified number of data points from starttime including value at starttime if a value exists
Outside - Returns specified number of data points from starttime including a data point at or prior to starttime
Interpolated - Returns specified number of data points from starttime including a data point interpolated at starttime
Auto - Same as interpolated except if resolution code 4 tags on PI 2 Server or step attribute is set on PI 3 Server, behavior follows that of "inside"
Check Boxes
Select backwards in time if you want to gather data from the archive going backwards from the time that was entered in Start time.
Select show bits if you want to show the extended status bits associated with the returned events.
Select show annotations if you want to show the annotations associated with the returned events.
Special Notes
This dialog box returns empty strings when there is a smaller number of values than the number which you specified. For example, if you wish to retrieve 400 values starting from midnight today and there are only 356 values (including filtered events), the final 44 cells have blank strings in them.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 37
If you enter the filter expression into a cell on the worksheet and refer to it in the dialog box, be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. Since tag names in filter expression are enclosed with single quotes, if the filter expression begins with a tagname, you must begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet.
Related Topics
Filter Expressions (page 90)
PINCompDat() (page 37)
PINCompFilDat() (page 38)
PINCompDat() PINCompDat(tagname, stime, numvals, outcode, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you want compressed data.
stime (string) The start time in PI time format.
numvals (integer) The number of compressed data points. Use a negative number to gather data from the archive that goes backwards from the stime.
outcode (integer) An output code. See Outcodes for more information on outcodes.
PIServer (string) The PI Server.
mode (string) The boundary type.
Returns
Outcodes
Example
The following retrieves 10 compressed data points and corresponding time stamps for the tag cdf144 starting from 1:00 a.m. this morning from the default PI Server with inside as boundary type:
=PINCompDat("cdf144","1:00",10,1,,"inside")
Add-in to Excel
Page 38
PINCompFilDat() PINCompFilDat(tagname, stime, numvals, filtexp, filtcode, outcode, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you want compressed data.
stime (string) The start time in PI time format.
numvals (integer) The number of compressed data points. Use a negative number to gather data from the archive that goes backwards from the stime.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
filtcode (integer) A filter code; use 1 to return Filtered status, 0 to skip.
outcode (integer) An output code. See Outcodes for more information on outcodes.
PIServer (string) The PI Server.
mode (string) The boundary type.
Returns
Refer to Outcodes.
Example
The following retrieves 10 compressed data points and the corresponding times, starting at 2:00 a.m., for the tag cdf144 while the tag cdep158 is greater than 38:
=PINCompFilDat("cdf144","2:00",10,"'cdep158'>38",1,1,,)
The status Filtered is displayed for times when the filter condition is false. Data are retrieved from the default PI Server with inside as boundary type.
Compressed Data (Start Time/End Time) Dialog Box
This dialog box returns compressed values from the PI Server based on a start time and an end time. The number of data points retrieved for the given time period is returned in the first cell. If a filter expression is not specified, the PICompDat() function is called. Otherwise, the PICompFilDat() function is called.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 39
Required Fields
Tagname
Start Time
End Time
Filter Expression
If a filter expression is specified, the specified range of compressed values are retrieved from the PI Server while a given filter expression is true. If the mark as filtered option is selected, a "Filtered" status is returned for each group of values that does not satisfy the filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
Boundary Type
There are 4 boundary types:
Inside (default) - Returns data points at and between starttime and endtime
Outside - Returns data points between starttime and endtime including a data point at or prior to starttime and a data point at or after endtime
Interpolated - Returns data points between starttime and endtime including a data point interpolated at starttime and a data point interpolated at endtime
Auto - Same as interpolated except if resolution code 4 tags on PI 2 Server or step attribute is set on PI 3 Server, behavior follows that of "inside"
Check Boxes
Select hide count if you do not want to display the amount of data events retrieved from the archive.
Select show bits if you want to show the extended status bits associated with the returned events.
Select show annotations if you want to show the annotations associated with the returned events.
Add-in to Excel
Page 40
Special Notes
This dialog box returns blank strings in the unused output cells when there is a smaller number of values in the archive than the output array originally specified. This situation may occur if you use relative time references. For example, if you retrieve values starting from y to y+5h, the number of values in the PI Server may be different when you call up the spreadsheet on different days.
If you enter the filter expression into a cell on the worksheet and refer to it in the dialog box, be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. Since tag names in filter expression are enclosed with single quotes, if the filter expression begins with a tagname, you must begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet.
Related Topics
Filter Expressions (page 90)
PICompDat() (page 40)
PICompFilDat() (page 41)
PICompDat() PICompDat(tagname, stime, etime, outcode, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you want compressed data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
outcode (integer) An output code. See Outcodes for more information on outcodes.
PIServer (string) The PI Server.
mode (string) The boundary type.
Returns
Refer to Outcodes.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 41
Example
The following retrieves compressed data points and corresponding time stamps for the tag cdf144 starting from 1:00 a.m. to 3:00 a.m. this morning from the default PI Server with inside as boundary type:
=PICompDat("cdf144","1:00","3:00",1,,"inside")
PICompFilDat() PICompFilDat(tagname, stime, etime, filtexp, filtcode, outcode, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you want compressed data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
filtcode (integer) A filter code; use 1 to return Filtered status, 0 to skip.
outcode (integer) An output code. See Outcodes for more information on outcodes.
PIServer (string) The PI Server.
mode (string) The boundary type.
Returns
Refer to Outcodes.
Example
The following retrieves compressed data points and the corresponding times, starting from 2:00 a.m. and ending at 10:00 a.m., for the tag cdf144 when the tag cdep158 is greater than 38:
=PICompFilDat("cdf144","2:00","10:00","'cdep158'>38",1,1,,)
The status Filtered is displayed for times when the filter condition is false. Data are retrieved from the default PI Server with inside as boundary type.
Add-in to Excel
Page 42
Sampled Data Dialog Box
This dialog box gathers evenly spaced, sampled values from the archive. If a filter expression is not specified, the PISampDat() function is called. Otherwise, the PISampFilDat() function is called.
Required Fields
Tagname
Start Time
End Time
Time Interval
Filter Expression
If a filter expression is specified, the specified range of compressed values are retrieved from the PI Server while a given filter expression is true. If the mark as filtered option is selected, a "Filtered" status is returned for each continuous set (block) of sampled values that do not satisfy the filter expression if the tag is on a PI 3 Server. If the tag is from a PI 2 Server, a "Filtered" status is returned for each sampled value that does not satisfy the filter expression. See Fi (page 90)lter Expressions for more information on the filter expression syntax.
Special Notes
If you can enter the filter expression into a cell on the worksheet and refer to it in the dialog box, be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. Since tagname in filter expression should be enclosed with single quotes, if the filter expression begins with a tagname, you need to begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet.
Related Topics
Filter Expressions (page 90)
PISampDat() (page 43)
PISampFilDat() (page 43)
PIExpDat() (page 44)
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 43
PISampDat() PISampDat(tagname, stime, etime, interval, outcode, PIServer)
Arguments
Argument Explanation
tagname(string) The tag for which you want sampled data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
outcode (integer) An output code; either 0, 1, 2, or 3.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Sampled data
1 Timestamps Sampled data
An output code of 2 transposes the output array that results from an output code of 0 while an output code of 3 transposes the output array that results from an output code of 1.
Example
The following retrieves sampled data for the tag located in cell B1, from midnight yesterday to midnight today at 3-hour intervals:
=PISampDat(b1,"y","t","3h",1,)
Timestamps are also returned.
PISampFilDat() PISampFilDat(tagname, stime, etime, interval, filtexp, filtcode, outcode, PI Server)
Arguments
Argument Explanation
tagname(string) The tag for which you want sampled data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
Add-in to Excel
Page 44
Argument Explanation
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
filtcode (integer) A filter code; use 1 to return Filtered status, 0 to skip.
outcode (integer) An output code; either 0, 1, 2, or 3.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Sampled data
1 Timestamps Sampled data
An output code of 2 transposes the output array that results from an output code of 0 and an output code of 3 transposes the output array that results from an output code of 1.
Example
The following formula retrieves sampled data for SINUSOID at 11-Jan-97, 11-Jan-97 1:00AM, 11-Jan-97 2:00AM, and 11-Jan-97 3:00AM:
=PISampFilDat("sinusoid","11-Jan-97","+3h","1h",A1,1,1,)
Timestamps are shown in column1 and values in column2. A "Filtered" status is returned for values do not satisfy the filter condition in cell A1.
PIExpDat() PIExpDat(expression, stime, etime, interval, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The calculation expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
outcode (integer) An output code; either 0, 1, 2, or 3.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Calculated data
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 45
Outcode Column 1 Column 2
1 Timestamps Calculated data
An output code of 2 transposes the output array that results from an output code of 0 while an output code of 3 transposes the output array that results from an output code of 1.
Example
The following calculates the square root of the value of the tag sinusoid from the PI Server named THEVAX at one-hour intervals, starting from midnight yesterday to midnight today:
=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax")
It also displays the timestamps.
Timed Data Dialog Box
This dialog box returns sampled values for a single tag that are synchronized with an array of timestamps. There are two modes to select from:
Interpolated - Interpolates values at the specified timestamps except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the previous value is simply carried forward
Exact Time - Retrieves the value in the archive for a specified time if an entry exists at that time. If no value exists, the message "No events found" is returned.
Required Fields
Tagname
Timestamp. The timestamp field has to be a reference to a time array. For PI 2, the timestamps in this time array must be either monotonically increasing or monotonically decreasing.
Related Topics
PITimeDat() (page 46)
PITimeExpDat() (page 46)
Add-in to Excel
Page 46
PITimeDat()
PITimeDat(tagname, timestamps, PIServer, mode)
Arguments
Argument Explanation
tagname (string) The tag for which you the sampled data.
timestamps (reference) A reference to an array of times in PI format. For PI 2, the values in this array must be either monotonically increasing or monotonically decreasing.
PIServer (string) The PI Server.
mode (string) The retrieval mode.
Returns
Sampled data. If the timestamps are in a single column, the data are returned along a single column. If the timestamps are in a single row, the data are returned along a single row.
Example
The following retrieves interpolated timed data for the times located in cells B1 through B12 for the tag mytag from the default PI Server:
=PITimeDat("mytag",b1:b12,,"interpolated")
PITimeExpDat() PITimeExpDat(expression, timestamps, PIServer)
Arguments
Argument Explanation
expression (string) The calculation expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
timestamps (reference) A reference to an array of times in PI format. For PI 2, the values in this array must be either monotonically increasing or monotonically decreasing.
PIServer (string) The PI Server
Returns
Sampled data. If the timestamps are in a single column, the data are returned along a single column. If the timestamps are in a single row, the data are returned along a single row.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 47
Example
The following calculates the square root of the value of the tag sinusoid for the times located in cells B1 through B12 from the default PI Server:
=PITimeExpDat("sqr('sinusoid')",b1:b12,)
Calculated Data Dialog Box
This dialog box returns a single calculated value or evenly spaced calculated values from the PI Data Archive. Calculation modes are:
Total
Minimum
Maximum
Standard deviation
Range
Average
Count
Mean
All Calculation modes are time-weighted except for the mean function, which is event-weighted.
Required Fields
Tagname
Start Time
End Time
Conversion Factor
Calculation Mode
Interval
To retrieve a single calculated value, do not specify an interval and the PICalcVal() function is used. To retrieve evenly spaced calculated data, the specified interval determines the spacing of the calculation and the PICalcDat() function is used.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 49
Check Box
Check show pctgood if you want FactoryTalk Historian DataLink to display the percentage of the time range that contains good value. We recommend that you always look at the percent good value before using the calculation result. The percent good value is normally returned to the right of calculated value cell. If the rows checkbox is selected, the percent good value is returned at the cell below the calculated value cell.
Timestamp(s) are returned when the calculation mode is minimum, maximum, or range.
Mode Column 1 Column 2 Column 3
Minimum Time of min. value Minimum value
Maximum Time of max. value Maximum value
Range Time of min. value Time of max. value Range value
Special Notes
When an interval is not specified and the mode is Total, Standard Deviation, Average, Count or Mean, the timestamps are not displayed even if the Show Timestamps check box is selected.
When an interval is specified and the mode is Max or Min, the timestamps displayed are the start time of each calculation interval.
When the calculation is a time-weighted Total and part of the archived data within the range are bad, the reported value is equal to the calculated total value divided by the fraction of the time period with good archived data. This data normalization is equivalent to the assumption that for the bad data time range, the tag value takes on the average value of the entire range. However, this assumption may not be valid when a large fraction of the time range contains bad data. Therefore, we recommend that you always look at the percent good value before using the calculation result.
The conversion factor is most often used when the calculation mode is Total and time unit of the PI tag being totalized is not the same as the server default. In all the PI 3 Servers and in most of the PI 2 Servers, the totalization default is "units per day." On the PI 2 Server, the totalization default time (totdefaulttime is the time unit in seconds) can be found in the file pilink:piparams.for.
Add-in to Excel
Page 50
The following table displays the conversion factors for two of the common PI 2 Server default time units vs. various flow tag units.
Flow tag unit Server default is units/day (totdefaulttime = 86400)
Server default is units/hour (totdefaulttime = 3600)
Units/day 1.0 0.041667
Units/hour 24 1
Units/minute 1440 60
Units/second 86400 3600
Related Topics
PICalcVal() (page 50)
PICalcDat() (page 52)
PICalcVal() PICalcVal(tagname, stime, etime, mode, cfactor, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
If the outcode is 0, only the calculated value is returned.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 51
If the outcode is 1, the following applies:
Mode Column 1 Column 2 Column 3
Total Total value
Minimum Time of min. Value Minimum value
Maximum Time of max. Value Maximum value
Stdev Stdev. Value
Range Time of min. Value Time of max. value Range value
Average Average value
Count Count value
Mean Mean value
An output code of 2 transposes the output array that results from an output code of 1, i.e., results are returned in rows instead of in columns.
Outcode of 3 is not used.
If the outcode is 4, the percent good is returned to the right of the value cell.
If the outcode is 5, the following applies:
Mode Column 1 Column 2 Column 3 Column 4
Total Total value Percent good
Minimum Time of min. value Minimum value Percent good
Maximum Time of max. value Maximum value Percent good
Stdev Stdev. value Percent good
Range Time of min. value Time of max. value Range value Percent good
Average Average value Percent good
Count Count value Percent good
Mean Mean value Percent good
An output code of 6 transposes the output array that results from an output code of 4, i.e., results are returned in rows instead of in columns.
An output code of 7 transposes the output array that results from an output code of 5, i.e., results are returned in rows instead of in columns.
Add-in to Excel
Page 52
Example
The following calculates a time-weighted total for the tag cdf144 from yesterday to today from the default PI Server:
=PICalcVal("cdf144","y","t","total",1440,4,)
The result is multiplied by 1440. The percent good is returned next to the total.
PICalcDat() PICalcDat(tagname, stime, etime, interval, mode, cfactor, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47).
outcode (integer) An output code; 0-7.
PIServer (string) The PI Server.
Returns
The outcode affects the output as follows:
0 Calculated values along a column
1 Timestamps and values along 2 columns
2 Calculated values along a row
3 Timestamps and values along 2 rows
4 Values and pctgood along 2 columns
5 Timestamps, values, and pctgood along 3 columns
6 Values and pctgood along 2 rows
7 Timestamps, values, and pctgood along 3 rows
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 53
Example
The following retrieves totals for the tag located in cell B1, from midnight yesterday to midnight today at 3-hour intervals from the default PI Server specified in the PILogin.ini file:
=PICalcDat(b1,"y","t","3h","total",24,1,)
Timestamps are also returned. The values are multiplied by 24 before they are displayed in the spreadsheet.
Advanced Calculated Data Dialog Box
This dialog box returns a single calculated value or evenly spaced calculated values from the PI Data Archive. Calculation modes are:
Total
Minimum
Maximum
Standard deviation
Range
Average
Count
Required Fields
Tagname or Expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
Start Time
End Time
Conversion Factor
Calculation Mode
Filter Expression
If a filter expression is specified, the requested summaries on the source point are calculated for the time ranges where the expression evaluates to true. See Filter Expressions (page 90) for more information on the filter expression syntax.
Add-in to Excel
Page 54
Interval
To retrieve a single calculated value, do not specify an interval. To retrieve evenly spaced calculated data, the specified interval determines the spacing of the calculation.
Expression Sampling Mode
There are 3 expression sampling modes for sampling the filter expression:
Pt. Compressed (default) - Evaluates the filter expression at the timestamp of any compressed value of the source point
Exp. Compressed - Evaluates the filter expression at the timestamp of any compressed values of any tags in the filter expression
Interpolated - Evaluates the filter expression at evenly spaced sampling intervals
There are 2 expression sampling modes for sampling the expression to be summarized:
Compressed (default) - Evaluates the expression at the timestamp of any compressed values of any tags in the expression
Interpolated - Evaluates the expression at evenly spaced sampling intervals
Expression Sampling Interval
If Expression Sampling Mode is specified as interpolated, the specified expression sampling interval determines the spacing at which the expression is evaluated. If the Expression Sampling Mode is not interpolated, then the expression sampling interval is ignored.
Calculation Basis
There are 2 types of calculation basis:
Time-Weighted (default) - Weights the values in the calculation by the time over which they apply.
Event-Weighted - Weights each event with the same weight. There must be at least one event within the time range to perform a successful calculation. For standard deviation, two events are required.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 55
Minimum Percent Good
The minimum percent good is the minimum percentage of good data over the time range at which data will be returned instead of an error "Insufficient good data."
Check Box
Refer to the Check Box description under Calculated Data Dialog Box (page 47).
Special Notes
Refer to the Special Notes section under Calculated Data Dialog Box (page 47).
Related Topics
Filter Expressions (page 90)
PIAdvCalcVal() (page 56)
PIAdvCalcFilVal() (page 57)
PIAdvCalcExpVal() (page 58)
PIAdvCalcExpFilVal() (page 59)
PIAdvCalcDat() (page 60)
PIAdvCalcFilDat() (page 60)
PIAdvCalcExpDat() (page 62)
PIAdvCalcExpFilDat() (page 63)
Add-in to Excel
Page 56
PIAdvCalcVal() PIAdvCalcVal(tagname, stime, etime, mode, calcbasis, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
minpctgood (number) Minimum percentage of good data over time range
Cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcVal() (page 50) function.
Example
The following calculates a time-weighted total for the tag cdf144 from yesterday to today from the default PI Server:
=PIAdvCalcVal("cdf144","y","t","total",0,50,1,4,)
The result is multiplied by 1. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 57
PIAdvCalcFilVal() PIAdvCalcFilVal(tagname, stime, etime, filtexp, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
sampmode (string) The sampling mode (pt. compressed, exp. compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
Cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcVal() (page 50) function.
Example
The following calculates a time-weighted total for the tag cdf144 from yesterday to today during the time periods when tag cdm158 is in Manual from the default PI Server:
=PIAdvCalcFilVal("cdf144","y","t","'cdm158'=""Manual""","total",0,"pt. compressed","10m",50,1,4,)
The result is multiplied by 1. Since pt.compressed is the specified sampling mode, the sampling interval is ignored and the filter expression will be sampled at the compressed
Add-in to Excel
Page 58
events of cdf144. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
PIAdvCalcExpVal() PIAdvCalcExpVal(expression, stime, etime, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The expression for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
sampmode (string) The sampling mode (compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcVal() (page 50) function.
Example
The following calculates a time-weighted total for the expression 'cdf144'+' cdt158' from yesterday to today from the default PI Server:
=PIAdvCalcExpVal("'cdf144'+'cdt158'","y","t","total",0,"compressed","10m",0,1,4,)
The result is multiplied by 1. Since compressed is the specified sampling mode, the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 59
PIAdvCalcExpFilVal() PIAdvCalcExpFilVal(expression, stime, etime, filtexp, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The expression for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
sampmode (string) The sampling mode (compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcVal() (page 50) function.
Example
The following calculates a time-weighted total for the expression 'cdf144'+' cdt158' when 'productid' = "Product2" from yesterday to today from the default PI Server:
=PIAdvCalcExpFilVal("'cdf144'+'cdt158'","y","t","'productid'="Product2"", "total",0,"compressed","10m",0,1,4,)
The result is multiplied by 1. Since compressed is the specified sampling mode, the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
Add-in to Excel
Page 60
PIAdvCalcDat() PIAdvCalcDat(tagname, stime, etime, interval, mode, calcbasis, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
minpctgood (number) Minimum percentage of good data over time range .
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47) .
outcode (integer) An output code; 0-7.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcDat() (page 52) function.
Example
The following retrieves totals for the tag cdf144, from midnight yesterday to midnight today at 3-hour intervals from the default PI Server:
=PIAdvCalcDat("cdf144","y","t","3h","total",0,50,1,4,)
The result is multiplied by 1. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
PIAdvCalcFilDat() PIAdvCalcFilDat(tagname, stime, etime, interval, filtexp, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 61
Arguments
Argument Explanation
tagname (string) The tag for which you want the calculated data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
sampmode (string) The sampling mode (pt. compressed, exp. compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47).
outcode (integer) An output code; 0-7.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcDat() (page 52) function.
Example
The following retrieves totals for the tag cdf144, from midnight yesterday to midnight today at 3-hour intervals during the time periods when tag cdf144 is in Manual from the default PI Server:
=PIAdvCalcFilDat("cdf144","y","t","3h","'cdm158'=""Manual""","total",0,"pt. compressed","10m",50,1,4,)
The result is multiplied by 1. Since pt.compressed is the specified sampling mode, the sampling interval is ignored and the filter expression will be sampled at the compressed events of cdf144. The percent good is returned next to the total.
Add-in to Excel
Page 62
PIAdvCalcExpDat() PIAdvCalcExpDat(expression, stime, etime, interval, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The expression for which you want the calculated data.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. 0 for time-weighted; 1 for event-weighted.
sampmode (string) The sampling mode (compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47).
outcode (integer) An output code; 0-7.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcDat() (page 52) function.
Example
The following retrieves totals for the expression 'cdf144'+'cdt158', from midnight yesterday to midnight today at 3-hour intervals from the default PI Server:
=PIAdvCalcExpDat("'cdf144'+'cdt158'","y","t","3h","total",0,"compressed", "10m",50,1,4,)
The result is multiplied by 1. Since compressed is the specified sampling mode, the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 63
PIAdvCalcExpFilDat() PIAdvCalcExpFilDat(expression, stime, etime, interval, filtexp, mode, calcbasis, sampmode, sampinterval, minpctgood, cfactor, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The expression for which you want the calculated value.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
filtexp (string) The filter expression. See Filter Expressions (page 90) for more information on the filter expression syntax.
mode (string) The calculation mode (total, minimum, maximum, stdev, range, average, count or mean).
calcbasis (integer) The calculation basis. (time-weighted or event-weighted).
sampmode (string) The sampling mode (compressed or interpolated).
sampinterval (string) The sampling interval in PI time format.
minpctgood (number) Minimum percentage of good data over time range.
cfactor (number) A multiplicative conversion factor. Should be 1 for max, min, avg, count, mean, std and range. For more discussion of the conversion factor, see Special Notes (page 47) under Calculated Data Dialog Box (page 47).
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
Refer to Returns section for PICalcDat() (page 52) function.
Example
The following calculates a time-weighted total for the expression 'cdf144'+' cdt158' when 'productid' = "Product2" at 3-hour intervals from yesterday to today from the default PI Server:
=PIAdvCalcExpFilDat("'cdf144'+'cdt158'","y","t","3h","'productid'="Product2"","total",time-weighted,"compressed","10m",0,1,4,)
The result is multiplied by 1. Since compressed is the specified sampling mode, the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. The percent good is returned next to the total.
Add-in to Excel
Page 64
Time Filtered Dialog Box
This dialog box returns the amount of time for which a given expression is true over a specified time range. The user can specify multiple time ranges as evenly space intervals as in the Calculated Data dialog box.
Required Fields
Expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
Start Time
End Time
Time units (default to seconds)
Special Notes
If you can enter the expression into a cell on the worksheet and refer to it in the dialog box, begin the expression with a single quote so that Excel will interpret the expression as a string. Since a tagname in a filter expression should be enclosed with single quotes, begin the expression with two single quotes when the expression is stored in a cell on the worksheet if the expression begins with a tagname.
Related Topics
Calculation Expressions (page 87)
PITimeFilterVal() (page 65)
PITimeFilter() (page 66)
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 65
PITimeFilterVal() PITimeFilterVal(expression, stime, etime, timeunit, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The calculation expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
timeunit (string) Unit of time for the result to be displayed. Valid entries are: seconds, minutes, hours and days .
outcode (integer) An output code; 0-7 except 3.
PIServer (string) The PI Server.
Returns
If the outcode is 0, 1, or 2 only the calculated value is returned.
Outcode of 3 is not used.
If the outcode is 4 or 5, the percent good is returned to the right of the value cell.
If the outcode is 6 or 7, the percent good is returned below the value cell.
Example
The following calculates the amount of time that the expression from cell $A$1 is true from the PI Server named THEVAX, starting from midnight yesterday to midnight today:
=PITimeFilterVal($A$1,"y","t","seconds",1,"thevax")
The calculation result is expressed in seconds.
Add-in to Excel
Page 66
PITimeFilter() PITimeFilter(expression, stime, etime, interval, timeunit, outcode, PIServer)
Arguments
Argument Explanation
expression (string) The calculation expression. See Calculation Expressions (page 87) for more information on calculation expression syntax.
stime (string) The start time in PI time format.
etime (string) The end time in PI time format.
interval (string) The time interval in PI time format.
timeunit (string) Unit of time for the result to be displayed. Valid entries are: seconds, minutes, hours and days.
outcode (integer) An output code; 0-7.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Calculated data
1 Timestamps Calculated data
An output code of 2 transposes the output array that results from an output code of 0 and an output code of 3 transposes the output array that results from an output code of 1.
Example
The following calculates the amount of time that the expression from cell $A$1 is true from the PI Server named THEVAX at one-hour intervals, starting from midnight yesterday to midnight today:
=PITimeFilter($A$1,"y","t","1h","seconds",1,"thevax")
It also displays the timestamps for the start time of each calculation interval. The calculation result is expressed in seconds.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 67
Point ID to Tag Dialog Box
This dialog box returns the tagname from the specified point ID.
Required Fields
Point ID
Related Topics
PIPointIDToTag() (page 67)
PIPointIDToTag() PIPointIDToTag(pointid, PIServer)
Arguments
Argument Explanation
pointid (string) Unique internal ID number not reused upon deletion of a point.
PIServer (string) The PI Server.
Returns
Tagname
Example
The following returns the tagname of the tag with point ID of 123 from server named THEVAX.
=PIPointIDToTag("123","thevax")
Attribute Mask to Tag Dialog Box
This dialog box returns a list of tags which match the tag attribute masks specified.
Add-in to Excel
Page 68
Required Fields
Tagname
Descriptor
Point Source
Point Type
Point Class
Engineering Units
Related Topics
PIAttributeMaskToTag () (page 68)
PIAttributeMaskToTag () PIAttributeMaskToTag(tagname, descriptor, pointsource, pointtype, pointclass, engunits, outcode, PIServer)
Arguments
Argument Explanation
tagname (string) Tagname mask.
descriptor (string) Descriptor mask.
pointsource (string) Point Source mask.
pointtype (string) Point Type mask.
pointclass (string) Point Class mask.
engunits (string) Engineering Units mask.
outcode (integer) An output code; either 0 or 2.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Tagname
An output code of 2 transposes the output array that results from an output code of 1.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 69
Example
The following returns the tagname of the tags which start with "sin" from server named THEVAX.
=PIAttributeMaskToTag("sin*","*","*","*","*","*",0,"thevax")
Alias Dialog Box
This dialog box returns a tagname when an alias is specified.
Required Fields
Alias
Module Path
Query Date
Related Topics
PIAliasToTag() (page 69)
PIAliasToTag() PIAliasToTag(alias, modulepath, querydate, outcode, PIServer)
Arguments
Argument Explanation
alias (string) Module item that is a reference to a PI point.
modulepath (string) Full path to a module in module database.
querydate (integer) Query for modules with effective dates at or after this date.
Outcode (integer) An output code; either 0, 1, or 2.
PIServer (string) The PI Server.
Returns
Outcode Column 1 Column 2
0 Tagname
1 Tagname Server of tag
Add-in to Excel
Page 70
An output code of 2 transposes the output array that results from an output code of 1.
Example
The following returns the tagname corresponding to the "Temperature" alias of module "Reactor1" which is a submodule of "Unit1". "Unit1" is at the root of the module database for a PI server named THEVAX. The module database is queried at current time.
=PIAliasToTag("Temperature","\Unit1\Reactor1","*",0,"thevax")
Property Dialog Box
This dialog box returns a value when a property is specified.
Required Fields
Property
Module Path
Query Date
Related Topics
PIPropertyToValue() (page 70)
PIPropertyToValue()
PIPropertyToValue(property, modulepath, querydate, PIServer, outcode)
Arguments
Argument Explanation
Property (string) Module item that has value of virtually anything.
modulepath (string) Full path to a module in module database.
querydate (integer) Query for modules with effective dates at or after this date.
PIServer (string) The PI Server.
Outcode (integer) An output code; either 0 or 2.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 71
Returns
An output code of 0 displays the value of the property in a column.
An output code of 2 displays the value of the property in a row.
Example
The following returns the value corresponding to the "Implementer" property of module "Reactor1" which is a submodule of "Unit1". "Unit1" is at the root of the module database for a PI server named THEVAX. The module database is queried at current time.
=PIPropertyToValue("Implementer","\Unit1\Reactor1","*","thevax")
Insert Trend Control
The Trend Control is an ActiveX control that can be inserted onto any Excel spreadsheet. The trend can display data from both the spreadsheet and a PI Server tag.
Add-in to Excel
Page 72
To create a trend, a trend wizard is provided to make inserting trends easier. There are two sources of data that the Trend Control can plot:
Worksheet Data
PI Data
Data on Worksheet
The Trend Wizard can be used to create a trend from data on an Excel worksheet.
If the data is to come from the worksheet, the cell range of the data must be specified. The cell range can be typed in manually or the mouse can be used to specify the range. To use the mouse to specify the range, click button at the right of the field. Another dialog box will appear. Selecting the range on the spreadsheet will generate the cell reference format in the dialog box.
The First element is trace name option is used if a name is to be provided for the trace on the trend. If this option is specified, the string in the first cell is used for the name of the trace. The first cell is the cell above the first value of the range if the data is arranged in the column format. If the data is arranged in the row format, then the first cell is the cell to the left of the first value of the range.
For ease of use with FactoryTalk Historian DataLink functions, the Include all cells in array option is specified as the default. If this option is specified, then only one cell of the array must be specified for the cell range. The rest of the array is automatically added to the cell range reference when the Add -> button is selected.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 73
The Plot as stepped data option gives the trace a jagged-saw look. This option is usually specified for discrete tags.
Data from PI
The Trend Wizard can also be used to create a trend from data directly from the PI Server.
To get data directly from the PI Server, the tagname needs to be specified. The tagname can be conveniently searched for from the point database of the PI Server. By pressing the Search... button, a Tag Search dialog box appears. This is the same Tag Search dialog box as the one that comes from the PI menu. Any tags selected from the Tag Search dialog box are automatically added to the list of traces.
By default DataLink displays color-blind markers to differentiate traces on monochrome viewers; color-blind markers are evenly spaced along a trace and do not indicate archived data points. Select the Markers checkbox to display markers that indicate the location of archived data points on the trace.
Another way of specifying tags is by cell reference. If the tag names are on the Excel spreadsheet, they can be referenced by checking the Cell Ref option box and specifying the cell(s) where the tagname(s) are. The server name can be specified in the same way.
After clicking Next, the start time and end time of the trend needs to be specified in PI time format.
Add-in to Excel
Page 74
Trend Title and Placement
The last screen is to configure the trend title and the placement of the trend.
If a new worksheet is selected, the trend is placed on a blank worksheet at the top left corner.
To display value attribute icons at the top of the trend, select the Show Value Attributes checkbox; icons appear when the range of data contains events that have the Questionable, Substituted, or Annotated bits set.
If the existing worksheet option is specified, then the cell where the trend is to be placed must be specified. The selected cell before entering the trend wizard is the default cell reference. Make sure to choose a cell, which does not contain data. If the cell references a cell containing data, the trend will cover the data. However, the data is not deleted. To move the trend, right-click the trend and select Move/Resize.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 75
Right Click Menu
After inserting the trend into the Excel worksheet, quick changes can be made to it by selecting some of the items on the right click menu.
To change the y-axis scaling, the Change Scale... option can be selected. There you can change both the time range and y-axis of the trend. If a change in the scale is deemed undesirable, the Revert option can be selected to undo the changed made. The Revert option always reverts back to the settings defined in the Trend Wizard.
To scroll through time, scroll bars can be enabled with the Scroll Bar option. The scroll bar appears at the bottom of the trend. Again, the Revert option can be used to undo changes made by the scroll bar.
To change the format of the trace or the trend itself, the Format... option can be used.
Add-in to Excel
Page 76
For instance, this option can be used to change the color or line thickness of a trace. Also it can be used to add legends to the trend. Define Trend... and Define Trend Time Range... brings back the Trend Wizard screens. Delete Trend option deletes the trend. Export Data... option pastes the values used to plot the trend onto the spreadsheet. The Move/Resize option moves and changes the trend to size of the specified cell range. The Copy/Paste option copies the trend to the clipboard and then prompts for the destination of the paste. The pasted trend is a copy of the trend in terms of all its formatting and references to cells.
Additional Information
For additional information on the use of the trend control, you can press the Help button on the Trend Wizard. Also there are additional help files in ...\PIPC\HELP\PITrend*. For instance, to learn more about Automation of the trend control, there is a ...\PIPC\HELP\PITrendAuto.hlp.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 77
Tag Search Dialog Box
This dialog box allows you to search for tags from your PI Server(s) and copy the results into the spreadsheet. To copy tags from the result list, you must first select each tag by clicking on the tagname while holding the CTRL key. To select an entire range of tags, click the first tag, then hold the SHIFT key and click the tag at the bottom of the range. Click OK to copy tags to the spreadsheet. If the "Copy PIServer Name" option in the Settings... dialog box is checked, the PI Server for each tag will be copied into the spreadsheet along with the tag names.
Tags are copied into the spreadsheet either along a single column or along a single row depending on the option selected in the "Copy items to sheet" section of the FactoryTalk Historian DataLink Settings... dialog.
The starting position where the copying takes place is the current cell. If the "Copy PIServer Name" option is enabled, the server names are copied into the spreadsheet in a column to the right of the tag names when the In a column option is selected in the "Copy items to sheet" section. If the In a row option is selected in the "Copy items to sheet" section, the server names are copied below the tag names in the spreadsheet.
Add-in to Excel
Page 78
Module Database Dialog Box
This dialog box allows you to search for aliases, properties, and modules from your PI Server(s) and copy the results into the spreadsheet.
The dialog box mostly consists of a tree view of the module database. The dialog box enables users to copy module database items to the spreadsheet. The tree view displays three types of module database items.
Aliases
Properties
Modules
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 79
There are two ways to select aliases and properties from the module database with each method copying a different set of items to the spreadsheet.
Selecting just one item copies that item to the spreadsheet.
Selecting "Aliases" or "Properties" item of a module copies all aliases or properties of that module respectively.
If the "copy module path" option is checked, the full module path of the alias or property is copied to the spreadsheet along with the alias or property in an adjacent cell.
To select a module, selecting just the one module and selecting copy module path will copy that module's full path to the spreadsheet. If the copy module path checkbox is not checked, then just the name of the module is pasted to the spreadsheet.
The PI Server drop-down list can be used to switch between module databases of different PI servers. The query date field can be used to specify the date and time context of the displayed module database. If the "Copy PIServer Name" option in the Settings... dialog-box is checked, the PI server for each module database item will be copied into the spreadsheet along with the module database item.
Connections Dialog Box
A dialog box manages your PI Server connections.
Add-in to Excel
Page 80
By using the right click menu, you can add additional PI Servers to the list, edit existing PI Servers, remove existing PI Servers, and set an existing PI Server as the default PI Server.
You can click on the checkbox to connect to and disconnect from PI Servers in the list. After you successfully connect to a PI Server, the Status field changes to checked, the user column returns the user that the connection is connected as, and the PI version column returns the version of the PI server that it connected to.
Settings Dialog Box
This dialog box controls your settings and preferences for FactoryTalk Historian DataLink.
Details for FactoryTalk Historian DataLink Functions and Dialog Boxes
FactoryTalk Historian Site Edition DataLink User Guide Page 81
The set of radio buttons In a row or In a column determines whether the selected tags in the TagSearch dialog box are copied to the spreadsheet along a row or a column.
The Copy PIServer name check box determines whether the PI Server's name is copied into the PIServer edit field if TagSearch is called from a PI dialog box. This option also determines whether the server names are copied into the spreadsheet for selected tags if TagSearch is called directly from the PI menu.
The Use PIServer Time Zone check box determines whether or not all the DataLink functions interpret time using the PI server time zone instead of the client machine time zone information. This option affects systems where the PI 3 Server machine has different time zone settings than the client machine.
The Display #N/A instead of Blanks check box determines whether or not "#N/A" or blanks are displayed when there is less data than the size of the DataLink function array. Select this check box when the DataLink function results are plotted by the Excel charting package.
The Locale Independent check box determines whether localized time strings should be used when parsing time data.
Add-in to Excel
Page 82
• Select this check box to force FactoryTalk Historian DataLink to parse the time string according to PI time format rules. This defines the date-time order as dd-MMM-yyyy hh:mm:ss, and the language of any strings as English.
• Clear this check box to enable FactoryTalk Historian DataLink to parse the time string according to your local regional settings, including date-time format preferences. If locale-specific parsing fails, FactoryTalk Historian DataLink will attempt to parse according to PI time format rules.
The Number format edit box lets you specify a default number formatting code. This string may be any valid code from the Format, Cells, Number list.
The Time format edit box lets you specify a default time formatting code. This string may be any valid code from the Format, Cells, Number list.
Select OK to save your settings; Cancel to abort your changes.
About
This menu choice displays FactoryTalk Historian DataLink version information.
Help
This menu choice calls FactoryTalk Historian DataLink Help.
Writing Data from Excel to PI
FactoryTalk Historian DataLink allows you to write a value from the worksheet to the PI Server. The FactoryTalk Historian DataLink macro function that performs these tasks is PIPutVal(). PIPutVal() replaces an existing event with the same timestamp in the Archive with the new value supplied by the user.
PIPutVal() can only be invoked from an Excel macro sheet or from an Excel VBA module using the application.run method. Please consult the file ...\PIPC\EXCEL\piexam32.xls on how to call PIPutVal in a VBA module. Specifically, look at the tags marked "PutVal" and the VBA module "PutVal_code."
PIPutVal()
PIPutVal(tagname, value, time stamp, PIServer, outcell)
Writing Data from Excel to PI
FactoryTalk Historian Site Edition DataLink User Guide Page 83
Arguments
Argument Explanation
tagname (string) The tag for which you to write the value to PI.
value (reference) The reference to a value to be written. It may be either a string (for digital states) or a number.
time stamp (string) A time stamp in PI time format.
PIServer (string) The PI Server.
outcell (reference) A reference to a cell in which the return value of this macro function is displayed.
Returns
The string FALSE will be returned if the macro function failed and an error message will be written to the outcell. If the write to the PI Server succeeds, the string TRUE will be returned and the status digital state written, integer written, or real value written will be written to the outcell.
Note: This function (PIPutVal) does not check whether the number to be written falls within the user-specified range for a tag. The range for a tag is from the zero to the zero + span, where zero and span are tag attributes specified by the user during point (tag) creation. FactoryTalk Historian DataLink will return a value written message even though "Over Range" or "Under Range" might have been entered into the PI Server.
Note: PIPutVal supports all PI 3 data types (including string input to string tags) as well as sub-second data. Timestamps are interpreted using client machine time zone information unless the "Use PI Server Time Zone" option is enabled or it is a PI 2 Server.
Example
The following puts the value located in the cell A5 into the PI Server of the default PI Server for midnight today for the tag testtag:
=PIPutVal("testtag",a5,"t",,e5)
The result of the macro function is placed into cell E5 on the macro sheet.
Add-in to Excel
Page 84
Limits from Excel for FactoryTalk Historian DataLink
Excel has a limitation on the number of elements in a calculation array. FactoryTalk Historian DataLink is subject to this limitation. Therefore, there is a maximum number of values that can be returned for a single PI function. The maximum number of PI events per retrieval is 65536.
The Excel SDK used by FactoryTalk Historian DataLink has a 255 character limitation on string length. Hence, input strings to DataLink like FactoryTalk Historian DataLink formulas or expressions in a reference cell cannot exceed 255 characters. Similarly, string output from FactoryTalk Historian DataLink, like PI string tag results, will be truncated by FactoryTalk Historian DataLink to 255 characters.
FactoryTalk Historian Site Edition DataLink User Guide Page 85
Appendix A: Troubleshooting
Consult the sections below if you are having difficulties with FactoryTalk Historian DataLink.
DataLink Add-in Doesn't Load Properly (page 85)
Connection Problems Reported in Log Files (page 86)
Limits from Excel for FactoryTalk Historian DataLink (page 84)
If you are still having problems after following these suggestions, see Technical Support and Resources (page 99) for details on contacting Technical Support.
DataLink Add-in Doesn't Load Properly
PI Menu Not Available on Excel Toolbar
Some user-written VBA scripts in Excel spreadsheets (or add-ins) have been known to reset the main Excel menu. If this happens, the PI menu disappears even though the FactoryTalk Historian DataLink add-in is still loaded. One of the symptoms of this phenomenon is that embedded FactoryTalk Historian DataLink array functions still work while the PI menu itself is not available. Restarting Excel usually fixes the problem.
Connection Problems Reported in Log Files
On PI 3 Server, information about connection attempts may be obtained via the PIGetMsg utility:
pigetmsg * * *-15m * "PInet*"
The above displays all messages that begin with the text "PINet" from 15 minutes ago to the current time. (FactoryTalk Historian DataLink connection messages should begin with "PINet".)
Add-in to Excel
Page 86
For PI 2 Server, the log files are located as follows:
UCX PISysExe:UCXPIServer.log
MultiNet PISysExe:MTNPIServer.log
PathWay PISysExe:PTWPIServer.log
TCPware PISysExe:TCPIServer.log
FactoryTalk Historian DataLink for Excel
On local PC, information about connection attempts may be obtained via the PIGetMsg utility:
pigetmsg * "EXCEL.EXE" *-15m *
The above displays all messages that are made by EXCEL.EXE from 15 minutes ago to the current time. (FactoryTalk Historian DataLink connection messages should come from EXCEL.EXE.)
FactoryTalk Historian Site Edition DataLink User Guide Page 87
Appendix B: Expression Syntax
PI expressions are used in FactoryTalk Historian DataLink functions that require calculation of mathematical functions, which include PI tags. The functions that require the user to specify a valid PI expression are: PIExpDat, PITimeFilter, PINCompFilDat, PICompFilDat, and PISampFilDat.
The PI expressions (also known as Performance Equations) used in the above functions must conform to syntax rules that are explained in the Performance Equation sections of the PI Server Applications Guide or the PI 3 Performance Equations Help File. A brief outline of these syntax rules is reproduced here for user convenience (however, the user is referred to the above manuals for a more complete discussion).
Note: There are some differences in Performance Equation calculation and syntax rules between PI 2 and PI 3 Server. These differences can require users to build separate expressions depending upon whether the PI Server being referred to is a PI 2 or a PI 3 server.
Calculation Expressions
The following describes the syntax of valid calculation expressions (used by PIExpDat) in FactoryTalk Historian DataLink.
Note: The examples below use two tag delimiters, colon (:) and period (.). Your FactoryTalk Historian System may use different ones.
In a tag calculation expression, mathematical operators and functions act upon tag names.
Add-in to Excel
Page 88
Mathematical Operators
Mathematical operators are:
+ addition
- subtraction
* multiplication
/ division
^ raise to a power
Example (('sinusoid')^3 + 'cdf144'/10)
The above expression determines the sum of the value of sinusoid cubed and the value of cdf144 divided by 10.
Mathematical Functions
Supported Mathematical Functions are:
abs absolute value
atn arc tangent (angle returned in radians)
cos cosine (argument in radians)
exp e (2.71828...) raised to a power
int integer part of a number
log natural logarithm
sgn sign function (-1 if argument is negative, 0 if zero, 1 if positive)
sin sine (argument in radians)
sqr square root function
tan tangent (argument in radians)
Calculation Expressions
FactoryTalk Historian Site Edition DataLink User Guide Page 89
Example (log('cdep158') - cos('cdep158'))
The above expression finds the difference between the natural logarithm of the value of the tag cdep158 and the cosine of the value of the tag cdep158.
Performance Equation Functions
If the version of your PI 2 Server is 2.0.9 or higher, or if you are using PI 3 Server, you can also evaluate expressions that contain current Performance Equation functions.
Some useful functions are:
BadVal()
StateNo()
TagBad()
NextVal()
PctGood()
PrevVal()
TimeEq()
TimeGE()
TimeGT()
TimeLE()
TimeLT()
TimeNE()
Example PctGood('cdep158', 'y', 't')
The PctGood function finds the time percentage, over a given range, when a tag's archived values are good.
In the above example, the percentage of time between midnight yesterday and midnight today, when the tag was receiving "good" values will be returned.
Add-in to Excel
Page 90
Curtime Keyword
You can refer to the timestamp of the calculation by using the keyword curtime explicitly in the expression. For example, you specify 20-Oct-97 for Start time, 21-Oct-97 for End time, 12h for Time interval and the following expression in the PIExpDat PI function:
(curtime - `20-Oct-97')/1s
Three sets of data will be returned as follows: 20-Oct-97 00:00:000 20-Oct-97 12:00:0043200 21-Oct-97 00:00:0086400
For more information on Performance Equation functions, consult the PI Server Applications Guide or the PI 3 Performance Equations Help File. Also, note that the PE syntax for PI 3 Server differs slightly from that on PI 2 Server.
Filter Expressions
The following describes the syntax of valid filter expressions in FactoryTalk Historian DataLink.
Note: The examples below use tag delimiters of : (colon) and . (period). Your FactoryTalk Historian System may use different ones.
Relational Operators
A filter expression uses the same arithmetic operators and functions as a calculation expression. In addition, one or more relational operators are necessary.
Relational operators are:
< less than
= equal to
> greater than
<= less than or equal to
<> not equal to
>= greater than or equal to
Filter Expressions
FactoryTalk Historian Site Edition DataLink User Guide Page 91
Example (abs('my:tag') >= 14.65)
The above expressions evaluates to TRUE (non-zero) if the absolute value of the tag mytag is at least 14.65.
When comparing digital tags, use the negative of the digital state code number.
For PI 2.0.9 or higher, use the digital state string itself. For example: ('my:tag' = "Manual")
Logical Operators
A filter expression may also contain logical operators such as:
and returns TRUE if both its arguments are TRUE.
or returns TRUE if at least one of its arguments is TRUE.
not returns TRUE if its argument is FALSE, and vice-versa.
Example
The following expression evaluates to TRUE if the value of the tag sinusoid is less than 45 and the square root of the value of the tag vdf1002 is greater than 2:
('sinusoid' < 45 and sqr('vd:f1002') > 2)
FactoryTalk Historian Site Edition DataLink User Guide Page 93
Appendix C: Examples of PI Time Strings
Start and End Time
In the following examples, omit the leading quote if you are entering the PI time string into a text edit field in an Excel dialog box. For example:
{PIArcVal 'sinusoid,'(25-dec-92 14:23),1,',A5}
PI Time String Meaning
'06-dec-91 15:00:00 3:00:00 p.m. 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
'*-1h One hour ago
't+8h 8:00:00 a.m. Today
'y-8h 4:00:00 p.m. The day before yesterday
'mon+14.5h 2:30:00 p.m. Last Monday
'sat-1m 11:59:00 p.m. Last Friday
Add-in to Excel
Page 94
Time Interval
In the following examples, omit the leading quote if you are entering a PI time string directly into a text edit field in an Excel dialog box.
PI Time String Meaning
'1.5h One and one-half hours
'32m Thirty-two minutes
'49s Forty-nine seconds
`+5h Five hours anchoring off starttime
`-5h Five hours anchoring off endtime
Note: A positive interval means to anchor off the starttime and a negative interval means to anchor off the endtime. If no plus or minus sign is used, then interval is assumed to be positive. So if starttime is "y", endtime is "t", and interval is "+5h" for Sampled Data function, then interpolated values are generated at y, y+5h, y+10h, y+15h, and y+20h. If the interval is "-5h" instead, then the interpolated values are generated at y+4h, y+9h, y+14h, y+19h and t.
FactoryTalk Historian Site Edition DataLink User Guide Page 95
Appendix D: Setup.ini Arguments
Silent Installs
For silent installs, please use the silent.ini provided in the DataLink distribution kit. Please make site-specific specifications as needed. Arguments in silent.ini are described further in PI SDK Setup.ini Arguments and FactoryTalk Historian DataLink Setup.ini Arguments sections. To use silent ini, type:
Setup.exe -f silent.ini
PI SDK Installation
There are a few arguments which can be added as arguments to the command line in order to install the SDK silently. In order for any of the arguments to work, the command line must have /qn in it. All arguments must be separated by a space. The following is an example of how the setup.ini should look like:
[COMMANDLINE] 5 = /qn PI_SERVER=localhost
Argument Meaning
/qn Install silently
PI_SERVER Name of default PI server
PI _ALIAS Alias name for default PI server
PI_PORT Default port for default PI server
PI_TYPE Server type for default PI server (either 2 or 3)
PI_USER Default user for default PI server
INSTALLDIR Installation path
PIBUF_ENABLE
Enables/disables buffering
ALLUSERS Installs for all users of machine
Add-in to Excel
Page 96
FactoryTalk Historian DataLink Installation
There are a few arguments which can be added as arguments to the command line in order to install the FactoryTalk Historian DataLink. All arguments must be separated by a space. The following is an example of how the setup.ini should look like:
[COMMANDLINE] 6 = /q SHARED=P:\APPS
Argument Meaning
/q Install silently
SHARED Network Installation pathname
ALLUSERS Installs for all users of machine
FactoryTalk Historian Site Edition DataLink User Guide Page 97
Appendix E: Outcodes
The outcode is just the decimal representation of binary bits. The bits are as follows:
1st bit: Show Timestamps bit
2nd bit: Orientation bit (columns/row)
3rd bit: Show Percent Good bit
4th bit: Hide Count bit
5th bit: Show Extended Status bit
6th bit: Show Annotations bit
7th bit: Show Start Time
8th bit: Show End Time
9th bit: Show Min/Max Time
The formula to calculate the corresponding outcode is
set) isbit that each for number bit theis (where 2 1 ii
xi∑ −
Note: Not all outcodes are valid for each function because not all options are available for every function.
Example
Suppose we want a Calculated Data function to display Percent Good, Start Time, and Min/Max Time. Since Start Time and Min/Max Time are displayed, the Show Timestamps bit must also be set.
Add-in to Excel
Page 98
{ }{ }
3252566441
2222
22222
9 7, 3, 1,
8620
191713111
TimeMin/Max Show Time,Start Show Good,Pct Show ,Timestamps Show
=+++=
+++=
+++==
==
−−−−−∑i
xioutcode
setbits
So the function shown in Excel would look like: =PICalcDat("sinusoid","y","t","1h","minimum", 1, 325,"piserver")
FactoryTalk Historian Site Edition DataLink User Guide Page 99
Appendix F: Technical Support and Resources
Contact Rockwell Automation Technical Support at the following:
• Customer Support Telephone — 1-440-646-3434
• Online Support — http://support.rockwellautomation.com
Knowledge Center
The Knowledge Center provides a searchable library of documentation and technical data, as well as a special collection of resources for system managers. For these options, click Knowledge Center in the Technical Support Web site.
The Search feature allows you to search Support Solutions, Bulletins, Support Pages, Known Issues, Enhancements, and Documentation (including user manuals, release notes, and white papers).
System Manager Resources include tools and instructions that help you manage: archive sizing, backup scripts, daily health checks, daylight savings time configuration, PI Server security, FactoryTalk Historian System sizing and configuration, PI trusts for interface nodes, and more.
Before You Call or Write for Help
When you contact Rockwell Automation Technical Support, please provide:
Product name, version, and/or build numbers
Computer platform (CPU type, operating system, and version number)
The time that the difficulty started
The message log(s) at that time
Add-in to Excel
Page 100
Find the Version and Build Numbers
To find version and build numbers for each FactoryTalk Historian System subsystem (which vary depending on installed upgrades, updates or patches) use either of the following methods:
If you have PI System Management Tools (PI SMT) installed, choose Start > Programs > PI System > PI System Management Tools. In PI SMT, select the server name, then under System Management Plug-Ins, open Operation > PI Version. The PI Version tree lists all versions.
If you do not have PI SMT installed, open a command prompt, change to the pi\adm directory, and enter piversion -v. To see individual version numbers for each subsystem, change to the pi\bin directory and type the subsystem name followed by the option -v (for example, piarchss.exe –v).
View Computer Platform Information
To view platform specifications:
In Windows, right-click My Computer and choose Properties. For more detailed information, choose Start > Run, and enter msinfo32.exe
In UNIX, use the command, uname -a
FactoryTalk Historian Site Edition DataLink User Guide Page 101
A
ActiveX control • 71 Advanced Calculated Data • 53 Attribute Mask to Tag • 68 Averages • 53
B
Bug Fixes List of • 3
C
Calculation Expressions • 87 Calculation Modes • 53 Can't Connect to the PI Server • 85 Case-sensitive
Node names • 3 Change arguments • 15, 28 Change Scale option • 75 Combo Boxes • 21 Compressed Data
(Number) • 35 (Times) • 38
connect() timeout error • 85 Connections
Problems • 85 Curtime Keyword • 89
D
Data Access • 7 PI 3 Server • 7
Define Trend option • 75
Delimiters • 87 Dialog Box
Advanced Calculated Data • 53 Alias • 69 Attribute Mask to Tag • 67 Compressed Data (Number) • 35 Compressed Data (Times) • 38 Enter time in Excel • 24 Functions • 30 Module Database • 78 Point ID to Tag • 67 Property • 70
E
Errors • 85 connect() timeout error • 85 Gethostbyname • 85 recv Error 0 • 85 select() timeout error • 85
Expressions • 44, 65, 66 Syntax • 87
F
FactoryTalk Historian DataLink Functions • 30 Installation arguments • 96 Loading Problems • 85
Filter Expressions • 90 Firewall Database • 7 Format option • 75 Functions • 27
Dialog Boxes • 30 Excel • 30
Index
Index
Performance Equation • 89 Provided in Excel • 9
G
Gethostbyname error • 85
H
Help • 82
I Input Timestamps
Start and End Time • 93 Time Interval • 94
Installation Arguments • 96 SDK • 95
L
Loading Problems • 85 Lotus 1-2-3 Add-in • 1
M
Maxima and Minima • 53 Microsoft Excel
Add-in • 1, 9 Module Database • 78 MultiNet
Name Translation, PI Client • 3
N
Node Authentication PI 2 Server • 3
Node Names TCP/IP • 3
O
Operating System • 1 Output Fields • 19
P
PathWay Name Translation, PI Client • 3
PC client name • 3
Performance Equation Syntax • 89
Performance Equations • 87 PI 2 Server
Server configuration • 3 PI 3 Server
configuration • 7 security • 7
PI Expressions • 87 Logical Operators • 91 Math Functions • 88 Mathematical Operators • 88 Performance Equations • 89 Relational Operators • 90
PI Menu Not displayed • 85
PI SDK Silent Installation • 95
PI System Manager • 3 PI time strings • 93 PIADMIN
User Privileges • 7 PIAdvCalcDat • 60 PIAdvCalcExpDat • 62 PIAdvCalcExpFilDat • 63 PIAdvCalcExpFilVal • 59 PIAdvCalcExpVal • 58 PIAdvCalcFilDat • 60 PIAdvCalcFilVal • 57 PIAdvCalcVal • 56 PIAliasToTag • 69 PIArcVal • 32 PICalcDat • 52 PICalcVal • 50 PICompDat • 40 PICompFilDat • 41 PICurrVal • 31 PIExpDat • 44 PIExpVal • 33 PINCompDat • 37 PINCompFilDat • 38 PINet nodes
security on • 3 PIPropertyValue • 70 PIPutVal • 82
Page 103
PISampDat • 43 PISampFilDat • 43 PIServer Fields • 19 PITagAtt • 35 PITimeDat • 46 PITimeExpDat • 46 PITimeFilter • 66 PITimeFilterVal • 65 Point Access • 7
PI 3 Server • 7 Point ID to Tag • 67
R
recv Error 0 • 85 Revert option • 75 Rockwell Automation Technical Support • 85
S
Sampled Data Example • 14
Scroll Bar option • 75 Security
PI 2 Server • 3 PI 3 Server • 7
select() timeout error • 85 setup.ini
Arguments • 95 FactoryTalk Historian DataLink • 96
Standard Deviations • 53 Syntax
Performance Equation • 89
T
TCP/IP • 1 Node Names • 3
TCPWare Name Translation, PI Client • 3
Timestamps Entering into FactoryTalk Historian DataLink • 24 Time Interval • 94
Trend Right-click menu • 75
Trend Control • 71
Troubleshooting • 85
U
UCX Name Translation for PI Client • 3
User Privileges PIADMIN • 7
username/password PI 3 Server • 7
V
Values Writing into PI • 82
Version PI System 2.0.9 • 89 Spreadsheet software • 2 TCP/IP • 1