Tag Configuration tool for the PI ECHO to PI Interface to the PI System

Version 2.0.0.0 Revision A

Copyright © 2007-2009 OSIsoft, Inc.

OSIsoft, Inc. OSIsoft Australia 777 Davis St., Suite 250 Perth, Australia San Leandro, CA 94577 USA Auckland, New Zealand (01) 510-297-5800 (main phone) OSI Software GmbH (01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) Altenstadt, Germany http://techsupport.osisoft.com OSIsoft Asia Pte Ltd. [email protected] Singapore Houston, TX Johnson City, TN OSIsoft Canada ULC Longview, TX Montreal, Canada Mayfield Heights, OH Calgary, Canada Philadelphia, PA Phoenix, AZ OSIsoft, Inc. Representative Office Savannah, GA Shanghai, People’s Republic of China Yardley, PA OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil

Sales Outlets/Distributors Middle East/North Africa South America/Caribbean Republic of South Africa Southeast Asia Russia/Central Asia South Korea Taiwan

www.osisoft.com

All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, Inc.

OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, Sigmafine, Analysis Framework, PI Datalink, IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI ManualLogger, PI ProfileView, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, Inc. All other trademarks or trade names used herein are the property of their respective owners. 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

Introduction...... 1 Reference Manuals...... 1 Principles of Operation...... 3 Connection to PI...... 3 Connection to ECHO...... 3 Exporting ECHO Datastreams...... 3 Runtime behavior...... 4 Configuring tags in PI...... 5 Tag Configuration Tool Installation...... 7 ECHO Configurator...... 9 Startup Command File...... 11 Command-line Parameters...... 11 Sample PIECHOInt_TagCfg.bat File...... 12 Sample PIECHOInt_TagCfg_CE.bat File...... 12 Appendix A: Error and Informational Messages...... 13 Sample .log file where successfully exported ECHO configuration...... 13 Sample .log file where failed during export of ECHO configuration...... 14 ECHO Errors...... 14 Revision History...... 15

Tag Configuration Tool for PI ECHO to PI Interface to the PI System iii Introduction

The Tag Configuration tool for the PI ECHOInt interface exports an ECHO configuration to a .csv file. This tool will export all of the datastreams in ECHO along with the properties needed to configure those tags in PI. The .csv file can then be imported into PI using the PI Tag Configurator. The name of the ECHO node and the path and filename of the .csv file are configurable options and are specified at startup of the tool. The Tag Configuration tool runs on a Windows Intel-based operating system (Windows 2000 SP3 & SP4, XP, or 2003) or a Windows based CE X86 platform. The tag configuration tool supports ECHO version 2.0 and later.

Reference Manuals

OSIsoft  PI Tag Configurator manual  PI ECHOInt Interface User Manual  ECHO General Developers Guide

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 1 Principles of Operation

The Tag Configuration tool for the PI ECHOInt interface exports an ECHO configuration to a csv file. This configuration will contain all of the datastreams configured on the requested node along with all the properties needed to properly create the tags in PI. The generated csv file will be formatted for use with the PI ECHOInt interface and can be imported into PI using the PI Tag Configurator. The tool consists of a single executable. Two command line options are required at startup, the name of the ECHO node and the path and filename for the generated csv file. Based on the path and filename for the csv file a .log file will be created to log informational messages about the status of the tool. The .log file will contain both information succeeded messages and any failed messages. Each time the tool is executed it will create a new csv file. If the file already exists its contents will be destroyed and a new file created.

Connection to PI

The Tag Configuration tool for the PI ECHOInt interface does not require a connection to PI. The tool makes a connection to ECHO and exports the configuration to a .csv file

Connection to ECHO

At startup the tool will initiate a connection to ECHO. If ECHO is unavailable, the tool will log an error and shut down. Once the connection to ECHO is available the tool can be restarted. NOTE: COM/DCOM must be properly configured from the machine where the tool is running to the machine where the ECHO Archive Engine is running.

Exporting ECHO Datastreams

Once the tool has established a connection to ECHO then the tool will begin exporting the datastreams to a file based on the Historian configuration. The Historian configuration will be used to set the pointsource and location1 properties. The Historian configuration will also be used to determine the order for exporting the datastreams. All datastreams for the first historian will be exported. All datastreams for the second historian will then be exported, and so forth. The tool will run once, export the configuration and shutdown. To pick up any point changes (adds, edits, or deletes) in ECHO the user must re-run the tool and a new file will be created. The new file will contain the current entire ECHO configuration.

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 2 Runtime behavior

