pi datalink user guide

PI DataLink User Guide

Version 3.1.6

12/18/2006

1992-2007 OSIsoft, Inc. All rights reserved

OSIsoft, Inc. 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)

http://techsupport.osisoft.com

[email protected]

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

OSIsoft Australia Perth, Australia Auckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSI Software Asia Pte Ltd. Singapore

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

PI DataLink User Guide Page iii

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

Contents

Page iv

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

PI DataLink User Guide Page 1

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.

Introduction

Page 2

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.

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.

Introduction

Page 4

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

Release notes for previous versions are in C:\APPS\PIPC\readme_dl.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.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.

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.

Introduction

Page 6

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.



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.

Introduction

Page 8

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.



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

Introduction

Page 10

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.


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.


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.


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

Add-in to Excel

Page 12

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:

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.

Add-in to Excel

Page 14

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

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.

Add-in to Excel

Page 16

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.

Tutorial


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

Add-in to Excel

Page 18

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.

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.

Add-in to Excel

Page 20

PI Menu

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

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

Add-in to Excel

Page 22

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.

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.

Add-in to Excel

Page 24

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.

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.

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.

Add-in to Excel

Page 28

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.

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.

Add-in to Excel

Page 30

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.



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

Add-in to Excel

Page 32

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.



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 Column 2

0 Current value

1 Timestamps Current value

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

Example

The following retrieves the current value and the corresponding timestamp for the tag let439 from the PI Server "holden:"

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

Archive Value Dialog Box

This dialog box gets a value at a specified time. There are five modes to select from:

Previous - Retrieves the value in the archive at or before the specified timestamp Previous only - Retrieves the value in the archive only before the specified timestamp Interpolated - Interpolates the value at the specified timestamp except for resolution code

4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the previous value is simply carried forward.

Auto - Same as interpolated except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the value at or before the specified timestamp is returned

Add-in to Excel

Page 34

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


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.


mode (string) The retrieval mode.

Returns


0 Archive value

1 Timestamp Archive value




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


expression (string) The expression for which you want the archive value.

time stamp (string) The PI timestamp.


Returns


0 Archive value

1 Timestamp Archive value


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

Add-in to Excel

Page 36

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:

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





filtercode Filter code

squareroot Square root flag

scan Scan flag

excdev Exception deviation in percent of span

excmin Exception minimum time in seconds



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


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


Returns

Tag attribute

Add-in to Excel

Page 38

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"



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


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.


mode (string) The boundary type.

Add-in to Excel

Page 40

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




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.




Returns

Refer to Outcodes.

Example

The following retrieves 10 compressed data points and the corresponding times, starting at 2:00 a.m., for the tag cdf144 while the tag cdep158 is greater than 38:

=PINCompFilDat("cdf144","2:00",10,"'cdep158'>38",1,1,,) The status Filtered is displayed for times when the filter condition is false. Data are retrieved from the default PI Server with inside as boundary type.



Compressed Data (Start Time/End Time) Dialog Box

This dialog box returns compressed values from the PI Server based on a start time and an end time. The number of data points retrieved for the given time period is returned in the first cell. If a filter expression is not specified, the PICompDat() function is called. Otherwise, the PICompFilDat() function is called.

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.

Add-in to Excel

Page 42

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


PICompDat() (page 42)

PICompFilDat() (page 43)

PICompDat() PICompDat(tagname, stime, etime, outcode, PIServer, mode)

Arguments




etime (string) The end time in PI time format.




Returns

Refer to Outcodes.



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










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.

Add-in to Excel

Page 44

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


PISampDat() (page 44)

PISampFilDat() (page 46)

PIExpDat() (page 47)

PISampDat() PISampDat(tagname, stime, etime, interval, outcode, PIServer)

Arguments


tagname(string) The tag for which you want sampled data.






interval (string) The time interval in PI time format.

outcode (integer) An output code; either 0, 1, 2, or 3.


Returns


0 Sampled data

1 Timestamps Sampled data

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

Example

The following retrieves sampled data for the tag located in cell B1, from midnight yesterday to midnight today at 3-hour intervals:

=PISampDat(b1,"y","t","3h",1,) Timestamps are also returned.

Add-in to Excel

Page 46

PISampFilDat() PISampFilDat(tagname, stime, etime, interval, filtexp, filtcode, outcode, PI Server)

Arguments


tagname(string) The tag for which you want sampled data.








