PI DataLink User GuideVersion 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
[email protected] 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, People’s 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 ........................150 Appendix D: Setup....................154 Appendix F: Technical Support and Resources ......................................................................................................ini Arguments........................................................................................................................................................................................................................155 Before You Call or Write for Help ................................................................................................152 Appendix E: Outcodes .......................................................................151 PI SDK Installation......................................................................................................151 Silent Installs..................................153 Example ..............................151 PI DataLink Installation ................................................................................................................149 Time Interval ........................................149 Start and End Time........................................................................................................................................................159 Page iv ....................Contents Appendix C: Examples of PI Time Strings ....156 Index ..................................................................................................................................................... With PI DataLink. However. and spreadsheet programs running on Microsoft Windows platforms. It allows users who have experience using 1-2-3 LotusScript programming to develop Lotus spreadsheet routines that call PI API functions. PI DataLink User Guide Page 1 . Combined with the functionality of the spreadsheet programs. users who wish to develop programs outside of Excel or Lotus 1-2-3 must purchase a separate PI SDK or PI API license. yet easy-to-use tool for gathering. analyzing. It allows users who have experience using Microsoft Visual Basic for Applications (VBA) to develop Excel routines that call PI SDK functions. 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. this feature makes PI DataLink a powerful. PI DataLink for Lotus 1-2-3 is built with OSIsoft's PI API product. Please contact an OSIsoft sales representative for more information.Chapter 1: Introduction PI DataLink provides a link between OSIsoft's PI 3 or PI 2 Server. a user running Microsoft Excel or Lotus 1-2-3 can exchange information directly with the PI System databases. or UNIX.4+ Attachmate Pathway. Page 2 . or XP Microsoft Windows NT. runtime release 1. version 4 SP6a Users of Microsoft Windows should use the TCP/IP layer built into the operating system.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. Windows. TCP/IP on OpenVMS If the PI Server runs on OpenVMS. one of the following operating systems is necessary: Microsoft Windows 98. 2000. TCP/IP To use TCP/IP.1+ Spreadsheet Programs Supported PI DataLink supports the following spreadsheet programs (32-bit versions only): Microsoft Excel 2000. PI DataLink communicates with the PI Server via the TCP/IP protocol. version 3. version 3. one of the following TCP/IP software packages is necessary on the VMS machine: DEC TCP/IP Services for OpenVMS.0+ Process Software TCPWare. version 9. Operating System and Network Software The PI Server may run on OpenVMS.0 and later. version 2. Lotus 1-2-3 release 9.1+ Cisco MultiNet.5 (included as part of Lotus SmartSuite Millennium) and later. exe from the distribution CD on the network file server. After a successful installation of PI DataLink to a network file server. Contact OSIsoft Sales for more information. edit the [COMMANDLINES] section of the setup. which has write privileges to P:\APPS\PIPC\DAT directory. 4. All changes made will be propagated to rest of shared installs. Individual users must subsequently perform an installation of either a standalone version or a shared version of PI DataLink. LOTUS. To create PI servers list. and SETUP subdirectories under C:\APPS\PIPC. Installation of a standalone version places a copy of all the PI DataLink files onto the user's local PC. 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 to a Network File Server This option is intended as a one-time procedure for a System Administrator. or globally to a network file server. Installation to a network file server is done on a local PC. Add PI servers as you would normally. either locally to a PC. A System Administrator normally performs the latter. 3. Refer to Setup. Run AdminSetup. 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. The following summarizes the procedure for installation to a network file server: 1. 2. For shared installations. Choose the destination directory (for example: C:\APPS\). The user may install PI DataLink from the distribution CD.ini Arguments (page 151) for more arguments. DAT. This installation in and of itself does not allow anyone to run PI DataLink.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. LIBRARY.Installation Installation Note: Before installation. each user of PI DataLink must be licensed to use this product. Setup will create EXCEL. PI DataLink User Guide Page 3 . do shared install on machine. The release notes are in P:\APPS\PIPC\readme_datalink. Installation of a shared version can only be performed from the network drive.. Browse and select the file PIPC32. For a shared installation of PI DataLink.exe). every user must install either a complete standalone version or a shared version. If PI DataLink is upgraded and placed in a directory different from the previous versions. look in the .XLL.Introduction The current release notes are in C:\APPS\PIPC\readme_datalink.\PIPC\EXCEL directory. then Excel's add-in manager should be used first to remove the old PIPC32. the file PIPC32. For a local installation..txt. Choose the destination directory. Installation to a Local PC (Standalone and Shared) In order to use PI DataLink. Installation of a standalone version may be performed either from the distribution CD or from the network drive. Then.txt. the new PIPC32. Configuration of Microsoft Excel If PI DataLink will be used with Microsoft Excel. P:\APPS\PIPC\SETUP\setup. and this is a first time installation (not an upgrade) of PI DataLink. you will need to add PI DataLink.. Release notes for previous versions are in P:\APPS\PIPC\readme_dl<version>. Release notes for previous versions are in C:\APPS\PIPC\readme_dl<version>. Start Excel.\PIPC\EXCEL directory on the network drive.exe from the distribution CD or from the setup directory on the network drive (for example. Page 4 . 2. 1.txt.txt..xll will be in the . 2. 3. Run setup.XLL. The following summarizes the procedure for installation to a local PC: 1.XLL file in the new location should be selected. Bring up Excel's add-in manager via Tools > Add-ins. 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 Dat. you see a number (for example. Accordingly. If instead. 192. you should run the following commands: $ multinet host_table compile $ @multinet:install_databases Consult your MultiNet documentation for more details.Introduction Name Translation . 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 host name whose access level to PI data is being controlled by PISysDat:PIServer. Consult your PathWay documentation for more details. To add an entry in the MultiNet host table on the VAX/Alpha for a PC.Dat. the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer.Dat. Page 8 . Accordingly. this means that PathWay (and hence the PI 2 Server) cannot determine the name of the PC client. the PI 2 Server asks MultiNet to supply the hostname for a given PI DataLink connection.file. the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer. 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. PathWay in turn queries the host database on the VAX/Alpha or the Domain Name Server (if configured).168. If instead. It is this latter hostname whose access level to PI data is being controlled by PISysDat:PIServer. Name Translation .168.100. you need to edit the twg$etc:Hosts.PathWay Under PathWay.100.77) for the foreign host. To confirm that PathWay is determining the PC name properly.Dat.77) for the foreign host. the PI 2 Server asks PathWay 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). you need to edit the MultiNet:Hosts. this means that MultiNet (and hence the PI 2 Server) cannot determine the name of the PC client. To confirm that MultiNet is determining the PC name properly.MultiNet Under MultiNet. After editing.Local file. you see a number (for example. To add an entry in the PathWay host table on the VAX for a PC. 192. PI DataLink User Guide Page 9 . PIConfig> @table pi_gen. ALLOW The above indicates that all PCs may connect to PI 3 Server.*. you need to edit the TCPWare:Hosts file. this means that TCPWare (and hence the PI 2 Server) cannot determine the name of the PC client. the PI 2 Server is using the DEFAULT level access in PISysDat:PIServer. 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. Accordingly.*.aspx) under "PI 3 Enterprise Server".*.100 are allowed to connect.*.aspx (http://techsupport.com/downloadcenter.100. You may need to restart TCPWare in order for the change to take effect. TCPWare in turn queries the host database on the VAX/AlphaAXP or the Domain Name Server (if configured). Consult your TCPWare documentation for more details. It is this latter host name whose access level to PI data is being controlled by PISysDat:PIServer. consult the PI Server User Manuals that are available for download from http://techsupport.77) for the remote host.osisoft.pifirewall PIConfig> @ostr hostmask. *. To add an entry in the TCPWare host table on the VAX/Alpha for a PC. For example.168.100. DISALLOW 192.*. 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.*.168.TCPWare Under TCPWare. To confirm that TCPWare is determining the PC name properly.Dat.168. 192.For the PI System Manager Name Translation . you see a number (for example.com/downloadcenter. ALLOW The above indicates that only PCs whose TCP/IP address start with 192.value PIConfig> @select hostmask=* PIconfig> @ends *. the PI 2 Server asks TCPWare to supply the hostname for a given PI DataLink connection.Dat.*. For more information.osisoft. If instead. Page 10 . For more information. the tag will not be found. if SINUSOID DataAccess is O:R. For this reason.osisoft. consult the PI Server User Manuals that are available for download from http://techsupport. and DataOwner is USER1. Otherwise. Point Access/Data Access Attributes When PI DataLink connects to PI 3 Server.ipaddr. if the tag SINUSOID is configured such that PtAccess is O:RW.aspx) under "PI 3 Enterprise Server". For example.osisoft. PI DataLink users normally should NOT log in as PIAdmin. G:NONE.piuser PIconfig> @select trust=* PIconfig> @ends MyPCTrust. W:NONE. This username is used in conjunction with the PtOwner. PI DataLink users must log in as USER1 in order to see data for this tag. Note: The user PIAdmin is a "super"-privileged user.0.com/downloadcenter. W:NONE.0. a read access error message is returned. consult the PI Server User Manuals that are available for download from http://techsupport. A user of PI DataLink who logs in as PIAdmin has read and write access to all tags. Only after this change is made can PI DataLink users who log in as USER1 be able to read and write data for SINUSOID. 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).com/downloadcenter.aspx (http://techsupport.iphost.aspx) under "PI 3 Enterprise Server". However.osisoft.osisoft. For more information.com/downloadcenter. it asks the user for a username and password.piadmin The above indicates that any app connecting to PI 3 Server from "mypc" gets piadmin privileges by default. and DataAccess fields. PIconfig> @table pitrust PIconfig> @ostr trust.0.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.com/downloadcenter. PI DataLink users must log in as USER1 in order to see this tag. PtAccess. Also. The PI System Manager would need to change DataAccess to O:RW (read and write).mypc. and PtOwner is USER1. DataOwner. Otherwise. G:NONE.0.aspx (http://techsupport. For example. 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. Moreover. ranges. users have the ability to write spreadsheet values back into PI. directly into a spreadsheet. 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 .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. minima. maxima. standard deviations. From the PI menu bar. If PI does not appear. the login dialog appears to prompt you for the password: Page 12 . Rather. you need to use Excel's add-in manager. If the default user account for your selected PI Server requires a password. If the Status indicates that the PI Server is not connected... See Configuration of Microsoft Excel. select Connections. it will serve to familiarize the user with the overall operation of this add-in.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. click the checkbox to connect. Start Excel and make sure that the PI menu choice is in Excel's menu bar. Verify Communications with PI Server In this first example. PI DataLink's features are not discussed in detail in this tutorial. we will confirm that PI DataLink has been installed properly and that it can connect to the PI Server.. Check the Troubleshooting (page 137) section. Open Excel.. we obtain the tag descriptor. dismiss the dialog box and move the cursor to cell A2 in the spreadsheet.. If you receive a login failure dialog box. current value. Select Tag Search. from the PI menu and enter "BA*" into the Tag Mask field. 2. 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. PI DataLink User Guide Page 13 . 1. Dismiss the Connections dialog box by clicking Cancel. you can also change the user name to log in as a different user from the default user. Next. confirm that you have a valid PI username/password. 4. From the PI menu. 3.Tutorial In this dialog. select Settings. and engineering units for some tags. A valid username/password changes the Status in the Connections dialog box and displays the user that DataLink is connected as... and make sure that the In a column radio button in the "Copy items to sheet" section is chosen. Tag Attributes and Current Value In this next example. 1. from A2 to A6. Move the cursor to cell B2.Add-in to Excel 5.1) and then simultaneously holding the CTRL key and clicking on each of the four other tags.. Select these five tags from the Search Results list by clicking on the first tag (BA:ACTIVE. BA:PHASE. 7.1. BA:LEVEL. Page 14 .1.. BA:CONC. Click the edit box under Tagname(s). Then.. Click Search to find tags that being with "BA". and BA:TEMP. 6. select Tag Attributes.1.1. The Search Results list should contain at least five tags: BA:ACTIVE. From the PI menu. click OK to copy the five tags along a single column. Position the mouse over cell A2 in the spreadsheet. Click and drag to select the reference A2:A6. Move the cursor to cell C2.Tutorial 8. 10. From the PI menu. Position the mouse over cell A2 in the spreadsheet. Click and drag to select the reference A2:A6. PI DataLink then retrieves Tag descriptors into cells B2 to B6.. Click the edit box under Tagname. 9. 11. select Current Value.. Click OK in the dialog box. In the dialog box.. Type or select "descriptor" from drop-down box below Attribute. PI DataLink User Guide Page 15 . click the time at left radio button. . Enter "CD*" into the Tag Mask field.. From the PI menu. Actual Values from the PI Server In this example. respectively. Move the cursor to cell C10. Page 16 . Click the Tag Search button. 14. 1. Click Search to search for tags that begin with CD. Select engunits from the Attribute list box. PI DataLink then retrieves engineering units into cells E2 to E6. Click the show timestamps check box. From the PI menu.. 15.. 3. and 1h (one hour interval) in the Time Interval field. Enter t (for midnight today) in the Start Time field. Move the cursor to cell E2 in the spreadsheet. 2. PI DataLink then retrieves current values and the timestamps of these current values into columns D and C. Click and drag to select the reference A2:A6. Click the edit box under Tagname(s). Click OK in the dialog box. The Tag Search dialog box then appears.. The tag cdt158 then appears in the Tagname field in the Sampled Data dialog box.Add-in to Excel 12. Select this tag and click OK. Position the mouse over cell A2 in the spreadsheet. Click OK in the dialog box. select Sampled Data. select Tag Attributes. 13. again. we gather sampled data for a single tag. +8h (eight hour offset from start time) in the End Time field. The tag "cdt158" should be returned. PI DataLink User Guide Page 17 .Tutorial 4. PI DataLink then retrieves interpolated data from midnight to 8:00am at 1-hour intervals. Click OK. Right click on any part of the array created in the previous example 2.. Page 18 . Change the end time from "+8h" to "+9h" and click OK. we make a change to the end time used in the previous example. 1. Select Sampled Data. 3. Note that the array size has increased by one row..Add-in to Excel Changing Arguments from the Dialog Box In this example. PI DataLink then retrieves interpolated data from midnight to 9:00am at 1-hour intervals. .. Change the Output Cell from $C$10 to $A$10 and click OK. Change the tag edit field from "CDT158" to "SINUSOID" 4. we show how to use an old array as a template for a different tag. Enter the appropriate parameters and PI DataLink retrieves the requested PI values. the fastest way to use PI DataLink to transfer data between PI and Excel is to select an option from the PI menu item. Select Sampled Data. 3. A dialog box then appears. The next sections describe the features of PI DataLink in greater detail. PI DataLink User Guide Page 19 .Tutorial Using Old Arrays as Templates In this example. Notice that the sampled data for tag "SINUSOID" is in A10. Right click on any part of the array created in the previous example 2. 1. PI DataLink Summary As the above examples indicate. it adds the PI menu item to Excel's menu bar. Page 20 .Add-in to Excel PI Menu When PI DataLink is added to Excel. maxima.PI Menu Pop-up menu selections are available from this menu item. minima. averages and means for multiple time periods Advanced Calculated Data is similar to calculated data but with more advanced options (i. 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. ranges. 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 . standard deviations.e. which contain the necessary text information.Add-in to Excel Dialog Boxes Edit Fields The edit fields can contain either the necessary text information or references to cells. in the dialog box below. PI DataLink determines the type of information entered in the edit field by context. In this procedure. 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. 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. Page 22 . For example. Excel automatically enters the cell reference(s) into the edit field for you. respectively. time at left or time on top. is inside. and for the Time Unit fields in Time Filtered.. the default expression sampling mode from Advanced Calculated Data.. two columns if timestamps OR percent good are to be displayed. dialog box available from the PI menu... The default retrieval mode from Archive Value.. two.. there is a set of radio buttons with options column(s) or row(s). compressed.. for the Type fields in Compressed Data (Number) and (Times). dialog boxes.. or optional. the default boundary type from both Compressed Data (Number) and (Times).g.... the servers above the dotted line are the servers currently connected and the ones below are currently disconnected... Choose time at left to display data in two columns. PI DataLink will use the default PI Server. In the drop-down list. Choose row(s) to display the data in either one. is interpolated... or three rows.. is pt. Current value).. You can change the default PI Server in the Connections. and the default time unit for Time Filtered.. The Output field allows you to specify the upper left-hand corner of the range where PI DataLink will place the resulting data. PI DataLink User Guide Page 23 ..... Choose time on top to display data in two rows. Data Displayed as Columns or Rows For dialog boxes that expect to return an array of PI values (for example. If the PI Server field is blank. or three columns if timestamps AND percent good are to be displayed. Choose column(s) to display the data in either one column. For dialog boxes that expect to return a single PI value (e. 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... The PI Server field in all of the dialog boxes is labeled as opt. for the Mode fields in Calculated and Advanced Calculated data. is seconds. the default calculation mode from both Calculated and Advanced Calculated Data. is total. List Boxes List boxes appear for the Mode field in Archive Value. Sampled data).Dialog Boxes PI Server and Output Fields The PI Server field allows the selection of a PI server from the known servers list. there is a set of radio buttons with options no timestamp. Whenever a point class is selected in the Point Class field.8. Cells. the first tagname selected will be copied to the tagname edit field.Add-in to Excel Combo Boxes Combo boxes appear for the Attribute field in Tag Attributes. Whenever a new PI server is selected in the PI Server field.. 7:12 PM on December 10th. Page 24 .. You can change this format to another by selecting the cells and choosing Format. Time in PI DataLink Returned Values The timestamps returned by the PI DataLink dialog boxes are in Excel format. the Point Class field is repopulated. For example. the number represents the number of days since 1900. 10-Dec-99 7:12pm is entered into a cell as the number 36504. 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. When a valid tag is entered. However PI DataLink formats these timestamps into a PI time string. Clicking the button will bring up the Tag Search dialog box. its point class will be retrieved and entered into the Point Class field automatically. For example. The Point Class field is automatically populated with all the available point classes for the listed PI server. the Attribute field is repopulated. 1999 is displayed as 10-Dec-99 19:12:00. dd-mmm-yy hh:mm:ss.. specifically...> button next to the tagname field in the dialog boxes allows you to search the PI database for tags. Tag Search in Dialog Boxes The <. See your Excel documentation for more information on formatting numbers as time.e. Number. If you press OK in the Tag Search dialog box. i.. Number. For example in German..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.. The entries for the number format and time format fields may be any valid Excel format code from Format. respectively. Cells. dialog box.0" formats numbers to one decimal place and the time format "hh:mm:ss" timestamps to be hour:minute:seconds. PI DataLink User Guide Page 25 . Custom. The number format "0. the equivalent of "General" and "dd-mmm-yyyy hh:mm" are "Standard" and "TT-MM-JJJJ hh:mm" respectively. you can specify another default number and time formatting code in PI DataLink. This is done via the PI > Settings. Add-in to Excel Page 26 . formatted in whatever style you wish). the time interval edit field of a dialog box must refer to a cell that contains the string 32m. Show Time Check Box A show time check box appears in some of the dialog boxes. See Start and End Time (page 149) and Time Interval (page 150) for examples of valid PI time strings. you may specify a number followed by an h or an m or an s (for hours.8.. to indicate a time interval of thirty two minutes. For the time interval edit field. but displays it according to Format.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. the start time is used as the reference time for the translation of the relative time in the end time field. 10-Dec-99 19:12.e. for example. type 32m into the edit field. type the desired PI time string. whose PI function normally returns an array of PI values. If this box is unchecked. minutes. If you want to use cell references. PI DataLink does not display the timestamps. a number). If you reference an array of tags in either the Sampled Data or Calculated Data dialog box. or seconds. The current wall clock is the reference time for the translation of the relative time in the start time field. and along the topmost row if the row(s) is selected. PI DataLink returns one common set of timestamps for the entire group of tags. '10-Dec-99 19:12) or to cells that contain an Excel time (for example. you cannot refer to a cell containing an Excel time (i. to specify an interval of 32 minutes. For example. Number. Selecting this check box returns the timestamps as well as the values.. Cells. you may refer only to cells that contain a valid PI time interval string. you may refer either to cells that contain a PI time in string format (e. '-1d'). respectively). However. Note that for PI time in relative time format (for example. Remember that Excel stores time as the number of days since 1900. That is. If you want to use cell references. the reference time is different for the start time and the end time.g. For example. These timestamps appear at the leftmost column if the column(s) radio button is selected. 36504. PI DataLink User Guide Page 27 . In this case. the time at left and time on top radio buttons produce the same result. For minimum. The timestamps are displayed according to the orientation (rowwise or columnwise) specified. the order of the columns from left to right would be: start time. the timestamp of the minimum value. the timestamp of the maximum value. maximum. When a time interval is specified: Select Start Time to display the start time of the interval. For tag names in a single column. Timestamp Data for a Time Interval or Range Some dialog boxes that return a single value for each interval of time (for example. Select End Time to display the end time of the interval. Note: When an array reference is specified in the Tagname field. if the orientation is columnwise and if all check boxes are selected. Calculated Data) provide check boxes that control which timestamps are displayed. timestamps will appear on top of the values. and range functions: Select Min/Max Time to display timestamps for the interval's minimum and maximum values. Current Value) provide radio buttons that control where timestamps are displayed. Select time on top to display the timestamp in a cell above the retrieved values. for the same example the order from left to right would be: start time. For instance. the timestamp of the minimum value. Select time at left to return a timestamp into a cell to the left of the retrieved values. For tag names in a single row. Select no timestamp to suppress the timestamp. PI DataLink returns the timestamp and value depending on whether the reference of tag names is horizontal or vertical.Add-in to Excel Positioning Timestamp Data Returned by PI DataLink Some dialog boxes that return a single value (for example. Page 28 . If the check box for End Time is cleared. end time. the timestamp of the maximum value. timestamps will appear to the left of the values. xls distributed with PI DataLink. the PI DataLink dialog boxes are a front end to construct the corresponding PI DataLink functions. see the putval_code module in the piexam32. These PI DataLink functions can only be used in cells of a worksheet. Visual Basic does not recognize PI DataLink functions. when you call up the Current Value dialog box and enter SINUSOID into the Tagname field. PI DataLink pastes a custom PI function into the cell. They cannot be called within a procedure in Excel Visual Basic. and to format the output. use the application. if you try to find the current value for a tag which does not exist. For example.0 macro sheet or run as a macro in VBA. This is the same as manually entering the PI functions into that range of cells. the message "PIPoint not found" appears in the output cell. The VBA code can then check the cell values for the PI function results. When an error occurs at the PI SDK level. These PI DataLink functions can also be entered manually into the cells in a worksheet. PI DataLink User Guide Page 29 . Rather.xls for an example of invoking the macro function in VBA. Please see the Entering PI Functions Directly into Excel section below for a more detailed explanation of how array functions are used. Since most of the PI DataLink functions return more than one data element. PIPutVal() can only be used in an Excel 4.run method to invoke macro functions. Error Reporting PI DataLink is written in C++ and Visual Basic and utilizes both the PI System's SDK and Microsoft Excel's API.) Excel then evaluates this function. Thus. the functions should be entered into Excel as array functions. Values When a PI DataLink dialog box brings data from the PI Server to Excel. For an example of entering PI functions into the spreadsheet using VBA. Please refer to the putval_code module in the piexam32.0. PI DataLink pastes the following function into the cell: =PICurrVal("sinusoid". In VBA. it does not put the actual value into a cell.PI DataLink Functions PI DataLink Functions Functions vs. For example. PI DataLink displays the PI SDK error in the cell. and displays the resulting number. 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. The arguments to the function are described further in Details for PI DataLink Functions and Dialog Boxes (page 32). The PI DataLink output function PIPutVal() is an Excel Macro function and cannot be used directly in the cells of a worksheet. Note that the value of the time stamp does not have to change in order for Excel to trigger the PI DataLink function. Pressing F9 in Excel does not force PI DataLink functions to get new data from the PI server. to bypass this. there are two different behaviors depending on what new cell is referenced. Page 30 . 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. 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. which updates whenever Excel recalculates. Excel will trigger the DataLink function when the spreadsheet recalculates. Changing Arguments using Dialog Boxes If an argument needs to be changed. Whenever Excel recalculates (due to the user pressing F9 or changing any cells in the spreadsheet). A dialog box will appear with all the edit fields filled in with the arguments that were previously specified for that array. e. values on the spreadsheet update only when a function argument changes. If the newly referenced cell is part of the original array. This was intentionally done because most of the other DataLink functions do not represent chronically changing data. the dynamic time functions will be updated by Excel. causing the PI DataLink function to run. Then refer to this cell in the start time or end time argument of the DataLink query. However. However. use (today()+1/3) for 8am today. If the newly referenced cell is not part of the original array.g. If there are fewer values.Add-in to Excel Refreshing PI Data in a Spreadsheet There are two ways to refresh the data on a spreadsheet. The second way is to make a change to the arguments passed to the PI DataLink functions. if more values are retrieved. 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. Any of the edit fields can be changed and the new array will reflect those changes. those values will not show unless the Recalculate function is selected. If the output edit field is changed. right click on any part of the array and select the PI DataLink function. then the array is pasted with the upper-leftmost cell of the array at the newly referenced cell. there is no problem. The only exception is the Current value function. Ctrl+Alt+Shift+F9 forces all DataLink functions to recalculate. then the entire array gets moved with the upper-leftmost cell of the array at the newly referenced cell. Because PI DataLink retrieves data from the PI Server via functions. it may not be appropriate to use the function wizard to enter PI functions into Excel. Therefore. the easiest way is to right click on any part of the array and select Select DataLink Formula. An outcode of 2 places the snapshot time in row one and the snapshot value in row two of a 2 x 1 array. or an error "You cannot change part of an array" appears. if you specify an array output range that is greater than the number of values returned from the function. Finally. In general. String Arguments For string arguments to functions. Also. select a 1 x 2 output array and enter: =PICurrVal("sinusoid". Refer to the detail description for each individual PI function for the meaning of its outcode. note that Excel function wizard will only insert function into one cell on the spreadsheet. Then perform the desired operation. moved or deleted." PI DataLink User Guide Page 31 . 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. you need to surround the arguments with double quotes. Entering PI Functions Directly into Excel Array Values All of PI DataLink functions except PIPutVal() return array values. the extra cells are displayed as empty cells even though they have an embedded formula. you must first select the appropriate array output range.PI DataLink Functions Selecting an Entire DataLink Function If a large PI DataLink function array needs to be copied. For example. Refer to the online help for Microsoft Excel for more information on array functions. enter the PI function and its arguments into Excel's formula bar. 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 0 in PICurrVal() results in the snapshot value in the single cell. For example. place the PI function into the cells with the CTRL+SHIFT+ENTER combination of keystrokes. "casaba") to retrieve the snapshot time and value for the tag sinusoid from the PI Server "casaba. 1. This being the case. Next. The entire Excel function array must be moved or deleted. Current Value Dialog Box This dialog box gets the current Snapshot value of a PI tag. and A3 respectively.0. the following function: =PICurrVal(A1. For example. Special Notes This function updates whenever Excel calculates or recalculates any cell in the spreadsheet. press the F9 key. enter: =PICurrVal("sinusoid". Page 32 .) into a 1x1 output range . To force an immediate recalculation. For example. PIServer Argument The PIServer argument is optional. you can omit the PIServer argument. to retrieve the current value for the tag sinusoid from the default PI Server. A3) gives the same result as the example above if the three arguments are stored in cell A1. If you want to use the default server. Each section describes the dialog box first and then discusses each of the arguments for the corresponding custom PI function or functions. Required Field Tagname. The reference to Tagname may be an array.Add-in to Excel Using Cell Reference in Arguments You can use cell references for all the arguments in all of PI DataLink functions. A2. Details for PI DataLink Functions and Dialog Boxes The following sections describe each of the PI DataLink functions in detail. A2. The default PIServer can be changed in the Connections dialog box. Returns Outcode Column 1 0 Current value 1 Timestamps Column 2 Current value An output code of 2 transposes the output array that results from an output code of 1. 1. or 2. Example The following retrieves the current value and the corresponding timestamp for the tag let439 from the PI Server "holden:" =PICurrVal("let439".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.Retrieves the value in the archive only before the specified timestamp Interpolated . There are five modes to select from: Previous . PIServer (string) The PI Server. PIServer) Arguments Argument Explanation Tagname (string) The tag for which you want the snapshot (current) value. either 0. the previous value is simply carried forward. outcode (integer) An output code.Retrieves the value in the archive at or before the specified timestamp Previous only .1. Auto . For this special case.Details for PI DataLink Functions and Dialog Boxes PICurrVal() PICurrVal(tagname."holden") Archive Value Dialog Box This dialog box gets a value at a specified time. outcode.Same as interpolated except for resolution code 4 tags on PI 2 Server and tags with step attribute set on PI 3 Server. the value at or before the specified timestamp is returned PI DataLink User Guide Page 33 . If no value exists. outcode. Page 34 . or 2. mode (string) The retrieval mode. either 0. time stamp (string) The PI timestamp. outcode (integer) An output code. Returns Outcode Column 1 0 Archive value 1 Timestamp Column 2 Archive value An output code of 2 transposes the output array that results from an output code of 1. the message "No events found" is returned Required Fields Tagname or Expression Timestamp Related Topics PIArcVal() (page 34) PIExpVal() (page 35) PIArcVal() PIArcVal(tagname. PIServer (string) The PI Server. PIServer.Retrieves the value in the archive only after the specified timestamp Exact Time .Retrieves the value in the archive at or after the specified timestamp Next Only .Retrieves the value in the archive for a specified time if an entry exists at that time. mode) Arguments Argument Explanation tagname (string) The tag for which you want the archive value. 1. timestamp.Add-in to Excel Next . "interpolated") PIExpVal() PIExpVal(expression."11-dec-92 19:20". "casaba"."y". 1992 from the PI Server "casaba:" =PIArcVal("cdep158".0. 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')". time stamp (string) The PI timestamp. PIServer) Arguments Argument Explanation expression (string) The expression for which you want the archive value.0.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."thevax") PI DataLink User Guide Page 35 . PIServer (string) The PI Server. timestamp. Returns Outcode Column 1 0 Archive value 1 Timestamp Column 2 Archive value An output code of 2 transposes the output array that results from an output code of 1. The default attribute is descriptor.com/downloadcenter.aspx (http://techsupport. 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. For a complete list of tag attributes. the list of tag attributes depends on the point class selected. choose a tag attribute from the combo box. available from http://techsupport.aspx) under "PI 3 Enterprise Server". For PI 2. Required Fields Tagname Tag attribute For PI3.Add-in to Excel Tag Attributes Dialog Box This dialog box retrieves a point attribute for a given tag.osisoft.com/downloadcenter.osisoft. 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 . Returns Tag attribute PI DataLink User Guide Page 37 . PIServer) Arguments Argument Explanation tagname (string) The tag for which you want an attribute. 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. used by some interfaces sourcept Tagname for output to other systems. attribute (string) The tag attribute.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. attribute. see the list under Tag Attributes Dialog Box (page 35). PIServer (string) The PI Server. ) 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 the mark as filtered option is selected. the PINCompDat() function is called. behavior follows that of "inside" Page 38 . Otherwise. Boundary Type There are 4 boundary types: Inside (default) . If a filter expression is not specified.Returns specified number of data points from starttime including a data point at or prior to starttime Interpolated . See Filter Expressions (page 146) for more information on the filter expression syntax.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 interpolated at starttime Auto . the PINCompFilDat() function is called.Same as interpolated except if resolution code 4 tags on PI 2 Server or step attribute is set on PI 3 Server. a "Filtered" status is returned for each group of values that does not satisfy the filter expression.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". 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 filter expression begins with a tagname. stime (string) The start time in PI time format. mode) Arguments Argument Explanation tagname (string) The tag for which you want compressed data. outcode (integer) An output code. Since tag names in filter expression are enclosed with single quotes. If you enter the filter expression into a cell on the worksheet and refer to it in the dialog box. the final 44 cells have blank strings in them. stime. mode (string) The boundary type. PIServer.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. For example. PIServer (string) The PI Server. numvals (integer) The number of compressed data points. Select show bits if you want to show the extended status bits associated with the returned events. Related Topics Filter Expressions (page 146) PINCompDat() (page 39) PINCompFilDat() (page 40) PINCompDat() PINCompDat(tagname. Use a negative number to gather data from the archive that goes backwards from the stime. Select show annotations if you want to show the annotations associated with the returned events. PI DataLink User Guide Page 39 . Special Notes This dialog box returns empty strings when there is a smaller number of values than the number which you specified. outcode. you must begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet. See Outcodes for more information on outcodes. numvals. be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. if you wish to retrieve 400 values starting from midnight today and there are only 356 values (including filtered events). Data are retrieved from the default PI Server with inside as boundary type. See Filter Expressions (page 146) for more information on the filter expression syntax.10. Use a negative number to gather data from the archive that goes backwards from the stime. this morning from the default PI Server with inside as boundary type: =PINCompDat("cdf144". stime (string) The start time in PI time format. use 1 to return Filtered status.m.."2:00".m. See Outcodes for more information on outcodes. filtexp (string) The filter expression. numvals. 0 to skip. mode (string) The boundary type. outcode. Returns Refer to Outcodes.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. Example The following retrieves 10 compressed data points and the corresponding times. stime. mode) Arguments Argument Explanation tagname (string) The tag for which you want compressed data.."1:00"."inside") PINCompFilDat() PINCompFilDat(tagname. outcode (integer) An output code.. for the tag cdf144 while the tag cdep158 is greater than 38: =PINCompFilDat("cdf144".1. Page 40 .10. filtcode. filtexp. filtcode (integer) A filter code.1. PIServer (string) The PI Server.1. PIServer. starting at 2:00 a."'cdep158'>38".) The status Filtered is displayed for times when the filter condition is false. numvals (integer) The number of compressed data points. 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.Same as interpolated except if resolution code 4 tags on PI 2 Server or step attribute is set on PI 3 Server.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 . the PICompFilDat() function is called. a "Filtered" status is returned for each group of values that does not satisfy the filter expression. PI DataLink User Guide Page 41 . If a filter expression is not specified. Required Fields Tagname Start Time End Time Filter Expression If a filter expression is specified.Returns data points between starttime and endtime including a data point interpolated at starttime and a data point interpolated at endtime Auto . See Filter Expressions (page 146) for more information on the filter expression syntax.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 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.Returns data points at and between starttime and endtime Outside . Otherwise. Boundary Type There are 4 boundary types: Inside (default) . the PICompDat() function is called. The number of data points retrieved for the given time period is returned in the first cell. be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. Page 42 . if the filter expression begins with a tagname. Select show annotations if you want to show the annotations associated with the returned events. stime. if you retrieve values starting from y to y+5h. PIServer. Related Topics Filter Expressions (page 146) PICompDat() (page 42) PICompFilDat() (page 43) PICompDat() PICompDat(tagname. Returns Refer to Outcodes. etime. you must begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet. PIServer (string) The PI Server. outcode (integer) An output code. etime (string) The end time in PI time format. the number of values in the PI Server may be different when you call up the spreadsheet on different days. mode (string) The boundary type. mode) Arguments Argument Explanation tagname (string) The tag for which you want compressed data. This situation may occur if you use relative time references.Add-in to Excel Select show bits if you want to show the extended status bits associated with the returned events. outcode. 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. For example. stime (string) The start time in PI time format. If you enter the filter expression into a cell on the worksheet and refer to it in the dialog box. Since tag names in filter expression are enclosed with single quotes. See Outcodes for more information on outcodes. 0 to skip.1. See Filter Expressions (page 146) for more information on the filter expression syntax.m. filtcode. this morning from the default PI Server with inside as boundary type: =PICompDat("cdf144". See Outcodes for more information on outcodes. filtexp (string) The filter expression. Sampled Data Dialog Box This dialog box gathers evenly spaced. PIServer (string) The PI Server. sampled values from the archive. use 1 to return Filtered status. Returns Refer to Outcodes. outcode. filtcode (integer) A filter code. PIServer. mode (string) The boundary type."inside") PICompFilDat() PICompFilDat(tagname. to 3:00 a. for the tag cdf144 when the tag cdep158 is greater than 38: =PICompFilDat("cdf144". stime. filtexp."3:00".m.. stime (string) The start time in PI time format.) The status Filtered is displayed for times when the filter condition is false.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. Example The following retrieves compressed data points and the corresponding times.1. etime. outcode (integer) An output code.. Data are retrieved from the default PI Server with inside as boundary type."10:00".1."1:00". mode) Arguments Argument Explanation tagname (string) The tag for which you want compressed data. Otherwise."2:00". and ending at 10:00 a..m. the PISampDat() function is called. starting from 2:00 a.m. the PISampFilDat() function is called. PI DataLink User Guide Page 43 . If a filter expression is not specified."'cdep158'>38". etime (string) The end time in PI time format. If the mark as filtered option is selected. etime. If the tag is from a PI 2 Server. the specified range of compressed values are retrieved from the PI Server while a given filter expression is true. a "Filtered" status is returned for each sampled value that does not satisfy the filter expression.Add-in to Excel Required Fields Tagname Start Time End Time Time Interval Filter Expression If a filter expression is specified. stime. if the filter expression begins with a tagname. 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. PIServer) Arguments Page 44 Argument Explanation tagname(string) The tag for which you want sampled data. etime (string) The end time in PI time format. you need to begin the expression with two single quotes when the filter expression is stored in a cell on the worksheet. Special Notes If you can enter the filter expression into a cell on the worksheet and refer to it in the dialog box. Since tagname in filter expression should be enclosed with single quotes. interval. See Fi (page 146)lter Expressions for more information on the filter expression syntax. be sure to begin the expression with a single quote so that Excel will interpret the expression as a string. stime (string) The start time in PI time format. outcode. . Related Topics Filter Expressions (page 146) PISampDat() (page 44) PISampFilDat() (page 46) PIExpDat() (page 47) PISampDat() PISampDat(tagname. PIServer (string) The PI Server. either 0. 2.Details for PI DataLink Functions and Dialog Boxes Argument Explanation interval (string) The time interval in PI time format. outcode (integer) An output code. Example The following retrieves sampled data for the tag located in cell B1."t". PI DataLink User Guide Page 45 . from midnight yesterday to midnight today at 3-hour intervals: =PISampDat(b1.1. Returns Outcode Column 1 0 Sampled data 1 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."y"."3h". 1. or 3.) Timestamps are also returned. use 1 to return Filtered status. Page 46 . 11-Jan-97 2:00AM. 11-Jan-97 1:00AM.) Timestamps are shown in column1 and values in column2. filtcode (integer) A filter code. PI Server) Arguments Argument Explanation tagname(string) The tag for which you want sampled data. or 3. 0 to skip. A "Filtered" status is returned for values do not satisfy the filter condition in cell A1. filtexp.Add-in to Excel PISampFilDat() PISampFilDat(tagname. 1. and 11-Jan-97 3:00AM: =PISampFilDat("sinusoid". stime. etime (string) The end time in PI time format.1. filtcode. interval (string) The time interval in PI time format. either 0."1h". See Filter Expressions (page 146) for more information on the filter expression syntax. Returns Outcode Column 1 0 Sampled data 1 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."11-Jan-97".1. etime. 2. stime (string) The start time in PI time format. filtexp (string) The filter expression. PIServer (string) The PI Server. outcode (integer) An output code. Example The following formula retrieves sampled data for SINUSOID at 11-Jan-97. interval. outcode."+3h".A1. outcode (integer) An output code. etime. 1. etime (string) The end time in PI time format. PIServer (string) The PI Server. either 0. interval (string) The time interval in PI time format. PIServer) Arguments Argument Explanation expression (string) The calculation expression."thevax") It also displays the timestamps. the message "No events found" is returned. outcode.Retrieves the value in the archive for a specified time if an entry exists at that time.Details for PI DataLink Functions and Dialog Boxes PIExpDat() PIExpDat(expression. 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')". If no value exists.1. interval. See Calculation Expressions (page 143) for more information on calculation expression syntax."1h". the previous value is simply carried forward Exact Time .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. 2. There are two modes to select from: Interpolated . PI DataLink User Guide Page 47 ."t". or 3. Timed Data Dialog Box This dialog box returns sampled values for a single tag that are synchronized with an array of timestamps. stime. stime (string) The start time in PI time format."y". For this special case. Returns Outcode Column 1 0 Calculated data 1 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. Add-in to Excel Required Fields Tagname Timestamp. mode (string) The retrieval mode. the values in this array must be either monotonically increasing or monotonically decreasing. timestamps (reference) A reference to an array of times in PI format. For PI 2. PIServer (string) The PI Server. mode) Arguments Argument Explanation tagname (string) The tag for which you the sampled data. the data are returned along a single column.b1:b12. timestamps.. If the timestamps are in a single column."interpolated") Page 48 . PIServer. 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. 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". If the timestamps are in a single row. The timestamp field has to be a reference to a time array. For PI 2. the data are returned along a single row. Returns Sampled data. See Calculation Expressions (page 143) for more information on calculation expression syntax.) Calculated Data Dialog Box This dialog box returns a single calculated value or evenly spaced calculated values from the PI Data Archive. If the timestamps are in a single column. the values in this array must be either monotonically increasing or monotonically decreasing. timestamps (reference) A reference to an array of times in PI format. PIServer (string) The PI Server Returns Sampled data. the data are returned along a single column. For PI 2. 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')".Details for PI DataLink Functions and Dialog Boxes PITimeExpDat() PITimeExpDat(expression. PIServer) Arguments Argument Explanation expression (string) The calculation expression. timestamps. Calculation modes are: Total Minimum Maximum Standard deviation Range Average Count Mean PI DataLink User Guide Page 49 . the data are returned along a single row.b1:b12. If the timestamps are in a single row. When an interval is specified and the mode is Max or Min. value Minimum value Maximum Time of max. do not specify an interval and the PICalcVal() function is used. If the rows checkbox is selected. Average. Required Fields Tagname Start Time End Time Conversion Factor Calculation Mode Interval To retrieve a single calculated value. value Column 3 Range value Special Notes When an interval is not specified and the mode is Total. value Time of max. the percent good value is returned at the cell below the calculated value cell. Count or Mean. or range. the timestamps displayed are the start time of each calculation interval.Add-in to Excel All Calculation modes are time-weighted except for the mean function. Page 50 . Check Box Check show pctgood if you want PI DataLink to display the percentage of the time range that contains good value. The percent good value is normally returned to the right of calculated value cell. Mode Column 1 Column 2 Minimum Time of min. the specified interval determines the spacing of the calculation and the PICalcDat() function is used. To retrieve evenly spaced calculated data. which is event-weighted. value Maximum value Range Time of min. Standard Deviation. the timestamps are not displayed even if the Show Timestamps check box is selected. 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. When the calculation is a time-weighted Total and part of the archived data within the range are bad. maximum. We recommend that you always look at the percent good value before using the calculation result. the tag value takes on the average value of the entire range. Timestamp(s) are returned when the calculation mode is minimum. Details for PI DataLink Functions and Dialog Boxes PI DataLink User Guide Page 51 . 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. this assumption may not be valid when a large fraction of the time range contains bad data. The following table displays the conversion factors for two of the common PI 2 Server default time units vs.0 0. the totalization default is "units per day. various flow tag units.for. std and range." On the PI 2 Server. Therefore. Should be 1 for max. stime. 0-7 except 3. see Special Notes (page 49) under Calculated Data Dialog Box (page 49) . etime. the totalization default time (totdefaulttime is the time unit in seconds) can be found in the file pilink:piparams. stime (string) The start time in PI time format. mode (string) The calculation mode (total. count. average. outcode (integer) An output code. mean.Add-in to Excel However. range. . Flow tag unit Server default is units/day (totdefaulttime = 86400) Server default is units/hour (totdefaulttime = 3600) Units/day 1. we recommend that you always look at the percent good value before using the calculation result. count or mean).041667 Units/hour 24 1 Units/minute 1440 60 Units/second 86400 3600 Related Topics PICalcVal() (page 52) PICalcDat() (page 54) PICalcVal() PICalcVal(tagname. mode. etime (string) The end time in PI time format. stdev. avg. cfactor. In all the PI 3 Servers and in most of the PI 2 Servers. PIServer (string) The PI Server. For more discussion of the conversion factor. PIServer) Arguments Page 52 Argument Explanation tagname (string) The tag for which you want the calculated value. min. outcode. minimum. maximum. cfactor (number) A multiplicative conversion factor. e. Value Maximum value Stdev Stdev. only the calculated value is returned. the following applies: Mode Column 1 Column 2 Column 3 Total Total value Percent good Minimum Time of min.. value Percent good Range Time of min.. 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. If the outcode is 4. value Maximum value Percent good Stdev Stdev. the following applies: Mode Column 1 Column 2 Total Total value Minimum Time of min. i. If the outcode is 5.Details for PI DataLink Functions and Dialog Boxes Returns If the outcode is 0.e.. Outcode of 3 is not used. If the outcode is 1. i. value Minimum value Percent good Maximum Time of max. Value Range Time of min. An output code of 7 transposes the output array that results from an output code of 5. results are returned in rows instead of in columns. results are returned in rows instead of in columns. Value Minimum value Maximum Time of max. 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. PI DataLink User Guide Page 53 . i.e. Value Average Average value Count Count value Mean Mean value Time of max. results are returned in rows instead of in columns. the percent good is returned to the right of the value cell. 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". cfactor (number) A multiplicative conversion factor. average. PIServer (string) The PI Server. The percent good is returned next to the total. values. see Special Notes (page 49) under Calculated Data Dialog Box (page 49). std and range. etime (string) The end time in PI time format. values."t". Returns The outcode affects the output as follows: Page 54 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. 0-7."y". and pctgood along 3 rows . avg."total". PICalcDat() PICalcDat(tagname. min. interval (string) The time interval in PI time format. cfactor. and pctgood along 3 columns 6 Values and pctgood along 2 rows 7 Timestamps. minimum. stdev. stime (string) The start time in PI time format. outcode (integer) An output code.4. mean. count or mean). Should be 1 for max. etime.1440. count. interval. mode. maximum. outcode.) The result is multiplied by 1440. stime. For more discussion of the conversion factor. range. PIServer) Arguments Argument Explanation tagname (string) The tag for which you want the calculated data. mode (string) The calculation mode (total. PI DataLink User Guide Page 55 ."3h".1.) Timestamps are also returned. See Calculation Expressions (page 143) for more information on calculation expression syntax. 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. the requested summaries on the source point are calculated for the time ranges where the expression evaluates to true."t".ini file: =PICalcDat(b1.24. from midnight yesterday to midnight today at 3-hour intervals from the default PI Server specified in the PILogin."total". The values are multiplied by 24 before they are displayed in the spreadsheet. Start Time End Time Conversion Factor Calculation Mode Filter Expression If a filter expression is specified.Details for PI DataLink Functions and Dialog Boxes Example The following retrieves totals for the tag located in cell B1."y". See Filter Expressions (page 146) for more information on the filter expression syntax. Event-Weighted . two events are required.Weights the values in the calculation by the time over which they apply. Expression Sampling Mode There are 3 expression sampling modes for sampling the filter expression: Pt.Evaluates the filter expression at the timestamp of any compressed value of the source point Exp.Evaluates the filter expression at evenly spaced sampling intervals There are 2 expression sampling modes for sampling the expression to be summarized: Compressed (default) . Compressed . If the Expression Sampling Mode is not interpolated. 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. Calculation Basis There are 2 types of calculation basis: Time-Weighted (default) .Add-in to Excel Interval To retrieve a single calculated value." Page 56 . the specified expression sampling interval determines the spacing at which the expression is evaluated. Compressed (default) . the specified interval determines the spacing of the calculation.Evaluates the expression at evenly spaced sampling intervals Expression Sampling Interval If Expression Sampling Mode is specified as interpolated.Evaluates the expression at the timestamp of any compressed values of any tags in the expression Interpolated . then the expression sampling interval is ignored. To retrieve evenly spaced calculated data.Weights each event with the same weight. There must be at least one event within the time range to perform a successful calculation. do not specify an interval. For standard deviation.Evaluates the filter expression at the timestamp of any compressed values of any tags in the filter expression Interpolated . 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 maximum.0. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. min. cfactor (number) A multiplicative conversion factor. stdev. PIServer) Arguments Argument Explanation expression (string) The expression for which you want the calculated value.1.0. avg. Should be 1 for max. sampinterval (string) The sampling interval in PI time format. minimum. For more discussion of the conversion factor. Returns Refer to Returns section for PICalcVal() (page 52) function."t". minpctgood (number) Minimum percentage of good data over time range. calcbasis."total". average. 0 for time-weighted. sampmode (string) The sampling mode (compressed or interpolated). calcbasis (integer) The calculation basis.) The result is multiplied by 1. Page 60 . mode. stime (string) The start time in PI time format. etime (string) The end time in PI time format. 1 for event-weighted. PIServer (string) The PI Server. The percent good is returned next to the total. outcode. 0-7 except 3. see Special Notes (page 49) under Calculated Data Dialog Box (page 49) .4. std and range."compressed ". minpctgood. 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'". stime. range.Add-in to Excel PIAdvCalcExpVal() PIAdvCalcExpVal(expression."10m". mode (string) The calculation mode (total. sampmode. cfactor. etime. sampinterval. mean. outcode (integer) An output code. Since compressed is the specified sampling mode. count."y". count or mean). sampmode (string) The sampling mode (compressed or interpolated). PIServer (string) The PI Server."10m". stime (string) The start time in PI time format. filtexp. 0-7 except 3. filtexp (string) The filter expression.0. sampinterval.0. minpctgood. minimum. maximum. etime. cfactor. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. Since compressed is the specified sampling mode. etime (string) The end time in PI time format. 1 for event-weighted.1. stdev."y".Details for PI DataLink Functions and Dialog Boxes PIAdvCalcExpFilVal() PIAdvCalcExpFilVal(expression. stime. calcbasis (integer) The calculation basis. sampinterval (string) The sampling interval in PI time format."compressed". For more discussion of the conversion factor. 0 for time-weighted. "total". mean. The percent good is returned next to the total. min. std and range. cfactor (number) A multiplicative conversion factor. calcbasis. outcode (integer) An output code. the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. count. 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'". See Filter Expressions (page 146) for more information on the filter expression syntax. avg. see Special Notes (page 49) under Calculated Data Dialog Box (page 49) ."t". Returns Refer to Returns section for PICalcVal() (page 52) function. range. sampmode. mode. average.4. Should be 1 for max."'productid'="Prod uct2"". PI DataLink User Guide Page 61 . PIServer) Arguments Argument Explanation expression (string) The expression for which you want the calculated value. mode (string) The calculation mode (total. outcode.) The result is multiplied by 1. minpctgood (number) Minimum percentage of good data over time range. count or mean). range. 1 for event-weighted.0. stdev. count. stime (string) The start time in PI time format.) The result is multiplied by 1. etime (string) The end time in PI time format. mode (string) The calculation mode (total. minpctgood. calcbasis (integer) The calculation basis. outcode. cfactor. PIServer) Arguments Argument Explanation tagname (string) The tag for which you want the calculated data. Should be 1 for max. Returns Refer to Returns section for PICalcDat() (page 54) function. PIServer (string) The PI Server. 0-7. The percent good is returned next to the total."t"."3h".50. Page 62 . count or mean). Example The following retrieves totals for the tag cdf144. minpctgood (number) Minimum percentage of good data over time range . maximum. mean. min. calcbasis."total". mode. from midnight yesterday to midnight today at 3-hour intervals from the default PI Server: =PIAdvCalcDat("cdf144". interval.4. For more discussion of the conversion factor. outcode (integer) An output code.Add-in to Excel PIAdvCalcDat() PIAdvCalcDat(tagname. std and range. interval (string) The time interval in PI time format. average. etime. stime. minimum. 0 for time-weighted. cfactor (number) A multiplicative conversion factor. see Special Notes (page 49) under Calculated Data Dialog Box (page 49) .1."y". avg. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. filtexp. mode (string) The calculation mode (total. See Filter Expressions (page 146) for more information on the filter expression syntax. interval (string) The time interval in PI time format."10m". PI DataLink User Guide Page 63 . the sampling interval is ignored and the filter expression will be sampled at the compressed events of cdf144."3h".4. compressed". count."t". average. etime (string) The end time in PI time format. Should be 1 for max. calcbasis. cfactor (number) A multiplicative conversion factor. minimum. calcbasis (integer) The calculation basis.Details for PI DataLink Functions and Dialog Boxes PIAdvCalcFilDat() PIAdvCalcFilDat(tagname. compressed. 0 for time-weighted. 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". The percent good is returned next to the total. Example The following retrieves totals for the tag cdf144."pt. Since pt. 1 for event-weighted.1. avg. maximum. sampmode. sampinterval.compressed is the specified sampling mode. filtexp (string) The filter expression."tota l". interval. cfactor. std and range."'cdm158'=""Manual""".0."y". sampmode (string) The sampling mode (pt. PIServer (string) The PI Server. min. PIServer) Arguments Argument Explanation tagname (string) The tag for which you want the calculated data. minpctgood. minpctgood (number) Minimum percentage of good data over time range. range. etime. outcode (integer) An output code. outcode. stime (string) The start time in PI time format. stdev. exp. see Special Notes (page 49) under Calculated Data Dialog Box (page 49). count or mean). 0-7. For more discussion of the conversion factor. stime. mode.) The result is multiplied by 1. compressed or interpolated).50. mean. Returns Refer to Returns section for PICalcDat() (page 54) function. sampinterval (string) The sampling interval in PI time format. interval (string) The time interval in PI time format. sampmode (string) The sampling mode (compressed or interpolated). std and range. Should be 1 for max. maximum. interval. Example The following retrieves totals for the expression 'cdf144'+'cdt158'. count or mean). Page 64 . mode. outcode. etime (string) The end time in PI time format. sampinterval."t". from midnight yesterday to midnight today at 3-hour intervals from the default PI Server: =PIAdvCalcExpDat("'cdf144'+'cdt158'". 0-7. For more discussion of the conversion factor. mean. minpctgood. min."total".4.) The result is multiplied by 1. cfactor. stime (string) The start time in PI time format.1. 1 for event-weighted."y". count. sampinterval (string) The sampling interval in PI time format. mode (string) The calculation mode (total."compr essed". calcbasis. minpctgood (number) Minimum percentage of good data over time range. "10m". PIServer) Arguments Argument Explanation expression (string) The expression for which you want the calculated data.0. minimum. calcbasis (integer) The calculation basis."3h". stdev.Add-in to Excel PIAdvCalcExpDat() PIAdvCalcExpDat(expression. sampmode. PIServer (string) The PI Server.50. Since compressed is the specified sampling mode. etime. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. Returns Refer to Returns section for PICalcDat() (page 54) function. average. cfactor (number) A multiplicative conversion factor. avg. see Special Notes (page 49) under Calculated Data Dialog Box (page 49). range. 0 for time-weighted. stime. the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. The percent good is returned next to the total. outcode (integer) An output code. sampmode (string) The sampling mode (compressed or interpolated). filtexp. PIServer (string) The PI Server."y". Since compressed is the specified sampling mode.time-weighted. std and range. mode. sampinterval (string) The sampling interval in PI time format. interval. Should be 1 for max. maximum. avg. The minpctgood is 50 percent so result will only be displayed if percent good is 50 percent or greater. stdev."10m". outcode (integer) An output code. The percent good is returned next to the total.Details for PI DataLink Functions and Dialog Boxes PIAdvCalcExpFilDat() PIAdvCalcExpFilDat(expression. cfactor (number) A multiplicative conversion factor. count or mean). count."total". 0-7 except 3.0. see Special Notes (page 49) under Calculated Data Dialog Box (page 49). etime.) The result is multiplied by 1. etime (string) The end time in PI time format."3h". calcbasis (integer) The calculation basis. stime (string) The start time in PI time format. average. sampmode. Returns Refer to Returns section for PICalcDat() (page 54) function."'productid'= "Product2"". minpctgood. stime. mean.4. filtexp (string) The filter expression. PIServer) Arguments Argument Explanation expression (string) The expression for which you want the calculated value. the sampling interval is ignored and the expression will be sampled at the combined compressed events of cdf144 and cdt158. calcbasis. PI DataLink User Guide Page 65 . outcode. sampinterval."compressed". (time-weighted or event-weighted). minimum.1. range. minpctgood (number) Minimum percentage of good data over time range. cfactor. mode (string) The calculation mode (total."t". 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'". min. For more discussion of the conversion factor. See Filter Expressions (page 146) for more information on the filter expression syntax. interval (string) The time interval in PI time format. 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. Required Fields Expression. 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. The user can specify multiple time ranges as evenly space intervals as in the Calculated Data dialog box. See Calculation Expressions (page 143) for more information on calculation expression syntax. 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 . or 2 only the calculated value is returned. If the outcode is 6 or 7. See Calculation Expressions (page 143) for more information on calculation expression syntax.Details for PI DataLink Functions and Dialog Boxes PITimeFilterVal() PITimeFilterVal(expression. PI DataLink User Guide Page 67 . timeunit (string) Unit of time for the result to be displayed."y". outcode (integer) An output code. Example The following calculates the amount of time that the expression from cell $A$1 is true from the PI Server named THEVAX. If the outcode is 4 or 5."seconds". PIServer) Arguments Argument Explanation expression (string) The calculation expression. Valid entries are: seconds. stime (string) The start time in PI time format. etime (string) The end time in PI time format. starting from midnight yesterday to midnight today: =PITimeFilterVal($A$1. the percent good is returned below the value cell."thevax") The calculation result is expressed in seconds."t". 0-7 except 3. timeunit. PIServer (string) The PI Server. Outcode of 3 is not used. 1. stime. outcode.1. minutes. the percent good is returned to the right of the value cell. hours and days . etime. Returns If the outcode is 0. Add-in to Excel PITimeFilter() PITimeFilter(expression. starting from midnight yesterday to midnight today: =PITimeFilter($A$1. See Calculation Expressions (page 143) for more information on calculation expression syntax."y"."1h"."thevax") It also displays the timestamps for the start time of each calculation interval. Valid entries are: seconds. timeunit (string) Unit of time for the result to be displayed. outcode. Returns Outcode Column 1 0 Calculated data 1 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. The calculation result is expressed in seconds. interval. PIServer) Arguments Argument Explanation expression (string) The calculation expression. stime. outcode (integer) An output code. 0-7. etime (string) The end time in PI time format. timeunit.1. minutes. Page 68 ."seconds". PIServer (string) The PI Server. interval (string) The time interval in PI time format. stime (string) The start time in PI time format. hours and days. 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. etime."t". Required Fields Point ID Related Topics PIPointIDToTag() (page 69) PIPointIDToTag() PIPointIDToTag(pointid. =PIPointIDToTag("123". 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."thevax") PI DataLink User Guide Page 69 .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 Tagname Descriptor Point Source Point Type Point Class Engineering Units Related Topics PIAttributeMaskToTag () (page 70) PIAttributeMaskToTag () PIAttributeMaskToTag(tagname. descriptor. pointsource (string) Point Source mask. either 0 or 2. pointclass. pointsource. engunits.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. engunits (string) Engineering Units mask. outcode. . pointclass (string) Point Class mask. descriptor (string) Descriptor mask. PIServer) Arguments Page 70 Argument Explanation tagname (string) Tagname mask. PIServer (string) The PI Server. pointtype. pointtype (string) Point Type mask. outcode (integer) An output code. "*"."*". 1. PIServer) Arguments Argument Explanation alias (string) Module item that is a reference to a PI point."*".Details for PI DataLink Functions and Dialog Boxes Returns Outcode Column 1 0 Tagname Column 2 An output code of 2 transposes the output array that results from an output code of 1. =PIAttributeMaskToTag("sin*". Outcode (integer) An output code. outcode. PI DataLink User Guide Page 71 . modulepath. modulepath (string) Full path to a module in module database. PIServer (string) The PI Server."*". or 2. Example The following returns the tagname of the tags which start with "sin" from server named THEVAX. querydate (integer) Query for modules with effective dates at or after this date. Required Fields Alias Module Path Query Date Related Topics PIAliasToTag() (page 71) PIAliasToTag() PIAliasToTag(alias."thevax") Alias Dialog Box This dialog box returns a tagname when an alias is specified.0. either 0. querydate."*". Example The following returns the tagname corresponding to the "Temperature" alias of module "Reactor1" which is a submodule of "Unit1". =PIAliasToTag("Temperature"."\Unit1\Reactor1".0.Add-in to Excel Returns Outcode Column 1 0 Tagname 1 Tagname Column 2 Server of tag An output code of 2 transposes the output array that results from an output code of 1. The module database is queried at current time."*"."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 . "Unit1" is at the root of the module database for a PI server named THEVAX. modulepath. querydate. Example The following returns the value corresponding to the "Implementer" property of module "Reactor1" which is a submodule of "Unit1". Outcode (integer) An output code. PIServer (string) The PI Server. either 0 or 2."\Unit1\Reactor1". querydate (integer) Query for modules with effective dates at or after this date. =PIPropertyToValue("Implementer". "Unit1" is at the root of the module database for a PI server named THEVAX.Details for PI DataLink Functions and Dialog Boxes PIPropertyToValue() PIPropertyToValue(property. The module database is queried at current time."thevax") PI DataLink User Guide Page 73 ."*". PIServer. An output code of 2 displays the value of the property in a row. outcode) Arguments Argument Explanation Property (string) Module item that has value of virtually anything. modulepath (string) Full path to a module in module database. Returns An output code of 0 displays the value of the property in a column. To create a trend.Add-in to Excel Insert Trend Control The Trend Control is an ActiveX control that can be inserted onto any Excel spreadsheet. 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 . The trend can display data from both the spreadsheet and a PI Server tag. The first cell is the cell above the first value of the range if the data is arranged in the column format. Selecting the range on the spreadsheet will generate the cell reference format in the dialog box. The cell range can be typed in manually or the mouse can be used to specify the range. PI DataLink User Guide Page 75 . click button at the right of the field. the string in the first cell is used for the name of the trace.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 this option is specified. If the data is arranged in the row format. If this option is specified. the Include all cells in array option is specified as the default. Another dialog box will appear. If the data is to come from the worksheet. For ease of use with PI DataLink functions. then only one cell of the array must be specified for the cell range. To use the mouse to specify the range. then the first cell is the cell to the left of the first value of the range. The rest of the array is automatically added to the cell range reference when the Add -> button is selected. the cell range of the data must be specified. The Plot as stepped data option gives the trace a jagged-saw look. This option is usually specified for discrete tags. The First element is trace name option is used if a name is to be provided for the trace on the trend. This is the same Tag Search dialog box as the one that comes from the PI menu. the start time and end time of the trend needs to be specified in PI time format. a Tag Search dialog box appears. color-blind markers are evenly spaced along a trace and do not indicate archived data points.. the tagname needs to be specified. Any tags selected from the Tag Search dialog box are automatically added to the list of traces. 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. After clicking Next. By default DataLink displays color-blind markers to differentiate traces on monochrome viewers.. To get data directly from the PI Server. Page 76 .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. The tagname can be conveniently searched for from the point database of the PI Server. By pressing the Search. Another way of specifying tags is by cell reference. button. The server name can be specified in the same way. Select the Markers checkbox to display markers that indicate the location of archived data points on the trace. or Annotated bits set. To move the trend. PI DataLink User Guide Page 77 . right-click the trend and select Move/Resize. select the Show Value Attributes checkbox. the trend will cover the data. the trend is placed on a blank worksheet at the top left corner. The selected cell before entering the trend wizard is the default cell reference. If the cell references a cell containing data. To display value attribute icons at the top of the trend.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. However. Make sure to choose a cell. If the existing worksheet option is specified. the data is not deleted. Substituted. then the cell where the trend is to be placed must be specified. If a new worksheet is selected. which does not contain data. icons appear when the range of data contains events that have the Questionable. . the Revert option can be selected to undo the changed made.. To scroll through time.. To change the format of the trace or the trend itself. If a change in the scale is deemed undesirable. Again. option can be used. The Revert option always reverts back to the settings defined in the Trend Wizard. the Change Scale.. quick changes can be made to it by selecting some of the items on the right click menu. the Format. the Revert option can be used to undo changes made by the scroll bar.Add-in to Excel Right Click Menu After inserting the trend into the Excel worksheet. Page 78 . To change the y-axis scaling. scroll bars can be enabled with the Scroll Bar option. There you can change both the time range and y-axis of the trend. The scroll bar appears at the bottom of the trend. option can be selected. this option can be used to change the color or line thickness of a trace. Export Data. there is a ... Define Trend.. The Copy/Paste option copies the trend to the clipboard and then prompts for the destination of the paste.\PIPC\HELP\PITrend*.Details for PI DataLink Functions and Dialog Boxes For instance. brings back the Trend Wizard screens. Also it can be used to add legends to the trend. and Define Trend Time Range. to learn more about Automation of the trend control. 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. PI DataLink User Guide Page 79 . option pastes the values used to plot the trend onto the spreadsheet. you can press the Help button on the Trend Wizard.. For instance.hlp.\PIPC\HELP\PITrendAuto. The Move/Resize option moves and changes the trend to size of the specified cell range. Delete Trend option deletes the trend.... Also there are additional help files in .. . the server names are copied below the tag names in the spreadsheet. 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.. click the first tag. Page 80 . dialog box is checked. then hold the SHIFT key and click the tag at the bottom of the range. To copy tags from the result list. If the "Copy PIServer Name" option in the Settings.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. you must first select each tag by clicking on the tagname while holding the CTRL key. To select an entire range of tags. 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. If the "Copy PIServer Name" option is enabled. Click OK to copy tags to the spreadsheet. The tree view displays three types of module database items. properties.Details for PI DataLink Functions and Dialog Boxes Module Database Dialog Box This dialog box allows you to search for aliases. 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. Aliases Properties Modules PI DataLink User Guide Page 81 . If the copy module path checkbox is not checked. The PI Server drop-down list can be used to switch between module databases of different PI servers. and set an existing PI Server as the default PI Server. selecting just the one module and selecting copy module path will copy that module's full path to the spreadsheet. Page 82 . you can add additional PI Servers to the list. then just the name of the module is pasted to the spreadsheet. By using the right click menu.. edit existing PI Servers. the PI server for each module database item will be copied into the spreadsheet along with the module database item. dialog-box is checked.. Selecting "Aliases" or "Properties" item of a module copies all aliases or properties of that module respectively. Connections Dialog Box A dialog box manages your PI Server connections. If the "Copy PIServer Name" option in the Settings.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. To select a module. The query date field can be used to specify the date and time context of the displayed module database. remove existing PI Servers. the full module path of the alias or property is copied to the spreadsheet along with the alias or property in an adjacent cell. If the "copy module path" option is checked. Selecting just one item copies that item to the spreadsheet. and the PI version column returns the version of the PI server that it connected to. After you successfully connect to a PI Server. Settings Dialog Box This dialog box controls your settings and preferences for PI DataLink. 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. PI DataLink User Guide Page 83 . This option affects systems where the PI 3 Server machine has different time zone settings than the client machine.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. 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. the user column returns the user that the connection is connected as. 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 Status field changes to checked. • Clear this check box to enable PI DataLink to parse the time string according to your local regional settings.run method. Please consult the file . Select this check box when the DataLink function results are plotted by the Excel charting package. • Select this check box to force PI DataLink to parse the time string according to PI time format rules.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. including date-time format preferences. and the language of any strings as English. PI DataLink will attempt to parse according to PI time format rules. The PI DataLink macro function that performs these tasks is PIPutVal(). Cells. PIPutVal() replaces an existing event with the same timestamp in the Archive with the new value supplied by the user. The Number format edit box lets you specify a default number formatting code.xls on how to call PIPutVal in a VBA module. Cells. The Locale Independent check box determines whether localized time strings should be used when parsing time data. This string may be any valid code from the Format. If locale-specific parsing fails... Select OK to save your settings. Number list. The Time format edit box lets you specify a default time formatting code. look at the tags marked "PutVal" and the VBA module "PutVal_code. Help This menu choice calls PI DataLink Help. Cancel to abort your changes. About This menu choice displays PI DataLink version information. Specifically.\PIPC\EXCEL\piexam32. PIPutVal() can only be invoked from an Excel macro sheet or from an Excel VBA module using the application. This defines the date-time order as dd-MMM-yyyy hh:mm:ss. Writing Data from Excel to PI PI DataLink allows you to write a value from the worksheet to the PI Server." Page 84 . This string may be any valid code from the Format. Number list. 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". outcell) Arguments Argument Explanation tagname (string) The tag for which you to write the value to PI. or real value written will be written to the outcell. the string TRUE will be returned and the status digital state written. outcell (reference) A reference to a cell in which the return value of this macro function is displayed. value. PI DataLink will return a value written message even though "Over Range" or "Under Range" might have been entered into the PI Server.Writing Data from Excel to PI PIPutVal() PIPutVal(tagname. PIServer. time stamp (string) A time stamp in PI time format. integer written. The range for a tag is from the zero to the zero + span.e5) The result of the macro function is placed into cell E5 on the macro sheet. PIServer (string) The PI Server. where zero and span are tag attributes specified by the user during point (tag) creation. 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. If the write to the PI Server succeeds. PI DataLink User Guide Page 85 .. It may be either a string (for digital states) or a number.a5. Note: This function (PIPutVal) does not check whether the number to be written falls within the user-specified range for a tag. value (reference) The reference to a value to be written."t". Returns The string FALSE will be returned if the macro function failed and an error message will be written to the outcell. time stamp. Note: PIPutVal supports all PI 3 data types (including string input to string tags) as well as sub-second data. PI DataLink is subject to this limitation.Add-in to Excel Limits from Excel for PI DataLink Excel has a limitation on the number of elements in a calculation array. The maximum number of PI events per retrieval is 65536. will be truncated by PI DataLink to 255 characters. there is a maximum number of values that can be returned for a single PI function. Therefore. string output from PI DataLink. 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. like PI string tag results. Page 86 . Similarly. Value at a specific time. With PI DataLink. minima. users can import PI data in various forms from a PI Server. PI DataLink gives users the ability to write values for a PI tag back into a PI Server. Compressed data while a given expression was true. Compressed (archived) data. Sampled data while a given expression was true. maxima. PI DataLink User Guide Page 87 . Tag attributes. Evenly spaced (sampled) data. Data from calculations on PI tag expressions. PI DataLink provides the following functions to retrieve data from the PI Server: Current value.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. Moreover. standard deviations. The amount of time while a particular PI tag expression was true. Totals. Sampled PI tag data synchronized with a user specified array of timestamps. averages and means for PI tags. ranges. click the Connect button. If the Status indicates that the PI Server is DISCONNECTED. it will serve to familiarize the user with the overall operation of this add-in. Rather. Verify Communications with PI Server In this first example. From the PI menu.. Make sure that the PI menu choice is in Lotus 1-2-3's menu bar. PI DataLink's features are not discussed in detail in this tutorial. Page 88 .. select Connections. Select the button <dialog boxes> to load the dialog boxes under the PI menu choice. If the default user account for your selected PI Server requires a password. the login dialog appears to prompt you for the password.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 should bring up a dialog page. we will confirm that PI DataLink has been installed properly and that it can connect to the PI Server. please refer to the section on Troubleshooting (page 137). Start Lotus 1-2-3. If the PI menu does not appear on the main 1-2-3 menu. Connect to a valid PI Server in the connection dialog box. you can also change the user name to log in as a different user from the default user. confirm that you have a valid PI username/password. select Settings. Tag Attributes and Current Value In this example. Dismiss the Connections dialog box by clicking Cancel. current value. 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. we will obtain the tag descriptor. 2. 1... If you receive a login failure dialog box. 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 . Check the Troubleshooting (page 137) section.. A valid username/password changes the Status in the Connections dialog box to either READ or READ/WRITE.\pipc\lotus\pidl_tutorial. Load the file ..Tutorial In this dialog. From the PI menu bar. and engineering units for a few tags. 3.123. Select Tag Search..Add-in for Lotus 1-2-3 4. 5. Next.. dismiss the dialog box and move the cursor to cell A2 in the spreadsheet. Page 90 . from the PI menu and enter BA into the Tag Mask field so that it reads "BA*". select Tag Attributes. PI DataLink User Guide Page 91 . BA:LEVEL.1) and then simultaneously holding the CTRL key and clicking on each of the four other tags. Notice that the current cell shows as the default in the Data output edit box. Then.A:A6.1.1.. click OK to copy the five tags along a single column. 9. The Search Results list should contain at least five tags: BA:ACTIVE. 8.. Highlight cells A:A2.1.1. Manual input ranges are also acceptable. BA:CONC.Tutorial 6.. from A2 to A6. Click the button to the right of the second edit box "Cells" under Tagname. 7. From the PI menu. Click Search to find tags that begin with "BA". BA:PHASE. Move the cursor to cell B2. The current cell shows as the default.. Select these five tags from the Search Results list by clicking on the first tag (BA:ACTIVE.1. 10. and BA:TEMP. If a range is selected. and a single row of tag names (on the same sheet) are examples of a valid range. 15. the text in that cell is also displayed in the tagname edit box. 14.A:B6. Note that the cell address is used in the macrocode when a cell address is designated in the tagname address edit box. A single cell. a range consisting of more than one column and row. If both the cell address and a specific tag name are used. Move the cell cursor to cell A:C2. The absolute tag name is used if a tagname is written into the tagname edit box. Page 92 . the tagname will have priority and appears in the resulting macro. From the list box labeled "Attributes" scroll down until the word "Descriptor" is visible. as described above. the name of the server should be entered into the designated edit box." manually enter the cell address as A:A10. If the user wants to get data from a server other than the default. This option will write the macro code associated with {PITAGATT} to the macro output cell address. When the edit box contains a valid range press OK. Alternatively.. Invalid ranges are multiple ranges. In the edit box labeled "Macro Output [Opt].. PI DataLink will write the tag descriptors into cells A:B2. It will also write the necessary macro code used to obtain the tag descriptors into cells A:A10. Select "Descriptor. a single column. 12. the "cell" button could have been selected. then just the range is displayed and nothing is written to the tagname edit box. No input is required for the PI Server edit box if the default server is desired. If a single cell is selected." 13. Notice the selected range is written into the edit box on the Tag Attributes dialog box. or any cell address that does not contain tag names.A:A14. ranges that consist of more than one sheet.Add-in for Lotus 1-2-3 11. Click OK. 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 The tag "cdt158" should be one of the tags returned.. dialog box.'. 3. Select this tag (or any other tag) and click OK. 1. Click Search to search for tags that begin with CD. If no PI Server is specified in the PIServer argument (i. or just a single quote or apostrophe). Go to the PI menu again and select Compressed Data (times) . In the above macro command.. From the PI menu. there are no spaces between each argument in the macro and commas serve as argument separators.. 2. The tag cdt158 is copied to cell A:C10 (the current active cell in the spreadsheet). which can be modified by using the PI > Connections. The reason is that Lotus 1-2-3 uses a single quote to indicate a label or a string. Move the cursor to cell A:C10.. Enter "CD" into the Tag Mask field so that it reads "cd*". there is a single space between the macro name (PITagAtt) and the first macro argument (c2).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. select Tag Search. or just a single quote) PI DataLink gets PI tag information from the default server. For example.'descriptor. Page 96 .ini file. Click on cell A:E:10 to make it the active cell. we gather sampled data for a single tag. Actual Values from PI Data Archive In this example. No PI Server specified (blank label.e. A tag attribute ('descriptor).. This is the PI Server specified in your PILogin. Also.d2} A reference to a tagname (cell C2).. The Tag Search dialog box then appears. and A cell representing the output cell (cell D2). blank. the macro command in cell A10 and its arguments are: {PITagAtt c2. A dialog box appears. Click the tagname cell reference button marked "Cell" and select cell A:C10. PI DataLink will retrieve archived data from midnight to 8:00am into the range. PI DataLink Summary As the above examples indicate. 5. Enter the appropriate parameters and PI DataLink retrieves the requested PI values. a +8h (eight hour offset) in the End time field. The next sections describe the features of PI DataLink in greater detail. Click OK..Tutorial 4.A:C18. Enter a t (for midnight today) in the Start time field. Click the Show Times check box. A:C10. 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. PI DataLink User Guide Page 97 . it adds the PI menu item to 1-2-3's menu bar. Page 98 .Add-in for Lotus 1-2-3 PI Menu When PI DataLink is added to Lotus 1-2-3. Exact Time Value retrieves a single value for a specific timestamp from the archive. Sampled Data retrieves evenly spaced (sampled) data from the archive. Archive Value retrieves a single value from the archive (may be interpolated). Calculated Value retrieves a single calculated (total. ranges. Tag Search searches for tags on connected PI servers. average or mean) value. PI DataLink User Guide Page 99 . Calculated Data retrieves totals.PI Menu The following pop-up menu selections are available from this menu item: Current Value retrieves the current value for a tag. Filtered Sampled Data retrieves evenly spaced (sampled) data that satisfy a filter condition. Tag Attributes retrieves a tag attribute. Time Filtered computes amount of time while a tag expression was true. maximum. Filtered Compressed Data (number) retrieves a specified number of compressed data that satisfy a filter condition. Compressed Data (number) retrieves compressed data based on a start time and a specified number of values. standard deviations. Connections manages PI server connections. Expression Calculation retrieves data from calculations on tag expressions. averages and means for multiple time periods. Help displays help on PI DataLink. minima. About displays version information on PI DataLink. Timed Data retrieves sampled data synchronized with an array of timestamps. Compressed Data (times) retrieves compressed data based on a start time and an end time. standard deviation. minimum. range. Filtered Compressed Data (time) retrieves compressed data that satisfy a filter condition for a given start time and end time. Settings displays PI DataLink settings and preferences. maxima. type the name of the tag for which you want data. you may also use the mouse to click the Cell or Cells button which brings up the cell reference dialog box. If entries exist in both the text edit field and the 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. In an array reference edit field. in a reference (Cell) edit field. PI DataLink will connect to the default PI Server. If the PIServer text edit field is left blank." or optional. For example. You can change the default PI Server in the Connection Dialog Box from the PI menu. in the Tagname field. Page 100 . Lotus 1-2-3 automatically enters the cell reference(s) into the edit field for you. 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. in the PICurrVal dialog box in the tutorial section. Edit Fields There are two types of edit fields in the dialog boxes: text edit fields and reference edit fields. In this procedure. you need to enter a reference to a cell on the spreadsheet that contains the necessary information. In either case. you may enter a reference to an array of cells on the spreadsheet. this field defaults to the active cell in the current worksheet. Many of the parameters contain both a text edit field and a reference edit field. The macro is useful if you want to run the command again to retrieve a new set of data later. Then you can click the cell (or click the cell and drag to adjacent cells) on the spreadsheet. respectively. For example. the reference edit fields for Tagname and Output ask for. Optional Fields The PIServer. Macro Output and Output fields in all of the dialog boxes are labeled as "opt. you type in the requested information. the text edit field will override the cell/range reference. If you do not specify an Output cell. In a text edit field. The Macro Output field is a reference edit field. A Cell (or Cells) indicates reference edit fields next to the edit box. The Output field allows you to specify the upper left-hand corner of the range where PI DataLink will place the resulting data.Add-in for Lotus 1-2-3 Dialog Boxes The following sections describe the user interaction and operation with the dialog boxes. However. . Sampled data).g.. Choose time at left to display data in two columns..'T. List Boxes List boxes appear for the Attribute field in Tag Attributes. and Calculated data. Thus.. and the cursor is placed over the macro code when the dialog box is opened.0. dialog boxes.1. the default point attribute to retrieve from Tag Attributes. the dialog box will be completely filled in based on the macro code. Choose row(s) to display the data in either one row or two rows. is now selected from the PI menu option.. there is a set of radio buttons with options column(s) or row(s). For dialog boxes that expect to return a single PI value (e.Dialog Boxes Data Displayed as Columns or Rows For dialog boxes that are expected to return an array of PI values (e.'CASABA.A:B2} If the Calculated Value.. The default item in these list boxes is the first item in the list. Unfortunately.. is Descriptor and the default calculation mode is Average. 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..g... 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.. the following dialog box appears: PI DataLink User Guide Page 101 . there is a set of radio buttons with options no timestamp. For dialog boxes that support an array of tags. Tag Search in Dialog Boxes The Tag Search button in the dialog boxes allows you to search the PI database for tags. time at left or time on top. and for the Mode field in the Calculated value.'Average..'*. Choose time on top to display data in two rows.. If there is macro code that already exists for a given dialog box. For example. Choose column(s) to display the data in one column (or two columns if timestamps are also displayed). the orientation of the tag array will override your selection of row/column option in determining the orientation of the output data. suppose the cursor were placed over a cell that contained the macro code below: {PICALCVAL 'Sinusoid. Current value). 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 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. along the top most row if the row(s) is selected. These timestamps appear at the left most column if the column(s) radio button is selected.g. The current wall clock is the reference time for the translation of the relative time in the start time field. when the tag names are in a single column. PI DataLink returns one common set of timestamps for the entire group of tags. Selecting this check box returns the timestamps as well as the values. Place parentheses around the time string if your time string is an absolute timestamp e. 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. Specifically. PI DataLink does not display the timestamps.Time in PI DataLink Note that for PI time in relative time format (e.g. However. However. Show Time Check Box A show time check box appears in some of the dialog boxes. the timestamps will appear to the left of the values.. PI DataLink User Guide Page 105 . the timestamps will appear on top of the values. '-1d).. No Timestamp/Time at Left/on Top Radio Buttons Some of the dialog boxes that return a single value (for example. use '(24-jun-00 13:38) to represent 1:38pm on June 24th. Likewise. If this box is unchecked. whose PI function normally returns an array of PI values. the reference time is different for the start time and the end time. Choose time on top if you want to display the timestamp in a cell on top of the retrieved values. when the tag names are along a single row. 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. 2000. If you reference an array of tags in either the Sampled data or Calculated data dialog box. However. 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. Page 106 .1. the command: {PIArcVal a1. it first generates the PI custom macro command and then executes the macro to put the data into the output cell. Dialog Box When a PI DataLink dialog box brings data from the PI Server to Lotus 1-2-3. When an error occurs at the PI API level. it is much easier to generate the macro string with the dialog boxes. the spreadsheet does not update automatically. When you change a cell entry in the spreadsheet. For example. Updating PI Data in a Spreadsheet As PI DataLink pulls data into Lotus 1-2-3 using custom macro commands. especially for functions with complex output options. you will have to re-run the {PICurrVal} macro every time you want the current value for a tag. You can achieve the same result by typing the macro and executing the macro manually. You must also re-execute macro commands that contain relative timestamps. if you try to find the current value for a tag which does not exist.'t+8h. the message "Tag not found: -5" appears in the output cell. 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. In addition.'. 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. For example. PI DataLink displays the PI API error in the cell.Add-in for Lotus 1-2-3 PI DataLink Custom Macro Commands Macro vs.d1} retrieves a value from the archive for the tag located in cell A1 at 8:00am of the current day. PIServer (string) The PIServer. Returns Outcode Column 1 0 Current value 1 Timestamps Column 2 Current value An output code of 2 transposes the output array that results from an output code of 1. or 2. The reference to Tagname may be an array.A5} PI DataLink User Guide Page 107 .'myvax. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the snapshot (current) value. Example To get the current value for cdf144 from the PI Server MYVAX and place the result into cell A5: {PICurrVal 'cdf144. outcode. Required Field Tagname. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. Current Value Dialog Box This dialog box gets the current snapshot value of a PI tag. PIServer. Each section describes the dialog box first and then discusses each of the arguments for the corresponding PI macro function. outcode (integer) An output code.0. either 0.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. {PICurrVal} {PICurrVal tagname. 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. PIServer. outcode. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. Required Fields Tagname. or 2.0.A5} Page 108 . time stamp (string) The PI timestamp. Returns Outcode Column 1 0 Archive value 1 Timestamp Column 2 Archive value An output code of 2 transposes the output array that results from an output code of 1. 1.Add-in for Lotus 1-2-3 Archive Value Dialog Box This dialog box gets a value at a specified time. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the archive value. either 0.'phoebe. The result is an interpolated value. except for resolution code 4 tags on PI 2 Server.'y. PIServer (string) The PIServer. For this special case. The reference to Tagname may be an array Timestamp {PIArcVal} {PIArcVal tagname. timestamp. outcode (integer) An output code. the value at or before the specified time is returned. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the archive value.A5} PI DataLink User Guide Page 109 .'y. 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. Required Fields Tagname.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.'phoebe. If no value exists. Timestamp {PIExTimeVal} {PIExTimeVal tagname. timestamp. PIServer. Returns A value from the PI Server if it exists. time stamp (string) The PI timestamp. The reference to Tagname may be an array. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. PIServer (string) The PIServer. the message "No archive entry at given time" is returned. value Time of max. If the time on top button is selected. the percent good value is returned in the cell below the calculated value cell. The percent good value is normally returned to the right of calculated value cell. or range. value Column 3 Range value . 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.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. maximum. value Minimum value Maximum Time of max. Calculation modes are Total (time-weighted) Minimum Maximum Standard deviation (time-weighted) Range Average (time-weighted) Mean (non-time-weighted) Required Fields Tagname. Timestamp(s) are returned when the calculation mode is minimum. value Maximum value Range Time of min. Page 110 Mode Column 1 Column 2 Minimum Time of min. We recommend that you always look at the percent good value before using the calculation result. PIServer. std and range. However. then use conversion factor of 24. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. etime. outcode. cfactor. minimum. the tag value takes on the average value of the entire range. See special note above for total. cfactor (number) Should be 1 for max. stime (string) The start time in PI time format. Returns If the outcode is 0.041667 for units/day 1 for units/hour 60 for units/minute 3600 for units/second {PICalcVal} {PICalcVal tagname.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. use conversion factors of: 0. 0-7 except 3. PIServer (string) The PI Server. outcode (integer) An output code. this assumption may not be valid when a large fraction of the time range contains bad data. avg. mode (string) The calculation mode (total. stime. we recommend that you always look at the percent good value before using the calculation result. min. For PI 2 Server with default rate of units per hour. only the calculated value is returned. etime (string) The end time in PI time format. PI DataLink User Guide Page 111 . mode. average or mean). the time unit of the server default is unit/day and the PI tag being totalized has units/hour. stdev. maximum. Therefore. This data normalization is equivalent to the assumption that for the bad data time range. For example. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the calculated value. range. the reported value is equal to the calculated total value divided by the fraction of the time period with good archived data. 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. '*-8h.. i. i. Value Maximum value Percent good Stdev Standard deviation Percent good Range Time of min.. value Range value An output code of 2 transposes the output array that results from an output code of 1.1.e. 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. If the outcode is 4. the following applies: Mode Column 1 Column 2 Total Total value Minimum Time of min. An output code of 7 transposes the output array that results from an output code of 5.Add-in for Lotus 1-2-3 If the outcode is 1.A5} Page 112 . Outcode of 3 is not used. If the outcode is 5. results are returned in rows instead of in columns. value Maximum value Stdev Standard deviation Value Range Time of min. results are returned in rows instead of in columns. value Average Average value Mean Mean value Column 3 Time of max. value Minimum value Maximum Time of max.'*. the percent good is returned to the right of the value cell.'minimum. results are returned in rows instead of in columns.e.e.. the following applies: Mode Column 1 Column 2 Column 3 Total Total value Percent good Minimum Time of min. i. 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. Value Minimum value Percent good Maximum Time of max.'. Value Time of max.1. The reference to Tagname may be an array. Choose a tag attribute from the list box.Dialog Box and PI Custom Macro Details Tag Attributes Dialog Box This dialog box retrieves a point attribute for a given tag. Tag attribute. Required Fields Tagname. 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 . The default attribute is descriptor. 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. 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. attribute. 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. PIServer.'. Attribute (string) The tag attribute. used by some interfaces sourcept Tagname for output to other systems. outcell} Arguments Argument Explanation tagname (string) The tag for which you want an attribute.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.A5} Page 114 . Outcode (integer) An output code. 1.'y. 2. 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. either 0. PIServer (string) The PI Server.1.A5} PI DataLink User Guide Page 115 . Returns Outcode Column 1 0 Sampled data 1 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. Outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. Interval (string) The time interval in PI time format. outcode.'t.'3h.Dialog Box and PI Custom Macro Details Sampled Data Dialog Box This dialog box gathers evenly spaced. PIServer.'. outcell} Arguments Argument Explanation Tagname(string) The tag for which you want sampled data. or 3. etime. Required Fields Tagname. The reference to Tagname may be an array Start Time End Time Time Interval {PISampDat} {PISampDat tagname. Etime (string) The end time in PI time format. sampled values from the archive. stime. interval. Stime (string) The start time in PI time format. 2. 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. numvals. or 3. if you want to retrieve 400 values starting from midnight today and there are only 356 values in the archive. PIServer (string) The PI Server. the final 44 cells are left blank by the PINCompDat function. PIServer.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. outcode. {PINCompDat} {PINCompDat tagname. either 0. For example. Outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. Outcode (integer) An output code. Use a negative number to gather data from the archive that goes backwards from the stime. 1. stime (string) The start time in PI time format. outcell} Arguments Page 116 Argument Explanation tagname (string) The tag for which you want compressed data. stime. Numvals (integer) The number of compressed 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. the first 50 values from yesterday will be replaced with new values. will display them as such. stime. 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 last 50 values from yesterday's function call will remain on the spreadsheet. The number of data points retrieved for the given time period is returned in the first cell. PIServer. 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.A5} The results are placed into an output range whose top left-hand corner is cell A5. {PICompDat} {PICompDat tagname.'(1:00). outcode. If you run the same function today. outcell} PI DataLink User Guide Page 117 .'. the function will retrieve the values between midnight yesterday and midnight today and regardless of how many values are retrieved.m. For example. if you ran the PICompDat function yesterday using the arguments 'y and 't for starttime and endtime and retrieved 100 values. etime.1.Dialog Box and PI Custom Macro Details Returns Outcode Column 1 0 Compressed data 1 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. this morning: {PINCompDat 'cdf144.10. Example The following retrieves 10 compressed data points and corresponding time stamps for the tag cdf144 starting from 1:00 a. If there are only 50 values today. Example The following retrieves compressed data points and corresponding time stamps for the tag cdf144 starting from 1:00 a. Timed Data Dialog Box This dialog box returns sampled values for a single tag that are synchronized with an array of timestamps. or 3. 2. etime (string) The end time in PI time format.'(1:00). to 3:00 a. The number of data points retrieved from the given time interval is returned in the first cell of row/column. outcode (integer) An output code. Page 118 . this morning.'. Returns Outcode Column 1 0 Compressed data 1 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.m. {PICompDat 'cdf144. PIServer (string) The PI Server. stime (string) The start time in PI time format. The timestamp field has to be a reference to a time array.m.'(3:00). either 0. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command.1.Add-in for Lotus 1-2-3 Arguments Argument Explanation tagname (string) The tag for which you want compressed data. Required Fields Tagname Timestamp.A5} The results are placed into an output range whose top left-hand corner is cell A5. 1. The timestamps in this time array must be either monotonically increasing or monotonically decreasing. The calculation mode can be a total.Dialog Box and PI Custom Macro Details {PITimeDat} {PITimeDat tagname. PIServer (string) The PI Server. Returns Sampled data. Required Fields Tagname.. If the timestamps are in a single row. timestamps (reference) A reference to an array of times in PI format. timestamps. maximum.B5} Calculated Data Dialog Box This dialog box returns evenly spaced calculated values from the PI Data Archive. the data are returned along a single row. the data are returned along a single column.A5. average or mean. The reference to Tagname may be an array Start Time End Time Time Interval Conversion Factor Calculation Mode PI DataLink User Guide Page 119 . The values in this array must be either monotonically increasing or monotonically decreasing. stdev.'. 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. minimum. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the sampled data. If the timestamps are in a single column. PIServer. range. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command.A25. outcode (integer) An output code. The percentage good values are normally returned to the right of the calculated value cells. cfactor. stdev. interval. 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 . std and range. stime. cfactor (number) A multiplicative conversion factor. outcell} Arguments Argument Explanation tagname (string) The tag for which you want the calculated data. We recommend that you always look at the percent good value before using the calculation result. minimum. Special Notes See notes in Calculated Value Dialog Box (page 110). See special notes on cfactor in PIcalcVal() for totals. outcode. etime (string) The end time in PI time format. maximum. If the row button and the show time button are both selected. average or mean). the percent good values are returned at the cells below the calculated value cells. {PICalcDat} {PICalcDat tagname. etime. range. interval (string) The time interval in PI time format. avg. PIServer (string) The PI Server. 0-7. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. Should be 1 for max. PIServer. min. mode (string) The calculation mode (total.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. mode. stime (string) The start time in PI time format. a "Filtered" status is returned for each sampled value that does not satisfy the filter expression. PI DataLink User Guide Page 121 . values.A10} Filtered Sampled Data Dialog Box This dialog box gathers evenly spaced.'y. If the Marker option is selected. Start Time End Time Time Interval Expression. If the tag is from a PI 2 Server.24.1. 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.Dialog Box and PI Custom Macro Details Timestamps and values along 2 rows Values and pctgood along 2 columns Timestamps.'1h.'total. Refer to Expression Syntax (page 143) for more information on the filter expression syntax. Required Fields Tagname.'t. sampled values from the archive when a given filter expression is true.'. 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. 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. The reference to Tagname may be an array. values. and pctgood along 3 columns Values and pctgood along 2 rows Timestamps. either 0.'y.1.'. Returns Outcode Column 1 0 Sampled data 1 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. or 3. PIServer (string) The PI Server. outcode (integer) An output code. 1. etime (string) The end time in PI time format. filtcode. when the tag cdep158 is greater than 80. outcode.'t. etime.'3h. filtexp. Example To get sampled data for sinusoid. filtexp (string) The filter expression. 2. 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.1. filtcode (integer) A filter code. See Filter Expressions (page 146) for more information on the filter expression syntax. interval (string) The time interval in PI time format. 0 to skip. interval. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. PIServer. stime.'('cdep158'>80).Add-in for Lotus 1-2-3 {PISampFilDat} {PISampFilDat tagname. use 1 to return Filtered status. stime (string) The start time in PI time format.A5} Page 122 . outcell} Arguments Argument Explanation tagname(string) The tag for which you want sampled data. If the Marker option is selected. if you want to retrieve 400 values starting from midnight today and there are only 356 values in the archive. a "Filtered" status is returned for each group of values that do not satisfy the filter expression. For example. Refer to Expression Syntax (page 143) for more information on the filter expression syntax. 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. Required Fields Tagname Start Time Number of data points Expression. 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.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. PI DataLink User Guide Page 123 . the final 44 cells are left blank by the PINCompFilDat function. filtcode.1. {PINCompFilDat 'cdf144.'('cdep158'>80).. use 1 to return Filtered status. numvals (integer) The number of compressed data points. filtexp (string) The filter expression. either 0. stime.1. See Filter Expressions (page 146) for more information on the filter expression syntax. Returns Outcode Column 1 0 Compressed data 1 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. stime (string) The start time in PI time format. 2. PIServer (string) The PI Server. The status "Filtered" is displayed for times when the filter condition is false. filtexp. Example The following retrieves 10 compressed data points and the corresponding times. outcell} Arguments Argument Explanation tagname (string) The tag for which you want compressed data. PIServer. 1. The results are placed into an output range whose upper left-hand corner is cell A5. outcode. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. or 3. outcode (integer) An output code.'.'(2:00). for the tag cdf144 while the tag cdep158 is greater than 80.m. starting from 2:00 a.10.Add-in for Lotus 1-2-3 {PINCompFilDat} {PINCompFilDat tagname.A5} Page 124 . Use a negative number to gather data from the archive that goes backwards from the stime. filtcode (integer) A filter code. 0 to skip. numvals. Special Notes This dialog box function only returns the actual number of archived data points in the PI archive. For example. while the last 50 values from yesterday's function call will remain on the spreadsheet. Required Fields Tagname Start Time End Time Expression. the first 50 values from yesterday will be replaced with new values. If there are only 50 values today that satisfy the filter criteria. If you run the same function today. The number of data points retrieved for the given time period is returned in the first cell.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. suppose you ran the PICompFilDat function yesterday using the arguments 'y and 't for starttime and endtime and retrieved 100 values. Refer to Expression Syntax (page 143) for more information on the filter expression syntax. PI DataLink User Guide Page 125 . the function will retrieve the values between midnight yesterday and midnight today. 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. stime. Example The following retrieves compressed data points and the corresponding timestamps. etime (string) The end time in PI time format. or 3.'t. stime (string) The start time in PI time format. for the tag cdf144 while the tag cdep158 is greater than 80.1. outcell} Arguments Argument Explanation tagname (string) The tag for which you want compressed data. 2. The number of data points retrieved from the given time interval is returned in the first cell of the row/column. See Filter Expressions (page 146) for more information on the filter expression syntax.'y. Returns Outcode Column 1 0 Compressed data 1 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. filtcode. yesterday till 0:00 a. filtexp (string) The filter expression. outcode.A5} Page 126 . PIServer. filtcode (integer) A filter code.m.'. 0 to skip. filtexp. 1. The results are placed into an output range whose upper left-hand corner is cell A5: {PICompFilDat'cdf144. outcode (integer) An output code. The status "Filtered" is displayed for times when the filter condition is false. either 0. today. starting from 0:00 a.m.Add-in for Lotus 1-2-3 {PICompFilDat} {PICompFilDat tagname. outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command.1. etime. use 1 to return Filtered status. PIServer (string) The PI Server.'('cdep158'>80). PIServer (string) The PI Server. or 3. Start Time End Time Time Interval {PIExpDat} {PIExpDat expression.Dialog Box and PI Custom Macro Details Expression Calculation Dialog Box This dialog box performs calculations. Refer to Expression Syntax (page 143) for more information on the expression syntax. Etime (string) The end time in PI time format. interval. 1. 2. Outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. See Expression Syntax (page 143) for more information on calculation expression syntax. PIServer. outcell} Arguments Argument Explanation Expression (string) The calculation expression. stime. either 0. Interval (string) The time interval in PI time format. outcode. Outcode (integer) An output code. Required Fields Expression. on an expression that contains tags. etime. over an evenly spaced time span. PI DataLink User Guide Page 127 . Stime (string) The start time in PI time format. 1.'y.'1h.'t. 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'). Required Fields Expression. Start Time End Time Time Interval Time units (defaults to seconds) Page 128 . User can specify multiple time ranges (evenly spaced intervals) as in the Calculated Data Dialog Box.'. Refer to Expression Syntax (page 143) for more information on the expression syntax.Add-in for Lotus 1-2-3 Returns Outcode Column 1 0 Calculated data 1 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.A5} Time Filtered Dialog Box This dialog box returns the amount of time for which a given expression is true over a time range. 2. etime (string) The end time in PI time format. PIServer. outcell} Arguments Argument Explanation expression (string) The calculation expression. either 0. Valid entries are: seconds. See Calculation Expressions (page 143) for more information on calculation expression syntax. stime (string) The start time in PI time format. timeunit."seconds". etime.Dialog Box and PI Custom Macro Details {PITimeFilter} {PITimeFilter expression.1. Example {PITimeFilter($A$1. starting from midnight yesterday to midnight today and places the result in cells E1 and E2 of the active sheet.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. outcode."1h"."y". PIServer (string) The PI Server."thevax". It also displays the timestamps for the start time of each calculation interval. Timeunit Unit of time for the result to be displayed. or 3. Returns Outcode Column 1 0 Calculated data 1 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. Interval (string) The time interval in PI time format. 1. interval. minutes. Outcell (reference) A cell specifying the upper left-hand corner of the output range that holds the results of this macro command. stime. The calculation result is expressed in seconds. PI DataLink User Guide Page 129 ."t". hours and days Outcode (integer) An output code. defines an existing PI Server as the default PI Server. After you successfully connect to a PI Server. By using the buttons on the bottom. you can perform the following tasks: Add . 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.Add-in for Lotus 1-2-3 Connections Dialog Box This dialog box manages your PI Server connections.removes existing PI Servers Set as Default .adds additional PI Servers to the list Edit . You can use the buttons on the right to Connect to and Disconnect from PI Servers in the list. click the Information button.modifies existing PI Servers Remove . Page 130 . . Click OK to copy tag names to the spreadsheet. the server names are copied below the tag names in the spreadsheet.. To copy tags from the result list. click the first tag. the PI Server for each tag will be copied into the spreadsheet along with the tag names. 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.. 01TEST. dialog box is checked. 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. then hold the SHIFT key and click the tag at the bottom of the range.TF. the tags 01:TEST. If the In a row option is selected. you must first select each tag by clicking on the tagname while holding the CTRL key. The cell position where the copying starts is the current cell.VF. dialog. and 413P11. 01TEST.. 01TEST.QA. To select an entire range of tags. If the "Copy PIServer Name" option in the Settings.LF. In the example below. PI DataLink User Guide Page 131 .PV are selected.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. 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 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. 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. Page 132 .Add-in for Lotus 1-2-3 Settings Dialog Box This dialog box controls your settings and preferences for PI DataLink. time stamp. {PIPutVal} {PIPutVal tagname.Writing Data from Lotus 1-2-3 to PI PI DataLink Help This menu choice calls up help on PI DataLink. or real value sent will be written to the outcell.123 on how to use these macros. time stamp (string) A time stamp in PI time format. If the function succeeds. Both functions will replace an existing event at the timestamp specified. integer sent. outcell} Arguments Argument Explanation tagname (string) The tag for which you to write the value to PI. It may be either a string (for digital states) or a number. Please consult the file . Value (reference) The reference to a value to be written. The PI DataLink macro commands that perform these tasks are PIPutVal and PIPutValX. Outcell (reference) A reference to a cell in which the return value of this macro function is displayed. PIPutVal supports classic PI point types while PIPutValX supports new PI point types for PI 3 Server. Returns If the macro function fails. value. PIServer (string) The PI Server. 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. About PI DataLink This menu choice displays PI DataLink version information. the string digital state sent. an error message will be written to the output cell.\PIPC\LOTUS\PIDL_input. PIServer... PI DataLink User Guide Page 133 . If the function succeeds. Timestamps are interpreted using server time zone information.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. PI DataLink will return a value written message even though "Over Range" or "Under Range" might have been entered into the PI Data Archive. It does not support writing string data to string tags and it does not support sub-second timestamps.a5. The range for a tag is from the zero to the zero + span. Page 134 .'. Outcell (reference) A reference to a cell in which the return value of this macro function is displayed. Returns If the macro function fails. Value (reference) The reference to a value to be written. PI DataLink will return a value written message even though "Over Range" or "Under Range" might have been entered into the PI Data Archive. 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. It may be either a string (for digital states) or a number. value sent will be written to the outcell. {PIPutVal 'testtag. where zero and span are tag attributes specified by the user during point (tag) creation. value. outcell} Arguments Argument Explanation tagname (string) The tag for which you to write the value to PI. where zero and span are tag attributes specified by the user during point (tag) creation.a10} {PIPutValX} {PIPutValX tagname. Note: PIPutValX does not check whether the number to be written falls within the user-specified range for a tag. an error message will be written to the output cell. Note: This function (PIPutVal) only supports integer. PIServer (string) The PI Server. The return status is placed into cell A10. PIServer. time stamp. time stamp (string) A time stamp in PI time format. digital state and real data types. the string.'t. a5.'. This is the limit for the number of rows in Lotus 1-2-3 spreadsheet.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. The return status is placed into cell A10. you can retrieve only 65536 values at a time. This limitation means that for a single custom PI macro command.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. 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. {PIPutValX 'testtag.'t. 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. 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 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. 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. the PI menu disappears even though the PI DataLink add-in is still loaded.123 file contains most of the DataLink dialog boxes and must be loaded for the DataLink dialog boxes to be available. DataLink Functions Not Available Through PI Menu in Lotus 1-2-3: The PI123DLG. see Technical Support and Resources (page 155) for details on contacting Technical Support. Restarting Excel usually fixes the problem. PI DataLink User Guide Page 137 .. If this happens. confirm that this file is in . If you can see the PI menu but cannot see the DataLink functions on the PI menu in 1-2-3..\lotus\123\auto and restart Lotus 1-2-3. One of the symptoms of this phenomenon is that embedded PI DataLink array functions still work while the PI menu itself is not available. 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.EXE.log MultiNet PISysExe:MTNPIServer. the log files are located as follows: UCX PISysExe:UCXPIServer.EXE" *-15m * The above displays all messages that are made by EXCEL. Save any files you were working on and restart Lotus 1-2-3.12A is not in ..) For PI 2 Server. click Register. check to see if it is available in the . please run setup for PI DataLink again.EXE from 15 minutes ago to the current time..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. Check the space in front of the path of the add-in file and click Done. If PIDL.log TCPware PISysExe:TCPIServer. (PI DataLink connection messages should begin with "PINet"... If it is..12A.\lotus\123\addins directory. Connection Problems Reported in Log Files On PI 3 Server.log PathWay PISysExe:PTWPIServer. in the Manage Add-ins dialog box.. go to the \lotus\123\addins directory and double-click on PIDL.log PI DataLink for Excel On local PC.\lotus\123\addins. (PI DataLink connection messages should come from EXCEL. information about connection attempts may be obtained via the PIGetMsg utility: pigetmsg * "EXCEL.. and confirm that PIDL.) ..12A is displayed in the list of add-ins.12A file does not appear in the list of available add-ins. If the PIDL. 2000. Check on the PC that PI DataLink is trying to connect to port 545. The PING command can be run from any directory at the command prompt. the host table is located in C:\WINNT\SYSTEM32\DRIVERS\ETC\hosts. Check to see that the PI Server service has been created and enabled on the PI Server machine. 2. For Windows NT. and XP. Be sure to PING the PI Server machine by name to confirm the communications between the PI Server and PI DataLink. the host table is located in C:\WINDOWS\hosts. 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.sam. The following are some common symptoms: Gethostbyname Error in pipc.sam file. Be aware that Windows 98 ships with a default C:\WINDOWS\hosts. A quick fix solution is to add the PI Server's address to the PC's local Host table.log. For Windows 98. you may think that you are editing hosts when in fact you are editing hosts.log This Gethostbyname error indicates that the PC cannot translate the name of the PI Server into a TCP/IP address. and Windows 98 often hides filename extensions. Connect() Timeout in pipc.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. Page 139 . For PI 2 Server 1. Thus. Error! Style not defined.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. 1. 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. Recv: Error: 0 in pipc. For PI 2 Server. confirm that the PI Server service is configured correctly.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. See PIBuild:PIServer. You should create the above [network] section and timeout entry if they do not currently exist.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. 2.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. Confirm that the PI Server is indeed running on the PI Server machine. The solution is to add the PC's name and TCP/IP address into the VAX/Alpha's local host table.txt for more information. Also. . you may increase PI DataLink's timeout parameter in the C:\PIPC\DAT\pilogin. See the previous section on name translation for more information. 8+ (PI 2. The instructions are in PIBuild:PIServer. 2.0. You must have PI 2. Page 141 . The PI Server service has not been enabled on the VAX/AlphaAXP. 5. 4. There may be a hardware or router problem associated with your network. TGV MultiNet) service on the VAX/AlphaAXP. On Windows systems.txt. ask your VMS system manager to check whether the PI Server auxiliary server has been configured. If you are running another TCP/IP (for example. Run a ping test between the Server and the PC: \>ping mypiserver 3. Enable the PI Server if necessary: $ ucx enable service PIServer. check Network Protocol Settings (Start > Settings > Control Panel > Network) and confirm TCP/IP is enabled. make sure that the auxiliary service for the PI Server is currently enabled: $ ucx show service PIServer. The version of your PI 2 Server does not support TCP/IP.DataLink Add-in Doesn't Load Properly TCP/IP Connection Problems 1. The PC cannot talk to the PI Server via TCP/IP.0. Error! Style not defined. If your VAX/AlphaAXP is running DEC TCP/IP Services for VMS.7 for DEC TCP/IP Services for VMS). . colon (:) and period (. Your PI System may use different ones. Note: The examples below use two tag delimiters. PI DataLink User Guide Page 143 . Calculation Expressions The following describes the syntax of valid calculation expressions (used by PIExpDat) in PI DataLink. PINCompFilDat. The functions that require the user to specify a valid PI expression are: PIExpDat.). PICompFilDat.Appendix B: Expression Syntax PI expressions are used in PI DataLink functions that require calculation of mathematical functions. 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. 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. Note: There are some differences in Performance Equation calculation and syntax rules between PI 2 and PI 3 Server. the user is referred to the above manuals for a more complete discussion). PITimeFilter. mathematical operators and functions act upon tag names. which include PI tags. In a tag calculation expression. and PISampFilDat. . 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.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.) raised to a power int integer part of a number log natural logarithm sgn sign function (-1 if argument is negative.71828. 0 if zero... when the tag was receiving "good" values will be returned. you can also evaluate expressions that contain current Performance Equation functions.0. 't') The PctGood function finds the time percentage. the percentage of time between midnight yesterday and midnight today.9 or higher. For example.Calculation Expressions Performance Equation Functions If the version of your PI 2 Server is 2. over a given range. 12h for Time interval and the following expression in the PIExpDat PI function: (curtime . when a tag's archived values are good. Some useful functions are: BadVal() StateNo() TagBad() NextVal() PctGood() PrevVal() TimeEq() TimeGE() TimeGT() TimeLE() TimeLT() TimeNE() Example PctGood('cdep158'. Curtime Keyword You can refer to the timestamp of the calculation by using the keyword curtime explicitly in the expression. 21-Oct-97 for End time. In the above example. 'y'. you specify 20-Oct-97 for Start time. Page 145 . or if you are using PI 3 Server.`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. For example: ('my:tag' = "Manual") . note that the PE syntax for PI 3 Server differs slightly from that on PI 2 Server. In addition. For PI 2. Relational Operators A filter expression uses the same arithmetic operators and functions as a calculation expression. use the negative of the digital state code number. When comparing digital tags. 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. one or more relational operators are necessary. (period). Your PI system may use different ones.0.Add-in for Lotus 1-2-3 For more information on Performance Equation functions. Note: The examples below use tag delimiters of : (colon) and . consult the PI Server Applications Guide or the PI 3 Performance Equations Help File.65. Also.65) The above expressions evaluates to TRUE (non-zero) if the absolute value of the tag mytag is at least 14.9 or higher. Filter Expressions The following describes the syntax of valid filter expressions in PI DataLink. use the digital state string itself. Page 147 .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. 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. and vice-versa. not returns TRUE if its argument is FALSE. . '(25-dec-92 14:23). 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. fri.1. mon.m. On December 6. .'. The day before yesterday 'mon+14. Saturday '*-1h One hour ago 't+8h 8:00:00 a.m.5h 2:30:00 p. wed. Last Monday 'sat-1m 11:59:00 p. For example: {PIArcVal 'sinusoid. If you are using the add-in for Lotus 1-2-3. 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. Monday.m. omit the leading quote if you are entering the PI time string into a text edit field in an Excel dialog box. Today 'y-8h 4:00:00 p.m..Appendix C: Examples of PI Time Strings Start and End Time In the following examples..m. Last Friday PI DataLink User Guide Page 149 . thu. sat 00:00:00 on the most recent Sunday. tue.A5} PI Time String Meaning '06-dec-91 15:00:00 3:00:00 p. you should enclose the PI Time String argument in parentheses. 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. then the interpolated values are generated at y+4h. PI Time String Meaning '1. y+5h. Page 150 . and interval is "+5h" for Sampled Data function. y+10h. and y+20h. then interval is assumed to be positive. y+19h and t. omit the leading quote if you are entering a PI time string directly into a text edit field in an Excel dialog box. y+15h. y+9h. then interpolated values are generated at y. So if starttime is "y". If no plus or minus sign is used. endtime is "t". y+14h. If the interval is "-5h" instead.Add-in for Lotus 1-2-3 Time Interval In the following examples. To use silent ini.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.ini Arguments Silent Installs For silent installs. type: Setup. please use the silent. All arguments must be separated by a space. The following is an example of how the setup.ini Arguments and PI DataLink Setup. Please make site-specific specifications as needed. the command line must have /qn in it.ini provided in the DataLink distribution kit.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 . Arguments in silent. In order for any of the arguments to work.Appendix D: Setup.ini Arguments sections.exe -f silent.ini are described further in PI SDK Setup. All arguments must be separated by a space.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 .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. The following is an example of how the setup. PI DataLink User Guide Page 153 .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 ∑2 xi −1 (where i is the bit number for each bit that is set) i Note: Not all outcodes are valid for each function because not all options are available for every function. "1h".Add-in for Lotus 1-2-3 Example Suppose we want a Calculated Data function to display Percent Good. Show Min/Max Time } = {1."t". Show Start Time."minimum". bits set = { Show Timestamps. Start Time. and Min/Max Time. 1. 325. the Show Timestamps bit must also be set. Since Start Time and Min/Max Time are displayed. 7."piserver") Page 154 . 3."y". Show Pct Good. 9 } outcode = ∑2 xi −1 = 21−1 + 2 3−1 + 2 7 −1 + 2 9−1 i 0 = 2 + 2 2 + 2 6 + 28 = 1 + 4 + 64 + 256 = 325 So the function shown in Excel would look like: =PICalcDat("sinusoid". which covers Service Reliance Program (SRP) service agreements. You will receive a response within 24 hours. and access all of the following resources at the OSIsoft Technical Support Web site: http://techsupport. in this case. to techsupport@osisoft. Personalized Online Technical Support The Online Call Center allows you to create a support call. My Download History. The My Support menu allows you to review My Products. Help Desk and Telephone Support Telephone support is available 24 hours a day.com OSIsoft provides the following support options and resources.osisoft. 7 days a week. including the problem description and message logs. Direct service may not available in some locations or during some hours. You can read complete information about technical support options. Choose My Support > My Calls (Online Support) in the Technical Support Web site.Appendix F: Technical Support and Resources OSIsoft provides dedicated technical support internationally. PI DataLink User Guide Page 155 . leave a message and your call will be returned within 4 hours. It also allows you to review information from your previous support calls. 7 days a week. 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.com. 24 hours a day. which will be responded to in 24 hours. and SRP Terms. PI Server security. as well as a special collection of resources for system managers. please provide: Product name. backup scripts. To see current SRP status. The Search feature allows you to search Support Solutions. hands-on troubleshooting. and/or build numbers Computer platform (CPU type. and white papers). System Manager Resources include tools and instructions that help you manage: archive sizing. go to My Support > SRP Terms on the Technical Support Web site. Remote Server Access Technical support engineers can remotely access your PI server to provide diagnostics. daylight savings time configuration. Before You Call or Write for Help When you contact OSIsoft Technical Support. and more. PI system sizing and configuration. daily health checks. version. PI trusts for interface nodes. and version number) The time that the difficulty started The message log(s) at that time . click Knowledge Center in the Technical Support Web site. and assistance. For these options. Bulletins. and Documentation (including user manuals. Known Issues. release notes. Enhancements.Add-in for Lotus 1-2-3 Knowledge Center The Knowledge Center provides a searchable library of documentation and technical data. Support Pages. On-site Technical Support OSIsoft provides on-site service according to SRP service level agreements. operating system. Choose Contact Us > Remote Access Options in the Technical Support Web site. open a command prompt. If you do not have PI SMT installed. select the server name. piarchss. use the command. updates or patches) use either of the following methods: If you have PI System Management Tools (PI SMT) installed. and enter msinfo32. uname -a PI DataLink User Guide Page 157 . change to the pi\adm directory.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. The PI Version tree lists all versions. choose Start > Run. open Operation > PI Version. then under System Management Plug-Ins. In PI SMT. choose Start > Programs > PI System > PI System Management Tools. right-click My Computer and choose Properties. change to the pi\bin directory and type the subsystem name followed by the option -v (for example.exe In UNIX.exe –v). View Computer Platform Information To view platform specifications: In Windows. For more detailed information. To see individual version numbers for each subsystem. and enter piversion -v. . Index A ActiveX control • 72 Advanced Calculated Data • 53 Apostrophe • 87 Archive Value • 106 Array Options • 99 Attribute Mask to Tag • 68 Averages • 53. 117 B Bug Fixes List of • 5 C Calculated Data • 117 Calculated Value • 108 Calculation Expressions • 141 Calculation Modes • 53. 105 Module Database • 79 Point ID to Tag • 67 Property • 70 Sampled Data • 113 Page 159 . 108. 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. 114 (Number) Filtered • 121 (Times) • 40. 108. 117 Can't Connect to the PI Server • 136 Case-sensitive Node names • 6 Change arguments • 17. 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. 29 Change Scale option • 76 Combo Boxes • 23 Compressed Data (Number) • 37. 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. 117 Menu • 96 Microsoft Excel Add-in • 1. 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. 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. 117 Mean Average • 108. 65. 108. 85 M Macros Macro commands Lotus 1-2-3 • 87 Macros vs. 11 Module Database • 79 MultiNet Name Translation. 98 .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. Dialogs • 104 Output Fields • 98 Output Option • 102 Maxima and Minima • 53. 66. 116 PICompFilDat • 42. 124 PICurrVal • 32. 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 . 131 PIPutValX • 132 PISampDat • 44. 109 PICompDat • 41. PI Client • 6 PC client name • 6 Percent Good • 108. 106 PICalcDat • 52. 122 PINet nodes security on • 6 PIPropertyValue • 71 PIPutVal • 83. 105 PIExpDat • 46. 118 PI DataLink User Guide PICalcVal • 50. 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. 98 PITagAtt • 36. 125 PIExpVal • 34 PIExTimeVal • 107 PINCompDat • 38. 113 PISampFilDat • 45. 114 PINCompFilDat • 39.Page 161 P PathWay Name Translation. 120 PIServer Fields • 22. 112 PITimeDat • 47. 108. 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.9 • 143 Spreadsheet software • 2 TCP/IP • 2 . 129 TCP/IP • 2 Node Names • 6 TCPWare Name Translation. 131 Verify Connections Excel add-in tutorial • 86 Lotus 1-2-3 add-in tutorial • 86 Version PI System 2. 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. 111 Tag Search • 99.0. 117 Syntax Performance Equation • 143 T Tag Attributes • 87.ini Arguments • 149 PI DataLink • 150 Show Time Check Box • 103 Single quote • 87 Standard Deviations • 53.Index Settings • 130 setup.