At startup the tool will establish a connection to ECHO. Once connected to ECHO, the tool will get the historians collection. Starting with the first historian in the collection, the tool will export all of the datastreams and properties to a .csv file. After the first Historian has completed then the tool will move to the next Historian in the collection, and so forth, until all Datastreams have been exported to the .csv file. For each datastream the following list of properties will be exported to the .csv file. The paragraphs that follow describe each property.  PI Tag Name  Descriptor  Instrumenttag:  Location1:  Location4:  Pointsource:  Pointtype:

The PI Tag Name is made up of a combination of the Historian name, underscore character, and the Datastream name. Because the PI Tag name must be a unique name and the Datastream name in ECHO is only required to be unique for a particular Historian then the PI tag names are generated using the format described above. For example if the Historian name in ECHO is Hist1 and the datastream defined under Hist1 is Ds1 then the PI Tag name would be Hist1_Ds1. The Descriptor for the PI tag is a copy of the Datastream descriptor field as stored in ECHO. The Instrumenttag field in PI is the reference to the point in the foreign system. This field is made up of the Historian Name and Datastream Name with each field being separated by the back slash character (‘\’). For example if you had Hist1 and Ds1 defined then the instrument tag field would contain Hist1\Ds1. The Location1 field is used by PI interfaces as the instance id and determines which tags belong to a particular copy of the interface. Using the Tag Configuration tool for the PI ECHOInt interface the Historian index is used as the Location1 value. This provides a grouping of the ECHO tags and allows the user to run multiple instances of the interface based on Historian configuration. For example if you had Hist1 and Hist2 and each Historian contained 1000 tags then you would have Location1=1 for the first 1000 tags and then have Location1=2 for the next 1000 tags. The Location4 field is used by PI interfaces as the scan class index. If you are running the PI ECHOInt interface using one of the read history options then the scan class should simply be set to 1. The PI Configuration tool exports the tags setting Location4=1. If you are running the PI ECHOInt interface in read current value mode then the scan class is

ECHOInt Interface to the PI System 3 Principles of Operation

used to determine how often to read the value for the tags. In this case the scan class should be configured by the user based on the update rates needed for the tag values.

The Pointsource field is similar to the Location1 setting in that it is used to group the tags for a particular copy of the interface. Similar to the Location1 property, the Pointsource is based on the Historian configuration and is generated using a capital E, an underscore character followed by the Historian Name. For example if you had Hist1 and Hist2 each with 1000 tags then you would have E_Hist1 as the pointsource for the first 1000 tags and have E_Hist2 as the pointsource for the next group of 1000 tags. The Pointtype field is the datatype for the tag in PI based on the current datatype in ECHO. The following ECHO data types are exported as an int32: VT_I1, VT_UI1, VT_I2, VT_UI2, VT_INT, VT_I4, VT_BOOL. The following ECHO data types are exported as a float64: VT_R8, VT_CY, VT_DATE, VT_UINT, VT_UI4. An ECHO VT_R4 is exported as a float32 and an ECHO VT_BSTR is exported as a string.

Configuring tags in PI

The Tag Configuration tool for the PI ECHOInt interface outputs a .csv file that can then be imported into PI using either the PI TagConfigurator or the piconfig utility. This is a manual process done by the user after having run the Tag Configuration tool. The PI TagConfigurator is an Excel add-in and is used to create, edit, and delete PI Points on local or remote PI servers. Refer to the PI TagConfigurator Help file for additional information on how to use this tool and create tags in PI. The piconfig utility is similar to the PI TagConfigurator in that it can create, edit and delete PI points. Refer to the PI Server System Management Guide Chapter 10 for details on this utility.

4 Tag Configuration Tool Installation

The Tag Configuration tool for the PI ECHOInt interface is installed with the PI ECHOInt interface installation. Refer to the PI ECHOInt interface for detailed information about this installation package. Once the PI ECHOInt interface has been installed then the Tag Configuration tool can be found in the folder “Tools” underneath the ECHOInt installation folder.

Supported Platforms: Windows 2000 SP 3 and SP4, XP, 2003, and Windows CE X86 platform. The tool is designed to run on the above mentioned Microsoft Windows operating systems and greater. Due to the dependency of ECHO on COM and DCOM, the Tag Configuration tool is not support on non-Windows platforms.

To run on a Windows CE X86 platform the PIECHOInt_TagCfg_CE.exe and pdb files must be copied to the Windows CE device where the ECHO archive engine is running.

Vendor Software Required The Tag Configuration tool for the PI ECHOInt Interface is an ECHO Client application and therefore requires the ECHO SDK to be installed on the machine where the tool will execute. ECHO provides several types of install packages. The Client-Only install package contains the minimum set of required files for the Tag Configuration Tool Node.

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 5 ECHO Configurator

