PI DataLink User Guide

Version 3.1.6
12/18/2006

1992-2007 OSIsoft, Inc. All rights reserved

OSIsoft, Inc.

OSIsoft Australia

777 Davis St., Suite 250

San Leandro, CA 94577 USA
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Perth, Australia
Auckland, New Zealand

http://techsupport.osisoft.com

OSI Software Asia Pte Ltd.

OSI Software GmbH

Altenstadt, Germany

techsupport@osisoft.com

Singapore

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA

OSIsoft Canada ULC

Montreal, Canada

OSIsoft, Inc. Representative Office

Shanghai, Peoples Republic of China

OSIsoft Japan KK
Tokyo, Japan

OSIsoft Mexico S. De R.L. De C.V.

Mexico City, Mexico

Sales Outlets/Distributors
Brazil
Middle East/North Africa
Republic of South Africa
Russia/Central Asia

South America/Caribbean
Southeast Asia
South Korea Taiwan

www.osisoft.com
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System,
PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned
in this book that are known to be trademarks or service marks have been appropriately
capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the
property of its owner and use herein in no way indicates an endorsement, recommendation, or
warranty of such party's products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 252.227-7013

Table of Contents
Chapter 1:

Introduction ..............................................................................................................1
Contents of PI DataLink.............................................................................................1
System Requirements ...............................................................................................2
Installation..................................................................................................................3
For the PI System Manager.......................................................................................6

Chapter 2:

Add-in to Excel.......................................................................................................11
Overview ..................................................................................................................11
Tutorial .....................................................................................................................12
PI Menu....................................................................................................................20
Dialog Boxes............................................................................................................22
Time in PI DataLink .................................................................................................24
PI DataLink Functions..............................................................................................29
Details for PI DataLink Functions and Dialog Boxes...............................................32
Writing Data from Excel to PI...................................................................................84
Limits from Excel for PI DataLink ............................................................................86

Chapter 3:

Add-in for Lotus 1-2-3 ...........................................................................................87

Tutorial .....................................................................................................................88
PI Menu....................................................................................................................98
Dialog Boxes..........................................................................................................100
Time in PI DataLink ...............................................................................................104
PI DataLink Custom Macro Commands ................................................................106
Dialog Box and PI Custom Macro Details .............................................................107
Writing Data from Lotus 1-2-3 to PI .......................................................................133
Limitations of PI DataLink for Lotus 1-2-3 .............................................................135

Appendix A:

Troubleshooting ..................................................................................................137
DataLink Add-in Doesn't Load Properly.................................................................137

Appendix B:

Expression Syntax...............................................................................................143
Calculation Expressions ........................................................................................143
Filter Expressions ..................................................................................................146

PI DataLink User Guide

Page iii

Contents

Appendix C:

Examples of PI Time Strings ..............................................................................149

Start and End Time................................................................................................149
Time Interval ..........................................................................................................150

Appendix D:

Setup.ini Arguments............................................................................................151
Silent Installs..........................................................................................................151
PI SDK Installation.................................................................................................151
PI DataLink Installation ..........................................................................................152

Appendix E:

Outcodes ..............................................................................................................153
Example .................................................................................................................154

Appendix F:

Technical Support and Resources ....................................................................155

Before You Call or Write for Help ..........................................................................156

Index ............................................................................................................................................159

Page iv

Chapter 1: Introduction
PI DataLink provides a link between OSIsoft's PI 3 or PI 2 Server, and spreadsheet programs
running on Microsoft Windows platforms. With PI DataLink, a user running Microsoft Excel
or Lotus 1-2-3 can exchange information directly with the PI System databases. Combined
with the functionality of the spreadsheet programs, this feature makes PI DataLink a
powerful, yet easy-to-use tool for gathering, analyzing, and reporting PI data.

Contents of PI DataLink
PI DataLink consists of the following two modules:
An add-in for Microsoft Excel
An add-in for Lotus 1-2-3

PI DataLink for Excel is built with OSIsoft's 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.
PI DataLink for Lotus 1-2-3 is built with OSIsoft's PI API product. It allows users who have
experience using 1-2-3 LotusScript programming to develop Lotus spreadsheet routines that
call PI API functions.
However, users who wish to develop programs outside of Excel or Lotus 1-2-3 must purchase
a separate PI SDK or PI API license. Please contact an OSIsoft sales representative for more
information.

PI DataLink User Guide

Page 1

Introduction

System Requirements
PI 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. PI DataLink communicates with
the PI Server via the TCP/IP protocol.
TCP/IP
To use TCP/IP, one of the following operating systems is necessary:
Microsoft Windows 98, 2000, or XP
Microsoft Windows NT, version 4 SP6a

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

PI DataLink supports the following spreadsheet programs (32-bit versions only):
Microsoft Excel 2000, version 9.0 and later.
Lotus 1-2-3 release 9.5 (included as part of Lotus SmartSuite Millennium) and later.

Page 2

Installation

Installation
Note: Before installation, each user of PI DataLink must be licensed to use this product.
Contact OSIsoft Sales for more information.

The user may install PI DataLink from the distribution CD, either locally to a PC, or globally
to a network file server. A System Administrator normally performs the latter.
After a successful installation of PI DataLink to a network file server, other users will be able
to install from the network drive to a local PC either a complete standalone version or a
shared version of PI DataLink.
Installation of a standalone version places a copy of all the PI DataLink files onto the user's
local PC. In an installation of the shared version, the main PI DataLink files remain on the
network file server and users run the program files off the server.

Installation to a Network File Server

This option is intended as a one-time procedure for a System Administrator. This installation
in and of itself does not allow anyone to run PI DataLink. Individual users must subsequently
perform an installation of either a standalone version or a shared version of PI DataLink.
Installation to a network file server is done on a local PC.
The following summarizes the procedure for installation to a network file server:
1. Run AdminSetup.exe from the distribution CD on the network file server.
2. Choose the destination directory (for example: C:\APPS\). Setup will create EXCEL,
DAT, LIBRARY, LOTUS, and SETUP subdirectories under C:\APPS\PIPC.
3. For shared installations, edit the [COMMANDLINES] section of the setup.ini in the
SETUP directory:
6 = SHARED="P:\APPS\PIPC"
where P: is the drive letter all local machines specify to point to the C: drive on the
network file server. Refer to Setup.ini Arguments (page 151) for more arguments.
4. To create PI servers list, do shared install on machine, which has write privileges to
P:\APPS\PIPC\DAT directory. Add PI servers as you would normally. All changes
made will be propagated to rest of shared installs.

PI DataLink User Guide

Page 3

Introduction

The current release notes are in C:\APPS\PIPC\readme_datalink.txt.

Release notes for previous versions are in
C:\APPS\PIPC\readme_dl<version>.txt.

Installation to a Local PC (Standalone and Shared)

In order to use PI DataLink, every user must install either a complete standalone version or a
shared version. Installation of a standalone version may be performed either from the
distribution CD or from the network drive. Installation of a shared version can only be
performed from the network drive.
The following summarizes the procedure for installation to a local PC:
1. Run setup.exe from the distribution CD or from the setup directory on the network drive
(for example, P:\APPS\PIPC\SETUP\setup.exe).
2. Choose the destination directory.
The release notes are in P:\APPS\PIPC\readme_datalink.txt.
Release notes for previous versions are in
P:\APPS\PIPC\readme_dl<version>.txt.

Configuration of Microsoft Excel

If PI DataLink will be used with Microsoft Excel, and this is a first time installation (not an
upgrade) of PI DataLink, you will need to add PI 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 PI DataLink,
look in the ...\PIPC\EXCEL directory on the network drive.
If PI 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.

Page 4

Installation

Configuration of Lotus 1-2-3

To configure PI DataLink to work with Lotus 1-2-3:
1. Start Lotus 1-2-3.
2. On the main menu go to: File > Add-Ins > Manage Add-Ins...
3. Click on Register in the Manage Add-Ins dialog.
4. Select pidl.12a in the ...\lotus\addins directory and click Open.
5. Check the space in front of the pidl.12a file path and click Done.
6. Exit out of Lotus 1-2-3 and start it again. The PI DataLink menu should now be available.
PI DataLink for Lotus 1-2-3 does not support shared installations. PI DataLink for 1-2-3 must
be installed separately on each computer (these installations can be done from a central
network installation).

New Features for Microsoft Excel Users

A list of new features in this version of PI DataLink is in the
...\PIPC\readme_datalink.txt file.

New Features for Lotus 1-2-3 Users

A list of new features in this version of PI DataLink is in the
...\PIPC\readme_datalink.txt file.

Bug Fixes
A list of known problems that are fixed in this version of PI DataLink is in the
...\PIPC\readme_datalink.txt file.

PI DataLink User Guide

Page 5

Introduction

For the PI System Manager

PI 2 Server

PI Server Service
If PI 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 PI 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:

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 PI DataLink.
3. The machine named "PC2" has no access to PI data. This level of security means that no
one can use PI 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 PI
DataLink.

Page 6

For the PI System Manager

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

PI DataLink User Guide

Page 7

Introduction

Name Translation - MultiNet

Under MultiNet, the PI 2 Server asks MultiNet to supply the hostname for a given PI
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 PI 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 PI
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 PI DataLink has connected to the PI 2 Server:
$ netstat

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.

Page 8

For the PI System Manager

Name Translation - TCPWare

