PI_HDATool
User’s Guide
Version 1.1.0.0
1
UniInt End-User Interface to the PI System
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
- Brazil
- Middle East/North Africa
- Republic of South Africa
- Russia/Central Asia
- South America/Caribbean
- Southeast Asia
- South Korea
- Taiwan
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
Unpublished – rights reserved under the copyright laws of the United States.
© 2004-2012 OSIsoft, LLC PI_HDATool.doc
1
UniInt End-User Interface to the PI System
Table of Contents
Introduction
Reference Manuals
Diagram of Hardware Connection
Principles of Operation
Installation
Starting PI_HDATool
Connect
Browse
Select Attributes
Set Filters
Make Browser
Select Items
Getting Item Handles
Reading Data
Timestamps
Read Raw
Read At Time
Read Processed
Asynch Reads
Writing Data
Saving and Loading Configuration Data
Saving
Loading
Remote Operation
Technical Information
Troubleshooting
1
PI_HDATool User's Guide1
Introduction
OPC (OLE for Process Control) is a standard established by the OPC Foundation task force to allow applications to access process data from the plant floor. The OPC HDA standard (HDA) was created by the Foundation to give a common interface between historical data archives and client applications which use that historical data.
HDA servers with communication interfaces that comply with the OPC Standard allow client software applications that follow this standard to communicate with any of those servers without regard to software releases or upgrades.
The connection between the client and the HDA server is either through the Microsoft COM interface or through OLE Automation.
This PI_HDATool uses an OPC COM custom interface to communicate with HDA servers. It is used to help configure and use the OSIsoft OPC Server with any third-party OPC HDA client.
This tool runs on NT platforms running NT4, Windows 2000, or XP.
The PI_HDATool provides the following features.
- Connections to as many as five HDA servers.
- Connection to up to 500 items per server.
- Synchronous read/write operations.
- Asynchronous read/write operations.
- Advise read operations.
- Tag filtering for refining the tags to be displayed and assigned as OPC items.
- Working configuration can be saved to file and reloaded later.
This document describes the PI_HDATool and how to use it to check communications with any Historical Data Access OPC Server.
Reference Manuals
OSIsoft
- OPC Data Access & Historical Data Access Server for the PI System
Vendor
The OPC standards are freely available from the OPC Foundation at
Diagram of Hardware Connection
1
PI_HDATool User's Guide1
Principles of Operation
This tool is designed to allow the user to validate data communication with an HDA server. It is not intended to be used to collect data for practical purposes, or as part of a functional application. It is simply provided as a way to test the functionality of an HDA server, and to verify that network and application permissions are correctly set to allow communication between an HDA server and a client application.
Specifically, the tool will execute one method of the OPC Historical Data Access specification when one button is clicked, wherever that is practically possible. For some functions, more than one call to the HDA server may be made when one button is clicked, for example: when a connection to the server is made, the tool will attempt to acquire several COM interface pointers, and will make several calls to the server. But overall, as far as possible, the rule is one click, one call. This is expressly intended to help in debugging problems in communicating with HDA servers, or to help in debugging the servers themselves.
There is no provision for storing data received from the HDA servers, or for sending data from a file or another program to an HDA server. This tool is for interactive use only.
1
PI_HDATool User's Guide1
Installation
This application does not require any installation. The only requirement to use the tool is the executable itself. It can be run from a floppy or CD, if it is not copied to the hard disk. This tool is installed into
PIHOME\PI-OPC Tools\PI_HDATool
during the installation of the OSIsoft OPC DA/HDA Server.
The OPC and HDA proxy files must be installed on all machines, both client and server. These files can be obtained from the OPC Foundation, if they are not already present, but both the client and the server probably include them in the installation.
This tool runs on Windows platforms running NT4, Windows 2000, or XP.
1
PI_HDATool User's Guide1
Starting PI_HDATool
To start the PI_HDATool, simply double-click on the PI_HDATool.exe file. The PI_HDATool appears as shown below.
Connect
The Server Name dropdown box will list the HDA servers found on the local system. Select the desired server name and then press Connect. If the HDA server is on another system, type in the node name of the system before pressing Connect and the HDA servers found on the remote system will be added to the Server Name dropdown box.
Security
The Security button allows OPC security to be used. If the HDA server supports OPC security, pressing this button will ask the HDA server for its security options. If the HDA server does not support OPC security at all, the tool will pop up a message to that effect. If NT security is enabled, the HDATool will ask if the user would like to try private security anyway. If NT security is not supported, or if the user asks to use private security anyway, the tool will pop up a window to allow the user to provide a username and password to be sent to the server. The Security button can be used repeatedly, or at any time during the connection, as each time it is pressed the HDATool performs a Logout of the current user, and then attempts to log in again with the new security setting. In this way, you can verify that your server allows either no access, or read-only access, or full access, depending on the user identity chosen.
It is important to note that the username and password, if used, will be sent over the network in the clear, unless some means is used to encrypt the entire communication between the server and the client. OPC Security does not provide any mechanism for encrypting the login information. For more information on the OPC Security standard, please see the OPC Foundation website.
Browse
Next, press the Browse button to bring up a Browse screen.
This is where the tags and properties that are accessible from theOPC server are listed.
Select Attributes
If Select Attributes is pressed, a list of attributes will display. Select the desired attributes, and press OK. The normal multiple select options work, with Shift-click to select a range, and Ctrl-click to select individual items.
Set Filters
Likewise, pressing Set Filters will bring up a filter dialog, where the user can specify what sorts of items he’s interested in seeing (Pointsource, Tagname, etc.). These filters will mostly accept wildcards, but a value must be selected in the Operator column (Equal, NotEqual, etc.) or anything in the Value column will be ignored. Note that strings are case insensitive. A common filter would be "Tagname, OPCHDA_EQUAL, *sinus*", which will result in the browse only returning tags that have "sinus" somewhere in their tagname.
Make Browser
Finally, press Make Browser. Whenever the filters or the attribute list are changed, the user will need to make a new browser in order to get the new settings. Note that by default, the tool asks for BRANCHes first, so the topmost level of BRANCHes will display, which will be a list of the PI systems known to the local PI SDK. A new browser always starts out at the server root, EXCEPT when the user has filtered on PI server. In that case, the OSI server will connect to the specified PI server and the browse will start out at the root of that PI server.
Select Items
To go down into a Module, double click on it. To go up, just press Browse Up. Remember that at any level, either BRANCHes or LEAFs will be displayed, but not both. The current position in the browse tree is always displayed in Current Branch. The user can also click Get Position to get a position string that he can copy and paste elsewhere. For example, the user might want to use the Go Directly To button later, to come back to his current position, so he can press Get Position, copy the position string to the Go Directly To box, and then when he wants to go back there, just press Go Directly To.
When the user has found one or more items he’s interested in, he can select them (the normal multiple select options work, with shift-click to select a range, and Ctrl-click to select individual items) and then press Get Item IDs. Then press Add to add them to the item list.
Browse around and add items until all desired items are included. Then press Done to get back to the main screen.
Getting Item Handles
Show Items will display the list. To delete items, select them and press Remove. Add items manually by typing them into the Item box and pressing Add. Doubleclicking on an item in the list will copy that item's ItemID into the Item box, where it can be edited, making it easy to add items that have similar ItemIDs.
Before data can be retrieved, the user must get handles for the items. Select the desired item handles, or select none of them to have all the items fetched. Then press Get Item Handles. If any of the items are not recognized by the server, a message will display so the ItemID can be fixed. Show Items will now show which items are connected.
Once Item handles are obtained, perform the standard HDA functions to read and write.
Reading Data
Timestamps
OPC uses Universal Coordinated Time (UTC) for timestamps, so there is no timezone or daylight savings time confusion. By default, the timestamps used by the tool are UTC. To translate timestamps into local time, check this box.
Read Raw
Read Raw needs a start and stop time specified, and the user may want to specify the max number of values to return for any item. Note that the times can be given as absolute times or as relative times. The format for relative time is similar to that for PI, but not identical. "NOW" is used instead of "*", and OPC also defines YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, and SECOND as being the start of the current year or month or week, etc. The offsets can be specified in each of those units as well, using Y, MO, W, D, H, M, and S. Note that the PI_HDATool will uppercase anything entered into the timestamp fields.
The easiest way to use absolute timestamps is to use a relative timestamp to retrieve a value from the OPC server. This is because the format of the time string depends on the local system settings, making it easiest to have the tool display a timestamp in order to find the correct format. Doubleclicking on any line in the value display will cause that line to be copied to the Item field, where it can be copied.
Max Values will limit the number of values returned, which is very useful when the amount of data within the time range is unknown.
Read At Time
Read At Time wants a set of timestamps; it's used to get values for sampled data. It is possible to copy timestamps from the data window to the timestamp window by selecting the timestamped lines and pressing Copy Timestamps, or by typing them in manually in the Add Timestamp window, and press the Read At Time button.
Read Processed
Read Processed lets the user get aggregate data from PI. First press the Select Aggregates button, and select the desired aggregates. Then set theResample Interval -- if the time between Start Time and End Time is 2 weeks, set a high resample interval or the maximum values for the server will be exceeded.
Asynch Reads
The asynchronous versions work like the synchronous versions, but they exercise the asynchronous interfaces of the server. The Advise Raw and Advise Processed functions will return the values up to the current time, and then as data comes in, they will continue to send values at the end of each time interval. See the HDA specification for more on how these work. To cancel an Advise, or to cancel an asynchronous read before it returns, select the Cancel ID from the list and press Cancel. A message will displaywith the server's response. If the server accepts the cancel, it should not return any more values.
Writing Data
The Updates button takes the user to the Updates screen, where he can write data to the OPC server.
Select the desired tag to write to, give a timestamp and a value, and select a quality. Add them to the list, and select another set of tag, time, value, and quality. When all the tags are in the list, press Insert, Replace, Insert/Replace, or Delete At Time. To delete all values from a tag for a range of time, enter the start and end times in the boxes, enter the tag name in the list, and press Delete Raw. This window can be moved to one side or shrunk.Use the main window to verify the progress made. The user will not be allowed to add or remove Items while the Update screen is active. To release Item handles, or add Items to the list, close the Update screen first.
The Query button just asks the server which of the Update functions it supports. A server is allowed to implement updates selectively, only supporting those operations which are allowed by the history archive to which it is connected.
Note that the tool will not allow new Items to be added to its list while the Updates window is open, but the user can switch back to the main screen and perform reads while this window is open. Also note that Insert will fail if there is already a value for that Item at that timestamp, while Replace will fail if there is not a value there already. Insert/Replace will Insert or Replace, depending on whether there's a value already existing.
1
PI_HDATool User's Guide1
Saving and Loading Configuration Data
The PI_HDATool allows the user to save configuration data to a file. This file can be reloaded into the PI_HDATool to avoid having to create a list of items.
Saving
To save the configuration data, follow the steps below:
- Select the server in the Connected Servers field.
- Click Save.
In the dialog box that appears, enter a file name. Then click OK. The data is saved in the file specified.
Loading
To load the configuration data, follow the steps below.
- Start the PI_HDATool.
- Click Load.
- In the dialog box that appears, enter a file name for the file, or click Browse search for the file. Then click OK. The configuration data is loaded into the PI_HDATool.
1
PI_HDATool User's Guide1
Remote Operation
The HDA Server can be located on a different node from the HDA client. For this remote operation, verify that DCOM settings are correct on the local and remote nodes. For detailed instructions, refer to the documentation that accompanies the server. Alternatively, refer to the user manual for the OSIsoft OPC Interface, which has detailed information about configuring DCOM.
1
PI_HDATool User's Guide1
Technical Information
In general, the tool is designed to execute one HDA method at a time. Wherever possible, when a button is pressed, one call is made to the HDA server. Of course, there is a compromise between usability and simplicity, so there are buttons which execute multiple commands, namely the commands which actually read and write data. When a Refresh or Read button is clicked, the tool will ask for the appropriate interface pointers, if it doesn't already have them, execute the requested operation, and finally it will release the pointers. The exception to this is the case where the group is advised. If the group has an Advise active, the asynchronous operation does not require any more interface pointers to be acquired, and the tool does not release the pointers after the operation is complete. The pointers are released when Unadvise is called.