pi echo to pi interface to the pi systemcdn.osisoft.com/interfaces/1573/pi_echoint_1.0.0.6.doc ·...

PI ECHO to PIInterface to the PI System

Version 1.0.0.6Revision D

How to Contact UsOSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA

Telephone(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone)

[email protected]

Houston, TX Johnson City, TN Mayfield Heights, OHPhoenix, AZ Savannah, GASeattle, WAYardley, PA

Worldwide OfficesOSIsoft AustraliaPerth, AustraliaAuckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSI Software Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, 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

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

© 2007 OSIsoft, Inc. PI_ ECHOInt.doc

http://WWW.OSISOFT.COM/

mailto:[email protected]

Table of Contents

Introduction......................................................................................................................1Reference Manuals........................................................................................................1

Supported Features........................................................................................................1

Diagram of Hardware Connection..................................................................................4

Principles of Operation...................................................................................................7Connection to PI.............................................................................................................7

Connection to ECHO......................................................................................................7

Time offset calculations..................................................................................................7

Loading PI Points...........................................................................................................7

Runtime behavior...........................................................................................................8

Data Collection...............................................................................................................8

Read History...............................................................................................................9

Read Current............................................................................................................11

Sending data to PI........................................................................................................11

Health Points Support...................................................................................................12

Data Timestamps.........................................................................................................13

Installation Checklist.....................................................................................................15Interface Installation......................................................................................................17

Naming Conventions and Requirements......................................................................17

Interface Directories.....................................................................................................17

PIHOME Directory Tree............................................................................................17

Interface Installation Directory..................................................................................18

Interface Installation Procedure....................................................................................18

Installing Interface as a Windows Service....................................................................18

Installing Interface Service with PI ICU....................................................................19

Installing Interface Service Manually........................................................................21

ECHO Configurator........................................................................................................23Digital States..................................................................................................................25PointSource....................................................................................................................27PI Point Configuration...................................................................................................29

PI ECHO to PI Interface to the PI System iii

Point Attributes.............................................................................................................29

Tag............................................................................................................................29

PointSource..............................................................................................................29

PointType..................................................................................................................29

Location1..................................................................................................................29

Location2..................................................................................................................30

Location3..................................................................................................................30

Location4..................................................................................................................30

Location5..................................................................................................................30

InstrumentTag...........................................................................................................30

ExDesc.....................................................................................................................31

Scan..........................................................................................................................31

Shutdown..................................................................................................................31

Output Points................................................................................................................32

Trigger Points...............................................................................................................32

Performance Point Configuration................................................................................33I/O Rate Tag Configuration...........................................................................................35

Monitoring I/O Rates on the Interface Node.................................................................35

Configuring I/O Rate Tags with PI ICU.........................................................................35

Configuring I/O Rate Tags Manually............................................................................37

Configuring PI Point on the PI Server.......................................................................37

Configuration on the Interface Node.........................................................................37

Startup Command File...................................................................................................39Configuring the Interface with PI ICU...........................................................................39

ECHOInt Interface Tab.............................................................................................41

Configuring the Interface manually...............................................................................44

Command-line Parameters..........................................................................................44

Read Parameters.........................................................................................................48

Sample PIECHOInt.bat File..........................................................................................48

Interface Node Clock.....................................................................................................49Security...........................................................................................................................51

Windows.......................................................................................................................51

Starting / Stopping the Interface on Windows............................................................53Starting Interface as a Service.....................................................................................53

Stopping Interface Running as a Service.....................................................................53

PI ECHO to PI Interface to the PI System iv

Buffering.........................................................................................................................55Configuring Buffering with PI ICU (Windows)...............................................................55

Configuring Buffering Manually....................................................................................58

Example piclient.ini File................................................................................................59

Appendix A: Error and Informational Messages.........................................................61Message Logs..............................................................................................................61

Error and Informational Messages (Debug turned on).................................................61

Error and Informational Messages (Debug options not set).........................................63

System Errors and PI Errors........................................................................................67

Revision History.............................................................................................................69

PI ECHO to PI Interface to the PI System v

IntroductionThe PI ECHO to PI (ECHOInt) interface copies data stream data from an ECHO historian to PI tags on a PI server. Data is moved in one direction, meaning data is copied from the ECHO historian to the PI server. The PI ECHOInt interface runs on a Windows Intel-based operating system (Windows 2000, XP, or 2003) and supports ECHO version 2.0 and later.

Interface tags created on the PI server, are configured to receive data from a unique source tag defined in ECHO. PI Tags receive either archive or current value updates from the source tag in ECHO. The type of data collection is configurable and is specified at interface startup.

Reference ManualsOSIsoft

PI Server manuals

PI API Installation manual

UniInt Interface User Manual

ECHO General Developers Guide

Supported FeaturesFeature Support

Part Number PI-IN-OS-ECHO-NTI

* Platforms Windows (2000, XP, 2003)

APS Connector No

Point Builder Utility Yes

ICU Control Yes

PI Point Types Float32 / Float64 / Int32 / Digital / String

Sub-second Timestamps Yes

Sub-second Scan Classes Yes

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Yes

Outputs from PI No

Inputs to PI: Scan-based / Unsolicited / Event Tags

Unsolicited and Scan-based

PI ECHO to PI Interface to the PI System 1

Feature Support

Supports Questionable Bit No

Supports Multi-character PointSource Yes

Maximum Point Count No

* Uses PI SDK No

PINet String Support N/A

* Source of Timestamps ECHO

* History Recovery Yes

* UniInt-based* Disconnected Startup* Set Device Status

Yes YesYes

Failover not supported at this time

* Vendor Software Required on PI Interface Node / PINet Node

Yes (ECHO SDK)

* Vendor Software Required on Foreign Device

Yes (ECHO Archive Engine, ECHO SDK)

Vendor Hardware Required No

* Additional PI Software Included with Interface

No

* Device Point Types VT_I1, VT_UI1, VT_I2, VT_UI2, VT_INT, VT_UINT, VT_I4, VT_UI4, VT_R4, VT_R8, VT_CY, VT_DATE, VT_BOOL, VT_BSTR

Serial-Based Interface No

* See paragraphs below for further explanation.

PlatformsThe Interface 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 ECHO Interface is not support on non-Windows platforms.

Uses PI SDKThe PI SDK and the PI API are bundled together and must be installed on each PI Interface Node. This Interface does not specifically make PI SDK calls.

Source of TimestampsThe ECHO historian provides a timestamp for each data event. Timestamps are received from ECHO in UTC format as a double value and the data is sent to PI using the PITIMESTAMP structure seconds field. The PITIMESTAMP seconds field is defined in PI as a double value representing UTC seconds. Because ECHO provides UTC time and PI stores UTC time then there are no time zone issues to handle.

The interface adjusts timestamps for clock drift. Clock drift is the time offset between the PI server and the ECHO Node. Adjusting for clock drift means the time offset is added to the source timestamp adjusting it to the receiving PI server time.


History RecoveryHistory recovery enables users to recover archive data for time periods when the interface was not running or otherwise unable to collect data. Several command line configuration options are available for configuring history recovery. See the section titled “Data Collection” for detailed information related to history recovery.

UniInt-basedUniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

Disconnected StartupThe ECHO to PI Interface requires that the PI API version 1.6.1.10 or later is installed for disconnected startup to work properly. The ECHOIntSetup.msi will fail to install if PI API 1.6.1.10 or later is not detected.

PI API 1.6.1.10 is included as part of the PI SDK 1.3.5.338 installation package.