Under TCPWare, the PI 2 Server asks TCPWare to supply the hostname for a given PI
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 PI 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 PI 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

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 that are available for download
from http://techsupport.osisoft.com/downloadcenter.aspx
(http://techsupport.osisoft.com/downloadcenter.aspx) under "PI 3 Enterprise Server".

PI DataLink User Guide

Page 9

Introduction

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 PI 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 available for download
from http://techsupport.osisoft.com/downloadcenter.aspx
(http://techsupport.osisoft.com/downloadcenter.aspx) under "PI 3 Enterprise Server".
Point Access/Data Access Attributes
When PI 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, PI 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, PI
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 PI 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 PI 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 available for download
from http://techsupport.osisoft.com/downloadcenter.aspx
(http://techsupport.osisoft.com/downloadcenter.aspx) under "PI 3 Enterprise Server".
Note: The user PIAdmin is a "super"-privileged user. A user of PI DataLink who logs in
as PIAdmin has read and write access to all tags. For this reason, PI DataLink
users normally should NOT log in as PIAdmin.

Page 10

Chapter 2: Add-in to Excel

Overview
The PI 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.
PI 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

PI DataLink User Guide

Page 11

Add-in to Excel

Tutorial
The goal of this tutorial is to get you started with using PI DataLink in Excel as quickly as
possible. PI 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 PI 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 menu bar, select Connections....

If the Status indicates that the PI Server is not connected, click the checkbox to connect. If the
default user account for your selected PI Server requires a password, the login dialog appears
to prompt you for the password:

Page 12

Tutorial

In this dialog, you can also change the user name to log in as a different user from the default
user.
A valid username/password changes the Status in the Connections dialog box and displays
the user that DataLink is connected as. Dismiss the Connections dialog box by clicking
Cancel.
If you receive a login failure dialog box, confirm that you have a valid PI
username/password. The appearance of the login failure dialog box even though the PI
username/password is valid indicates that PI DataLink cannot connect to the PI Server. Check
the Troubleshooting (page 137) section.

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.

PI DataLink User Guide

Page 13

Add-in to Excel

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

Page 14

Tutorial

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

PI DataLink User Guide

Page 15

Add-in to Excel

12. Click OK in the dialog box. PI 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. PI DataLink then retrieves engineering units into cells E2 to
E6.

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.

Page 16

Tutorial

4. Click OK. PI DataLink then retrieves interpolated data from midnight to 8:00am at
1-hour intervals.

PI DataLink User Guide

Page 17

Add-in to Excel

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. PI DataLink then retrieves
interpolated data from midnight to 9:00am at 1-hour intervals. Note that the array size has
increased by one row.

Page 18

Tutorial

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.

PI DataLink Summary
As the above examples indicate, the fastest way to use PI 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 PI DataLink retrieves the requested PI values. The next
sections describe the features of PI DataLink in greater detail.

PI DataLink User Guide

Page 19

Add-in to Excel

PI Menu
When PI DataLink is added to Excel, it adds the PI menu item to Excel's menu bar.

Page 20

PI Menu

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
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 PI DataLink settings and preferences
About displays version information on PI DataLink
Help displays help on PI DataLink

PI DataLink User Guide

Page 21

Add-in to Excel

Dialog Boxes
Edit Fields
The edit fields can contain either the necessary text information or references to cells, which
contain the necessary text information. PI DataLink determines the type of information
entered in the edit field by context.
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.

Page 22

Dialog Boxes

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, PI 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 PI
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
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.
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.

PI DataLink User Guide

Page 23

Add-in to Excel

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 PI DataLink settings.

Time in PI DataLink
Returned Values
The timestamps returned by the PI 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 PI 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.

Page 24

Time in PI DataLink

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 PI
DataLink. This is done via the PI > Settings... dialog box.

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.

PI DataLink User Guide

Page 25

Add-in to Excel

Page 26

Time in PI DataLink

Entering Timestamps into PI 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.
See Start and End Time (page 149) and Time Interval (page 150) 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, PI
DataLink does not display the timestamps.
If you reference an array of tags in either the Sampled Data or Calculated Data dialog box,
PI DataLink returns one common set of timestamps for the entire group of tags.

PI DataLink User Guide

Page 27

Add-in to Excel

Positioning Timestamp Data Returned by PI 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, PI 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.

Page 28

PI DataLink Functions

PI DataLink Functions
Functions vs. Values
When a PI DataLink dialog box brings data from the PI Server to Excel, it does not put the
actual value into a cell. Rather, PI 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, PI DataLink pastes the following function into the cell:
=PICurrVal("sinusoid",0,)

Excel then evaluates this function, and displays the resulting number. Thus, the PI DataLink
dialog boxes are a front end to construct the corresponding PI DataLink functions, and to
format the output.
These PI DataLink functions can also be entered manually into the cells in a worksheet. The
arguments to the function are described further in Details for PI DataLink Functions and
Dialog Boxes (page 32). Since most of the PI 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 PI 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 PI DataLink
functions. The only way to invoke the PI 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 PI DataLink.
The PI 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
PI DataLink is written in C++ and Visual Basic and utilizes both the PI System's SDK and
Microsoft Excel's API. When an error occurs at the PI SDK level, PI 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.

PI DataLink User Guide

Page 29

Add-in to Excel

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 PI DataLink functions.
Because PI 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 PI 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 PI DataLink function to run. Note that the value of the time stamp does not have
to change in order for Excel to trigger the PI 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 PI
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.

Page 30

PI DataLink Functions

Selecting an Entire DataLink Function

If a large PI 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 PI 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."

PI DataLink User Guide

Page 31

Add-in to Excel

Using Cell Reference in Arguments

You can use cell references for all the arguments in all of PI 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 PI DataLink Functions and Dialog Boxes

The following sections describe each of the PI 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.

Page 32

Details for PI DataLink Functions and Dialog Boxes

PICurrVal()
PICurrVal(tagname, outcode, PIServer)
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

Current value

Timestamps

Column 2

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

PI DataLink User Guide

Page 33

Add-in to Excel

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
Required Fields
Tagname or Expression
Timestamp

Related Topics
PIArcVal() (page 34)
PIExpVal() (page 35)
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

Archive value

Timestamp

Column 2

Archive value

An output code of 2 transposes the output array that results from an output code of 1.

Page 34

Details for PI DataLink Functions and Dialog Boxes

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")

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

Archive value

Timestamp

Column 2

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")

PI DataLink User Guide

Page 35

Add-in to Excel

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
http://techsupport.osisoft.com/downloadcenter.aspx
(http://techsupport.osisoft.com/downloadcenter.aspx) under "PI 3 Enterprise Server".
For PI 2, choose a tag attribute from the combo box. The default attribute is descriptor. Tag
attributes are:

Page 36

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

Details for PI DataLink Functions and Dialog Boxes

Attribute

Explanation

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)

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 35).

PIServer (string)

The PI Server.

Returns
Tag attribute

PI DataLink User Guide

Page 37

Add-in to Excel

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
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 146) 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"

Page 38

Details for PI DataLink Functions and Dialog Boxes

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.
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 146)
PINCompDat() (page 39)
PINCompFilDat() (page 40)
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.

PI DataLink User Guide

Page 39

Add-in to Excel

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")

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 146) 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.

Page 40

Details for PI DataLink Functions and Dialog Boxes

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.
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 146) 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.

PI DataLink User Guide

Page 41

Add-in to Excel

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 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 146)
PICompDat() (page 42)
PICompFilDat() (page 43)
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.

Page 42

Details for PI DataLink Functions and Dialog Boxes

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 146) 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.

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.

PI DataLink User Guide

Page 43

Add-in to Excel

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 146)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 146)
PISampDat() (page 44)
PISampFilDat() (page 46)
PIExpDat() (page 47)
PISampDat()
PISampDat(tagname, stime, etime, interval, outcode, PIServer)

Arguments

Page 44

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.

Details for PI DataLink Functions and Dialog Boxes

Argument

Explanation

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

Sampled data

Timestamps

Column 2

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.

PI DataLink User Guide

Page 45

Add-in to Excel

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.

filtexp (string)

The filter expression. See Filter Expressions (page 146) 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

Sampled data

Timestamps

Column 2

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.

Page 46

Details for PI DataLink Functions and Dialog Boxes

PIExpDat()
PIExpDat(expression, stime, etime, interval, outcode, PIServer)

Arguments
Argument

Explanation

expression (string)

The calculation expression. See Calculation Expressions (page 143) 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

Calculated data

Timestamps

Column 2

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.

PI DataLink User Guide

Page 47

Add-in to Excel

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 48)
PITimeExpDat() (page 49)
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")

Page 48

Details for PI DataLink Functions and Dialog Boxes

PITimeExpDat()
PITimeExpDat(expression, timestamps, PIServer)

Arguments
Argument

Explanation

expression (string)

The calculation expression. See Calculation Expressions (page 143)

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

PI DataLink User Guide

Page 49

Add-in to Excel

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.
Check Box
Check show pctgood if you want PI 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

Minimum

Time of min. value

Minimum value

Maximum

Time of max. value

Maximum value

Range

Time of min. value

Time of max. value

Column 3

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.

Page 50

Details for PI DataLink Functions and Dialog Boxes

PI DataLink User Guide

Page 51

Add-in to Excel

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

Units/minute

1440

60

Units/second

86400

3600

Related Topics
PICalcVal() (page 52)
PICalcDat() (page 54)
PICalcVal()
PICalcVal(tagname, stime, etime, mode, cfactor, outcode, PIServer)

Arguments

Page 52

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 49) under Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Details for PI DataLink Functions and Dialog Boxes

Returns
If the outcode is 0, only the calculated value is returned.
If the outcode is 1, the following applies:
Mode

Column 1

Column 2

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

Average

Average value

Count

Count value

Mean

Mean value

Time of max. value

Column 3

Range 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

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

Average

Average value

Percent good

Count

Count value

Percent good

Mean

Mean value

Percent good

Range value

Column 4

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.

PI DataLink User Guide

Page 53

Add-in to Excel

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 49) under Calculated Data Dialog
Box (page 49).

outcode (integer)

An output code; 0-7.

PIServer (string)

The PI Server.

Returns
The outcode affects the output as follows:

Page 54

Calculated values along a column

Timestamps and values along 2 columns

Calculated values along a row

Timestamps and values along 2 rows

Values and pctgood along 2 columns

Timestamps, values, and pctgood along 3 columns

Values and pctgood along 2 rows

Timestamps, values, and pctgood along 3 rows

Details for PI DataLink Functions and Dialog Boxes

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 143) 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 146)
for more information on the filter expression syntax.

PI DataLink User Guide

Page 55

Add-in to Excel

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

Page 56

Details for PI DataLink Functions and Dialog Boxes

Check Box
Refer to the Check Box description under Calculated Data Dialog Box (page 49).
Special Notes
Refer to the Special Notes section under Calculated Data Dialog Box (page 49).
Related Topics
Filter Expressions (page 146)
PIAdvCalcVal() (page 58)
PIAdvCalcFilVal() (page 59)
PIAdvCalcExpVal() (page 60)
PIAdvCalcExpFilVal() (page 61)
PIAdvCalcDat() (page 62)
PIAdvCalcFilDat() (page 63)
PIAdvCalcExpDat() (page 64)
PIAdvCalcExpFilDat() (page 65)

PI DataLink User Guide

Page 57

Add-in to Excel

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 49) under
Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcVal() (page 52) 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.

Page 58

Details for PI DataLink Functions and Dialog Boxes

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 146) 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 49) under
Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcVal() (page 52) 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
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.

PI DataLink User Guide

Page 59

Add-in to Excel

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 49) under
Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcVal() (page 52) 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.

Page 60

Details for PI DataLink Functions and Dialog Boxes

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 146) 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 49) under
Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcVal() (page 52) 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'="Prod
uct2"", "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.

PI DataLink User Guide

Page 61

Add-in to Excel

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 49) under
Calculated Data Dialog Box (page 49) .

outcode (integer)