The ECHO Configurator can be used to test the communication between the node with the Tag Configuration tool and the ECHO Archive Engine Node. For the tool and ECHO to properly communicate, COM/DCOM must be configured. The ECHO Client-Only installation package provides options for automatically configuring COM/DCOM. If additional information is needed, then refer to the ECHO General Developers Guide for details on setting up COM/DCOM manually. Once installed, go to “Start\Programs\ECHO” and select “ECHO Configurator”. Right- click on the “Component Historian Configuration” tree view item and select the “Connect” menu item.

In the Connect to Remote Node dialog box, enter the name of the node where the ECHO Archive Engine is running. Once the configurator can successfully connect to this node, then the tag configuration tool should also be able to connect successfully.

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 6 Startup Command File

When configuring the batch file (PIECHOIntTagCfg.bat or PIECHOIntTagCFG_CE.bat) the command-line parameters can begin with a / or with a -. For example, /echo=Machine1 and –echo=Machine1 command-line parameters are equivalent. For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). There are only two command-line parameters for the Tag Configuration tool. The first required option is /echo=NodeName where NodeName is the.

Command-line Parameters

Parameter Description /echo=Hostname The name or IP Address of the node where the ECHO Archive or Engine is installed. /echo=IPAddr Note: Use ECHO Configurator to test communication between interface node and ECHO node. Required /file=”path\file” The path and filename for the .csv file created by the tool. This file will contain the ECHO configuration in .csv file format. The Required path and filename must be enclosed in quotes if the path contains spaces. The file should end in a .csv file extension.

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 7 Startup Command File

Sample PIECHOInt_TagCfg.bat File

The following is an example file: REM======REM REM PIECHOInt_TagCfg.bat REM REM Sample startup file for the Tag Configuration tool for the PI ECHOInt REM Interface to the PI System REM REM======REM REM Sample command line REM .\PIECHOInt_TagCfg.exe ^ /ECHO=xxxx ^ /file="D:\abc\def\Results.csv" REM REM End of PIECHOInt_TagCfg.bat File

Sample PIECHOInt_TagCfg_CE.bat File

REM======REM REM PIECHOInt_TagCfg_CE.bat REM REM Sample startup file for the Tag Configuration tool for the PI ECHOInt REM Interface to the PI System REM REM======REM REM Sample command line REM .\PIECHOInt_TagCfg_CE.exe ^ /ECHO=xxxx ^ /file="D:\abc\def\Results.csv" REM REM End of PIECHOInt_TagCfg_CE.bat File

8 Appendix A: Error and Informational Messages

Using the required command line option /file=”path\filename” a .log file will be created. This .log file will contain both informational messages as well as failed messages. This file can be used to monitor the export and verify things are working properly. A minimal set of successful messages are printed so that the file contains useful information but not too much information. For example if the user input to the tag configuration tool is as follows: /file=”D:\a b c\d e f\Results.csv” then a log file would be created with the same name and a .log extension: “D:\a b c\d e f\Results.csv.log”

There are two categories of errors. Errors that cause the tool to shut down and errors that are logged and the tool continues to run.

Errors that cause the tool to shut down:  ECHO communication errors  Failure accessing the Historians collection and or accessing a particular Historian  Failure accessing the Datastreams collection for any Historian  Failure accessing the Datastream itself

Errors that cause the tool to log a message and continue running:  Failure accessing an individual property of the datastream

Sample .log file where successfully exported ECHO configuration TagCfg successfully connected to ECHO Node Successfully accessed historians collection with count= 2.

Processing historian 1: Name = Hist1 Datastream Count = 2

Processing historian 2: Name = Hist2

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 9 Appendix A: Error and Informational Messages

Datastream Count = 2

TagCfg Operation completed successfully.

Sample .log file where failed during export of ECHO configuration TagCfg successfully connected to ECHO Node Successfully accessed historians collection with count= 3.

Processing historian 1: Name = Hist1 Datastream Count = 1

Error: -2147023169: The remote procedure call failed and did not execute.

Error: Failed reading Descriptor property of ECHO Datastream: Hist1\Ds1.

TagCfg Operation completed with errors.

ECHO Errors

The ECHOSDKRef.chm help file contains a list of ECHO error codes and their meaning. The Tag Configuration tool will write the ECHO error code and its meaning to the .log file at runtime when an error is encountered. Refer to the ECHOSDKRef.chm help for additional information related to ECHO errors.

10 Revision History

Date Author Comments 15-May-2007 PHawkins Skeleton Version 2.5.2 Initial manual version. 18-Mar-2009 PHawkins Version 2.0.0.0; Added support for Windows CE X86 platform. 24-Mar-2009 MKelly Version 2.0.0.0, Revision A; Updated title page and contacts page, added sample batch file for CE version of Tag Configuration program.

Tag Configuration Tool for PI ECHO to PI Interface to the PI System 11