Set Device StatusUniInt UI_DEVSTAT tag is supported.

The Health tag with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the source device. The update values and meaning of this tag are as follows:

a) System Digital State "Good" - the interface is properly communicating with ECHO and is able to read data as required. When in this state, the system digital state of "Good" will be written to the Device Status tag.

b) "1 | Starting" - the interface is starting.

c) "3 | 1 device(s) in error" - the interface is not able to communicate with ECHO. If we had good communication to ECHO and connection goes down, then the value of the Device status tag will be set to 3, meaning communication failure.

d) "4 | Intf Shutdown" - the interface is shutting down.

Please refer to the UniInt Interface User Manual.doc file for more information on how to configure health points.

Vendor Software RequiredThe ECHO Interface is an ECHO Client application and therefore requires the ECHO SDK to be installed on the Interface Node. ECHO provides several types of install packages. The Client-Only install package contains the minimum set of required files for the Interface Node.

Device Point TypesThe following ECHO data types are mapped to an int32 in PI:

VT_I1, VT_UI1, VT_I2, VT_UI2, VT_INT, VT_I4, VT_BOOL

The following ECHO data types are mapped to a float64 in PI:


Introduction

VT_R8, VT_CY, VT_DATE, VT_UINT, VT_UI4

The ECHO data type VT_R4 is mapped to a float32 in PI.

The ECHO data type VT_BSTR is mapped to a string in PI.

Diagram of Hardware Connection

4

OR

If ECHO is running on a PC then the ECHOInt Interface can be installed on the same box, on a separate Interface Node or on the PI Server Node.

If ECHO is running on a CE device then the Interface cannot be installed on the same box as ECHO and must be installed on either a separate Interface Node or on the PI Server Node.

The recommended option for running an OSI Interface is on a dedicated Interface Node so as not to slow down the PI Server and/or the ECHO Server.


Principles of OperationThe PI ECHOInt interface copies data from ECHO to PI. It consists of a single executable and startup configuration file. No specific tag limit exists for the interface. However, data throughput (events/sec) can be limited by available network and/or system resources on the source and receiving nodes.

Connection to PIThe PI ECHOInt interface establishes the initial connection to PI and reconnects to PI in the event that the connection is lost for some reason. If the Interface is started while the PI Server is down, the Interface will periodically try to establish a connection until the PI Server is up.

Connection to ECHOAt startup the interface will initiate the connection to ECHO. If ECHO is unavailable, the reconnect delay parameter tells the interface how often to retry the connection. Once ECHO becomes available, then the interface will continue.

If the connection to ECHO goes down while the interface is running, then it will go into a wait state and retry the ECHO connection based on the value of the reconnect delay parameter.

IOTimeout is written to all ECHOInt interface tags in PI when the connection is lost after having a successful connection to ECHO.

Time offset calculationsOnce the interface has successfully connected to ECHO and PI, then the time offset from each machine is calculated and the time adjustment is added to the timestamp as the data goes from ECHO to PI. The offset is updated every 2 minutes and used for data timestamp adjustments and to timestamp interface status events such as IOTimeout. It is required that each participating Node has the correct system time for its configured time zone. At this point the interface is ready to begin loading points and collecting data.

Loading PI PointsOnce the interface has established an initial connection to ECHO and PI the interface searches the PI Point Database for points that belong to the interface and a point list is created. If the point passes the initial set of checks then it is loaded by the interface. If the data stream is not found in ECHO after the point was loaded then a message is logged to the pipc log file saying the tag was removed from the interface.

Point changes (adds, edits, or deletes) in PI are automatically detected by the interface and handled appropriately. Point changes (adds, edits, or deletes) in ECHO are not


automatically handled. At startup when the tag is loaded, the Interface expects to find the data stream in ECHO. If the data stream is not found in ECHO, then the PI tag is dropped from the configuration and a message is written to the pipc log file. If ECHO shuts down, then the tag list is saved and re-initialized when ECHO is restarted. But, any tag that was dropped from the configuration at startup is never re-added unless the point is edited in PI.

Runtime behaviorOnce startup is complete, the Interface enters the processing loop, which includes:

Servicing scheduled input points (/rc ReadCurrent command line parameter). Each Scan Class is processed in turn writing current value to each tag based on scan class update rate.

Servicing unsolicited input points (/rh ReadHistory command line parameter). Each scan class is continually processed in turn writing one history value per tag. Tags are grouped internally based on scan class assignment. However the read history option does not use the scan class update rate.

The PI Point Database is checked every 2 minutes for points that are added, edited, and deleted. If point updates are detected, the points are loaded (or reloaded) by the Interface as appropriate. The 2-minute update interval can be adjusted with the /updateinterval command-line parameter discussed in the UniInt Interface User Manual. The Interface will only process 25 point updates at a time. If more than 25 points are added, edited, or deleted at one time, the Interface will process the first 25 points, wait 30 seconds (or by the time specified by the /updateinterval parameter, whichever is lower), process the next 25 points, and so on. Once all points have been processed, the Interface will resume checking for updates every 2 minutes (or by the time specified by the /updateinterval parameter). The Interface will write the digital state SCAN OFF to any points that are removed from the Interface while it is running.

Data CollectionThere are two modes of data collection provided by the interface, history recovery and read current. The command line parameters specified at startup of the interface determine the mode of data collection. History recovery enables users to recover archive data for specific time periods when the interface was not running or otherwise unable to collect data. After performing history recovery, the interface begins scanning for updates. When the interface is scanning for updates each tag continually receives an archive value from its configured source data stream. The read current option allows tags to be updated in PI at each scan class update rate. In this mode, the current value of the data stream in ECHO is read each time the configured scan class update rate has elapsed and only that value is sent to PI.


Read HistoryThere are four command-line options available for reading history data. Only one read history option can be specified. The paragraphs that follow provide detailed information associated with each option.

Read History - /rh

Read History starting ‘x’ number of hours in the past - /rh=x

Read History and shut down - /rhs

Read History specific time range and shut down - /hronly=starttime,endtime

Read History ( /rh )The Read History /rh option reads data from ECHO and sends it to PI on a continual basis. At start up of the interface, UniInt loads tags from PI based on pointsource and instance ID. As each tag is loaded, its snapshot value is read from PI. The timestamp returned from the snapshot is the start time for that tag. Each tag is read individually and each start time is stored as a property of the tag. After all of the tags have been loaded, then data is continually read from ECHO and sent to PI. Each tag has its own start time and reads data from ECHO based on that start time. One value per tag is read from ECHO and sent to PI for each tag in the configuration. The tags are grouped based on scan class assignment. The reads start with scan class 1, scan class 2, and so on. The scan class assignment simply provides a grouping of the data. Each tag is read one at a time for each scan class and the data continually sent to PI.

The interface does not shutdown until requested by the user when the /rh option has been specified. In summary, this option transfers all history data from ECHO to PI based on the last snapshot timestamp of the data in PI. Once all history data has been transferred, then the Interface continually sends all current data and keeps the two systems in sync with one another.

If the interface is shut down and later restarted with the /rh option, then the interface will start sending data to PI based on the last snapshot value. The result is there will be no data overlap in PI, no missing values and no timestamp configuration required.

Read History starting ‘x’ number of hours in the past ( /rh=x )This option works the same way as the /rh option described above with one exception: the calculation of the start time for each tag. When the /rh option is not followed by =x, the start time is defined on a per tag basis and is the last snapshot timestamp for the tag in PI. The start time using /rh can be different for each tag. Using the /rh=x option, the start time is the same for all tags. It is calculated based on the start time of the Interface minus ‘x’ number of hours into the past. For example if the interface was started with the option /rh=8, then the start time for each tag would be the current time minus 8 hours.