Returns


0 Sampled data

1 Timestamps Sampled data

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

Example

The following formula retrieves sampled data for SINUSOID at 11-Jan-97, 11-Jan-97 1:00AM, 11-Jan-97 2:00AM, and 11-Jan-97 3:00AM:

=PISampFilDat("sinusoid","11-Jan-97","+3h","1h",A1,1,1,) Timestamps are shown in column1 and values in column2. A "Filtered" status is returned for values do not satisfy the filter condition in cell A1.



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

Arguments


expression (string) The calculation expression. See Calculation Expressions (page 143) for more information on calculation expression syntax.






Returns


0 Calculated data

1 Timestamps Calculated data

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

Example

The following calculates the square root of the value of the tag sinusoid from the PI Server named THEVAX at one-hour intervals, starting from midnight yesterday to midnight today:

=PIExpDat("sqr('sinusoid')","y","t","1h",1,"thevax") It also displays the timestamps.

Timed Data Dialog Box

This dialog box returns sampled values for a single tag that are synchronized with an array of timestamps. There are two modes to select from:

Interpolated - Interpolates values at the specified timestamps except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. For this special case, the previous value is simply carried forward

Exact Time - Retrieves the value in the archive for a specified time if an entry exists at that time. If no value exists, the message "No events found" is returned.

Add-in to Excel

Page 48

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


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.


mode (string) The retrieval mode.

Returns

Sampled data. If the timestamps are in a single column, the data are returned along a single column. If the timestamps are in a single row, the data are returned along a single row.

Example

The following retrieves interpolated timed data for the times located in cells B1 through B12 for the tag mytag from the default PI Server:

=PITimeDat("mytag",b1:b12,,"interpolated")



PITimeExpDat() PITimeExpDat(expression, timestamps, PIServer)

Arguments


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

Add-in to Excel

Page 50

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 Column 3

Minimum Time of min. value Minimum value

Maximum Time of max. value Maximum value

Range Time of min. value Time of max. value Range value

Special Notes

When an interval is not specified and the mode is Total, Standard Deviation, Average, Count or Mean, the timestamps are not displayed even if the Show Timestamps check box is selected. When an interval is specified and the mode is Max or Min, the timestamps displayed are the start time of each calculation interval.

When the calculation is a time-weighted Total and part of the archived data within the range are bad, the reported value is equal to the calculated total value divided by the fraction of the time period with good archived data. This data normalization is equivalent to the assumption that for the bad data time range, the tag value takes on the average value of the entire range.

Add-in to Excel

Page 52

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 1

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


tagname (string) The tag for which you want the calculated value.



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.




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 Column 3

Total Total value

Minimum Time of min. Value Minimum value

Maximum Time of max. Value Maximum value

Stdev Stdev. Value

Range Time of min. Value Time of max. value Range value

Average Average value

Count Count value

Mean Mean value

An output code of 2 transposes the output array that results from an output code of 1, i.e., results are returned in rows instead of in columns.

Outcode of 3 is not used.

If the outcode is 4, the percent good is returned to the right of the value cell.

If the outcode is 5, the following applies:

Mode Column 1 Column 2 Column 3 Column 4

Total Total value Percent good

Minimum Time of min. value Minimum value Percent good

Maximum Time of max. value Maximum value Percent good

Stdev Stdev. value Percent good

Range Time of min. value Time of max. value Range value Percent good

Average Average value Percent good

Count Count value Percent good

Mean Mean value Percent good



Add-in to Excel

Page 54

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


tagname (string) The tag for which you want the calculated data.




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.


Returns

The outcode affects the output as follows:

0 Calculated values along a column 1 Timestamps and values along 2 columns 2 Calculated values along a row 3 Timestamps and values along 2 rows 4 Values and pctgood along 2 columns 5 Timestamps, values, and pctgood along 3 columns 6 Values and pctgood along 2 rows 7 Timestamps, values, and pctgood along 3 rows



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.

Add-in to Excel

Page 56

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



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


PIAdvCalcVal() (page 58)

PIAdvCalcFilVal() (page 59)

PIAdvCalcExpVal() (page 60)

PIAdvCalcExpFilVal() (page 61)

PIAdvC

pi datalink user guide

Documents

contents of pi datalink

pi datalink functions

canada osisoft

pi processbook

pi menu

japan osisoft mexico

pi system manager

rights reserved osisoft