An output code; 0-7.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcDat() (page 54) 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.

Page 62

Details for PI DataLink Functions and Dialog Boxes

PIAdvCalcFilDat()
PIAdvCalcFilDat(tagname, stime, etime, interval, filtexp, mode,
calcbasis, sampmode, sampinterval, 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.

filtexp (string)

The filter expression. See Filter Expressions (page 146) 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 49) under
Calculated Data Dialog Box (page 49).

outcode (integer)

An output code; 0-7.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcDat() (page 54) 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""","tota
l",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.

PI DataLink User Guide

Page 63

Add-in to Excel

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 49)
under Calculated Data Dialog Box (page 49).

outcode (integer)

An output code; 0-7.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcDat() (page 54) 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,"compr
essed", "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.

Page 64

Details for PI DataLink Functions and Dialog Boxes

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 146)

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 49) under Calculated Data Dialog Box (page 49).

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

Returns
Refer to Returns section for PICalcDat() (page 54) 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.

PI DataLink User Guide

Page 65

Add-in to Excel

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 143) 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 143)
PITimeFilterVal() (page 67)
PITimeFilter() (page 68)

Page 66

Details for PI DataLink Functions and Dialog Boxes

PITimeFilterVal()
PITimeFilterVal(expression, stime, etime, timeunit, outcode,
PIServer)

Arguments
Argument

Explanation

expression (string)

The calculation expression. See Calculation Expressions

(page 143) 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.

PI DataLink User Guide

Page 67

Add-in to Excel

PITimeFilter()
PITimeFilter(expression, stime, etime, interval, timeunit, outcode,
PIServer)

Arguments
Argument

Explanation

expression (string)

The calculation expression. See Calculation Expressions

(page 143) 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

Calculated data

Timestamps

Column 2

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.

Page 68

Details for PI DataLink Functions and Dialog Boxes

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 69)
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")

PI DataLink User Guide

Page 69

Add-in to Excel

Attribute Mask to Tag Dialog Box

This dialog box returns a list of tags which match the tag attribute masks specified.
Required Fields
Tagname
Descriptor
Point Source
Point Type
Point Class
Engineering Units

Related Topics
PIAttributeMaskToTag () (page 70)
PIAttributeMaskToTag ()
PIAttributeMaskToTag(tagname, descriptor, pointsource, pointtype,
pointclass, engunits, outcode, PIServer)

Arguments

Page 70

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.

Details for PI DataLink Functions and Dialog Boxes

Returns
Outcode

Column 1

Tagname

Column 2

An output code of 2 transposes the output array that results from an output code of 1.
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 71)
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.

PI DataLink User Guide

Page 71

Add-in to Excel

Returns
Outcode

Column 1

Tagname

Tagname

Column 2

Server of tag

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 73)

Page 72

Details for PI DataLink Functions and Dialog Boxes

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.

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")

PI DataLink User Guide

Page 73

Add-in to Excel

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.

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

Page 74

Details for PI DataLink Functions and Dialog Boxes

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 PI 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.
The Plot as stepped data option gives the trace a jagged-saw look. This option is usually
specified for discrete tags.

PI DataLink User Guide

Page 75

Add-in to Excel

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.

Page 76

Details for PI DataLink Functions and Dialog Boxes

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.

PI DataLink User Guide

Page 77

Add-in to Excel

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.

Page 78

Details for PI DataLink Functions and Dialog Boxes

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.

PI DataLink User Guide

Page 79

Add-in to Excel

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

Page 80

Details for PI DataLink Functions and Dialog Boxes

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

PI DataLink User Guide

Page 81

Add-in to Excel

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.

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.

Page 82

Details for PI DataLink Functions and Dialog Boxes

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

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.

PI DataLink User Guide

Page 83

Add-in to Excel

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.

Select this check box to force PI 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 PI DataLink to parse the time string according to your
local regional settings, including date-time format preferences. If locale-specific
parsing fails, PI 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 PI DataLink version information.

Help
This menu choice calls PI DataLink Help.

Writing Data from Excel to PI

PI DataLink allows you to write a value from the worksheet to the PI Server. The PI
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."

Page 84

Writing Data from Excel to PI

PIPutVal()
PIPutVal(tagname, value, time stamp, PIServer, outcell)

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

PI DataLink User Guide

Page 85

Add-in to Excel

Limits from Excel for PI DataLink

Excel has a limitation on the number of elements in a calculation array. PI 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 PI DataLink has a 255 character limitation on string length. Hence,
input strings to DataLink like PI DataLink formulas or expressions in a reference cell cannot
exceed 255 characters. Similarly, string output from PI DataLink, like PI string tag results,
will be truncated by PI DataLink to 255 characters.

Page 86

Chapter 3: Add-in for Lotus 1-2-3

The PI DataLink add-in for Lotus 1-2-3 provides users with the ability to exchange PI tag
data with their PI Server(s) directly. With PI DataLink, users can import PI data in various
forms from a PI Server. Moreover, PI DataLink gives users the ability to write values for a PI
tag back into a PI Server.
PI DataLink provides the following functions to retrieve data from the PI Server:
Current value.
Value at a specific time.
Tag attributes.
Evenly spaced (sampled) data.
Sampled data while a given expression was true.
Compressed (archived) data.
Compressed data while a given expression was true.
Sampled PI tag data synchronized with a user specified array of timestamps.
Data from calculations on PI tag expressions.
The amount of time while a particular PI tag expression was true.
Totals, minima, maxima, standard deviations, ranges, averages and means for PI tags.

PI DataLink User Guide

Page 87

Add-in for Lotus 1-2-3

Tutorial
The goal of this section is to get you started using PI DataLink in Lotus 1-2-3 as quickly as
possible. PI 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 PI DataLink has been installed properly and that it
can connect to the PI Server.
Start Lotus 1-2-3. PI DataLink should bring up a dialog page. Select the button <dialog
boxes> to load the dialog boxes under the PI menu choice. Make sure that the PI menu
choice is in Lotus 1-2-3's menu bar. If the PI menu does not appear on the main 1-2-3 menu,
please refer to the section on Troubleshooting (page 137).
From the PI menu, select Connections...

If the Status indicates that the PI Server is DISCONNECTED, click the Connect button. If
the default user account for your selected PI Server requires a password, the login dialog
appears to prompt you for the password.

Page 88

Tutorial

In this dialog, you can also change the user name to log in as a different user from the default
user.
A valid username/password changes the Status in the Connections dialog box to either
READ or READ/WRITE. Dismiss the Connections dialog box by clicking Cancel.
If you receive a login failure dialog box, confirm that you have a valid PI
username/password. The appearance of the login failure dialog box even though the PI
username/password is valid indicates that PI DataLink cannot connect to the PI Server. Check
the Troubleshooting (page 137) section.

Tag Attributes and Current Value

In this example, we will obtain the tag descriptor, current value, and engineering units for a
few tags.
1. Load the file ...\pipc\lotus\pidl_tutorial.123.
2. Connect to a valid PI Server in the connection dialog box.
3. From the PI menu bar, select Settings... and make sure that the "In a column" radio button
in the "Copy items to sheet" section is chosen:

PI DataLink User Guide

Page 89

Add-in for Lotus 1-2-3

4. Next, dismiss the dialog box and move the cursor to cell A2 in the spreadsheet.
5. Select Tag Search... from the PI menu and enter BA into the Tag Mask field so that it
reads "BA*".

Page 90

Tutorial

6. Click Search to find tags that begin 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.
7. 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
the four other tags. Then, click OK to copy the five tags along a single column, from A2
to A6.
8. Move the cursor to cell B2. From the PI menu, select Tag Attributes....

Notice that the current cell shows as the default in the Data output edit box.
9. Click the button to the right of the second edit box "Cells" under Tagname.

10. The current cell shows as the default. Highlight cells A:A2..A:A6. Manual input ranges
are also acceptable.

PI DataLink User Guide

Page 91

Add-in for Lotus 1-2-3

11. When the edit box contains a valid range press OK. Notice the selected range is written
into the edit box on the Tag Attributes dialog box. If a single cell is selected, the text in
that cell is also displayed in the tagname edit box. If a range is selected, then just the
range is displayed and nothing is written to the tagname edit box. A single cell, a single
column, and a single row of tag names (on the same sheet) are examples of a valid range.
Invalid ranges are multiple ranges, ranges that consist of more than one sheet, a range
consisting of more than one column and row, or any cell address that does not contain tag
names.
12. From the list box labeled "Attributes" scroll down until the word "Descriptor" is visible.
Select "Descriptor."
13. In the edit box labeled "Macro Output [Opt]," manually enter the cell address as A:A10.
Alternatively, the "cell" button could have been selected, as described above. This option
will write the macro code associated with {PITAGATT} to the macro output cell address.
Note that the cell address is used in the macrocode when a cell address is designated in
the tagname address edit box. The absolute tag name is used if a tagname is written into
the tagname edit box. If both the cell address and a specific tag name are used, the
tagname will have priority and appears in the resulting macro.
14. If the user wants to get data from a server other than the default, the name of the server
should be entered into the designated edit box. No input is required for the PI Server edit
box if the default server is desired.

15. Click OK. PI DataLink will write the tag descriptors into cells A:B2..A:B6. It will also
write the necessary macro code used to obtain the tag descriptors into cells
A:A10..A:A14. Move the cell cursor to cell A:C2.

Page 92

Tutorial

16. From the PI menu, select Current Value....

17. In the second edit box under tagname, manually enter the cell address A:A2..A:A6 or
click the button beside the edit box and select A:A2..A:A6.
18. In the edit box labeled "Macro Output [Opt]," note that the cell address A:A15 already
exists. This is a feature that automatically pastes macro code below the previous macro
code entry until the user executes a dialog box without a cell address in the "Macro
Output [Opt]" edit box.
19. In the Data Output edit box, notice that the default cell address is already A:C2.
20. Below the Data Output edit box there are three radio buttons describing the relative
output location of the timestamp to that of the data. Select "Time on left."
21. Click OK and PI DataLink will write the current values into cells A:D2..A:D6 with their
associated timestamps into A:C2..A:C6. Also, notice that the associated macrocode is
written into cells A:A15..A:A19.
22. Move the cell cursor to cell A:E2. From the PI menu, select Tag Attributes... again.
23. In the second edit box under tagname, either manually enter the cell address A:A2..A:A6
or click the button beside the edit box and select A:A2..A:A6.
24. Select "Units" in the Attributes list box.
25. In the edit box labeled "Macro Output [Opt]," enter the cell address A:A20.
In the Data Output edit box, notice that the default cell address is already A:E2.

PI DataLink User Guide

Page 93

Add-in for Lotus 1-2-3

26. Click OK and PI DataLink will write the engineering units into cells A:E2..A:E6 and the
associated macro code into cells A:A20..A:A24.

27. Move the cursor to cell A:A10. From the PI menu, select Tag Attributes.... Notice that the
dialog box is completely filled in based on the information provided in the macro in
A:A10. This is a time saving feature that is helpful when similar macrocode already
exists for the desired operation.
28. Experiment by moving the cursor to cell A:A15 and selecting Current Value... from the
PI menu.
29. Place the cursor on cell A:A2. From the PI menu, select Current Value.... Notice that the
dialog box detects that there is a tagname in the current cell and attempts to fill in the
dialog box as much as possible. The tagname is written to the tagname edit box. Since
there is data with timestamps directly to the right of the tagname, the dialog box writes to
the output cell edit box A:B2 with timestamps on the left.
30. Experiment by selecting ranges of tag names and selecting Current Value... or Tag
Attribute....
31. Experiment by selecting the entire range A:A2..A:A6 and then opening either the Current
Value... or the Tag Attribute... dialog box from the PI menu option.
32. To update the table created in prior steps, place the cursor on cell A:A10. Press the ALT
and F3 keys simultaneously. The Run Scripts & Macros dialog box appears:

Page 94

Tutorial

33. Click the Macro radio button and then click Run or press the Enter key. Lotus 1-2-3
executes the macro commands contained in cells A:A10 through A:A24.
The macro commands and their functions are summarized below:
Cell

Macro command

Function

A10

{PITagAtt}

Get a tag attribute (descriptor)

A11

{PITagAtt}

Get a tag attribute (descriptor)

A12

{PITagAtt}

Get a tag attribute (descriptor)

A13

{PITagAtt}

Get a tag attribute (descriptor)

A14

{PITagAtt}

Get a tag attribute (descriptor)

A15

{PICurrVal}

Get the current value

A16

{PICurrVal}

Get the current value

A17

{PICurrVal}

Get the current value

A18

{PICurrVal}

Get the current value

A19

{PICurrVal}

Get the current value

A20

{PITagAtt}

Get a tag attribute (units)

A21

{PITagAtt}

Get a tag attribute (units)

A22

{PITagAtt}

Get a tag attribute (units)

A23

{PITagAtt}

Get a tag attribute (units)

A24

{PITagAtt}

Get a tag attribute (units)

After Lotus 1-2-3 executes the macro commands, cell B2 contains the descriptor for the tag,
BA:ACTIVE.1, cell D2 the current value for BA:CONC.1, cell C2 the corresponding time,
and cell E2 the engineering units. Similar data are found for the tags BA:LEVEL.1,
BA:PHASE.1, and BA:TEMP.1 in cells B3 through E3, B4 through E4, B5 through E5, and
B6 through E6, respectively.

PI DataLink User Guide

Page 95

Add-in for Lotus 1-2-3

Note that a single quote (or apostrophe) prefaces many of the arguments to the macro
commands in A10 through A24. The reason is that Lotus 1-2-3 uses a single quote to indicate
a label or a string.
For example, the macro command in cell A10 and its arguments are:
{PITagAtt c2,'descriptor,',d2}
A reference to a tagname (cell C2);
A tag attribute ('descriptor);
No PI Server specified (blank label, or just a single quote or apostrophe); and
A cell representing the output cell (cell D2).

In the above macro command, there is a single space between the macro name (PITagAtt)
and the first macro argument (c2). Also, there are no spaces between each argument in the
macro and commas serve as argument separators.
If no PI Server is specified in the PIServer argument (i.e., blank, or just a single quote)
PI DataLink gets PI tag information from the default server. This is the PI Server specified in
your PILogin.ini file, which can be modified by using the PI > Connections... dialog box.

Actual Values from PI Data Archive

In this example, we gather sampled data for a single tag.
1. Move the cursor to cell A:C10. From the PI menu, select Tag Search. The Tag Search
dialog box then appears.
2. Enter "CD" into the Tag Mask field so that it reads "cd*". Click Search to search for tags
that begin with CD. The tag "cdt158" should be one of the tags returned. Select this tag
(or any other tag) and click OK. The tag cdt158 is copied to cell A:C10 (the current
active cell in the spreadsheet).
3. Click on cell A:E:10 to make it the active cell. Go to the PI menu again and select
Compressed Data (times) ....

Page 96

Tutorial

4. Click the tagname cell reference button marked "Cell" and select cell A:C10. Enter a t
(for midnight today) in the Start time field, a +8h (eight hour offset) in the End time field.
Click the Show Times check box.
5. Click OK. PI DataLink will retrieve archived data from midnight to 8:00am into the
range, A:C10..A:C18.

PI DataLink Summary
As the above examples indicate, the fastest way to use PI DataLink to transfer data between
PI and 1-2-3 is to select an option from the PI menu. A dialog box appears. Enter the
appropriate parameters and PI DataLink retrieves the requested PI values. The next sections
describe the features of PI DataLink in greater detail.

PI DataLink User Guide

Page 97

Add-in for Lotus 1-2-3

PI Menu
When PI DataLink is added to Lotus 1-2-3, it adds the PI menu item to 1-2-3's menu bar.

Page 98

PI Menu

The following pop-up menu selections are available from this menu item:
Current Value retrieves the current value for a tag.
Archive Value retrieves a single value from the archive (may be interpolated).
Exact Time Value retrieves a single value for a specific timestamp from the archive.
Calculated Value retrieves a single calculated (total, minimum, maximum, range,

standard deviation, average or mean) value.

Tag Attributes retrieves a tag attribute.
Sampled Data retrieves evenly spaced (sampled) data from the archive.
Compressed Data (number) retrieves compressed data based on a start time and a

specified number of values.

Compressed Data (times) retrieves compressed data based on a start time and an end

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

Filtered Sampled Data retrieves evenly spaced (sampled) data that satisfy a filter

condition.
Filtered Compressed Data (number) retrieves a specified number of compressed data

that satisfy a filter condition.

Filtered Compressed Data (time) retrieves compressed data that satisfy a filter

condition for a given start time and end time.

Expression Calculation retrieves data from calculations on tag expressions.
Time Filtered computes amount of time while a tag expression was true.
Connections manages PI server connections.
Tag Search searches for tags on connected PI servers.
Settings displays PI DataLink settings and preferences.
About displays version information on PI DataLink.
Help displays help on PI DataLink.

PI DataLink User Guide

Page 99

Add-in for Lotus 1-2-3

Dialog Boxes
The following sections describe the user interaction and operation with the dialog boxes.

Edit Fields
There are two types of edit fields in the dialog boxes: text edit fields and reference edit fields.
A Cell (or Cells) indicates reference edit fields next to the edit box. In a text edit field, you
type in the requested information. For example, in the Tagname field, type the name of the
tag for which you want data.
However, in a reference (Cell) edit field, you need to enter a reference to a cell on the
spreadsheet that contains the necessary information. In an array reference edit field, you may
enter a reference to an array of cells on the spreadsheet. In either case, you may also use the
mouse to click the Cell or Cells button which brings up the cell reference dialog box. Then
you can click the cell (or click the cell and drag to adjacent cells) on the spreadsheet. In this
procedure, Lotus 1-2-3 automatically enters the cell reference(s) into the edit field for you.
For example, in the PICurrVal dialog box in the tutorial section, the reference edit fields for
Tagname and Output ask for, a cell on the spreadsheet that contains the tagname and a cell
on the spreadsheet into which you wish to place the output of the current value, respectively.
Many of the parameters contain both a text edit field and a reference edit field. If entries exist
in both the text edit field and the reference edit field, the text edit field will override the
cell/range reference.

Optional Fields
The PIServer, Macro Output and Output fields in all of the dialog boxes are labeled as
"opt." or optional. If the PIServer text edit field is left blank, PI DataLink will connect to the
default PI Server. You can change the default PI Server in the Connection Dialog Box from
the PI menu.
The Macro Output field is a reference edit field, which allows you to specify the upper left
hand corner of the range where PI DataLink will place the macro code that retrieves your
data. The macro is useful if you want to run the command again to retrieve a new set of data
later.
The Output field allows you to specify the upper left-hand corner of the range where PI
DataLink will place the resulting data. If you do not specify an Output cell, this field defaults
to the active cell in the current worksheet.

Page 100

Dialog Boxes

Data Displayed as Columns or Rows

For dialog boxes that are expected to return an array of PI values (e.g., Sampled data), there is
a set of radio buttons with options column(s) or row(s). Choose column(s) to display the
data in one column (or two columns if timestamps are also displayed). Choose row(s) to
display the data in either one row or two rows.
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 selection of row/column option in determining the orientation of the output data.

List Boxes
List boxes appear for the Attribute field in Tag Attributes... and for the Mode field in the
Calculated value..., and Calculated data... dialog boxes. The default item in these list boxes is
the first item in the list. Thus, the default point attribute to retrieve from Tag Attributes... is
Descriptor and the default calculation mode is Average.

Tag Search in Dialog Boxes

The Tag Search button in the dialog boxes allows you to search the PI database for tags.
Unfortunately, the feature that allows the selected tag to be pasted into the PI DataLink dialog
box does not work in PI DataLink for 1-2-3.

Automatic Filling of Dialog Boxes

Where the cursor is placed in the spreadsheet upon opening a dialog box will determine how
completely the dialog box is filled in. If there is macro code that already exists for a given
dialog box, and the cursor is placed over the macro code when the dialog box is opened, the
dialog box will be completely filled in based on the macro code. For example, suppose the
cursor were placed over a cell that contained the macro code below:
{PICALCVAL 'Sinusoid,'T,'*,'Average,1,0,'CASABA,A:B2}

If the Calculated Value... is now selected from the PI menu option, the following dialog box
appears:

PI DataLink User Guide

Page 101

Add-in for Lotus 1-2-3

You can then make minor changes to the dialog box, and execute the dialog box.
The above automatic filling of dialog boxes is not available for the Time Filtered... dialog box
in PI DataLink 1.9.
PI123DLG.123 will try to determine how to fill in the dialog box based on where the cursor
is placed in a spreadsheet containing data. For example, if the cursor is placed on a tagname
with two recognizable timestamps to the right of the tagname and a time interval to the right
of the timestamps, PI123DLG.123 will insert the spreadsheet information into the dialog box
appropriately.
The spreadsheet below depicts the above scenario:

Page 102

Dialog Boxes

When the Sampled Data... dialog box is opened with the range A1...A4 selected, the Sampled
Data dialog box would appear as below:

Notice that the Data Output cell is assumed to be the first free cell to the right of the
spreadsheet information. In the above case, the default Data Output cell is A:E1. This
scenario would also work if the spreadsheet data were below the tagname in column A.

PI DataLink User Guide

Page 103

Add-in for Lotus 1-2-3

Macro Output Option

Each dialog box has the Macro Output option. The Macro Output option will allow you to
specify where to write the macro string(s) associated with each dialog box. The macro code
written to the designated output cell address will be based on the information given in the
dialog box. This option is helpful when constructing a spreadsheet that you want to update in
the future. After the spreadsheet is constructed using the dialog boxes along with the macro
output option, you may run the constructed macrocode to update the spreadsheet instead of
reopening all of the dialog boxes.
PI123DLG.123 tracks which cells macrocode is being written to for the purpose of
automatically filling in the Macro Output reference address upon opening a dialog box. The
tracking mechanism is invoked when you first input a cell address into the Macro Output
reference edit field. After which, PI123DLG.123 assumes you would like to continue writing
code to the next available row in the same column as the previous macrocode was written to.
The tracking mechanism is canceled when a dialog box is executed with no cell address in the
Macro Output dialog box, or the previous macro generated in the spreadsheet was deleted, or
the user selects a different file.
The tracking mechanism eliminates manual cell address input when creating spreadsheets that
require several dialog box executions. Macro code will automatically be generated so that
future updates of the spreadsheets can be done simply by executing the macros instead of
reopening dialog boxes.

Time in PI DataLink
Returned Values
The timestamps returned by PI DataLink are in Lotus 1-2-3 format; i.e., it is a number that
represents the number of days since 1900. For example, 24-Jul-00 07:12:00 AM is entered
into a cell as the number 36731.3.
PI DataLink automatically formats these timestamps into a date and time format i.e.,
07/24/2000 07:12:00 AM. You can change this time format to another by selecting the cells
and using the Format... feature from the Range option of the menu bar. See your Lotus 1-2-3
documentation for more information.

Time Arguments in Macro Commands

Many of the macro commands call for a start time and end time. For these arguments, you
may enter the time string as an argument or refer either to cells that contain a PI time in string
format or to cells that contain a time in Lotus 1-2-3 value format.

Page 104

Time in PI DataLink

Note that for PI time in relative time format (e.g., '-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.
Refer to Examples of PI Time Strings (page 149) for examples of valid PI time strings. Place
parentheses around the time string if your time string is an absolute timestamp e.g., use
'(24-jun-00 13:38) to represent 1:38pm on June 24th, 2000.

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 left most column if the column(s) radio button is
selected; along the top most row if the row(s) is selected. If this box is unchecked, PI
DataLink does not display the timestamps.
If you reference an array of tags in either the Sampled data or Calculated data dialog box, PI
DataLink returns one common set of timestamps for the entire group of tags.

No Timestamp/Time at Left/on Top Radio Buttons

Some of the dialog boxes that return a single value (for example, Current Value) have a set of
radio buttons with a choice of:
no timestamp
time at left
time on top

Choose time at left if you want PI DataLink to return a timestamp into a cell to the left of the
retrieved values. Choose time on top if you want to display the timestamp in a cell on top of
the retrieved values.
However, if you use an array reference in the Tagname field and select either the time at left
or the time on top radio button, PI DataLink returns the timestamp and value depending on
whether the reference of tag names is horizontal or vertical. Specifically, when the tag names
are in a single column, the timestamps will appear to the left of the values. Likewise, when
the tag names are along a single row, the timestamps will appear on top of the values.

PI DataLink User Guide

Page 105

Add-in for Lotus 1-2-3

PI DataLink Custom Macro Commands

Macro vs. Dialog Box
When a PI DataLink dialog box brings data from the PI Server to Lotus 1-2-3, it first
generates the PI custom macro command and then executes the macro to put the data into the
output cell. You can achieve the same result by typing the macro and executing the macro
manually. However, it is much easier to generate the macro string with the dialog boxes,
especially for functions with complex output options.

Error Reporting
PI DataLink is written in LotusScript and C++ and utilizes both the PI System's API and
Lotus 1-2-3's SDK. When an error occurs at the PI API level, PI DataLink displays the PI
API error in the cell. For example, if you try to find the current value for a tag which does not
exist, the message "Tag not found: -5" appears in the output cell.

Updating PI Data in a Spreadsheet

As PI DataLink pulls data into Lotus 1-2-3 using custom macro commands, the spreadsheet
does not update automatically. When you change a cell entry in the spreadsheet, you must
re-run the macro command(s) that references the cell that has been modified in order for your
spreadsheet to display new values. You must also re-execute macro commands that contain
relative timestamps. In addition, you will have to re-run the {PICurrVal} macro every time
you want the current value for a tag.
For example, the command:
{PIArcVal a1,'t+8h,1,',d1}

retrieves a value from the archive for the tag located in cell A1 at 8:00am of the current day.
You must re-run this macro when (1) you change the contents of the cell A1 and (2) when
you call up the spreadsheet for the first time each day because t+8h is a relative timestamp.

Page 106

Dialog Box and PI Custom Macro Details

Dialog Box and PI Custom Macro Details

The following sections describe each of the PI DataLink functions in detail. Each section
describes the dialog box first and then discusses each of the arguments for the corresponding
PI macro function.

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.

{PICurrVal}
{PICurrVal tagname, outcode, PIServer, outcell}

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

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Current value

Timestamps

Column 2

Current value

An output code of 2 transposes the output array that results from an output code of 1.
Example
To get the current value for cdf144 from the PI Server MYVAX and place the result into cell
A5:
{PICurrVal 'cdf144,0,'myvax,A5}

PI DataLink User Guide

Page 107

Add-in for Lotus 1-2-3

Archive Value Dialog Box

This dialog box gets a value at a specified time. The result is an interpolated value, except for
resolution code 4 tags on PI 2 Server. For this special case, the value at or before the
specified time is returned.
Required Fields
Tagname. The reference to Tagname may be an array
Timestamp

{PIArcVal}
{PIArcVal tagname, timestamp, outcode, PIServer, outcell}

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

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Archive value

Timestamp

Column 2

Archive value

An output code of 2 transposes the output array that results from an output code of 1.
Example
To get the archive value from the PI Server PHOEBE for the tag sinusoid at midnight
yesterday and place the result into an output range whose upper left-hand corner is cell A5:
{PIArcVal 'sinusoid,'y,0,'phoebe,A5}

Page 108

Dialog Box and PI Custom Macro Details

Exact Time Value Dialog Box

This dialog box gets a value from the PI Server for a specified time if an entry exists in the
archive at that time. If no value exists, the message "No archive entry at given time" is
returned.
Required Fields
Tagname. The reference to Tagname may be an array.
Timestamp

{PIExTimeVal}
{PIExTimeVal tagname, timestamp, PIServer, outcell}

Arguments
Argument

Explanation

tagname (string)

The tag for which you want the archive value.

time stamp (string)

The PI timestamp.

PIServer (string)

The PIServer.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
A value from the PI Server if it exists. If no value exists, the message "No archive entry at
given time" is returned.
Example
To get the archive value from the PI Server PHOEBE for the tag sinusoid at exactly midnight
yesterday and place the result into an output range whose upper left-hand corner is cell A5:
{PIExTimeVal 'sinusoid,'y,'phoebe,A5}

PI DataLink User Guide

Page 109

Add-in for Lotus 1-2-3

Calculated Value Dialog Box

This dialog box returns a single calculated value from a range of archived values of a tag.
Calculation modes are
Total (time-weighted)
Minimum
Maximum
Standard deviation (time-weighted)
Range
Average (time-weighted)
Mean (non-time-weighted)

Required Fields
Tagname. The reference to tagname may be an array
Start time
End time
Conversion factor
Calculation mode

Check Box
Check show pctgood if you want PI DataLink to display the percentage of the time range that
contained good values. 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 time on top button is selected, the percent good value is returned
in the cell below the calculated value cell.
Timestamp(s) are returned when the calculation mode is minimum, maximum, or range.

Page 110

Mode

Column 1

Column 2

Minimum

Time of min. value

Minimum value

Maximum

Time of max. value

Maximum value

Range

Time of min. value

Time of max. value

Column 3

Range value

Dialog Box and PI Custom Macro Details

Special Notes
When the calculation mode is Total and part of the archived data within the range is 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 used most often when the calculation mode is Total and the time
unit of the PI tag being totalized is not the same as the server default. For example, the time
unit of the server default is unit/day and the PI tag being totalized has units/hour, then use
conversion factor of 24. For PI 2 Server with default rate of units per hour, use conversion
factors of:
0.041667 for units/day
1 for units/hour
60 for units/minute
3600 for units/second

{PICalcVal}
{PICalcVal tagname, stime, etime, mode, cfactor, outcode, PIServer,
outcell}

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 or mean).

cfactor (number)

Should be 1 for max, min, avg, std and range. See special
note above for total.

outcode (integer)

An output code; 0-7 except 3.

PIServer (string)

The PI Server.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
If the outcode is 0, only the calculated value is returned.

PI DataLink User Guide

Page 111

Add-in for Lotus 1-2-3

If the outcode is 1, the following applies:

Mode

Column 1

Column 2

Total

Total value

Minimum

Time of min. value

Minimum value

Maximum

Time of max. value

Maximum value

Stdev

Standard deviation Value

Range

Time of min. value

Average

Average value

Mean

Mean value

Column 3

Time of max. value

Range 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

Total

Total value

Percent good

Minimum

Time of min. Value

Minimum value

Percent good

Maximum

Time of max. Value

Maximum value

Percent good

Stdev

Standard deviation

Percent good

Range

Time of min. Value

Time of max. Value

Average

Average value

Percent good

Mean

Mean value

Percent good

Range value

Column 4

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.
Example
To get the time of and minimum value (with a multiplicative factor of 1) during the most
recent 8 hours for the tag sqf100 from the default PI Server and place the result into an output
range whose upper left-hand corner is cell A5:
{PICalcVal 'sqf100,'*-8h,'*,'minimum,1,1,',A5}

Page 112

Dialog Box and PI Custom Macro Details

Tag Attributes Dialog Box

This dialog box retrieves a point attribute for a given tag.
Required Fields
Tagname. The reference to Tagname may be an array.
Tag attribute.

Choose a tag attribute from the list 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

PI DataLink User Guide

Page 113

Add-in for Lotus 1-2-3

Attribute

Explanation

compmax

Compression maximum time in seconds

totalcode

Totalization code

convers

Conversion factor for post-processed 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)

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

Tag point number

pointid

Internal point id number

{PITagAtt}
{PITagAtt tagname, attribute, PIServer, outcell}

Arguments
Argument

Explanation

tagname (string)

The tag for which you want an attribute.

Attribute (string)

The tag attribute, see above list.

PIServer (string)

The PI Server.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Tag attribute
Example
To get the tag descriptor for sinusoid from the default PI Server and place the result into cell
A5:
{PITagAtt 'sinusoid,'descriptor,',A5}

Page 114

Dialog Box and PI Custom Macro Details

Sampled Data Dialog Box

This dialog box gathers evenly spaced, sampled values from the archive.
Required Fields
Tagname. The reference to Tagname may be an array
Start Time
End Time
Time Interval

{PISampDat}
{PISampDat tagname, stime, etime, interval, outcode, PIServer,
outcell}

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.

Outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Sampled data

Timestamps

Column 2

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
To get sampled data for sinusoid at three-hour intervals from midnight yesterday to midnight
today and place the result into an output range whose upper left hand corner is cell A5:
{PISampDat 'sinusoid,'y,'t,'3h,1,',A5}

PI DataLink User Guide

Page 115

Add-in for Lotus 1-2-3

Compressed Data (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.
Required Fields
Tagname
Start Time
Number of data points

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.
Special Notes
This dialog box function only returns the actual number of archived data points in the PI
archive if this number is lower than the number of values asked for. For example, if you want
to retrieve 400 values starting from midnight today and there are only 356 values in the
archive, the final 44 cells are left blank by the PINCompDat function.
{PINCompDat}
{PINCompDat tagname, stime, numvals, outcode, PIServer, outcell}

Arguments

Page 116

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; either 0, 1, 2, or 3.

PIServer (string)

The PI Server.

Outcell (reference)

A cell specifying the upper left-hand corner of the output range

that holds the results of this macro command.

Dialog Box and PI Custom Macro Details

Returns
Outcode

Column 1

Compressed data

Timestamps

Column 2

Compressed 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 retrieves 10 compressed data points and corresponding time stamps for the tag
cdf144 starting from 1:00 a.m. this morning:
{PINCompDat 'cdf144,'(1:00),10,1,',A5}

The results are placed into an output range whose top left-hand corner is cell A5.

Compressed Data (times) 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.
Required Fields
Tagname
Start Time
End Time

Special Notes
This dialog box function only returns the actual number of archived data points in the PI
archive. For example, if you ran the PICompDat function yesterday using the arguments 'y
and 't for starttime and endtime and retrieved 100 values. If you run the same function today,
the function will retrieve the values between midnight yesterday and midnight today and
regardless of how many values are retrieved, will display them as such. If there are only 50
values today, the first 50 values from yesterday will be replaced with new values; the last 50
values from yesterday's function call will remain on the spreadsheet.
{PICompDat}
{PICompDat tagname, stime, etime, outcode, PIServer, outcell}

PI DataLink User Guide

Page 117

Add-in for Lotus 1-2-3

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; either 0, 1, 2, or 3.

PIServer (string)

The PI Server.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Compressed data

Timestamps

Column 2

Compressed 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. The
number of data points retrieved from the given time interval is returned in the first cell of
row/column.
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.
{PICompDat 'cdf144,'(1:00),'(3:00),1,',A5}

The results are placed into an output range whose top left-hand corner is cell A5.

Timed Data Dialog Box

This dialog box returns sampled values for a single tag that are synchronized with an array of
timestamps.
Required Fields
Tagname
Timestamp. The timestamp field has to be a reference to a time array. The timestamps in

this time array must be either monotonically increasing or monotonically decreasing.

Page 118

Dialog Box and PI Custom Macro Details

{PITimeDat}
{PITimeDat tagname, timestamps, PIServer, outcell}

Arguments
Argument

Explanation

tagname (string)

The tag for which you want the sampled data.

timestamps (reference)

A reference to an array of times in PI format. The values

in this array must be either monotonically increasing or
monotonically decreasing.

PIServer (string)

The PI Server.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

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
To get sampled data for cdf144 from the default PI Server for the increasing timestamps
specified in cells A5 to A25 and place the result into an output range whose upper left hand
corner is cell B5:
{PITimeDat 'cdf144,A5..A25,',B5}

Calculated Data Dialog Box

This dialog box returns evenly spaced calculated values from the PI Data Archive. The
calculation mode can be a total, minimum, maximum, stdev, range, average or mean.
Required Fields
Tagname. The reference to Tagname may be an array
Start Time
End Time
Time Interval
Conversion Factor
Calculation Mode

PI DataLink User Guide

Page 119

Add-in for Lotus 1-2-3

Check Box
Check show pctgood if you want PI DataLink to display the percentage of the time range that
contains good values. We recommend that you always look at the percent good value before
using the calculation result. The percentage good values are normally returned to the right of
the calculated value cells. If the row button and the show time button are both selected, the
percent good values are returned at the cells below the calculated value cells.
Special Notes
See notes in Calculated Value Dialog Box (page 110).
{PICalcDat}
{PICalcDat tagname, stime, etime, interval, mode, cfactor, outcode,
PIServer, outcell}

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 or mean).

cfactor (number)

A multiplicative conversion factor. Should be 1 for max, min,

avg, std and range. See special notes on cfactor in PIcalcVal()
for totals.

outcode (integer)

An output code; 0-7.

PIServer (string)

The PI Server.

outcell (reference)

A cell specifying the upper left-hand corner of the output range

that holds the results of this macro command.

Returns
The outcode affects the output as follows:
Calculated values along a column
Timestamps and values along 2 columns
Calculated values along a row

Page 120

Dialog Box and PI Custom Macro Details

Timestamps and values along 2 rows

Values and pctgood along 2 columns
Timestamps, values, and pctgood along 3 columns
Values and pctgood along 2 rows
Timestamps, values, and pctgood along 3 rows

Example
To get timestamps and totals (with a multiplicative factor of 24) at one hour intervals from
midnight yesterday to midnight today for the tag cdf144 from the default PI Server and place
the result into an output range whose upper left hand corner is cell A10:
{PICalcDat 'cdf144,'y,'t,'1h,'total,24,1,',A10}

Filtered Sampled Data Dialog Box

This dialog box gathers evenly spaced, sampled values from the archive when a given filter
expression is true. If the Marker 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.
Required Fields
Tagname. The reference to Tagname may be an array.
Start Time
End Time
Time Interval
Expression. Refer to Expression Syntax (page 143) for more information on the filter

expression syntax.
Check Boxes
Uncheck the Markers box to suppress the return of a "Filtered" status into the cell for the
time range when the values do not satisfy the filter condition.

PI DataLink User Guide

Page 121

Add-in for Lotus 1-2-3

{PISampFilDat}
{PISampFilDat tagname, stime, etime, interval, filtexp, filtcode,
outcode, PIServer, outcell}

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.

filtexp (string)

The filter expression. See Filter Expressions (page 146) 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.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Sampled data

Timestamps

Column 2

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
To get sampled data for sinusoid, when the tag cdep158 is greater than 80, at three-hour
intervals from midnight yesterday to midnight today from the default PI Server and place the
result into an output range whose upper left hand corner is cell A5:
{PISampFilDat 'sinusoid,'y,'t,'3h,'('cdep158'>80),1,1,',A5}

Page 122

Dialog Box and PI Custom Macro Details

Filtered Compressed Data (number) Dialog Box

This dialog box returns a specified number of compressed values from the PI Server while a
given filter expression is true. If the Marker option is selected, a "Filtered" status is returned
for each group of values that do not satisfy the filter expression.
Required Fields
Tagname
Start Time
Number of data points
Expression. Refer to Expression Syntax (page 143) for more information on the filter

expression syntax.
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.
Uncheck the markers box to suppress the return of a Filtered status into the cell for the time
range whose value does not satisfy the filter condition.
Special Notes
This dialog box function only returns the actual number of archived data points in the PI
archive if this number is lower than the number of values asked for. For example, if you want
to retrieve 400 values starting from midnight today and there are only 356 values in the
archive, the final 44 cells are left blank by the PINCompFilDat function.

PI DataLink User Guide

Page 123

Add-in for Lotus 1-2-3

{PINCompFilDat}
{PINCompFilDat tagname, stime, numvals, filtexp, filtcode, outcode,
PIServer, outcell}

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 146) 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.

outcell (reference)

A cell specifying the upper left-hand corner of the output range

that holds the results of this macro command.

Returns
Outcode

Column 1

Compressed data

Timestamps

Column 2

Compressed 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 retrieves 10 compressed data points and the corresponding times, starting from
2:00 a.m., for the tag cdf144 while the tag cdep158 is greater than 80. The status "Filtered" is
displayed for times when the filter condition is false. The results are placed into an output
range whose upper left-hand corner is cell A5.
{PINCompFilDat 'cdf144,'(2:00),10,'('cdep158'>80),1,1,',A5}

Page 124

Dialog Box and PI Custom Macro Details

Filtered Compressed Data (times) Dialog Box

This dialog box returns compressed values from the PI Server while a given filter expression
is true for a given start time and end time. The number of data points retrieved for the given
time period is returned in the first cell.
Required Fields
Tagname
Start Time
End Time
Expression. Refer to Expression Syntax (page 143) for more information on the filter

expression syntax.
Check Boxes
Uncheck the markers box to suppress the return of a Filtered status into the cell for the time
range whose value does not satisfy the filter condition.
Special Notes
This dialog box function only returns the actual number of archived data points in the PI
archive. For example, suppose you ran the PICompFilDat function yesterday using the
arguments 'y and 't for starttime and endtime and retrieved 100 values. If you run the same
function today, the function will retrieve the values between midnight yesterday and midnight
today. If there are only 50 values today that satisfy the filter criteria, the first 50 values from
yesterday will be replaced with new values, while the last 50 values from yesterday's function
call will remain on the spreadsheet.

PI DataLink User Guide

Page 125

Add-in for Lotus 1-2-3

{PICompFilDat}
{PICompFilDat tagname, stime, etime, filtexp, filtcode, outcode,
PIServer, outcell}

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 146) 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.

outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Compressed data

Timestamps

Column 2

Compressed 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. The
number of data points retrieved from the given time interval is returned in the first cell of the
row/column.
Example
The following retrieves compressed data points and the corresponding timestamps, starting
from 0:00 a.m. yesterday till 0:00 a.m. today, for the tag cdf144 while the tag cdep158 is
greater than 80. The status "Filtered" is displayed for times when the filter condition is false.
The results are placed into an output range whose upper left-hand corner is cell A5:
{PICompFilDat'cdf144,'y,'t,'('cdep158'>80),1,1,',A5}

Page 126

Dialog Box and PI Custom Macro Details

Expression Calculation Dialog Box

This dialog box performs calculations, over an evenly spaced time span, on an expression that
contains tags.
Required Fields
Expression. Refer to Expression Syntax (page 143) for more information on the

expression syntax.
Start Time
End Time
Time Interval

{PIExpDat}
{PIExpDat expression, stime, etime, interval, outcode, PIServer,
outcell}

Arguments
Argument

Explanation

Expression (string)

The calculation expression. See Expression Syntax (page

143) 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.

Outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

PI DataLink User Guide

Page 127

Add-in for Lotus 1-2-3

Returns
Outcode

Column 1

Calculated data

Timestamps

Column 2

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
To calculate the sum of the values of sinusoid and sqf100 at one-hour intervals from
midnight yesterday to midnight today from the default PI Server and place the timestamps
and the results into an output range whose upper left-hand corner is cell A5:
{PIExpDat'('sinusoid'+'sqf100'),'y,'t,'1h,1,',A5}

Time Filtered Dialog Box

This dialog box returns the amount of time for which a given expression is true over a time
range. User can specify multiple time ranges (evenly spaced intervals) as in the Calculated
Data Dialog Box.
Required Fields
Expression. Refer to Expression Syntax (page 143) for more information on the

expression syntax.
Start Time
End Time
Time Interval
Time units (defaults to seconds)

Page 128

Dialog Box and PI Custom Macro Details

{PITimeFilter}
{PITimeFilter expression, stime, etime, interval, timeunit, outcode,
PIServer, outcell}

Arguments
Argument

Explanation

expression (string)

The calculation expression. See Calculation Expressions

(page 143) 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

Unit of time for the result to be displayed. Valid entries are:

seconds, minutes, hours and days

Outcode (integer)

An output code; either 0, 1, 2, or 3.

PIServer (string)

The PI Server.

Outcell (reference)

A cell specifying the upper left-hand corner of the output

range that holds the results of this macro command.

Returns
Outcode

Column 1

Calculated data

Timestamps

Column 2

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
{PITimeFilter($A$1,"y","t","1h","seconds",1,"thevax",E1}

The above macro 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 and places the result in cells E1 and E2 of the active sheet. It also displays
the timestamps for the start time of each calculation interval. The calculation result is
expressed in seconds.

PI DataLink User Guide

Page 129

Add-in for Lotus 1-2-3

Connections Dialog Box

This dialog box manages your PI Server connections.

By using the buttons on the bottom, you can perform the following tasks:
Add - adds additional PI Servers to the list
Edit - modifies existing PI Servers
Remove - removes existing PI Servers
Set as Default - defines an existing PI Server as the default PI Server.

You can use the buttons on the right to Connect to and Disconnect from PI Servers in the
list. After you successfully connect to a PI Server, the Status field changes to either READ or
READ/WRITE.
To find information such as local PC node name/address and PI Server name/address, click
the Information button.

Page 130

Dialog Box and PI Custom Macro Details

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 tag
names 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.
In the example below, the tags 01:TEST.TF, 01TEST.LF, 01TEST.QA, 01TEST.VF, and
413P11.PV are selected.

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 PI DataLink
Settings... dialog. The cell position where the copying starts 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 left 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, the server names are copied below
the tag names in the spreadsheet.

PI DataLink User Guide

Page 131

Add-in for Lotus 1-2-3

Settings Dialog Box

This dialog box controls your settings and preferences for PI DataLink.

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 supplies the option to copy the PI server name
alongside the tagname when using the TagSearch dialog box to populate cells in a
spreadsheet.
The Use PIServer Time Zone check box is used by PI DataLink to determine whether or not
the user wants DataLink to interpret all timestamps based on the PI server's Time Zone
settings.
The Connect to PIServer on startup check box determines whether PI DataLink
immediately connects to the default PI Server when Lotus 1-2-3 starts up.

Page 132

Writing Data from Lotus 1-2-3 to PI

PI DataLink Help
This menu choice calls up help on PI DataLink.

About PI DataLink
This menu choice displays PI DataLink version information.

Writing Data from Lotus 1-2-3 to PI

PI DataLink allows you to write a value from the worksheet to the PI Data Archive. The PI
DataLink macro commands that perform these tasks are PIPutVal and PIPutValX. PIPutVal
supports classic PI point types while PIPutValX supports new PI point types for PI 3 Server.
Both functions will replace an existing event at the timestamp specified. Please consult the
file ...\PIPC\LOTUS\PIDL_input.123 on how to use these macros.

{PIPutVal}
{PIPutVal tagname, value, time stamp, PIServer, outcell}

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
If the macro function fails, an error message will be written to the output cell. If the function
succeeds, the string digital state sent, integer sent, or real value sent will be written to the
outcell.

PI DataLink User Guide

Page 133

Add-in for Lotus 1-2-3

Note: 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. PI DataLink will return a value written message even though "Over
Range" or "Under Range" might have been entered into the PI Data Archive.

Note: This function (PIPutVal) only supports integer, digital state and real data types. It
does not support writing string data to string tags and it does not support
sub-second timestamps. Timestamps are interpreted using server time zone
information.

Example
The following puts the value located in the cell A5 into the archive of the default PI Server
for midnight today for the tag testtag. The return status is placed into cell A10.
{PIPutVal 'testtag,a5,'t,',a10}

{PIPutValX}
{PIPutValX tagname, value, time stamp, PIServer, outcell}

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
If the macro function fails, an error message will be written to the output cell. If the function
succeeds, the string, value sent will be written to the outcell.
Note: PIPutValX 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. PI DataLink will return a value written message even though "Over
Range" or "Under Range" might have been entered into the PI Data Archive.

Page 134

Limitations of PI DataLink for Lotus 1-2-3

Note: This function (PIPutValX) supports all PI 3 Server 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 PIServer 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 archive of the default PI Server
for midnight today for the tag testtag. The return status is placed into cell A10.
{PIPutValX 'testtag,a5,'t,',a10}

Limitations of PI DataLink for Lotus 1-2-3

PI DataLink is limited to 65536 timestamps and their corresponding values for a single
custom PI macro command in Lotus 1-2-3. This limitation means that for a single custom
PI macro command, you can retrieve only 65536 values at a time. This is the limit for the
number of rows in Lotus 1-2-3 spreadsheet.

PI DataLink User Guide

Page 135

Appendix A: Troubleshooting
Consult the sections below if you are having difficulties with PI DataLink.
DataLink Add-in Doesn't Load Properly (page 137)
Connection Problems Reported in Log Files (page 138)
Limits from Excel for PI DataLink (page 86)
Limitations of PI DataLink for Lotus 1-2-3 (page 135)

If you are still having problems after following these suggestions, see Technical Support and
Resources (page 155) 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 PI DataLink
add-in is still loaded. One of the symptoms of this phenomenon is that embedded PI DataLink
array functions still work while the PI menu itself is not available. Restarting Excel usually
fixes the problem.

DataLink Functions Not Available Through PI Menu in Lotus 1-2-3:

The PI123DLG.123 file contains most of the DataLink dialog boxes and must be loaded
for the DataLink dialog boxes to be available. If you can see the PI menu but cannot see the
DataLink functions on the PI menu in 1-2-3, confirm that this file is in
...\lotus\123\auto and restart Lotus 1-2-3.

PI DataLink User Guide

Page 137

Add-in for Lotus 1-2-3

PI Menu Not Available on Lotus 1-2-3 Toolbar

On the Lotus 1-2-3 main menu go to: File > Add-Ins > Manage Add-Ins... and confirm that
PIDL.12A is displayed in the list of add-ins. Check the space in front of the path of the
add-in file and click Done. Save any files you were working on and restart Lotus 1-2-3. If the
PIDL.12A file does not appear in the list of available add-ins, check to see if it is available
in the ...\lotus\123\addins directory. If it is, click Register... in the Manage Add-ins
dialog box, go to the \lotus\123\addins directory and double-click on PIDL.12A.
If PIDL.12A is not in ...\lotus\123\addins, please run setup for PI DataLink again.

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. (PI DataLink connection messages should begin with "PINet".)
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

PI 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. (PI DataLink connection messages should come from EXCEL.EXE.)

DataLink Add-in Doesn't Load Properly

PI DataLink for Lotus 1-2-3

The log file for connection attempts is located on the PC in C:\PIPC\DAT\pipc.log.
The general procedure for determining the cause of the lack of connection between PI
DataLink and the PI Server is to check log files on both the PC and the PI Server. The
following are some common symptoms:
Gethostbyname Error in pipc.log
This Gethostbyname error indicates that the PC cannot translate the name of the PI Server
into a TCP/IP address. A quick fix solution is to add the PI Server's address to the PC's local
Host table.
For Windows 98, the host table is located in C:\WINDOWS\hosts. Be aware that Windows
98 ships with a default C:\WINDOWS\hosts.sam file, and Windows 98 often hides
filename extensions. Thus, you may think that you are editing hosts when in fact you are
editing hosts.sam.
For Windows NT, 2000, and XP, the host table is located in
C:\WINNT\SYSTEM32\DRIVERS\ETC\hosts.
Be sure to PING the PI Server machine by name to confirm the communications between the
PI Server and PI DataLink. The PING command can be run from any directory at the
command prompt.
Connect() Timeout in pipc.log
The connect() timeout error usually indicates that PI DataLink cannot connect to the specified
port number (545 or 5450) for the specified PI Server machine.
For PI 2 Server
1. Check to see that the PI Server service has been created and enabled on the PI Server
machine.
2. Check on the PC that PI DataLink is trying to connect to port 545.

Error! Style not defined.

Page 139

Add-in for Lotus 1-2-3

For PI 3 Server
Check on the PC that PI DataLink is trying to connect to port 5450.
Select() Timeout in pipc.log
The select() timeout error usually indicates that PI 2 Server machine is not translating the
PC's address into a name fast enough. The solution is to add the PC's name and TCP/IP
address into the VAX/Alpha's local host table. See the previous section on name translation
for more information.
Also, you may increase PI DataLink's timeout parameter in the
C:\PIPC\DAT\pilogin.ini file:
[network] timeout=60

The above indicates that PI DataLink should wait 60 seconds before timing out while waiting
for a reply from the PI Server.
You should create the above [network] section and timeout entry if they do not currently
exist.
Recv: Error: 0 in pipc.log
The recv:Error:0 usually indicates that PI DataLink has successfully connected to port
545/5450 on the PI Server machine, but has not received a reply.
1. Confirm that the PI Server is indeed running on the PI Server machine.
2. For PI 2 Server, confirm that the PI Server service is configured correctly. See
PIBuild:PIServer.txt for more information.

DataLink Add-in Doesn't Load Properly

TCP/IP Connection Problems

1. The version of your PI 2 Server does not support TCP/IP. You must have PI 2.0.8+ (PI
2.0.7 for DEC TCP/IP Services for VMS).
2. The PC cannot talk to the PI Server via TCP/IP. There may be a hardware or router
problem associated with your network. Run a ping test between the Server and the PC:
\>ping mypiserver
3. On Windows systems, check Network Protocol Settings (Start > Settings > Control Panel
> Network) and confirm TCP/IP is enabled.
4. The PI Server service has not been enabled on the VAX/AlphaAXP.
5. If your VAX/AlphaAXP is running DEC TCP/IP Services for VMS, make sure that the
auxiliary service for the PI Server is currently enabled: $ ucx show service
PIServer. Enable the PI Server if necessary: $ ucx enable service PIServer.
If you are running another TCP/IP (for example, TGV MultiNet) service on the
VAX/AlphaAXP, ask your VMS system manager to check whether the PI Server
auxiliary server has been configured. The instructions are in
PIBuild:PIServer.txt.

Error! Style not defined.

Page 141

Appendix B: Expression Syntax

PI expressions are used in PI 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 PI
DataLink.
Note: The examples below use two tag delimiters, colon (:) and period (.). Your PI
System may use different ones.

In a tag calculation expression, mathematical operators and functions act upon tag names.

PI DataLink User Guide

Page 143

Add-in for Lotus 1-2-3

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)

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.

Calculation Expressions

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

Error! Bookmark not defined.

Page 145

Add-in for Lotus 1-2-3

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 PI DataLink.
Note: The examples below use tag delimiters of : (colon) and . (period). Your PI 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

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")

Filter Expressions

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)

Error! Bookmark not defined.

Page 147

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. If you are using the add-in for Lotus 1-2-3, you should
enclose the PI Time String argument in parentheses. 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

PI DataLink User Guide

Page 149

Add-in for Lotus 1-2-3

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.

Page 150

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 PI 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_ENABL
E

Enables/disables buffering

ALLUSERS

Installs for all users of machine

PI DataLink User Guide

Page 151

Add-in for Lotus 1-2-3

PI DataLink Installation
There are a few arguments which can be added as arguments to the command line in order to
install the PI 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

Page 152

Argument

Meaning

/q

Install silently

SHARED

Network Installation pathname

ALLUSERS

Installs for all users of machine

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

xi 1

(where i is the bit number for each bit that is set)

Note: Not all outcodes are valid for each function because not all options are available
for every function.

PI DataLink User Guide

Page 153

Add-in for Lotus 1-2-3

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.
bits set = { Show Timestamps, Show Pct Good, Show Start Time, Show Min/Max Time }
= {1, 3, 7, 9 }
outcode =

xi 1

= 211 + 2 31 + 2 7 1 + 2 91

i
0

= 2 + 2 2 + 2 6 + 28
= 1 + 4 + 64 + 256
= 325

So the function shown in Excel would look like:

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

Page 154

Appendix F: Technical Support and Resources

OSIsoft provides dedicated technical support internationally, 24 hours a day, 7 days a week.
You can read complete information about technical support options, and access all of the
following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com
OSIsoft provides the following support options and resources.

Help Desk and Telephone Support

Telephone support is available 24 hours a day, 7 days a week. Direct service may not
available in some locations or during some hours; in this case, leave a message and your call
will be returned within 4 hours.
USA and Canada: (510) 297-5828
Outside of North America: +01 510-297-5828
FAX: (510) 352-2349

E-mail Support
E-mail technical support inquiries, including the problem description and message logs, to
techsupport@osisoft.com. You will receive a response within 24 hours.

Personalized Online Technical Support

The Online Call Center allows you to create a support call, which will be responded to in 24
hours. It also allows you to review information from your previous support calls. Choose My
Support > My Calls (Online Support) in the Technical Support Web site. The My Support
menu allows you to review My Products, My Download History, and SRP Terms, which
covers Service Reliance Program (SRP) service agreements.

PI DataLink User Guide

Page 155

Add-in for Lotus 1-2-3

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, PI system sizing and configuration, PI trusts for interface nodes, and more.

Remote Server Access

Technical support engineers can remotely access your PI server to provide diagnostics,
hands-on troubleshooting, and assistance. Choose Contact Us > Remote Access Options in
the Technical Support Web site.

On-site Technical Support

OSIsoft provides on-site service according to SRP service level agreements. To see current
SRP status, go to My Support > SRP Terms on the Technical Support Web site.

Before You Call or Write for Help

When you contact OSIsoft 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

Before You Call or Write for Help

Find the Version and Build Numbers

To find version and build numbers for each PI 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

PI DataLink User Guide

Page 157

Index

A
ActiveX control 72
Advanced Calculated Data 53
Apostrophe 87
Archive Value 106
Array
Options 99
Attribute Mask to Tag 68
Averages 53, 108, 117

B
Bug Fixes
List of 5

C
Calculated Data 117
Calculated Value 108
Calculation Expressions 141
Calculation Modes 53, 108, 117
Can't Connect to the PI Server 136
Case-sensitive
Node names 6
Change arguments 17, 29
Change Scale option 76
Combo Boxes 23
Compressed Data
(Number) 37, 114
(Number) Filtered 121
(Times) 40, 115
(Times) Filtered 123
Configuring
Lotus 1-2-3 5
connect() timeout error 136

PI DataLink User Guide

Connections 128
Dialog Box 128
Problems 136
Current Value 87, 105
Curtime Keyword 143

D
Data Access 9
PI 3 Server 9
Define Trend option 76
Delimiters 141
Dialog Box 98, 105
Advanced Calculated Data 53
Alias 69
Archive Value 106
Attribute Mask to Tag 68
Calculated Data 117
Calculated Value 108
Compressed Data (Number) 37, 114
Compressed Data (Times) 40, 115
Connections 128
Current Value 105
Edit Fields 98
Enter time in Excel 26
Enter time in Lotus 1-2-3 102
Exact Time Value 107
Expression Calculation 125
Filtered Compressed Data (Number) 121
Filtered Compressed Data (Times) 123
Filtered Sampled Data 119
Functions 31, 105
Module Database 79
Point ID to Tag 67
Property 70
Sampled Data 113

Page 159

Index

Settings 130
Tag Attributes 111
Tag Search 129
Time Filtered 126
Timed Data 116

E
Edit Fields 98
Enter Time to PI DataLink 102
Errors 135
connect() timeout error 136
Gethostbyname 136
recv Error 0 136
Reporting 104
select() timeout error 136
Exact Time Value 107
Expressions 46, 65, 66, 125
Calculation 125
Syntax 141
Time Filtered 126

F
Features Summary 95
Filter Expressions 144
Filtered Data
Compressed(Number) 121
Compressed(Times) 123
Sampled 119
Firewall Database 9
Format option 76
Functions 28
Dialog Boxes 31
Excel 31
Performance Equation 143
Provided in Excel 11
Provided in Lotus 1-2-3 85

G
Gethostbyname error 136

H
Help 82

I
Input Timestamps
Start and End Time 147
Time Interval 148
Installation
Arguments 150
Configuring 1-2-3 5
Local 4
Network 3
SDK 149

L
Limitations
PI DataLink for 1-2-3 133
List Boxes 99
Loading Problems 135
Lotus 1-2-3 Add-in 1, 85

M
Macros
Macro commands
Lotus 1-2-3 87
Macros vs. Dialogs 104
Output Fields 98
Output Option 102
Maxima and Minima 53, 108, 117
Mean Average 108, 117
Menu 96
Microsoft Excel
Add-in 1, 11
Module Database 79
MultiNet
Name Translation, PI Client 6

N
Node Authentication
PI 2 Server 6
Node Names
TCP/IP 6

O
Operating System 2
OSIsoft Technical Support 135
Output Fields 22, 98

Page 161

P
PathWay
Name Translation, PI Client 6
PC client name 6
Percent Good 108, 117
Performance Equation
Syntax 143
Performance Equations 141
PI 2 Server
Server configuration 6
PI 3 Server
configuration 9
security 9
PI DataLink
Functions 31
Installation arguments 150
Loading Problems 135
PI Expressions 141
Logical Operators 145
Math Functions 142
Mathematical Operators 142
Performance Equations 143
Relational Operators 144
PI Menu
Not displayed 135
PI SDK
Silent Installation 149
PI System Manager 6
PI time strings 147
PIADMIN
User Privileges 9
PIAdvCalcDat 60
PIAdvCalcExpDat 62
PIAdvCalcExpFilDat 63
PIAdvCalcExpFilVal 59
PIAdvCalcExpVal 58
PIAdvCalcFilDat 61
PIAdvCalcFilVal 57
PIAdvCalcVal 56
PIAliasToTag 69
PIArcVal 33, 106
PICalcDat 52, 118

PI DataLink User Guide

PICalcVal 50, 109

PICompDat 41, 116
PICompFilDat 42, 124
PICurrVal 32, 105
PIExpDat 46, 125
PIExpVal 34
PIExTimeVal 107
PINCompDat 38, 114
PINCompFilDat 39, 122
PINet nodes
security on 6
PIPropertyValue 71
PIPutVal 83, 131
PIPutValX 132
PISampDat 44, 113
PISampFilDat 45, 120
PIServer Fields 22, 98
PITagAtt 36, 112
PITimeDat 47, 117
PITimeExpDat 48
PITimeFilter 66
PITimeFilterVal 65
Point Access 9
PI 3 Server 9
Point ID to Tag 67

R
recv Error 0 136
Refreshing PI data in a spreadsheet
Lotus 1-2-3 104
Reporting Errors 104
Revert option 76

S
Sampled Data 113
Example 16
Filtered 119
Scroll Bar option 76
Security
PI 2 Server 6
PI 3 Server 9
select() timeout error 136

Page 161

Index

Settings 130
setup.ini
Arguments 149
PI DataLink 150
Show Time Check Box 103
Single quote 87
Standard Deviations 53, 108, 117
Syntax
Performance Equation 143

T
Tag Attributes 87, 111
Tag Search 99, 129
TCP/IP 2
Node Names 6
TCPWare
Name Translation, PI Client 6
Timed Data 116
Timestamps
Entering into PI DataLink 26
In Lotus 1-2-3 102
In Microsoft Excel 102
Time Interval 148
Toolbar 96
Totals 108, 117
Trend
Right-click menu 76
Trend Control 72
Troubleshooting 135
Tutorial
DataLink for Lotus 1-2-3 86
DataLink for Microsoft Excel 86

U
UCX
Name Translation for PI Client 6
User Privileges
PIADMIN 9
username/password
PI 3 Server 9

V
Values
Writing into PI 82, 131
Verify Connections

Excel add-in tutorial 86

Lotus 1-2-3 add-in tutorial 86
Version
PI System 2.0.9 143
Spreadsheet software 2
TCP/IP 2