The Interface does not shutdown until requested by the user when the /rh=x option has been specified. In summary, this option starts reading data from ECHO ‘x’ number of hours in the past starting now. It will continue reading data and keep the systems in sync until shut down by the user.


Principles of Operation

Read History and shut down ( /rhs )This option works the same way as the /rh option described above with one exception: the Interface shuts down after it reads the data starting at the timestamp of the last value in PI until the start time of the Interface. For each PI tag, the end time is set to the start time of the Interface and the start time is based on the last snapshot value in PI. Once this range of data has been read from ECHO and sent to PI for all tags, the interface will shut itself down.

This option is useful for scheduling the interface to run at particular times. Using this option, the data set in PI will have no overlap and no missing values, and the user does not have to configure the start time, end time ranges.

The Windows Scheduler can be used to start the Interface at a particular time - daily, periodically throughout the day, weekly, etc. The Windows Scheduler can be found on the Windows “Control Panel” dialog as the “Scheduled Tasks” item. Once opened, click the “Add Scheduled Tasks” item and follow the instructions to get started. Browse to the PI ECHOInt executable (...PIPC\Interfaces\ECHOInt\PIECHOInt.exe), follow the instructions to setup the time, add the appropriate user name and password, and then click “Finish”.

After adding a task to run the Interface, double click the Scheduled task from the list in the “Scheduled Tasks” dialog. Update the “Run” box to include the command line parameters required for the Interface.

10

The Interface will then run when started by the Windows Scheduler, and using the /rhs option will continually send data to PI based on the last sent value, run until now, and shutdown.

Read History time range and shut down ( /hronly=starttime,endtime )The/hronly=starttime,endtime option specifies a particular time range to read data then shuts down. The PI Time format is supported for the starttime, endtime parameters. Below is a description of the supported PI Time formats. Refer to the Data Archive Manual for additional information.

Absolute format containing some fields of DD-MMM-YY hh:mm:ss

Relative time in +|- n d|h|m|s

Absolute time specified with a word (TODAY, YESTERDAY, SUNDAY, MONDAY...)

An asterisk for the current time

A combination time using one of the word absolute times and a relative time

Read CurrentThe Read Current /rc option reads data from ECHO and sends to PI based on the scan class update rate. History data is not read at startup of the interface when the /rc command line option has been specified. One value per tag is read from ECHO and sent to PI when the associated scan class update rate has elapsed. The reads start with scan class 1, scan class 2, and so on. All tags in a scan class are read before the next scan class starts reading. The scan class assignment provides both a grouping of the data reads and the requested update rate for reading the data.

The interface does not shutdown until requested by the user when the /rc option has been specified. In summary, this option transfers current value of all tags at the requested update rate and continues running until the user shuts down the interface.

Sending data to PIThere are two modes available for sending data to PI, UniInt and the PI API. The command line parameter specified at startup of the interface determines the mode used for sending data to PI.

UniIntThe default is to send data to PI using UniInt. UniInt provides many additional features not available when using the PI API such as exception processing, health tags, and additional support for data range and data type checking. To use this option no command line parameters are required.

When using UniInt to write data to PI, in most cases the /q option (provided by UniInt) should be used. This option queues exception data before sending it to PI. The maximum queue size is approximately 4 kilobytes. The queue is flushed at the end of each scan to


Principles of Operation

ensure all updates are sent. See the UniInt Interface User Manual for more information about UniInt-supported command line options.

Note: Enabling data queuing will increase throughput by as much as an order of magnitude or more (10,000 versus 1,000 events/second).

PI APIThe second option is to send data to PI using the PI API. This option is faster and provides a more optimized solution for high speed data. However, exception processing and other UniInt features are not available when sending the data to PI using the PI API.

The following command line option is required to send data to PI using the PI API:/piapi

Using this option the interface will transfer the data as is to the PI Snapshot. If an error occurs for any data value sent to PI using the PI API then a message is logged to the pipc log file. This message will contain the PI Tag ID, the Error number and the Error text describing the issue.

Health Points SupportUniInt-based interfaces provide a set of health points used to monitor the health of an interface. The meaning of some of the health points is dependent on the design of the interface. The Health points are defined in the UniInt Interface User Manual. The following lists identify the points not supported, the points fully supported as defined by UniInt, and the points whose meaning does not follow the UniInt standard definition.

The Health Points listed below are not supported by the PI ECHOInt Interface:

Output Rate Tag

Output Bad Value Rate Tag

Trigger Rate Tag

Trigger Bad Value Rate Tag

Scan Class IO Rate Tag

Scan Class Bad Value Rate Tag

Scan Class Scan Time

Scan Class Device Scan Time

The Health Points listed below are supported by the PI ECHOInt Interface and are defined by UniInt in the UniInt Interface User Manual.

Heartbeat Tag - If the value of the Heartbeat Tag is updating, then the interface is running.

Scan Class Information Tag - Defines the number of scan classes used by the interface along with their associated update rate. This tag also includes the update rate of the Heartbeat tag.

12

Device Status Tag - If the interface is able to read data from ECHO then the digital state value of ‘Good’ is written to the device status tag in PI.

Message Counter Tag - Keeps track of the number of messages the interface has logged to the pipc log file.

The Health Points listed below are supported by the PI ECHOInt Interface and do not follow the UniInt standard definition.

IORate Tag - meaning of this tag is dependent on the type of write method used to send data to PI. If sending data to PI using the PI API, then this tag has no meaning. If sending the data to PI using UniInt, then it has the standard definition as defined by UniInt, updates at the heartbeat update rate, and is the total number of values sent to PI (before exception processing occurs) by the Interface during that time period.

Scan Class Scans Skipped Tag - meaning of this tag is dependent on the type of read option used by the Interface - read history versus read current. If running in read history mode, then the tag has no real value. If running in read current mode, then the tag has the standard definition as defined by UniInt and shows the number of scans being skipped because the Interface has been configured to run faster than it is able.

Scan Class Scan Count Tag - meaning of this tag is dependent on the type of read option used by the Interface - read history versus read current. If running in read history mode, then the tag has no real value. If running in read current mode, then the tag has the standard definition as defined by UniInt and shows the number of scans executed by the interface.

Data TimestampsECHO provides a timestamp for each data event. Because both ECHO and PI store UTC seconds then the timestamps automatically handle time zone differences. Clock drift between nodes is handled by the interface. To function properly, each Node must have the correct system time configured for its time zone.

Clock drift is the time offset between the current time on the PI Server Node and the current time on the ECHO Node. The time offset is added to the timestamp provided by ECHO before sending the data to PI. The time offset is also used to calculate the start time and end time when running in history recovery mode.

Offsets are calculated at startup once the interface has successfully connected to both PI and ECHO. At runtime offsets are re-calculated every 2 minutes. If a change is detected from previous offset to current offset then a message is logged to the pipc log file.

The PI ECHOInt interface does not support sending data to PI2 Servers. If support for a PI2 Server is required, then contact technical support to request this feature.


Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this checklist helps get the Interface running. If not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.

1. Install the PI Interface Configuration Utility (which installs PI SDK and PI API)

2. Verify that PI API has been installed.

3. Install the interface.

4. Using the ECHO Client-Only Installation kit, install both the ECHO SDK and the ECHO Sample Applications (includes the ECHO Configurator).

5. Test the connection between the Interface Node and ECHO by using the ECHO Configurator.

6. Define digital states. On and Off are required in the System Digital State Table.

7. Configure PI points.

InstrumentTag is the path to the data stream in ECHO

Location1 is the interface instance.

Location2 maps a PI tag to the Extended Value field for ECHO data.

Location3 is not used.

Location4 is the scan class.

Location5 is not used.

PointSource identifies points for this copy of the interface and matches the startup command line option /ps.

PointType should match the data type of the data stream in ECHO.

8. Configure the interface using the PI ICU utility or edit the startup command file manually. It is recommended to use PI ICU whenever possible.

9. Configure I/O Rate tag (optional) using the PI ICU.

10. Set up tag and Node security.

11. Start the interface without buffering and verify data.

12. Stop and restart the interface with buffering and again verify data.


Interface InstallationOSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server Node. A PI Interface Node is any node other than the PI Server Node where the PI Application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services . Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.

The guidelines are different if an interface is installed on the PI Server Node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Bufserv is not enabled on the PI Server Node. Bufserv can be enabled on the PI Server Node so that interfaces on the PI Server Node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server Node. See the UniInt Interface User Manual for special procedural information.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is PIECHOInt.exe and that the startup command file is called PIECHOInt.bat.

When Configuring the Interface ManuallyWhen configuring the interface manually, it is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, PIECHOInt1.exe and PIECHOInt1.bat would typically be used for interface number 1, PIECHOInt2.exe and PIECHOInt2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.

Interface Directories

PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located


in the %windir% directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\pipc

The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryPlace all copies of the interface into a single directory. The suggested directory is:PIHOME\Interfaces\ECHOInt\Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation ProcedureThe PI ECHOInt Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. To install, run the ECHOInt_x.x.x.x.exe installation kit.

Installing Interface as a Windows ServiceThe PI ECHOInt Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.


Installing Interface Service with PI ICUThe PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service ConfigurationService nameThe Service name box shows the name of the current interface service. This service name is obtained from the interface executable.

IDThis is the service id used to distinguish multiple instances of the same interface using the same executable.

Display nameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.

Log on asThe Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on


Interface Installation

as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

PasswordIf a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.

Confirm PasswordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies

list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a

service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

20

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI ICU dialog.

Installing Interface Service ManuallyHelp for installing the interface as a service is available at any time with the command:PIECHOInt.exe –help

Change to the directory where the PIECHOInt1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewith Bufserv implemented

Manual service PIECHOInt.exe –install –depend “tcpip bufserv”

Automatic service PIECHOInt.exe –install –auto –depend “tcpip bufserv”

*Automatic service with service id

PIECHOInt.exe –serviceid X –install –auto –depend “tcpip bufserv”

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewithout Bufserv implemented

Manual service PIECHOInt.exe –install –depend tcpip

Automatic service PIECHOInt.exe –install –auto –depend tcpip

*Automatic service with service id

PIECHOInt.exe –serviceid X –install –auto –depend tcpip

*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) parameter found in the interface .bat file.

Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.


Status of the ICU Status of the

Interface Service

Service installed or uninstalled

ECHO Configurator The ECHO Configurator can be used to test the communication between the PI Interface Node and the ECHO Node. For the Interface Node 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” treeview 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 interface should also be able to connect successfully.


Digital StatesFor more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time.

If the interface receives bad data from an interface point, it writes the system digital state “Bad” to PI instead of a value.

If the connection to ECHO was previously good and is now bad then the interface writes the system digital state “IOTimeout” to PI for all tags configured for the interface.

System Digital State CachingThe system digital state values for ‘Bad’ and ‘IOTimeout’ are cached at startup of the interface and used throughout the life of the interface. If the integer value of the system digital state “Bad” or “IOTimeout” has changed since startup of the interface then the interface will not detect the new value and will continue sending the value cached at startup.


PointSource The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string ECHOHst1 may be used to identify points that belong to the PI ECHOInt Interface. To implement this, the PointSource attribute would be set to ECHOHst1 for every PI Point that is configured for the PI ECHOInt Interface. Then, if /ps=ECHOHst1 is used on the startup command-line of the PI ECHOInt Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of ECHOHst1. Before an interface loads a point, the Interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the Interface. For additional information, see the /ps parameter.

Case-sensitivity for PointSource AttributeIf the Interface is running on a PINet Node, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, the case of the PointSource is insignificant.

In all cases, the PointSource character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet Node communicating to a PI Server.

Reserved Point SourcesSeveral subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.

Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Point AttributesUse the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.

TagA tag is a label or name for a point. Any tag name can be used in accordance with the normal PI point naming conventions.

LengthThe length of the Tag name is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

PI API PI Server Maximum Length

1.6 or higher 3.4.370.x or higher 1023

1.6 or higher Below 3.4.370.x 255

Below 1.6 3.4.370.x or higher 255

Below 1.6 Below 3.4.370.x 255

PointSourceThe PointSource is a unique, single or multi-character string that is used to identify the PI point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “Point Source” section.

PointTypeTypically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.

Float16, float32, float 64, int16, int32, digital, and string point types are supported. For more information on the individual PointTypes, see PI Server manuals.

Location1Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter.


PI Point Configuration

Location2Location2 maps the Extended Value field of an ECHO data value to a PI tag. In ECHO a data object has two fields - value and extended value. The default (Loc2=0) maps the value from ECHO to PI. If Location2=1 then the Extended Value field of the data object will be mapped to the PI Tag.

Example:

PI tag name: Location2 Instrument tag

Ds1_value 0 Node1\Hst1\Ds1

Ds1_extValue 1 Node1\Hst1\Ds1

In this example both PI tags are mapped to the same ECHO data stream but one PI tag stores the actual value of the data object and the other PI tag stores the extended value of the same data object.

Location3Location3 is not used by this interface.

Location4Scan-based Inputs (/rc read current command line parameter)Location4 defines the scan class for the PI point. The scan class determines the frequency at which current value reads are scanned for new values. For more information, see the description of the /f flag in the section called “Startup Command File”

Unsolicited Inputs (/rh history recovery command line parameter)Location4 defines the scan class for the PI point. The scan class determines the order in which the history data is read from ECHO. All tags for a scan class are read and the data sent to PI. The scan class simply provides a grouping of the tags.

Location5Location5 is not used by this interface.

InstrumentTagLengthThe length of the InstrumentTag attribute is limited by the version of the PI API and the version of the PI Server. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

PI API PI Server Maximum Length

1.6 or higher 3.4.370.x or higher 1023

1.6 or higher Below 3.4.370.x 32

Below 1.6 3.4.370.x or higher 32

Below 1.6 Below 3.4.370.x 32

30

FormatThe instrument tag attribute is used to identify the ECHO data stream defined in the ECHO historian. The instrument tag attribute is the full path to the ECHO data stream: NodeName\HistorianName\DatastreamName

At startup, the NodeName is checked with the command line parameter -echo=NodeName. If these two fields do not match, then the tag is logged as being in error and is dropped from the configuration.

ExDescThe ExDesc tag attribute is used by the interface to configure UniInt supported Health Points.

Scan The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the Interface is edited so that the point is no longer valid for the Interface, the point will be removed from the Interface and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the Interface is changed, the point will be removed from the Interface and SCAN OFF will be written to the point.

ShutdownThe Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to the PI Server manuals.

It is undesirable to write SHUTDOWN events if the interface is calculating the start time based on the last value written to PI for the tag. This is the case for both the /rh option and the /rhs option. If the SHUTDOWN event is needed, then the interface should be restarted with the /rh=x option.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the Interface when the -stopstat=Shutdown command-line argument is specified.SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in the PI Server manuals.


PI Point Configuration

BufservIt is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

Output Points Currently not supported by the first release of the PI ECHOInt interface.

Trigger PointsCurrently not supported by the first release of the PI ECHOInt interface.

32

Performance Point ConfigurationPerformance Points are currently not supported by the PI ECHOInt interface.


I/O Rate Tag ConfigurationAn I/O Rate tag measures the throughput of an Interface. In particular, the value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server. Because values are averaged over a 10-minute interval, the first calculated value is not written to the PI Server until 10 minutes after the Interface has started. The user can configure one I/O Rate tag for each copy of the Interface that is in use.

The PI ECHOInt interface provides two methods for sending data to PI, the PI API or UniInt. If the Interface is configured to send data to PI using the PI API, then the I/O Rate tag is not available (i.e. it will have no meaning and will always record zero). If the Interface is configured to send data to PI using UniInt, then this number will reflect the amount of data actually sent to PI.

Monitoring I/O Rates on the Interface NodeFor Windows, the 10-minute rate averages (in events/minute) can be monitored with a client application such as PI ProcessBook.

Configuring I/O Rate Tags with PI ICU The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing I/O Rate Tags.


PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use.

Enable IORates for this InterfaceThe Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O Rates for the selected interface, check this box.

Tag StatusThe Tag Status column indicates whether the I/O Rate tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI

Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the PI ICU is not able to access the PI Server

In FileThe In File column indicates whether the I/O Rate tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

Event CounterThe Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command-line equivalent is -ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

TagnameThe tag name listed under the Tagname column is the name of the I/O Rate tag.

SnapshotThe Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.

Button Menu OptionsCreateCreate the suggested I/O Rate tag with the tag name indicated in the Tagname column.

DeleteDelete the I/O Rate tag listed in the Tagname column.

ResetReset IORate EventCounter and Tag Settings


RenameAllow the user to specify a new name for the I/O Rate tag listed in the Tagname column.

Add to FileAdd the tag to the IORates.dat file with the event counter listed in the Event Counter Column.

Search Allow the user to search the PI Server for a previously defined I/O Rate tag.

Configuring I/O Rate Tags ManuallyThere are two configuration steps.

1. Configuring the PI Point on the PI Server

2. Configuration on the Interface Node

Configuring PI Point on the PI ServerCreate an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeFor the following examples, assume that the name of the PI tag is PIECHOInt001, and that the name of the I/O Rate on the home node is PIECHOInt001.

1. Edit/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.

Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat.

Add a line in the iorates.dat file of the form:PIECHOInt001, x

where PIECHOInt001 is the name of the I/O Rate Tag and x corresponds to the first instance of the -ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, -ec=x, should be unique for each copy of the interface.

2. Set the -ec=x parameter on the startup command file of the interface to match the event counter in the iorates.dat file.


The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.

38

Startup Command FileThere are two methods for configuring the interface. Use the PI ICU (Interface Configuration Utility) or configure the command files manually.

Configuring the Interface with PI ICUNote: PI ICU requires PI 3.3 or greater.

The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (PIECHOInt1.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the module database. The procedure below describes the necessary steps for using PI ICU to configure the PI ECHOInt Interface.

From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE..., and then Browse to the PIECHOInt.exe executable file. Then, enter values for Point Source and Interface ID#. A window such as the following results:

“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.

Click on Add.

The following display should appear:


Note that in this example the Host PI System is STARSHOLLOW, which means that the interface will be configured to communicate with that PI Server. However, to configure the interface to communicate with a remote PI Server, select ‘Interface => Connections…’ item from PI ICU menu and make it the default server. If the remote node is not present in the list of servers, it can be added.

Once the interface is added to PI ICU, near the top of the main PI ICU screen, the Interface Type should be ECHOInt. If not, use the drop-down box to change the Interface Type to be ECHOInt.

Click on Apply to enable the PI ICU to manage this copy of the PI ECHOInt Interface.

The next step is to make selections in the interface-specific tab (i.e. “ECHOInt”) that allow the user to enter values for the startup parameters that are particular to the PI ECHOInt Interface.


Since the PI ECHOInt Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface.

To set up the interface as a Windows Service, use the Service tab. This tab allows configuration of the interface to run as a service as well as to starting and stopping of the interface. The interface can also be run interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive.

For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. The next section describes the selections that are available from the ECHOInt tab. Once selections have been made on the PI ICU GUI, press the Apply button in order for PI ICU to make these changes to the interface’s startup file.

ECHOInt Interface TabSince the startup file of the PI ECHOInt Interface is maintained automatically by the PI ICU, use the ECHOInt tab to configure the startup parameters and not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.


Startup Command File

ECHOInt

GeneralECHO Archive Engine Node NameThis box is used to specify the name of the node where the ECHO Archive Engine is installed. Either the Node name or IP Address of the ECHO Archive Engine must be specified. Note: Use ECHO Configurator to test communication between interface node and ECHO node. (/ECHO=<HOSTNAME>)

ECHO Archive Engine IP AddressThese text boxes are used to specify the IP Address of the node where the ECHO Archive Engine is installed. Either the Node name or IP Address of the ECHO Archive Engine must be specified. Note: Use ECHO Configurator to test communication between interface node and ECHO node. (/ECHO=<IPAddress>)

Reconnect DelayThis box is used to specify reconnect delay. The reconnect delay is the amount of time to wait before re-trying a failed ECHO connection. It is used at interface startup if the connection fails and used at runtime if connection goes bad. Optional. (/RD=#, default=120000, specified in milliseconds)

Send data to PI using the PI APICheck this text box to send data to PI using the PI API. This is recommended if the data transfer rate is very low and writing the data to PI using UniInt does not meet the expected performance needs. See Sending Data to PI for more information on when to enable this option. Optional (/PIAPI)

42

Note: When the /piapi parameter is NOT specified, the ICU control will automatically add the /q parameter to the interface configuration when the ICU control is saved.

Debug OptionsEnable DebugCheck this box to enable debug messages. These messages will be printed to the screen when the interface runs interactively, and to the pipc.log file when the interface is run as a service. There are two levels of debug available:

Log tag configuration errors – only logs errors regarding tag configuration (/DB=1)

Log runtime data errors – only logs errors encountered with runtime data (/DB=2)

If all debug checkboxes are selected, then /db=3 (the sum of the debug options) and all possible messages are printed or logged.

Data CollectionOne of the following options is required to successfully run the ECHOInt interface.

Read CurrentSelect this option to read current value. This read option is used to read the current value for all tags based on scan class update rate. If the interface has three scan classes: /f=00:00:01 /f=00:00:05 /f=00:00:10 then tags belonging to scan class one will update every second. Tags in scan class two will update every five seconds and so forth. (/RC)

Read HistorySelect this option to read history. This will read historical data from ECHO starting with the timestamp for the last value in PI for each tag (the snapshot value), read until current time, and continually keep data in sync. (/RH)

Read History # Hours and continue runningSelect this option to read history starting the specified number of hours in the past. The interface will read the historical data up to current time, then continue running keeping the systems in sync. (/RH=#.#)

Read History and stopSelect this option to read history and then exit. The interface will start at the last value written to the PI snapshot, read until current time, and shutdown. (/RHS)

NOTE: the windows scheduler can be used to start the interface at a specific time and then use the /rhs read option for data transfer

Read History time range and shutdownSelect this option to read a historical time range and then exit. The interface will read data from ECHO starting at the start time specified, read until the end time specified, and then shutdown the interface. (/HRONLY=starttime,endtime)

NOTE: starttime and endtime use PI Time Format. See the Data Archive Manual for additional information regarding starttime,endtime formats



Additional ParametersThis box is used to add any command-line parameters which are not currently supported by the ICU Control. Each command-line parameter should be separated by a space. If the argument to a command-line parameter has embedded spaces then surround the whole argument in double quotes.

Configuring the Interface manually When configuring the batch file (PIECHOInt1.bat) the command-line parameters can begin with a / or with a -. For example, the /ps=M and –ps=M 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). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters

The command-line parameters have been divided into 2 tables. The first table is the standard interface command line parameters supported by UniInt. Refer to the UniInt Interface User Manual for more detailed information about the “General Interface Operation” command line options. The second table is the PI ECHOInt interface’s supported command line options.

Command-line ParametersParameter Description

/db=x

Optional

The /db parameter is used to specify a debug level when the interface is experiencing issues. Under normal conditions this parameter should not be needed. The debug flag is an OR'd check. The flag can be set to 1 for tag configuration errors, 2 for runtime data errors or 3 for all errors.

/ec=#

Optional

The first instance of the /ec parameter on the command-line is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1. Also, if the /ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without /ec=x explicitly defined will write to the same I/O Rate point. This means either explicitly defining an event counter other than 1 for each copy of the interface or not associating any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.”

/echo=<Hostname> or/echo=<IPAddr>

Required

The name or IP Address of the node where the ECHO Archive Engine is installed. Note: Use ECHO Configurator to test communication between interface node and ECHO node.

44

Parameter Description

/f=SSor/f=SS,SSor /f=HH:MM:SSor/f=HH:MM:SS,hh:mm:ss

Required

The /f parameter defines the time period between scans in terms of hours (HH), minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time with an optional time offset specified in terms of hours (hh), minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period that is specified is assumed to be in seconds. Each instance of the /f parameter on the command-line defines a scan class for the interface. There is no limit to the number of scan classes that can be defined. The first occurrence of the /f parameter on the command-line defines the first scan class of the interface; the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class via the Location4 PI Point attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example:/f=00:01:00,00:00:05 /f=00:00:07or, equivalently:/f=60,5 /f=7The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, and the second scan class has a scanning frequency of 7 seconds. When an offset is specified, the scans occur at discrete moments in time according to the formula:scan times = (reference time) + n(frequency) + offsetwhere n is an integer and the reference time is midnight on the day that the interface was started. In the above example, frequency is 60 seconds and offset is 5 seconds for the first scan class. This means that if the interface was started at 05:06:06, the first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined.The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans.Sub-second Scan ClassesSub-second scan classes can be defined on the command-line, such as/f=0.5 /f=00:00:00.1where the scanning frequency associated with the first scan class is 0.5 seconds and the scanning frequency associated with the second scan class is 0.1 of a second.Similarly, sub-second scan classes with sub-second offsets can be defined, such as/f=0.5,0.2 /f=1,0Wall Clock SchedulingScan classes that strictly adhere to wall clock scheduling are now possible. Previously, wall clock scheduling was possible, but not




across daylight saving time. For example, /f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells UniInt to use the new wall clock scheduling algorithm.

/host=host:portRequired

The/host parameter is used to specify the PI Home Node. Host is the IP address of the PI Sever Node or the domain name of the PI Server Node. Port is the port number for TCP/IP communication. The port is always 5450. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults. Examples:The interface is running on a PI Interface Node, the domain name of the PI home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450

/id=#Required

The /id parameter is used to specify the interface identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. UniInt always uses the /id parameter in the fashion described above. This interface also uses the /id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to Location1. For this interface, use only numeric characters in the identifier. For example,/id=1

/ps=xRequired

The /ps parameter specifies the point source for the interface. X is not case sensitive and can be any unique single or multiple character string. For example, /ps=P and /ps=p are equivalent. The point source that is assigned with the /ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.

46


/qOptional (recommended)

When the /q parameter is present, Snapshots and exceptions are queued before they are sent to the PI Server Node. Extended PI API mode behavior:The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled.Non-Extended PI API mode behavior:The maximum queue size is 255 bytes for a PI Interface Node. For example, if the interface is running on a Windows Node and is communicating to a PI Server, then the maximum queue size is 255. The queue is flushed between scans if it is not filled.When the /q parameter is specified in non-extended PI API mode, the PI API sends integer values as 16-bit integers instead of 32-bit integers. Therefore, integer points will be limited to values between 0 and 32767. Values higher than 32767 need to be sent to floating-point PI tags.

/rd=x

Optional

Reconnect delay. Amount of time to wait before re-trying a failed ECHO connection. Used at startup if the connection fails and used at runtime if connection goes bad.

/stopstator/stopstat=digstateDefault:/stopstat=”Intf Shut”Optional

If the /stopstat parameter is present on the startup command line, then the digital state Intf Shut will be written to each PI Point when the interface is stopped. It is undesirable to write stopstat events if the interface is calculating the start time based on the last value written to PI for the tag. This is the case for both the /rh option and the /rhs option. If stopstat is needed then the interface should be restarted with the /rh=# option. If /stopstat=digstate is present on the command line, then the digital state, digstate, will be written to each PI Point when the interface is stopped. For a PI 3 Server, digstate must be in the system digital state table. UniInt uses the first occurrence in the table.If neither /stopstat nor /stopstat=digstate is specified on the command line, then no digital states will be written when the interface is shut down.Examples:/stopstat=shutdown/stopstat=”Intf Shut” The entire digstate value should be enclosed within double quotes when there is a space in digstate.

/uitrace=tagname

Optional

Log all values and timestamps for a particular tag.Turn on this option to trace issues in the interface.

/piapi

Optional

Add this option to send data to PI using the PI API methods as opposed to the default option which is to use UniInt. This will improve performance when fast data rates are required.



Read ParametersOne of the following parameters is required for interface operation.

Parameter Description/hronly=starttime,endtime

Read history time range and shutdown. Read data from ECHO starting at start time, read until end time then shutdown the interface.NOTE: starttime, endtime uses PI Time Format. See the Data Archive Manual for additional information regarding starttime,endtime formats.

/rc Read current. This read option is used to read the current value in ECHO for all tags based on scan class update rate. If the interface has three scan classes: /f=00:00:01 /f=00:00:05 /f=00:00:10 then tags belonging to scan class one will update every second. Tags in scan class two will update every five seconds and so forth.

/rh Read history. This will read historical data from ECHO starting with the timestamp for the last value in PI for each tag (the snapshot value), read until current time, and continually keep data in sync.

/rh=#.# Read history from ECHO starting # number of hours in the past. Read until now, then continue running keeping the systems in sync.

/rhs Read history from ECHO and stop. Start at last value written to PI snapshot, read until NOW and shutdown. NOTE: the windows scheduler can be used to start the interface at a specific time and then use the /rhs read option for data transfer.

Sample PIECHOInt.bat FileThe following is an example file:REM=======================================================================REMREM PIECHOInt.batREMREM Sample startup file for the PI ECHOInt Interface to the PI SystemREMREM=======================================================================REM REM OSIsoft strongly recommends using PI ICU to modify startup files.REMREM Sample command lineREM .\PIECHOInt.exe" 1 -echo=PAM /rh -PS=ECHOInt1 -ID=1 /host=XXXXXX:5450 ^ /q -maxstoptime=120 /f=00:00:01 /f=00:00:05 REMREM End of PIECHOInt.bat File

48

Interface Node ClockMake sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the Interface Node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.


SecurityWindows

The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.

PI Server v3.3 and HigherSecurity configuration using piconfigFor PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:C:\PI\adm> piconfig@table pitrust@mode create@istr Trust,IPAddr,NetMask,PIUsera_trust_name,192.168.100.11,255.255.255.255,piadmin@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr

PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

Security Configuring using Trust EditorThe Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.


PI Server v3.2For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:C:\PI\adm> piconfig@table pi_gen,piproxy@mode create@istr host,proxyaccountpiapimachine,piadmin@quitIn place of piapimachine, put the name of the PI Interface Node as it is seen by PI Server.


Starting / Stopping the Interface on Windows This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:PIECHOInt.exe –start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Stopping Interface Running as a ServiceIf the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:PIECHOInt.exe –stopThe service can be removed by:PIECHOInt.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


BufferingFor complete information on buffering, please refer to the PI API Installation Instruction.

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Note: Change the Local Security Policy on Windows XP. 1. Open “Administrative Tools” from the control panel. 2. Open “Local Security Policy” from administrative tools. 3. Browse to “Security Options” under “Local Policies.” 4. Double click on “System Objects: Default owner for objects created by members of the Administrators group.” 5. Change the dropdown from “Object Creator” to “Administrators group.”The behavior of Bufserv should now be the same on Windows XP as it was for Windows NT 4 and 2000.

Configuring Buffering with PI ICU (Windows)Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the PI API Buffering (bufserv) process. The user can start and stop the PI API Buffering process from the Service tab:


Service TabThe Service tab allows for some PI API Buffering service configuration. For further configuration changes, use the Services applet.

Service NameThe Service name displays the name of the PI API Buffering Service.

Display NameThe Display name displays the full name associated with the PI API Buffering service.

Log On AsLog on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as: above.

Confirm passwordReenter the password to verify it has been typed correctly both times.

DependenciesThe Dependencies lists the Windows services on which the PI API Buffering service is dependent.

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.


Start / Stop ServiceThe Start / Stop buttons allow for the PI API Buffering service to be started and stopped. If the service is not created, this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Service Startup TypeThe Startup Type indicates whether the PI API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the PI API Buffering service is set to start automatically.

Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the PI API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

Settings TabThe Settings tab allows for configuration of the 7 configurable settings used by PI API Buffering. Default values are used if no other value is provided.


Buffering

Enable BufferingEnable the PI API Buffering feature.

Maximum File SizeMaximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send RateSend rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.


Primary Memory Buffer SizePrimary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer SizeSecondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer ObjectsMax transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause RateWhen buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry RateWhen the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.


58

Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and cannot be changed.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Configuring Buffering ManuallyBuffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the .dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0, 1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 – 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 – 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 – 2,000,000 100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS 1 – 2,000,000 500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 – 2,000,000 32768 Primary memory buffer size. (bytes)

BUF2SIZE 64 – 2,000,000 32768 Secondary memory buffer size. (bytes)

SENDRATE 0 – 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)


Buffering

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.

Keywords Values Default Description

PIHOMENODE string none Windows default server is in pilogin.ini

DSTMISMATCH 0 – 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)

Example piclient.ini FileOn Windows, the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a connection before retrying”.

On Windows a piclient.ini file might look like:

[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI API connection routines have a 1 minute default

timeout.RETRYRATE=600

60

Appendix A:Error and Informational Messages

The string ECHOInt> ID> is pre-pended to error messages written to the message log. ECHOInt is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command-line.

Message LogsThe location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information.

Messages are written to PIHOME\dat\pipc.log at the following times.

When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command line parameters used, and the number of points.

As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.

If one of the following options are on the command-line then various informational messages are written to the log file: /dbuniint=x, /db=x, -uitrace=tagname.

Error and Informational Messages (Debug turned on)There are 3 command-line options available for printing additional information to the pipc log file. The first two options are provided by UniInt and are standard across interfaces. The /dbuniint=x flag and the -uitrace=tagname flag. See the UniInt Users Manual for more detailed information about using these options.

The /dbuniint=x flag can be used to print the following types of messages: Initialization, Point additions, Exit handler, Sending data to PI, Main control loop, Point list creation, Point edits, IORate points, Services, Timestamps, Perf Counters, PI SDK, and Maximum.

The -uitrace=tagname flag can be used to log all values and timestamps for a particular tag. If the tag is updating frequently, then this option can quickly fill up the pipc log file. To use this option, specify the name of the PI Tag to be logged.

The /db=x flag is supplied by the PI ECHOInt Interface and can be used to print two types of messages. The flag can be set to 1 and the interface will print tag configuration messages. The flag can be set to 2 and the interface will print runtime information about the number of values read from ECHO and the number of values sent to PI on a per scan class basis. The flag is an OR'd check so setting the value to 3 will print both tag configuration and runtime data values.

The following is a list of the messages printed by the PI ECHOInt interface when the /db=x option has been specified and the configuration contains 1 PI Tag defined in Scan Class 1.


If the/db=x option is found on the command line then the following message is printed:

ECHOInt> 1> Debug level set to x

If the /db =1 or /db =3 option has been specified then the following message is printed for each tag added to the PI ECHOInt configuration.

ECHOInt> 1> Successfully added tag to ECHO tag map for ScanClass[1], TagCount= 1

If the /db =1 or /db =3 option has been specified then the following message is printed for each tag removed from the interface while the interface is up and running. During normal shutdown remove messages are not printed.

ECHOInt> 1> Successfully removed tag from ECHO tag map for ScanClass[1], TagCount= 1

If the /db =2 or /db =3 option has been specified then the following message is printed each time all tags for a scan class have been read from ECHO.

ECHOInt> 1> Data values read from ECHO for ScanClass[1] = 1

If the /db =2 or /db =3 option has been specified then the following message is printed each time a set of data is sent to PI and the interface is using the UniInt to write to PI.

ECHOInt> 1> Data values sent to PI for ScanClass[1] = 1, failed= 0

If the/db =2 or /db =3 option has been specified then the following message is printed each time a set of data is sent to PI and the interface is using the PI API. Note this example is sending Integer data to PI.

ECHOInt> 1> Count of Integer data sent to PI for ScanClass[1] = 1

If the interface had 4 tags configured, one of each type - integer, float, string, and digital - then the interface would print a separate message for each data type.

ECHOInt> 1> Count of Float data sent to PI for ScanClass[1] = 1ECHOInt> 1> Count of Integer data sent to PI for ScanClass[1] = 1ECHOInt> 1> Count of String data sent to PI for ScanClass[1] = 1ECHOInt> 1> Count of Digital data sent to PI for ScanClass[1] = 1

If a failure sending data to PI occurs then the following message will be logged.


ECHOInt> 1> Count of Integer data sent to PI for ScanClass[1]=x, duplicates= x, removed= x

Error and Informational Messages (Debug options not set)The following is a list of error/informational messages printed to the pipc log by the interface. These messages are not related to the debug options previously defined. These messages are always printed and cannot be turned off.

This message is printed at the first attempt of making a connection to the ECHO Archive Engine. In these examples, the name of the ECHO Node is ‘ABC’.

ECHOInt> 1> Trying to connect to requested ECHO Node ABC

If the connection was successful then the following message is printed.

ECHOInt> 1> Successfully connected to requested ECHO Node ABC

If the connection failed then the following message is printed and the interface will continue retrying the connection each time the -rd=x ReconnectDelay timeout has elapsed.

ECHOInt> 1> Failed connecting to ECHO Node ABC, will retry connection every ‘x’ milliseconds

Once the interface can successfully connected to the ECHO Node then the “Successfully connected ...” message listed above will be printed.

If the connection was previously good and for some reason the connection goes bad then the following message is printed.

ECHOInt> 1> lost connection to ECHO Node ABC, will retry connection every ‘x’ milliseconds"

If a catastrophic failure occurs at startup in the thread communicating with ECHO, then the following message will be printed to the pipc log file.

ECHOInt> 1> Unknown failure in thread connection to ECHO, shutting down interface

If a catastrophic failure occurs at runtime (i.e. after successful startup) in the thread communicating with ECHO then the following message will be printed to the pipc log file.

ECHOInt> 1> Unknown failure communicating with ECHO Node ABC, shutting down ECHO communication threadAt startup of the interface, UniInt calls the interface with each tag found in PI whose pointsource and instance ID match that of the interface. At this time some checks are made to validate the tag and it is added to the list of tags for a connection to ECHO. If the


Appendix A: Error and Informational Messages

tag is not found in ECHO then the following message is printed and the tag is removed from the tag list.

ECHOInt> 1> Failed connecting to ECHO Tag NodeName\HistorianName\DatastreamName, PI Tag (tag/id) removed from interface configuration

As stated above, this message means the tag passed initial checks and was loaded by UniInt but failed when making the actual connection to ECHO and is no longer part of the tag list for the interface. This can occur either at startup of the interface or if the connection to ECHO goes down, comes back up and the tag is not found in ECHO.

If the interface fails to call the ECHO Archive Engine and get the current UTC time on the ECHO Node then the offset from the Interface Node to the ECHO Node will be set to zero and the following message will be printed.

ECHOInt> 1> Failed to calculate time offset from Interface Node to ECHO Node, defaulting to zero

Offsets are calculated both at startup of the interface and at runtime every 2 minutes. If the previous value and the current value do not match then the following message is printed to the pipc log file.

ECHOInt> 1> (UTC Time on Interface Node) - (UTC Time on ECHO Node) = ‘x’ seconds

The same is true for the offset from the Interface Node to the PI Server Node.

ECHOInt> 1> (UTC Time on PI Node) - (UTC Time on Interface Node) = ‘x’ seconds

If for some reason the offset to ECHO is stored and the calculated start time of a tag minus the stored offset to ECHO is negative then the following message will be printed.

ECHOInt> 1> Error: Failed subtracting offset to ECHO (x) from expected start time, defaulting to start time with no offsets (starttime)

If the-echo=node command-line option requests an ECHO Archive Engine that is 1.3 or earlier then the following message will be printed to the pipc log file.

ECHOInt> 1> this version of ECHOInt only supports ECHO 2.0 or later. for ECHO 1.3 support contact ECHO Tech Support

If the interface failed to write data to PI for a tag and the interface was configured to use the PI API for sending data then the following message is printed.

ECHOInt> 1> Error: Failed to write data to PI for Tag ‘Tag-ID’. Error: xSee the section titled “System Errors and PI Errors” for additional information related to PI API errors.

64

If a read history command-line option was specified and the interface fails to read the last snapshot value from PI for the specified tag then the following message is printed.

ECHOInt> 1> Error: failed to read last snapshot timestamp for PI Tag “tagname”. Defaulting to current time

If an exception sending data to PI using the PI API occurs then the following message is printed. In this example Integer data is being sent to PI.

ECHOInt> 1> Exception occurred sending Integer data to PI for ScanClass[x], Cnt=x

If a failure occurred sending data to PI using UniInt, then the following message is printed.

ECHOInt> 1> ui_update_tag_sc() failed for PI Tag ‘tagname’ (tag/id)

If UniInt is requesting read current values for each scan class and the interface cannot keep up with the request then the following message is logged.

ECHOInt> 1> Interface in Over-Run Mode: Request to Read Current Value for tags in ScanClass (x) has been skipped.

If an error occurs at startup while parsing the command-line input then a specific message will be logged informing the user of the issue and the interface will shut down. Errors that cause the interface to shutdown at startup are listed here:


Appendix A: Error and Informational Messages

ECHOInt> 1> Error: /f option requires scan class update rateECHOInt> 1> Error: -echo option specified more than onceECHOInt> 1> Error: -echo option requires ECHO Node NameECHOInt> 1> Error: interface shutting down due to cmdline parsing errorECHOInt> 1> Error: Required command line option missing: /ps=x /id=# -echo=node /f=##ECHOInt> 1> Error: failed to allocate thread for ECHO communication, shutting downECHOInt> 1> Error: failed to allocate scanclass objects, shutting down ECHOInt> 1> Error: /db option requires debug level greater than zeroECHOInt> 1> Error: /db option requires debug levelECHOInt> 1> Error: Failed parsing scan class inputECHOInt> 1> Error: failed parsing time string inputs for /hronly=starttime,endtime cmdline option, interface shutting downECHOInt> 1> Error: /hronly cmdline option requires starttime,endtime parameters, interface shutting downECHOInt> 1> Error: Bad interface id definition (/id=#). Argument is either missing or invalid.ECHOInt> 1> Error: /id option requires instance ID numberECHOInt> 1> Error: Illegal ECHO reconnect delay specified (-rd=ECHOInt> 1> Error: -rd option requires millisecondsECHOInt> 1> Error: invalid history recovery time specified: /rh=ECHOInt> 1> Error: Read option required - /rc for read current OR /rh for read historyECHOInt> 1> Error: Too many read options specified: use either /rc for read current OR /rh for read HistoryECHOInt> 1> Error: System digital state 'I/O Timeout' not found in SYSTEM state setECHOInt> 1> Error: System digital state 'Bad' not found in SYSTEM state setECHOInt> 1> Error: failed to start ECHO Communication thread, shutting down

The following is a list of error messages that can occur when UniInt is calling the interface to load a tag found in PI whose pointsource and instance ID match that of the interface. If one of the following messages is printed to the pipc log file, then the tag has been dropped from the interface configuration and will not receive data in PI by the interface.

66

ECHOInt> 1> Error: Invalid Loc4 scan class requested for PI Tag ‘tagname’ (tag-Id)ECHOInt> 1> Error: Invalid Loc2 read option requested for PI Tag ‘tagname’ (tag-Id)ECHOInt> 1> Error: Failed storing PI Tag ‘tagname’ (tag-Id)ECHOInt> 1> Error: Invalid ECHO node name requested in instrument tag field for PI Tag ‘tagname’ (tag-Id)

System Errors and PI ErrorsSystem errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.

Error Descriptions Descriptions of system and PI errors can be obtained with the pidiag utility:

\PI\adm\pidiag –e error_number


Revision HistoryDate Author Comments

13-Apr-2007 PHawkins Skeleton Version 2.5.2Initial manual version.

8-May-2007 Janelle Version 1.0.0.4, Revision A: updated formatting; added ICU Control section

11-May-2007 PHawkins Updated cmd line option and added support for new UniInt Health tag. Version 1.0.0.6

16-May-2007 Janelle Version 1.0.0.6, Revision A: added set device status information

18-May-2007 MKelly Version 1.0.0.6, Revision B: Made formatting changes, updated IORates section descriptions, fixed header and footers, updated sample batch file.

21-May-2007 PHawkins Version 1.0.0.6, Revision C: made clarifications in the text.

30-May-2007 Janelle Version 1.0.0.6, Revision D: added support information for disconnected startup


pi echo to pi interface to the pi systemcdn.osisoft.com/interfaces/1573/pi_echoint_1.0.0.6.doc ·...

Documents